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

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

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

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

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

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

始める前に

  • リリースノートをよく確認してください。
  • クラスターは静的コントロールプレーンとetcd Pod、または外部etcdを使用している必要があります。
  • データベースに保存されたアプリケーションレベルの状態など、重要なコンポーネントのバックアップを取ってください。 kubeadm upgradeはワークロードには触れず、Kubernetes内部のコンポーネントのみを対象としますが、バックアップは常に推奨されます。
  • Swapを無効にする必要があります。

追加情報

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

etcdのアップグレードに関する考慮事項

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

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

パッケージリポジトリの変更

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

アップグレード先バージョンを決定する

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

# リスト内の最新の1.34バージョンを探します。
# 形式は1.34.x-*のようになります。
sudo apt update
sudo apt-cache madison kubeadm

DNFを使うシステム:

# リスト内の最新の1.34バージョンを探します。
# 形式は1.34.x-*のようになります。
sudo yum list --showduplicates kubeadm --disableexcludes=kubernetes

DNF5を使うシステム:

# リスト内の最新の1.34バージョンを探します。
# 形式は1.34.x-*のようになります。
sudo yum list --showduplicates kubeadm --setopt=disable_excludes=kubernetes

期待するバージョンが表示されない場合は、Kubernetesパッケージリポジトリが利用されているか確認してください。

コントロールプレーンノードのアップグレード

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

"kubeadm upgrade"の実行

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

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

    # 1.34.x-*のxを、今回のアップグレードで選んだ最新パッチに置き換えてください
sudo apt-mark unhold kubeadm && \
sudo apt-get update && sudo apt-get install -y kubeadm='1.34.x-*' && \
sudo apt-mark hold kubeadm

    DNFを使うシステム:

    # 1.34.x-*のxを、今回のアップグレードで選んだ最新パッチに置き換えてください
sudo yum install -y kubeadm-'1.34.x-*' --disableexcludes=kubernetes

    DNF5を使うシステム:

    # 1.34.x-*のxを、今回のアップグレードで選んだ最新パッチに置き換えてください
sudo yum install -y kubeadm-'1.34.x-*' --setopt=disable_excludes=kubernetes

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

    kubeadm version

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

    sudo kubeadm upgrade plan

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

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

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

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

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

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

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

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

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

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

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

sudo kubeadm upgrade apply

の代わりに、

sudo kubeadm upgrade node

を使用します。

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

ノードのドレイン

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

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

kubeletとkubectlのアップグレード

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

    # 1.34.x-*のxを、今回のアップグレードで選んだ最新パッチに置き換えてください
sudo apt-mark unhold kubelet kubectl && \
sudo apt-get update && sudo apt-get install -y kubelet='1.34.x-*' kubectl='1.34.x-*' && \
sudo apt-mark hold kubelet kubectl

    DNFを使うシステム:

    # 1.34.x-*のxを、今回のアップグレードで選んだ最新パッチに置き換えてください
sudo yum install -y kubelet-'1.34.x-*' kubectl-'1.34.x-*' --disableexcludes=kubernetes

    DNF5を使うシステム:

    # 1.34.x-*のxを、今回のアップグレードで選んだ最新パッチに置き換えてください
sudo yum install -y kubelet-'1.34.x-*' kubectl-'1.34.x-*' --setopt=disable_excludes=kubernetes

  2. kubeletを再起動します。

    sudo systemctl daemon-reload
sudo systemctl restart kubelet

ノードのuncordon(スケジュール可能化)

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

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

ワーカーノードのアップグレード

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

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

クラスターの状態を確認する

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

kubectl get nodes

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

障害状態からの復旧

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に手動で復元できます。 何らかの理由で特定のコンポーネントのアップグレード前とアップグレード後のマニフェストに差分がない場合、そのコンポーネントのバックアップファイルは書き込まれません。

動作の仕組み

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設定をアップグレードする。
最終更新 August 08, 2026 at 10:32 PM PST: Apply suggestions from code review (c2975912dd)