# kubeadmクラスターのアップグレード

LLMS index: [llms.txt](/llms.txt)

---

<!-- overview -->

このページでは、kubeadmで作成したKubernetesクラスターをバージョン1.35.xから1.36.xに、または1.36.xから1.36.y(y > x)にアップグレードする方法を説明します。
マイナーバージョンを飛ばしてのアップグレードはサポートされていません。
詳細は[バージョンスキューポリシー](/releases/version-skew-policy/)を参照してください。

古いバージョンのkubeadmで作成したクラスターのアップグレードについては、次のページを参照してください。

- [1.34から1.35へのkubeadmクラスターのアップグレード](https://v1-35.docs.kubernetes.io/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade/)
- [1.33から1.34へのkubeadmクラスターのアップグレード](https://v1-34.docs.kubernetes.io/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade/)
- [1.32から1.33へのkubeadmクラスターのアップグレード](https://v1-33.docs.kubernetes.io/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade/)
- [1.31から1.32へのkubeadmクラスターのアップグレード](https://v1-32.docs.kubernetes.io/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade/)

Kubernetesプロジェクトでは最新のパッチリリースへの早めのアップグレードと、サポート対象のマイナーリリースを実行することを推奨しています。
これによりセキュリティを維持できます。

アップグレードの大まかなワークフローは次の通りです。

1. プライマリコントロールプレーンノードをアップグレードする。
1. 追加のコントロールプレーンノードをアップグレードする。
1. ワーカーノードをアップグレードする。

## 始める前に

- [リリースノート](https://git.k8s.io/kubernetes/CHANGELOG)をよく確認してください。
- クラスターは静的コントロールプレーンとetcd Pod、または外部etcdを使用している必要があります。
- データベースに保存されたアプリケーションレベルの状態など、重要なコンポーネントのバックアップを取ってください。
  `kubeadm upgrade`はワークロードには触れず、Kubernetes内部のコンポーネントのみを対象としますが、バックアップは常に推奨されます。
- [Swapを無効にする必要があります](https://serverfault.com/questions/684771/best-way-to-disable-swap-in-linux)。

### 追加情報 {#additional-information}

- 以下の手順は、アップグレード中にいつノードをドレインするかの目安を示しています。
  kubeletの**マイナー**バージョンアップグレードを行う場合、対象ノードは事前にドレインする必要があります。
  コントロールプレーンノードの場合、CoreDNS Podや他の重要なワークロードが実行されている可能性があります。
  詳しくは[ノードのドレイン](/docs/tasks/administer-cluster/safely-drain-node/)を参照してください。
- Kubernetesプロジェクトではkubeletとkubeadmのバージョンを合わせることを推奨しています。
  kubeadmより古いkubeletを使うことは可能ですが、サポートされているバージョン範囲内である必要があります。
  詳細は[kubeletに対するkubeadmのバージョンの差異](/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm/#kubeadm-s-skew-against-the-kubelet)を参照してください。
- アップグレード後はすべてのコンテナが再起動されます。
  これはコンテナのハッシュ値が変わるためです。
- kubeletのアップグレード後にkubeletサービスが正常に再起動したことを確認するには、`systemctl status kubelet`を実行するか、`journalctl -xeu kubelet`でサービスログを確認できます。
- `kubeadm upgrade`は`--config`フラグで[`UpgradeConfiguration` API type](/docs/reference/config-api/kubeadm-config.v1beta4)を受け付けます。
  これによりアップグレードプロセスを構成できます。
- `kubeadm upgrade`は既存クラスターの再構成をサポートしません。
  既存クラスターの再構成については[kubeadmクラスターの再構成](/docs/tasks/administer-cluster/kubeadm/kubeadm-reconfigure)の手順に従ってください。

### etcdのアップグレードに関する考慮事項 {#considerations-when-upgrading-etcd}

`kube-apiserver`のStatic Podは(ノードをドレインしていても)常に実行されているため、etcdのアップグレードを含むkubeadmアップグレードを実行すると、新しいetcd Static Podが再起動している間にサーバーへの処理中のリクエストが停滞する可能性があります。
回避策として、`kubeadm upgrade apply`コマンドを開始する数秒前に`kube-apiserver`プロセスを一時的に停止することが可能です。
こうすることで処理中のリクエストを完了させ、既存接続をクローズでき、etcdのダウンタイムの影響を最小限にできます。
コントロールプレーンノードでは次のように行います。

```shell
killall -s SIGTERM kube-apiserver # kube-apiserverのグレースフルシャットダウンをトリガーする
sleep 20 # 処理中のリクエストの完了まで少し待つ
kubeadm upgrade ... # kubeadm upgradeコマンドを実行
```

<!-- steps -->

## パッケージリポジトリの変更 {#changing-the-package-repository}

- コミュニティが運営するパッケージリポジトリ(`pkgs.k8s.io`)を使用している場合、目的のKubernetesマイナーリリース向けにパッケージリポジトリを有効にする必要があります。
  詳しくは[Kubernetesパッケージリポジトリの変更](/docs/tasks/administer-cluster/kubeadm/change-package-repository/)を参照してください。

<div class="alert alert-secondary callout note" role="note">
  <strong>備考:</strong> 古いパッケージリポジトリ(<code>apt.kubernetes.io</code>および<code>yum.kubernetes.io</code>)は<a href="/blog/2023/08/31/legacy-package-repository-deprecation/">2023年9月13日以降、非推奨となり凍結されています</a>。
<strong><a href="/blog/2023/08/15/pkgs-k8s-io-introduction/"><code>pkgs.k8s.io</code>にてホストされている新しいリポジトリ</a>の使用が強く推奨されており、2023年9月13日以降にリリースされたKubernetesのバージョンをインストールするには必須となっています。</strong>
非推奨の古いリポジトリとその内容は、将来事前予告なく削除される可能性があります。
新しいパッケージリポジトリでは、v1.24.0以降のKubernetesバージョンのダウンロードを提供しています。
</div>


## アップグレード先バージョンを決定する {#determine-which-version-to-upgrade-to}

OSのパッケージマネージャーを使って、Kubernetes 1.36の最新パッチを見つけます。

<ul class="nav nav-tabs" id="tabs-k8s-install-versions" role="tablist"><li class="nav-item"><a data-bs-toggle="tab" class="nav-link active" href="#tabs-k8s-install-versions-0" role="tab" aria-controls="tabs-k8s-install-versions-0" aria-selected="true">Ubuntu、DebianまたはHypriotOS</a></li>
	  
		<li class="nav-item"><a data-bs-toggle="tab" class="nav-link" href="#tabs-k8s-install-versions-1" role="tab" aria-controls="tabs-k8s-install-versions-1">CentOS、RHELまたはFedora</a></li></ul>

<div class="tab-content" id="tabs-k8s-install-versions-content"><div class="tab-body tab-pane fadeshow active"
        id="tabs-k8s-install-versions-0" role="tabpanel" aria-labelledby="tabs-k8s-install-versions-0-tab" tabindex="k8s-install-versions"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-shell" data-lang="shell"><span class="line"><span class="cl"><span class="c1"># リスト内の最新の1.36バージョンを探します。</span>
</span></span><span class="line"><span class="cl"><span class="c1"># 形式は1.36.x-*のようになります。</span>
</span></span><span class="line"><span class="cl">sudo apt update
</span></span><span class="line"><span class="cl">sudo apt-cache madison kubeadm
</span></span></code></pre></div></div><div class="tab-body tab-pane fade"
        id="tabs-k8s-install-versions-1" role="tabpanel" aria-labelledby="tabs-k8s-install-versions-1-tab" tabindex="k8s-install-versions"><p>DNFを使うシステム:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-shell" data-lang="shell"><span class="line"><span class="cl"><span class="c1"># リスト内の最新の1.36バージョンを探します。</span>
</span></span><span class="line"><span class="cl"><span class="c1"># 形式は1.36.x-*のようになります。</span>
</span></span><span class="line"><span class="cl">sudo yum list --showduplicates kubeadm --disableexcludes<span class="o">=</span>kubernetes
</span></span></code></pre></div><p>DNF5を使うシステム:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-shell" data-lang="shell"><span class="line"><span class="cl"><span class="c1"># リスト内の最新の1.36バージョンを探します。</span>
</span></span><span class="line"><span class="cl"><span class="c1"># 形式は1.36.x-*のようになります。</span>
</span></span><span class="line"><span class="cl">sudo yum list --showduplicates kubeadm --setopt<span class="o">=</span><span class="nv">disable_excludes</span><span class="o">=</span>kubernetes
</span></span></code></pre></div></div></div>


期待するバージョンが表示されない場合は、[Kubernetesパッケージリポジトリが利用されているか確認してください。](/docs/tasks/administer-cluster/kubeadm/change-package-repository/#verifying-if-the-kubernetes-package-repositories-are-used)

## コントロールプレーンノードのアップグレード {#upgrading-control-plane-nodes}

コントロールプレーンノードのアップグレードはノードごとに順に実行する必要があります。
まずアップグレードするコントロールプレーンノードを選んでください。
そのノードには`/etc/kubernetes/admin.conf`ファイルが存在する必要があります。

### "kubeadm upgrade"の実行 {#call-kubeadm-upgrade}

**最初のコントロールプレーンノードの場合**

1. kubeadmをアップグレードします。

   <ul class="nav nav-tabs" id="tabs-k8s-install-kubeadm-first-cp" role="tablist"><li class="nav-item"><a data-bs-toggle="tab" class="nav-link active" href="#tabs-k8s-install-kubeadm-first-cp-0" role="tab" aria-controls="tabs-k8s-install-kubeadm-first-cp-0" aria-selected="true">Ubuntu、DebianまたはHypriotOS</a></li>
	  
		<li class="nav-item"><a data-bs-toggle="tab" class="nav-link" href="#tabs-k8s-install-kubeadm-first-cp-1" role="tab" aria-controls="tabs-k8s-install-kubeadm-first-cp-1">CentOS、RHELまたはFedora</a></li></ul>

<div class="tab-content" id="tabs-k8s-install-kubeadm-first-cp-content"><div class="tab-body tab-pane fadeshow active"
        id="tabs-k8s-install-kubeadm-first-cp-0" role="tabpanel" aria-labelledby="tabs-k8s-install-kubeadm-first-cp-0-tab" tabindex="k8s-install-kubeadm-first-cp"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-shell" data-lang="shell"><span class="line"><span class="cl"><span class="c1"># 1.36.x-*のxを、今回のアップグレードで選んだ最新パッチに置き換えてください</span>
</span></span><span class="line"><span class="cl">sudo apt-mark unhold kubeadm <span class="o">&amp;&amp;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">sudo apt-get update <span class="o">&amp;&amp;</span> sudo apt-get install -y <span class="nv">kubeadm</span><span class="o">=</span><span class="s1">&#39;1.36.x-*&#39;</span> <span class="o">&amp;&amp;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">sudo apt-mark hold kubeadm
</span></span></code></pre></div></div><div class="tab-body tab-pane fade"
        id="tabs-k8s-install-kubeadm-first-cp-1" role="tabpanel" aria-labelledby="tabs-k8s-install-kubeadm-first-cp-1-tab" tabindex="k8s-install-kubeadm-first-cp"><p>DNFを使うシステム:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-shell" data-lang="shell"><span class="line"><span class="cl"><span class="c1"># 1.36.x-*のxを、今回のアップグレードで選んだ最新パッチに置き換えてください</span>
</span></span><span class="line"><span class="cl">sudo yum install -y kubeadm-<span class="s1">&#39;1.36.x-*&#39;</span> --disableexcludes<span class="o">=</span>kubernetes
</span></span></code></pre></div><p>DNF5を使うシステム:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-shell" data-lang="shell"><span class="line"><span class="cl"><span class="c1"># 1.36.x-*のxを、今回のアップグレードで選んだ最新パッチに置き換えてください</span>
</span></span><span class="line"><span class="cl">sudo yum install -y kubeadm-<span class="s1">&#39;1.36.x-*&#39;</span> --setopt<span class="o">=</span><span class="nv">disable_excludes</span><span class="o">=</span>kubernetes
</span></span></code></pre></div></div></div>


1. ダウンロードが期待したバージョンであることを確認します。

   ```shell
   kubeadm version
   ```

1. アップグレードプランを確認します。

   ```shell
   sudo kubeadm upgrade plan
   ```

   このコマンドはクラスターがアップグレード可能かどうかをチェックし、アップグレードできるバージョンを取得します。
   また、コンポーネント設定のバージョン状態を示すテーブルも表示します。

   
<div class="alert alert-info" role="note"><h4 class="alert-heading">備考:</h4><code>kubeadm upgrade</code>はこのノードで管理している証明書の更新も自動で行います。
証明書更新を無効にするには<code>--certificate-renewal=false</code>フラグを使用できます。
証明書管理の詳細は<a href="/ja/docs/tasks/administer-cluster/kubeadm/kubeadm-certs/">kubeadmによる証明書管理</a>を参照してください。</div>


1. アップグレードするバージョンを選び、適切なコマンドを実行します。
   例えば:

   ```shell
   # 今回選んだパッチバージョンでxを置き換えてください
   sudo kubeadm upgrade apply v1.36.x
   ```

   コマンドが終了すると、次のようなメッセージが表示されます。

   ```
   [upgrade/successful] SUCCESS! Your cluster was upgraded to "v1.36.x". Enjoy!

   [upgrade/kubelet] Now that your control plane is upgraded, please proceed with upgrading your kubelets if you haven't already done so.
   ```

   
<div class="alert alert-info" role="note"><h4 class="alert-heading">備考:</h4>v1.28より前のバージョンでは、kubeadmは他のコントロールプレーンインスタンスがアップグレードされていない場合でも、<code>kubeadm upgrade apply</code>実行中にアドオン(CoreDNSやkube-proxyを含む)を直ちにアップグレードするモードがデフォルトでした。
これは互換性の問題を引き起こす可能性があります。
v1.28以降、kubeadmは全てのコントロールプレーンインスタンスがアップグレードされているかを確認してから、アドオンのアップグレードを開始するモードをデフォルトにしています。
コントロールプレーンインスタンスは順次アップグレードするか、最後のインスタンスのアップグレードを他のインスタンスの完了まで開始しないようにしてください。
アドオンのアップグレードは、最後のコントロールプレーンインスタンスがアップグレードされた後に行われます。</div>


1. CNIプロバイダーのプラグインを手動でアップグレードします。

   コンテナネットワークインターフェース(CNI)プロバイダーは、独自のアップグレード手順を持つ場合があります。
   [アドオン](/docs/concepts/cluster-administration/addons/)のページで使用しているCNIプロバイダーを確認し、追加のアップグレード手順が必要かどうかを確認してください。

   なお、CNIプラグインがDaemonSetで動作している場合、追加のコントロールプレーンノードではこの手順は不要です。

**他のコントロールプレーンノードの場合**

最初のコントロールプレーンノードと同様の手順ですが、

```shell
sudo kubeadm upgrade apply
```

の代わりに、

```shell
sudo kubeadm upgrade node
```

を使用します。

また、`kubeadm upgrade plan`の実行やCNIプラグインのアップグレードは不要です。

### ノードのドレイン {#drain-the-node}

メンテナンス準備として、ノードをスケジューリング不可にしてワークロードを退避させます。

```shell
# <node-to-drain>をドレインするノード名に置き換えてください
kubectl drain <node-to-drain> --ignore-daemonsets
```

### kubeletとkubectlのアップグレード {#upgrade-kubelet-and-kubectl}

1. kubeletとkubectlをアップグレードします。

   <ul class="nav nav-tabs" id="tabs-k8s-install-kubelet" role="tablist"><li class="nav-item"><a data-bs-toggle="tab" class="nav-link active" href="#tabs-k8s-install-kubelet-0" role="tab" aria-controls="tabs-k8s-install-kubelet-0" aria-selected="true">Ubuntu、DebianまたはHypriotOS</a></li>
	  
		<li class="nav-item"><a data-bs-toggle="tab" class="nav-link" href="#tabs-k8s-install-kubelet-1" role="tab" aria-controls="tabs-k8s-install-kubelet-1">CentOS、RHELまたはFedora</a></li></ul>

<div class="tab-content" id="tabs-k8s-install-kubelet-content"><div class="tab-body tab-pane fadeshow active"
        id="tabs-k8s-install-kubelet-0" role="tabpanel" aria-labelledby="tabs-k8s-install-kubelet-0-tab" tabindex="k8s-install-kubelet"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-shell" data-lang="shell"><span class="line"><span class="cl"><span class="c1"># 1.36.x-*のxを、今回のアップグレードで選んだ最新パッチに置き換えてください</span>
</span></span><span class="line"><span class="cl">sudo apt-mark unhold kubelet kubectl <span class="o">&amp;&amp;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">sudo apt-get update <span class="o">&amp;&amp;</span> sudo apt-get install -y <span class="nv">kubelet</span><span class="o">=</span><span class="s1">&#39;1.36.x-*&#39;</span> <span class="nv">kubectl</span><span class="o">=</span><span class="s1">&#39;1.36.x-*&#39;</span> <span class="o">&amp;&amp;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">sudo apt-mark hold kubelet kubectl
</span></span></code></pre></div></div><div class="tab-body tab-pane fade"
        id="tabs-k8s-install-kubelet-1" role="tabpanel" aria-labelledby="tabs-k8s-install-kubelet-1-tab" tabindex="k8s-install-kubelet"><p>DNFを使うシステム:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-shell" data-lang="shell"><span class="line"><span class="cl"><span class="c1"># 1.36.x-*のxを、今回のアップグレードで選んだ最新パッチに置き換えてください</span>
</span></span><span class="line"><span class="cl">sudo yum install -y kubelet-<span class="s1">&#39;1.36.x-*&#39;</span> kubectl-<span class="s1">&#39;1.36.x-*&#39;</span> --disableexcludes<span class="o">=</span>kubernetes
</span></span></code></pre></div><p>DNF5を使うシステム:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-shell" data-lang="shell"><span class="line"><span class="cl"><span class="c1"># 1.36.x-*のxを、今回のアップグレードで選んだ最新パッチに置き換えてください</span>
</span></span><span class="line"><span class="cl">sudo yum install -y kubelet-<span class="s1">&#39;1.36.x-*&#39;</span> kubectl-<span class="s1">&#39;1.36.x-*&#39;</span> --setopt<span class="o">=</span><span class="nv">disable_excludes</span><span class="o">=</span>kubernetes
</span></span></code></pre></div></div></div>


1. kubeletを再起動します。

   ```shell
   sudo systemctl daemon-reload
   sudo systemctl restart kubelet
   ```

### ノードのuncordon(スケジュール可能化) {#uncordon-the-node}

ノードを再びスケジュール可能にしてオンラインにします。

```shell
# <node-to-uncordon>を対象ノード名に置き換えてください
kubectl uncordon <node-to-uncordon>
```

## ワーカーノードのアップグレード {#upgrade-worker-nodes}

ワーカーノードのアップグレードは、ワークロードを実行するための必要最小限の容量を損なわない範囲で、ノードを1台ずつまたは複数台ずつ順に実行してください。

LinuxとWindowsのワーカーノードのアップグレード方法については次のページを参照してください。

- [Linuxノードのアップグレード](/docs/tasks/administer-cluster/kubeadm/upgrading-linux-nodes/)
- [Windowsノードのアップグレード](/docs/tasks/administer-cluster/kubeadm/upgrading-windows-nodes/)

## クラスターの状態を確認する {#verify-the-status-of-the-cluster}

kubeletをすべてのノードでアップグレードした後、kubectlがクラスターにアクセス可能な場所から以下のコマンドを実行し、すべてのノードが再び利用可能であることを確認してください。

```shell
kubectl get nodes
```

`STATUS`列にはすべてのノードで`Ready`が表示され、バージョン番号が更新されているはずです。

## 障害状態からの復旧 {#recovering-from-a-failure-state}

`kubeadm upgrade`が失敗してロールバックしない場合(例えば実行中の予期しないシャットダウンなど)、再度`kubeadm upgrade`を実行することで回復できます。
`kubeadm upgrade`は冪等性があり、最終的に実際の状態が宣言した望ましい状態であることを保証します。

悪い状態から回復するため、クラスターが実行しているバージョンを変更せずに`sudo kubeadm upgrade apply --force`を実行することもできます。

アップグレード中、kubeadmは`/etc/kubernetes/tmp`配下に、次のバックアップフォルダーを書き込みます。

- `kubeadm-backup-etcd-<date>-<time>`
- `kubeadm-backup-manifests-<date>-<time>`

`kubeadm-backup-etcd`には、このコントロールプレーンノードのローカルetcdメンバーデータのバックアップが含まれます。
etcdのアップグレードに失敗し、自動ロールバックが機能しない場合、このフォルダーの内容を`/var/lib/etcd`に手動で復元できます。
外部etcdを使用している場合、このバックアップフォルダーは空になります。

`kubeadm-backup-manifests`には、このコントロールプレーンノードのStatic Podマニフェストファイルのバックアップが含まれます。
アップグレードの失敗や自動ロールバックが機能しない場合、このフォルダーの内容を`/etc/kubernetes/manifests`に手動で復元できます。
何らかの理由で特定のコンポーネントのアップグレード前とアップグレード後のマニフェストに差分がない場合、そのコンポーネントのバックアップファイルは書き込まれません。


<div class="alert alert-info" role="note"><h4 class="alert-heading">備考:</h4>kubeadmを使ったクラスターのアップグレード後、バックアップディレクトリ<code>/etc/kubernetes/tmp</code>は残り、これらのバックアップファイルは手動で削除する必要があります。</div>


## 動作の仕組み {#how-it-works}

`kubeadm upgrade apply`は次のことを行います。

- クラスターがアップグレード可能な状態であることをチェックする。
  - APIサーバーに到達可能であること
  - すべてのノードが`Ready`状態であること
  - コントロールプレーンが健全であること
- バージョンスキューポリシーを適用する。
- コントロールプレーンのイメージが利用可能であるか、あるいはマシンに取得可能であることを確認する。
- コンポーネント設定がバージョンアップを必要とする場合、代替を生成する、またはユーザー提供の上書きを使用する、あるいはその両方を行う。
- コントロールプレーンコンポーネントをアップグレードし、いずれかが起動しない場合はロールバックする。
- 新しい`CoreDNS`と`kube-proxy`マニフェストを適用し、必要なすべてのRBACルールが作成されていることを確認する。
- APIサーバーの新しい証明書とキーファイルを作成し、期限が180日以内に切れる場合は古いファイルをバックアップする。

`kubeadm upgrade node`は追加のコントロールプレーンノードで次のことを行います。

- kubeadmの`ClusterConfiguration`をクラスターから取得する。
- オプションでkube-apiserverの証明書をバックアップする。
- コントロールプレーンコンポーネントのStatic Podマニフェストをアップグレードする。
- このノードのkubelet設定をアップグレードする。

`kubeadm upgrade node`はワーカーノードで次のことを行います。

- kubeadmの`ClusterConfiguration`をクラスターから取得する。
- このノードのkubelet設定をアップグレードする。
