Kubernetesクラスタのアップグレード（#18）

はじめに

これまで参加してきたインターンシップで、Kubernetesクラスタのアップグレードに苦労したという話を耳にする機会が何度かありました。また、古いバージョンのKubernetesクラスタを使い続けている組織も少なくない印象を受けています。

当時は話を聞くだけで実感を持って共感することはできませんでした。しかし、研究室には#14で構築したオンプレミスのKubernetesクラスタがあり、幸運にも実際にアップグレードを経験できる環境があります。むしろ、このような貴重な経験を得るためにクラスタを構築したと言っても過言ではありません。

kubernetes.io

本記事では、上記の公式ドキュメントを参考に、kubeadmで構築したオンプレミスKubernetesクラスタをv1.32からv1.34までアップグレードする手順を紹介します。

1. アップグレード対象バージョンの確認

今回はv1.32からv1.34へのアップグレードを行います。

root@polaris:~$ kubectl get nodes
NAME      STATUS   ROLES           AGE    VERSION
aries     Ready    <none>          153d   v1.32.3
gemini    Ready    <none>          132d   v1.33.1
polaris   Ready    control-plane   153d   v1.32.3
taurus    Ready    <none>          153d   v1.32.3

クラスタ内にはすでにv1.33 のノードがありますが、Kubernetesではマイナーバージョンのスキップがサポートされていないため、「v1.32 → v1.33」→「v1.33 → v1.34」という2段階でアップグレードを実施する必要があります。

基本的な手順は両ステップで共通しているため、本記事ではv1.33へのアップグレード手順を中心に紹介し、v1.34へのアップグレード部分は割愛します。

v1-33.docs.kubernetes.io

また、アップグレードを行う前には必ずリリースノートのUrgent Upgrade Notesに目を通しておきましょう。

github.com

なお、重要なコンポーネントのバックアップはベストプラクティスとされていますが、kubeadm upgradeで影響を受けるのはKubernetes内部のコンポーネントのみであり、ワークロードには直接影響しないため今回は省略しました。

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

まず、アップグレードするバージョンを確認します。

root@polaris:~$ sudo apt update
root@polaris:~$ sudo apt-cache madison kubeadm
   kubeadm | 1.32.9-1.1 | https://pkgs.k8s.io/core:/stable:/v1.32/deb  Packages
   kubeadm | 1.32.8-1.1 | https://pkgs.k8s.io/core:/stable:/v1.32/deb  Packages
   # 省略

アップグレード対象のv1.33系が確認できないため、/etc/apt/sources.list.d/kubernetes.listのURLを以下のように変更します。

- deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.32/deb/ /
+ deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.33/deb/ /

root@polaris:~$ sudo apt update
root@polaris:~$ sudo apt-cache madison kubeadm
   kubeadm | 1.33.5-1.1 | https://pkgs.k8s.io/core:/stable:/v1.33/deb  Packages
   kubeadm | 1.33.4-1.1 | https://pkgs.k8s.io/core:/stable:/v1.33/deb  Packages
   # 省略

v1.33系が表示されたので、今回は最新のパッチバージョンであるv1.33.5にアップグレードします。

root@polaris:~$ sudo apt-mark unhold kubeadm && \
sudo apt-get update && sudo apt-get install -y kubeadm='1.33.5-*' && \
sudo apt-mark hold kubeadm
# 省略

root@polaris:~$ kubeadm version
kubeadm version: &version.Info{Major:"1", Minor:"33", EmulationMajor:"", EmulationMinor:"", MinCompatibilityMajor:"", MinCompatibilityMinor:"", GitVersion:"v1.33.5", GitCommit:"03e764d0394bdff662e960c70d25b3c30d731666", GitTreeState:"clean", BuildDate:"2025-09-09T19:50:45Z", GoVersion:"go1.24.6", Compiler:"gc", Platform:"linux/amd64"}

root@polaris:~$ sudo kubeadm upgrade plan
# 省略

root@polaris:~$ sudo kubeadm upgrade apply v1.33.5
# 省略
[upgrade] SUCCESS! A control plane node of your cluster was upgraded to "v1.33.5".

[upgrade] Now please proceed with upgrading the rest of the nodes by following the right order.

