Ubuntu 26.04 Kubernetes ワーカーノードの追加 – kubeadm join でクラスタへ参加する

Kubernetes のワーカーノードは、事前準備を済ませた Ubuntu 26.04 サーバーで kubeadm join を実行してクラスタへ参加させます。control plane の構築とは分けて、join 前の状態確認、短寿命 token の作成、参加後の node 状態確認を順番に扱うと安全です。

この記事では、/etc/kubernetes/kubelet.conf の有無で参加済みかを確認し、control plane 側で kubeadm token create --ttl 10m --print-join-command を実行して、ワーカーノードで kubeadm join する流れをまとめます。

worker node だけを対象にする

ワーカーノード追加は、control plane の初期化や再作成とは別の作業です。control plane ノードに対して誤って worker join の手順を適用しないように、対象ノードの役割を先に確認します。

hostname
kubeadm version -o short
systemctl status kubelet --no-pager

参加済みか確認する

/etc/kubernetes/kubelet.conf が存在する場合、そのノードはすでにクラスタへ参加済みの可能性があります。再 join の前に、既存状態を確認します。

sudo test -f /etc/kubernetes/kubelet.conf
sudo ls -l /etc/kubernetes/kubelet.conf
sudo systemctl status kubelet --no-pager

control plane 側で token を作成する

join command は control plane 側で作成します。短い TTL を指定して、使い終わった token が長く残らないようにします。

sudo kubeadm token create --ttl 10m --print-join-command

出力される command には token と discovery token CA cert hash が含まれます。短寿命でもクラスタ参加に使える情報なので、不要に共有したり、長期間ログへ残したりしないように扱います。

worker node で kubeadm join を実行する

control plane で生成された join command を、対象の worker node で実行します。

sudo kubeadm join k8s-api.example.com:6443 --token abcdef.0123456789abcdef --discovery-token-ca-cert-hash sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

kubelet の状態を確認する

join 後は worker node 側で kubelet の状態を確認します。CNI や control plane との疎通に問題がある場合、ここでエラーが出ます。

sudo systemctl status kubelet --no-pager
sudo journalctl -u kubelet -n 80 --no-pager
sudo crictl info

control plane 側で node を確認する

control plane 側の kubeconfig を使って、追加した worker node が表示されるか確認します。CNI 導入前後や network plugin の状態によって、最初は NotReady になる場合があります。

kubectl get nodes -o wide
kubectl describe node worker-node-name
kubectl get pods -A -o wide

token の状態を確認する

必要に応じて、control plane 側で token の一覧を確認します。TTL を短くしている場合、時間経過で token は使えなくなります。

sudo kubeadm token list
sudo kubeadm token delete abcdef

よくある確認ポイント

トラブル時の切り分け

join が失敗する場合は、token、CA hash、API endpoint、firewall、時刻同期、container runtime、kubelet の順に確認します。

timedatectl
nc -vz k8s-api.example.com 6443
sudo kubeadm token list
sudo journalctl -u kubelet -n 120 --no-pager
sudo crictl ps -a

まとめ

Ubuntu 26.04 の Kubernetes ワーカーノード追加では、kubeadm join を実行する前に、対象が worker node であること、/etc/kubernetes/kubelet.conf が存在しないこと、control plane へ到達できることを確認します。

join command は control plane 側で短寿命 token として作成し、worker node で実行します。参加後は worker node 側の kubelet と、control plane 側の kubectl get nodes の両方で状態を確認します。

関連記事

Ubuntu 26.04 Kubernetes コントロールプレーンの構築 – kubeadm init と dual-stack を扱う Ubuntu 26.04 Kubernetes ノードの事前準備 – kubelet / kubeadm とAPTリポジトリを構成する Ubuntu 22.04 Kubernetes クラスター構築の事前準備 – kubeadm ノードの前提を確認する Ubuntu 26.04 containerd の基本設定 – Kubernetes 用 CRI runtime を構成する Ubuntu 26.04 MicroK8s の基本設定 – snap で単体 Kubernetes を構成する Ubuntu 26.04 kubeconfig の基本設定 – kubectl の context と複数クラスタを管理する Ubuntu 22.04 containerd の設定 – Kubernetes ノード向けに SystemdCgroup を有効化する Ubuntu 26.04 swap の無効化 – swapoff と fstab で永続停止する