Kubernetes クラスター構築 – kubeadm で controlPlaneEndpoint と CNI を整理する

kubeadm を使って Kubernetes クラスターを構築します。この記事では、事前準備が完了した Ubuntu ノードを前提に、コントロールプレーンの初期化、CNI の導入、ワーカーノードの参加、確認までを整理します。

元の記事では、コントロールプレーンを将来的に冗長化できるように controlPlaneEndpoint にロードバランサーの VIP / FQDN を指定していました。この考え方は今でも重要です。単一 master から始める場合でも、API endpoint を固定しておくと後から構成を拡張しやすくなります。

構成の前提

• kubeadm を使って Kubernetes クラスターを構築する
• containerd が設定済みである
• swap は無効化済みである
• Pod CIDR と Service CIDR を事前に決めておく
• kube-proxy は IPVS モードを使う
• CNI は Calico を使う想定にする
• API endpoint はロードバランサーの FQDN を使う

ここで重要なのは、kubeadm init を単発コマンドとして実行するのではなく、設計値を kubeadm-config.yaml にまとめてから初期化することです。

kubeadm 設定ファイルを作成する

以下は Kubernetes 1.29 系を想定した kubeadm 設定例です。実際のバージョンに合わせて apiVersion や Kubernetes リポジトリのバージョンを確認してください。

mkdir -p ~/work/k8s
tee ~/work/k8s/kubeadm-config.yaml >/dev/null <<'EOF'
apiVersion: kubeadm.k8s.io/v1beta3
kind: ClusterConfiguration
clusterName: k8s-base-g01-cluster
kubernetesVersion: stable
controlPlaneEndpoint: k8s-base-g01-cluster.ext.s01.example.com:6443
networking:
  podSubnet: 10.244.0.0/16
  serviceSubnet: 10.96.0.0/12
  dnsDomain: cluster.local
---
apiVersion: kubeadm.k8s.io/v1beta3
kind: InitConfiguration
localAPIEndpoint:
  advertiseAddress: 10.1.0.10
  bindPort: 6443
nodeRegistration:
  kubeletExtraArgs:
    node-ip: 10.1.0.10
---
apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
cgroupDriver: systemd
---
apiVersion: kubeproxy.config.k8s.io/v1alpha1
kind: KubeProxyConfiguration
mode: ipvs
EOF

controlPlaneEndpoint には、コントロールプレーン API へ到達するための固定名を指定します。HAProxy などのロードバランサーを前段に置く場合は、その VIP / FQDN を指定します。

podSubnet と serviceSubnet は、既存ネットワークと重複しないように決めます。ここを後から変えるのは面倒なので、クラスター構築前に設計します。

コントロールプレーンを初期化する

設定ファイルを使って kubeadm init を実行します。

sudo kubeadm init --config ~/work/k8s/kubeadm-config.yaml --upload-certs

初期化に成功すると、kubeadm join 用のコマンドが表示されます。ワーカーノード追加用と、コントロールプレーン追加用のコマンドは意味が違うため、出力を分けて控えておきます。

kubectl を使えるようにする

初期化後、管理ユーザーで kubectl を使えるようにします。

mkdir -p ~/.kube
sudo cp /etc/kubernetes/admin.conf ~/.kube/config
sudo chown "$(id -u):$(id -g)" ~/.kube/config
kubectl get nodes

この時点では、CNI がまだ入っていないためノードは NotReady になることがあります。これは通常の流れです。

CNI をインストールする

Pod ネットワークを有効にするため、CNI を導入します。ここでは Calico を使う前提です。

kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.27.0/manifests/calico.yaml

Calico のバージョンやマニフェストは、利用する Kubernetes バージョンに合わせて確認します。Pod CIDR を独自に変更している場合は、Calico 側の CIDR 設定も合わせる必要があります。

kubectl get pods -n kube-system
kubectl get nodes

CNI Pod が起動し、ノードが Ready になれば、クラスターとして動き始めています。

