kubeadmクラスターのアップグレード
このページでは、kubeadmで作成したKubernetesクラスターをバージョン1.33.xから1.34.xに、または1.34.xから1.34.y (y > x)にアップグレードする方法を説明します。マイナーバージョンを飛ばしてのアップグレードはサポートされていません。詳細はVersion Skew Policyを参照してください。
古いバージョンのkubeadmで作成したクラスターのアップグレードについては、次のページを参照してください。
- 1.33から1.34へのkubeadmクラスターのアップグレード
- 1.32から1.33へのkubeadmクラスターのアップグレード
- 1.31から1.32へのkubeadmクラスターのアップグレード
- 1.30から1.31へのkubeadmクラスターのアップグレード
Kubernetesプロジェクトでは最新のパッチリリースへの早めのアップグレードと、サポート対象のマイナーリリースを実行することを推奨しています。これによりセキュリティを維持できます。
アップグレードの大まかなワークフローは次の通りです。
- プライマリコントロールプレーンノードをアップグレードする。
- 追加のコントロールプレーンノードをアップグレードする。
- ワーカーノードをアップグレードする。
前提条件
- リリースノートをよく確認してください。
- クラスターは静的コントロールプレーンと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フラグでUpgradeConfigurationAPI typeを受け付けます。これによりアップグレードプロセスを構成できます。kubeadm upgradeは既存クラスターの再構成をサポートしません。既存クラスターの再構成についてはReconfiguring a kubeadm clusterの手順に従ってください。
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マイナーリリース向けにパッケージリポジトリを有効にする必要があります。詳しくはChanging The Kubernetes Package Repositoryを参照してください。
apt.kubernetes.io and yum.kubernetes.io) have been
deprecated and frozen starting from September 13, 2023.
Using the new package repositories hosted at pkgs.k8s.io
is strongly recommended and required in order to install Kubernetes versions released after September 13, 2023.
The deprecated legacy repositories, and their contents, might be removed at any time in the future and without
a further notice period. The new package repositories provide downloads for Kubernetes versions starting with v1.24.0.
アップグレード先バージョンを決定する
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の実行
最初のコントロールプレーンノードの場合
-
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 kubeadmDNFを使うシステム:
# 1.34.x-*のxを、今回のアップグレードで選んだ最新パッチに置き換えてください sudo yum install -y kubeadm-'1.34.x-*' --disableexcludes=kubernetesDNF5を使うシステム:
# 1.34.x-*のxを、今回のアップグレードで選んだ最新パッチに置き換えてください sudo yum install -y kubeadm-'1.34.x-*' --setopt=disable_excludes=kubernetes -
ダウンロードが期待したバージョンであることを確認します。
kubeadm version -
アップグレードプランを確認します。
sudo kubeadm upgrade planこのコマンドはクラスターがアップグレード可能かどうかをチェックし、アップグレードできるバージョンを取得します。また、コンポーネント設定のバージョン状態を示すテーブルも表示します。
備考:
kubeadm upgradeはこのノードで管理している証明書の更新も自動で行います。証明書更新を無効にするには--certificate-renewal=falseフラグを使用できます。証明書管理の詳細はkubeadmによる証明書管理を参照してください。 -
アップグレードするバージョンを選び、適切なコマンドを実行します。例えば:
# 今回選んだパッチバージョンで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.備考:
v1.28より前のバージョンでは、kubeadmは他のコントロールプレーンインスタンスがアップグレードされていない場合でも、kubeadm upgrade apply実行中にアドオン(CoreDNSやkube-proxyを含む)を直ちにアップグレードするモードがデフォルトでした。これは互換性の問題を引き起こす可能性があります。v1.28以降、kubeadmは全てのコントロールプレーンインスタンスがアップグレードされているかを確認してからアドオンのアップグレードを開始するモードをデフォルトにしています。コントロールプレーンインスタンスは順次アップグレードするか、最後のインスタンスのアップグレードを他のインスタンスの完了まで開始しないようにしてください。アドオンのアップグレードは最後のコントロールプレーンインスタンスがアップグレードされた後に行われます。 -
CNIプロバイダーのプラグインを手動でアップグレードします。
コンテナネットワークインターフェース(CNI)プロバイダーはそれ自体のアップグレード手順を持つ場合があります。アドオンのページで使用しているCNIプロバイダーを確認し、追加のアップグレード手順が必要かどうかを確認してください。
なお、CNIプラグインがDaemonSetで動作している場合、追加のコントロールプレーンノードではこの手順は不要です。
他のコントロールプレーンノードの場合
最初のコントロールプレーンノードと同様の手順ですが、次を使用します。
sudo kubeadm upgrade node
代わりに次のコマンドは使用しません。
sudo kubeadm upgrade apply
また、kubeadm upgrade planの実行やCNIプラグインのアップグレードは不要です。
ノードのドレイン
メンテナンス準備として、ノードをスケジューリング不可にしてワークロードを退避させます。
# <node-to-drain>をドレインするノード名に置き換えてください
kubectl drain <node-to-drain> --ignore-daemonsets
kubeletとkubectlのアップグレード
-
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 kubectlDNFを使うシステム:
# 1.34.x-*のxを、今回のアップグレードで選んだ最新パッチに置き換えてください sudo yum install -y kubelet-'1.34.x-*' kubectl-'1.34.x-*' --disableexcludes=kubernetesDNF5を使うシステム:
# 1.34.x-*のxを、今回のアップグレードで選んだ最新パッチに置き換えてください sudo yum install -y kubelet-'1.34.x-*' kubectl-'1.34.x-*' --setopt=disable_excludes=kubernetes -
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を使ったクラスターのアップグレード後、バックアップディレクトリ/etc/kubernetes/tmpは残り、これらのバックアップファイルは手動で削除する必要があります。動作の仕組み
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設定をアップグレードする。