この時点では、kubectl get nodesのVERSION列は変わりません。これは、表示されるバージョンがkubeletのバージョンを参照しているためです。公式ドキュメントに従って、kubeletとkubectlもアップグレードします。

root@polaris:~$ kubectl drain polaris --ignore-daemonsets
# 省略

root@polaris:~$ sudo apt-mark unhold kubelet kubectl && \
sudo apt-get update && sudo apt-get install -y kubelet='1.33.5-*' kubectl='1.33.5-*' && \
sudo apt-mark hold kubelet kubectl
# 省略

root@polaris:~$ sudo systemctl daemon-reload
root@polaris:~$ sudo systemctl restart kubelet

root@polaris:~$  kubectl uncordon polaris
# 省略

root@polaris ~ $  kubectl get nodes
NAME      STATUS   ROLES           AGE    VERSION
aries     Ready    <none>          153d   v1.32.3
gemini    Ready    <none>          132d   v1.33.1
polaris   Ready    control-plane   153d   v1.33.5
taurus    Ready    <none>          153d   v1.32.3

今回のKubernetesクラスタはコントロールプレーンノードが1台のみの構成です。そのため、kubeadm upgrade applyの実行中やkubelet再起動時にAPIサーバーが一時的に停止し、数分程度のダウンタイムが発生しました（HA構成であれば回避可能です）。

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

以下の公式ドキュメントに従い、ワーカーノードを1台ずつ順番にアップグレードしていきます。

v1-33.docs.kubernetes.io

手順はコントロールプレーンノードと同じく

1. kubeadmのアップグレード
2. ノードのdrain
3. kubeletとkubectlのアップグレード
4. ノードのuncordon

という流れで実行します。

root@aries:~$ sudo sed -i 's/v1\.32/v1.33/' /etc/apt/sources.list.d/kubernetes.list
root@aries:~$ sudo apt update
# 省略
root@aries:~$ sudo apt-mark unhold kubeadm && \
sudo apt-get update && sudo apt-get install -y kubeadm='1.33.5-*' && \
sudo apt-mark hold kubeadm
# 省略
root@aries:~$ sudo kubeadm upgrade node
# 省略

# コントロールプレーンノード上で実行
root@polaris:~$ kubectl drain aries --ignore-daemonsets --delete-emptydir-data
# 省略

root@aries:~$ sudo apt-mark unhold kubelet kubectl && \
sudo apt-get update && sudo apt-get install -y kubelet='1.33.5-*' kubectl='1.33.5-*' && \
sudo apt-mark hold kubelet kubectl
root@aries:~$ sudo systemctl daemon-reload
root@aries:~$ sudo systemctl restart kubelet

# コントロールプレーンノード上で実行
root@polaris:~$ kubectl uncordon aries
# 省略

同じ手順を全てのワーカーノードに適用すると、アップグレードが完了します。

root@polaris:~$ kubectl get nodes
NAME      STATUS   ROLES           AGE    VERSION
aries     Ready    <none>          154d   v1.33.5
gemini    Ready    <none>          132d   v1.33.5
polaris   Ready    control-plane   154d   v1.33.5
taurus    Ready    <none>          154d   v1.33.5

まとめ

本記事では、オンプレミス環境に構築したKubernetesクラスタをkubeadmを用いて段階的にアップグレードする手順を紹介しました。

CNIプラグインとして利用しているCiliumについては、コントロールプレーンノードのアップグレード完了時点で、Kubernetes v1.33との互換性が保証されているv1.18へアップグレードするのが望ましいです。ただし今回は、以下の公式ドキュメントで必須となっているpre-flight checkに失敗したため、保留としました。

docs.cilium.io

その後、v1.33と同じ手順でv1.34へのアップグレードも完了させました。

root@polaris:~$ kubectl get nodes
NAME      STATUS   ROLES           AGE    VERSION
aries     Ready    <none>          154d   v1.34.1
gemini    Ready    <none>          132d   v1.34.1
polaris   Ready    control-plane   154d   v1.34.1
taurus    Ready    <none>          154d   v1.34.1

クラスタの規模は小さいにも関わらず想定以上に手間がかかり、アップグレード作業の大変さを実感しました。また、マネージドKubernetesの自動アップグレードの便利さも再確認できました。

小規模なクラスタではありましたが、実際に手を動かしてアップグレードを経験できたのは良い経験でした。