このページでは、kubeadmで作成したKubernetesクラスターをバージョン1.36.xから1.37.xに、または1.37.xから1.37.y(y > x)にアップグレードする方法を説明します。 マイナーバージョンを飛ばしてのアップグレードはサポートされていません。 詳細はバージョンスキューポリシーを参照してください。
古いバージョンのkubeadmで作成したクラスターのアップグレードについては、次のページを参照してください。
Kubernetesプロジェクトでは最新のパッチリリースへの早めのアップグレードと、サポート対象のマイナーリリースを実行することを推奨しています。 これによりセキュリティを維持できます。
アップグレードの大まかなワークフローは次の通りです。
kubeadm upgradeはワークロードには触れず、Kubernetes内部のコンポーネントのみを対象としますが、バックアップは常に推奨されます。systemctl status kubeletを実行するか、journalctl -xeu kubeletでサービスログを確認できます。kubeadm upgradeは--configフラグでUpgradeConfiguration API typeを受け付けます。
これによりアップグレードプロセスを構成できます。kubeadm upgradeは既存クラスターの再構成をサポートしません。
既存クラスターの再構成についてはkubeadmクラスターの再構成の手順に従ってください。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パッケージリポジトリの変更を参照してください。apt.kubernetes.ioおよびyum.kubernetes.io)は2023年9月13日以降、非推奨となり凍結されています。
pkgs.k8s.ioにてホストされている新しいリポジトリの使用が強く推奨されており、2023年9月13日以降にリリースされたKubernetesのバージョンをインストールするには必須となっています。
非推奨の古いリポジトリとその内容は、将来事前予告なく削除される可能性があります。
新しいパッケージリポジトリでは、v1.24.0以降のKubernetesバージョンのダウンロードを提供しています。OSのパッケージマネージャーを使って、Kubernetes 1.37の最新パッチを見つけます。
# リスト内の最新の1.37バージョンを探します。
# 形式は1.37.x-*のようになります。
sudo apt update
sudo apt-cache madison kubeadm
DNFを使うシステム:
# リスト内の最新の1.37バージョンを探します。
# 形式は1.37.x-*のようになります。
sudo yum list --showduplicates kubeadm --disableexcludes=kubernetes
DNF5を使うシステム:
# リスト内の最新の1.37バージョンを探します。
# 形式は1.37.x-*のようになります。
sudo yum list --showduplicates kubeadm --setopt=disable_excludes=kubernetes
期待するバージョンが表示されない場合は、Kubernetesパッケージリポジトリが利用されているか確認してください。
コントロールプレーンノードのアップグレードはノードごとに順に実行する必要があります。
まずアップグレードするコントロールプレーンノードを選んでください。
そのノードには/etc/kubernetes/admin.confファイルが存在する必要があります。
最初のコントロールプレーンノードの場合
kubeadmをアップグレードします。
# 1.37.x-*のxを、今回のアップグレードで選んだ最新パッチに置き換えてください
sudo apt-mark unhold kubeadm && \
sudo apt-get update && sudo apt-get install -y kubeadm='1.37.x-*' && \
sudo apt-mark hold kubeadm
DNFを使うシステム:
# 1.37.x-*のxを、今回のアップグレードで選んだ最新パッチに置き換えてください
sudo yum install -y kubeadm-'1.37.x-*' --disableexcludes=kubernetes
DNF5を使うシステム:
# 1.37.x-*のxを、今回のアップグレードで選んだ最新パッチに置き換えてください
sudo yum install -y kubeadm-'1.37.x-*' --setopt=disable_excludes=kubernetes
ダウンロードが期待したバージョンであることを確認します。
kubeadm version
アップグレードプランを確認します。
sudo kubeadm upgrade plan
このコマンドはクラスターがアップグレード可能かどうかをチェックし、アップグレードできるバージョンを取得します。 また、コンポーネント設定のバージョン状態を示すテーブルも表示します。
kubeadm upgradeはこのノードで管理している証明書の更新も自動で行います。
証明書更新を無効にするには--certificate-renewal=falseフラグを使用できます。
証明書管理の詳細はkubeadmによる証明書管理を参照してください。アップグレードするバージョンを選び、適切なコマンドを実行します。 例えば:
# 今回選んだパッチバージョンでxを置き換えてください
sudo kubeadm upgrade apply v1.37.x
コマンドが終了すると、次のようなメッセージが表示されます。
[upgrade/successful] SUCCESS! Your cluster was upgraded to "v1.37.x". Enjoy!
[upgrade/kubelet] Now that your control plane is upgraded, please proceed with upgrading your kubelets if you haven't already done so.
kubeadm upgrade apply実行中にアドオン(CoreDNSやkube-proxyを含む)を直ちにアップグレードするモードがデフォルトでした。
これは互換性の問題を引き起こす可能性があります。
v1.28以降、kubeadmは全てのコントロールプレーンインスタンスがアップグレードされているかを確認してから、アドオンのアップグレードを開始するモードをデフォルトにしています。
コントロールプレーンインスタンスは順次アップグレードするか、最後のインスタンスのアップグレードを他のインスタンスの完了まで開始しないようにしてください。
アドオンのアップグレードは、最後のコントロールプレーンインスタンスがアップグレードされた後に行われます。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.37.x-*のxを、今回のアップグレードで選んだ最新パッチに置き換えてください
sudo apt-mark unhold kubelet kubectl && \
sudo apt-get update && sudo apt-get install -y kubelet='1.37.x-*' kubectl='1.37.x-*' && \
sudo apt-mark hold kubelet kubectl
DNFを使うシステム:
# 1.37.x-*のxを、今回のアップグレードで選んだ最新パッチに置き換えてください
sudo yum install -y kubelet-'1.37.x-*' kubectl-'1.37.x-*' --disableexcludes=kubernetes
DNF5を使うシステム:
# 1.37.x-*のxを、今回のアップグレードで選んだ最新パッチに置き換えてください
sudo yum install -y kubelet-'1.37.x-*' kubectl-'1.37.x-*' --setopt=disable_excludes=kubernetes
kubeletを再起動します。
sudo systemctl daemon-reload
sudo systemctl restart kubelet
ノードを再びスケジュール可能にしてオンラインにします。
# <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に手動で復元できます。
何らかの理由で特定のコンポーネントのアップグレード前とアップグレード後のマニフェストに差分がない場合、そのコンポーネントのバックアップファイルは書き込まれません。
/etc/kubernetes/tmpは残り、これらのバックアップファイルは手動で削除する必要があります。kubeadm upgrade applyは次のことを行います。
Ready状態であることCoreDNSとkube-proxyマニフェストを適用し、必要なすべてのRBACルールが作成されていることを確認する。kubeadm upgrade nodeは追加のコントロールプレーンノードで次のことを行います。
ClusterConfigurationをクラスターから取得する。kubeadm upgrade nodeはワーカーノードで次のことを行います。
ClusterConfigurationをクラスターから取得する。