Ubuntu 26.04 Kubernetes コントロールプレーンの構築 – kubeadm init と dual-stack を扱う

Kubernetes コントロールプレーンを kubeadm で構築するときは、kubeadm init のコマンドだけでなく、API endpoint、node-ip、Pod / Service CIDR、kubelet の cgroup driver、kube-proxy mode を事前に決めておく必要があります。

この記事では、Ubuntu 26.04 で kubeadm-config.yaml を用意し、kubeadm init --config ... --upload-certs で初回の control plane を作成し、/etc/kubernetes/admin.conf を管理ユーザーの kubeconfig として配置する流れをまとめます。

既存 control plane を壊さない

既存の /etc/kubernetes/admin.conf があるノードでは、すでに control plane が初期化済みの可能性があります。再作成や reset は別作業として扱い、初期化処理と混ぜない方が安全です。

sudo test -f /etc/kubernetes/admin.conf
sudo ls -l /etc/kubernetes/admin.conf
sudo kubeadm version -o short

kubeadm-config.yaml を用意する

kubeadm-config.yaml には、InitConfiguration、ClusterConfiguration、KubeletConfiguration、KubeProxyConfiguration を分けて書きます。

apiVersion: kubeadm.k8s.io/v1beta4
kind: InitConfiguration
localAPIEndpoint:
  advertiseAddress: "10.0.0.10"
  bindPort: 6443
nodeRegistration:
  kubeletExtraArgs:
  - name: node-ip
  value: "10.0.0.10,fd00:10::10"
---
apiVersion: kubeadm.k8s.io/v1beta4
kind: ClusterConfiguration
clusterName: "k8s.example.com"
controlPlaneEndpoint: "k8s-api.example.com:6443"
networking:
  podSubnet: "10.244.0.0/16,fd00:244::/56"
  serviceSubnet: "10.96.0.0/12,fd00:96::/112"
---
apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
cgroupDriver: "systemd"
---
apiVersion: kubeproxy.config.k8s.io/v1alpha1
kind: KubeProxyConfiguration
mode: "ipvs"

node-ip を明示する

複数 NIC や dual-stack のノードでは、kubelet が意図しないアドレスを node address として選ぶことがあります。node-ip で IPv4 と IPv6 を明示しておくと、クラスタ内部の見え方をそろえやすくなります。

ip address
ip route
grep -n "node-ip" kubeadm-config.yaml

Pod / Service CIDR を決める

Pod subnet と Service subnet は、既存ネットワーク、VPN、拠点間経路、ロードバランサー用アドレス帯と衝突しないように決めます。dual-stack の場合は IPv4 と IPv6 の両方を指定します。

grep -n "podSubnet" kubeadm-config.yaml
grep -n "serviceSubnet" kubeadm-config.yaml
ip route get 10.244.0.1
ip -6 route get fd00:244::1

kubeadm init を実行する

初回構築では、設定ファイルを指定して kubeadm init を実行します。--upload-certs を付けると、control plane 追加時に必要な証明書共有の準備ができます。

sudo kubeadm init --config kubeadm-config.yaml --upload-certs

admin.conf を配置する

初期化が成功すると /etc/kubernetes/admin.conf が作成されます。管理ユーザーで kubectl を使えるように、~/.kube/config へ配置します。

install -d -m 0700 "$HOME/.kube"
sudo install -o "$USER" -g "$USER" -m 0600 /etc/kubernetes/admin.conf "$HOME/.kube/config"
kubectl config current-context
kubectl get nodes -o wide

コントロールプレーンの状態を確認する

初期化直後は CNI が入るまで node が NotReady になることがあります。API server、controller-manager、scheduler、etcd の static Pod と、node 状態を確認します。

sudo crictl ps | grep -E 'kube-apiserver|kube-controller-manager|kube-scheduler|etcd'
kubectl get nodes -o wide
kubectl get pods -A
kubectl cluster-info

CNI 導入前後を分けて見る

kubeadm は control plane の土台を作りますが、Pod network は CNI 側の責務です。Calico などを導入する前後で、node readiness と CoreDNS の状態を分けて確認します。

kubectl get nodes
kubectl get pods -n kube-system -o wide
kubectl describe node "$(hostname)" | grep -A5 -E 'Conditions|NetworkUnavailable'

確認ポイント

まとめ

Ubuntu 26.04 で Kubernetes コントロールプレーンを構築する場合、kubeadm init を単発コマンドとして実行するより、kubeadm-config.yaml に API endpoint、node-ip、Pod / Service CIDR、cgroup driver、kube-proxy mode を明示する方が再現性を高めやすくなります。

また、既存 control plane の reset と初回構築は分けて扱います。/etc/kubernetes/admin.conf の有無を確認し、初期化後は管理ユーザーの ~/.kube/config を安全な権限で配置してから、node、static Pod、CNI 導入前後の状態を確認します。

関連記事

Ubuntu 26.04 Kubernetes ワーカーノードの追加 – kubeadm join でクラスタへ参加する Ubuntu 26.04 Kubernetes ノードの事前準備 – kubelet / kubeadm とAPTリポジトリを構成する Ubuntu 26.04 VLAN の基本設定 – Netplan で tagged VLAN を扱う Ubuntu 22.04 Kubernetes クラスター構築の事前準備 – kubeadm ノードの前提を確認する Ubuntu 26.04 kubeconfig の基本設定 – kubectl の context と複数クラスタを管理する Ubuntu 26.04 MicroK8s の基本設定 – snap で単体 Kubernetes を構成する Ubuntu 26.04 containerd の基本設定 – Kubernetes 用 CRI runtime を構成する Ubuntu 22.04 Kubernetes 管理ツールのインストール – kubectl / Helm / calicoctl の使い分け