ワーカーノードを追加する

ワーカーノードでは、コントロールプレーン初期化時に表示された kubeadm join コマンドを実行します。

sudo kubeadm join k8s-base-g01-cluster.ext.s01.example.com:6443 --token <token> --discovery-token-ca-cert-hash sha256:<hash>

トークンの有効期限が切れた場合は、コントロールプレーン側で再発行します。

kubeadm token create --print-join-command

追加後、コントロールプレーン側でノードを確認します。

kubectl get nodes -o wide

コントロールプレーンを追加する場合

コントロールプレーンを追加する場合は、--control-plane と証明書キーを含む join コマンドを使います。これはワーカーノード追加とは別物です。

sudo kubeadm join k8s-base-g01-cluster.ext.s01.example.com:6443 --token <token> --discovery-token-ca-cert-hash sha256:<hash> --control-plane --certificate-key <certificate-key>

単一ノード構成から始める場合でも、最初から controlPlaneEndpoint をロードバランサーに向けておくと、後からコントロールプレーンを増やしやすくなります。

状態を確認する

構築後は、ノード、Pod、Component、Service を確認します。

kubectl get nodes -o wide
kubectl get pods -A
kubectl get svc -A
kubectl cluster-info

問題がある場合は、kube-system の Pod 状態、CNI、kubelet、containerd、名前解決、時刻同期を順に確認します。

初期化し直す場合

検証環境でクラスターを作り直す場合は、kubeadm reset を使います。ただし、これはクラスター状態を壊す操作なので、本番環境では安易に実行しません。

sudo kubeadm reset
rm -rf ~/.kube

CNI の残骸や iptables / IPVS の状態が残ることもあります。検証で何度も作り直す場合は、クリーンな OS からやり直す方が原因切り分けは簡単です。

まとめ

kubeadm で Kubernetes クラスターを構築する場合、重要なのは kubeadm init のコマンドそのものではなく、事前に設計値を決めておくことです。API endpoint、Pod CIDR、Service CIDR、CNI、kube-proxy モード、ノード IP を曖昧にしたまま進めると、後から問題の原因が分かりにくくなります。

まず OS 側の前提を揃え、kubeadm-config.yaml に設計値をまとめ、コントロールプレーン初期化、CNI 導入、ノード参加、状態確認の順に進めます。この流れを守ると、単なるコマンド集ではなく、クラスター構築の構造として理解しやすくなります。

関連記事

• Ubuntu 22.04 Kubernetes クラスター構築の事前準備 – kubeadm ノードの前提を整える
• Ubuntu 22.04 Kubernetes 管理ツールのインストール – kubectl / Helm / calicoctl を整理する
• Ubuntu 22.04 HAProxy ロードバランサー – frontend / backend とヘルスチェック
• Ubuntu 22.04 Netplan ネットワーク設定 – DHCP / 固定 IP / DNS の基本
• Ubuntu 22.04 chrony の設定 – サーバー運用向けに時刻同期を管理する

Related posts:

Kubernetes クラスタの初期化 – kubeadm reset の基本 Ubuntu 22.04 Kubernetes クラスター構築の事前準備 – kubeadm ノードの前提を整える Ubuntu 22.04 Kubernetes 管理ツールのインストール – kubectl / Helm / calicoctl を整理する Ubuntu 22.04 Apache 基本構築 – VirtualHost と DocumentRoot を整理する Ubuntu 22.04 Samba 構築 – LDAP 認証と SID を整理する 古い Kubernetes クラスター構築メモ – kubeadm 手順を現在の記事へ読み替える Kubernetes Helmの導入 Kubernetes マニフェストを理解する apiVersion Kubernetes 1 つの Pod 内で複数の CentOS コンテナを実行する Kubernetes Nginx コンテナと Service ClusterIP Kubernetes を前提とした仮想 アーキテクチャの考察 Kubernetes コントロールプレーンノードを追加できない場合