Cluster API 徹底解説 — クラスタを Kubernetes リソースとして管理する

+----------------------------------------------------------------------+
|                      Management Cluster                              |
|                                                                      |
|  +----------------+  +----------------+  +------------------------+  |
|  | CAPI Core      |  | Bootstrap      |  | Control Plane          |  |
|  | Controller     |  | Provider       |  | Provider               |  |
|  | (Cluster,      |  | (CABPK:        |  | (KCP: KubeadmControl-  |  |
|  |  Machine, MS,  |  |  KubeadmConfig)|  |  Plane controller)     |  |
|  |  MD, MHC)      |  +----------------+  +------------------------+  |
|  +----------------+                                                  |
|  +-------------------------------+                                   |
|  | Infrastructure Provider       |   etcd に保存された宣言:           |
|  | (CAPA/CAPZ/CAPV/CAPD/Metal3)  |   Cluster, MachineDeployment,     |
|  +-------------------------------+   KubeadmControlPlane ...         |
+----------------------------------------------------------------------+
        |                        |                          |
        | プロビジョニング/reconcile|                          |
        v                        v                          v
+----------------+      +----------------+        +----------------+
| Workload       |      | Workload       |        | Workload       |
| Cluster A      |      | Cluster B      |        | Cluster C      |
| (prod-seoul)   |      | (prod-tokyo)   |        | (edge-store-7) |
+----------------+      +----------------+        +----------------+

                         +-----------+
                         |  Cluster  |  クラスタ全体の傘リソース
                         +-----+-----+
                               |
            +------------------+-------------------+
            | controlPlaneRef                      | infrastructureRef
            v                                      v
 +----------------------+              +---------------------------+
 | KubeadmControlPlane  |              | (Infra)Cluster            |
 | (replicas, version)  |              | 例: DockerCluster,        |
 +----------+-----------+              |     AWSCluster: VPC/LB等  |
            |                          +---------------------------+
            | 作成/管理
            v
       +---------+     1:1      +------------------------+
       | Machine |------------- | (Infra)Machine         |
       +---------+              | 例: DockerMachine,     |
            ^                   |     AWSMachine: VM     |
            |                   +------------------------+
            |  作成                      ^ 1:1
   +--------+-------+                   |
   |   MachineSet   | <-- テンプレート参照: (Infra)MachineTemplate
   +--------+-------+                    KubeadmConfigTemplate
            ^
            | 作成/ローリング交換
   +--------+----------------+         +---------------------+
   |   MachineDeployment     |         | MachineHealthCheck  |
   |  (replicas, version,    |         |  異常マシンの検知 →   |
   |   rolling strategy)     |         |  remediation(交換)  |
   +-------------------------+         +---------------------+

# CAPD が Docker ソケットを使えるように kind クラスタを作成
cat > kind-mgmt.yaml <<EOF
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
name: capi-mgmt
nodes:
  - role: control-plane
    extraMounts:
      - hostPath: /var/run/docker.sock
        containerPath: /var/run/docker.sock
EOF
kind create cluster --config kind-mgmt.yaml

# ClusterClass 機能を有効化してから CAPI + CAPD をインストール
export CLUSTER_TOPOLOGY=true
clusterctl init --infrastructure docker

kubectl get pods -A | grep -E "capi|capd|cert-manager"
# capd-system / capi-kubeadm-bootstrap-system /
# capi-kubeadm-control-plane-system / capi-system が Running なら正常

# dev-cluster-01.yaml — Cluster: 最上位の傘
apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
metadata:
  name: dev-cluster-01
  namespace: default
  labels:
    env: dev
    region: local
spec:
  clusterNetwork:
    pods:
      cidrBlocks: ["192.168.0.0/16"]
    serviceDomain: cluster.local
  controlPlaneRef:
    apiVersion: controlplane.cluster.x-k8s.io/v1beta1
    kind: KubeadmControlPlane
    name: dev-cluster-01-cp
  infrastructureRef:
    apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
    kind: DockerCluster
    name: dev-cluster-01
---
# インフラクラスタ: CAPD では LB コンテナなどを表現
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: DockerCluster
metadata:
  name: dev-cluster-01
  namespace: default
---
# コントロールプレーンマシンのインフラテンプレート
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: DockerMachineTemplate
metadata:
  name: dev-cluster-01-cp
  namespace: default
spec:
  template:
    spec:
      extraMounts:
        - containerPath: /var/run/docker.sock
          hostPath: /var/run/docker.sock
---
# KubeadmControlPlane: コントロールプレーンの宣言
apiVersion: controlplane.cluster.x-k8s.io/v1beta1
kind: KubeadmControlPlane
metadata:
  name: dev-cluster-01-cp
  namespace: default
spec:
  replicas: 1
  version: v1.31.4
  machineTemplate:
    infrastructureRef:
      apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
      kind: DockerMachineTemplate
      name: dev-cluster-01-cp
  kubeadmConfigSpec:
    clusterConfiguration:
      apiServer:
        certSANs: [localhost, 127.0.0.1, 0.0.0.0, host.docker.internal]
    initConfiguration:
      nodeRegistration:
        criSocket: unix:///var/run/containerd/containerd.sock
    joinConfiguration:
      nodeRegistration:
        criSocket: unix:///var/run/containerd/containerd.sock
---
# ワーカーマシンのインフラテンプレート
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: DockerMachineTemplate
metadata:
  name: dev-cluster-01-md-0
  namespace: default
spec:
  template:
    spec: {}
---
# ワーカーマシンのブートストラップ(join)設定テンプレート
apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
kind: KubeadmConfigTemplate
metadata:
  name: dev-cluster-01-md-0
  namespace: default
spec:
  template:
    spec:
      joinConfiguration:
        nodeRegistration:
          criSocket: unix:///var/run/containerd/containerd.sock
---
# MachineDeployment: ワーカープールの宣言
apiVersion: cluster.x-k8s.io/v1beta1
kind: MachineDeployment
metadata:
  name: dev-cluster-01-md-0
  namespace: default
spec:
  clusterName: dev-cluster-01
  replicas: 2
  selector:
    matchLabels: null
  template:
    spec:
      clusterName: dev-cluster-01
      version: v1.31.4
      bootstrap:
        configRef:
          apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
          kind: KubeadmConfigTemplate
          name: dev-cluster-01-md-0
      infrastructureRef:
        apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
        kind: DockerMachineTemplate
        name: dev-cluster-01-md-0

kubectl apply -f dev-cluster-01.yaml

# ツリー形式で全体の状態を見る(最も有用なコマンド)
clusterctl describe cluster dev-cluster-01

# 個別リソースの追跡
kubectl get cluster,machinedeployment,machineset,machine
kubectl get kubeadmcontrolplane
docker ps   # CAPD が作った「マシン」コンテナが見えます

clusterctl get kubeconfig dev-cluster-01 > dev-01.kubeconfig

kubectl --kubeconfig dev-01.kubeconfig get nodes
# STATUS NotReady — CNI インストール前なので正常

# Calico のインストール (Cilium、Flannel など何でも可)
kubectl --kubeconfig dev-01.kubeconfig apply -f \
  https://raw.githubusercontent.com/projectcalico/calico/v3.29.1/manifests/calico.yaml

kubectl --kubeconfig dev-01.kubeconfig get nodes
# しばらくすると全ノード Ready

# コントロールプレーンのアップグレード: KCP の version のみ変更
kubectl patch kubeadmcontrolplane dev-cluster-01-cp --type merge \
  -p '{"spec":{"version":"v1.32.2"}}'

# ワーカーのアップグレード: MachineDeployment の version を変更
kubectl patch machinedeployment dev-cluster-01-md-0 --type merge \
  -p '{"spec":{"template":{"spec":{"version":"v1.32.2"}}}}'

KCP アップグレード (replicas=3 の場合)
 1. 新しい v1.32 コントロールプレーンマシンを 1 台作成 (計 4 台)
 2. kubeadm join --control-plane で合流、etcd メンバー 4
 3. 古い v1.31 マシンを 1 台選択 → etcd member remove → drain → 削除 (計 3 台)
 4. 古いマシンがなくなるまで 1〜3 を繰り返し
 5. クォーラムは常に維持: 3 → 4 → 3 → 4 → 3

MachineDeployment アップグレード (RollingUpdate 戦略)
 1. 新バージョンの MachineSet を作成
 2. maxSurge/maxUnavailable に従って新マシンを追加、古いマシンを drain して削除
 3. 古い MachineSet の replicas が 0 になるまで繰り返し

# ワーカー 2 台 → 5 台
kubectl scale machinedeployment dev-cluster-01-md-0 --replicas=5

# コントロールプレーン 1 台 → 3 台 (HA への移行)
kubectl scale kubeadmcontrolplane dev-cluster-01-cp --replicas=3

apiVersion: cluster.x-k8s.io/v1beta1
kind: MachineHealthCheck
metadata:
  name: dev-cluster-01-worker-mhc
  namespace: default
spec:
  clusterName: dev-cluster-01
  # 一度に多くのマシンを交換しすぎないための安全弁
  maxUnhealthy: 40%
  # 起動後この時間内にノードとして合流できなければ異常
  nodeStartupTimeout: 10m
  selector:
    matchLabels:
      cluster.x-k8s.io/deployment-name: dev-cluster-01-md-0
  unhealthyConditions:
    - type: Ready
      status: Unknown
      timeout: 300s
    - type: Ready
      status: "False"
      timeout: 300s

apiVersion: cluster.x-k8s.io/v1beta1
kind: ClusterClass
metadata:
  name: standard-dev
  namespace: default
spec:
  controlPlane:
    ref:
      apiVersion: controlplane.cluster.x-k8s.io/v1beta1
      kind: KubeadmControlPlaneTemplate
      name: standard-dev-cp
    machineInfrastructure:
      ref:
        apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
        kind: DockerMachineTemplate
        name: standard-dev-cp-machine
  infrastructure:
    ref:
      apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
      kind: DockerClusterTemplate
      name: standard-dev-infra
  workers:
    machineDeployments:
      - class: default-worker
        template:
          bootstrap:
            ref:
              apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
              kind: KubeadmConfigTemplate
              name: standard-dev-worker-bootstrap
          infrastructure:
            ref:
              apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
              kind: DockerMachineTemplate
              name: standard-dev-worker-machine
  variables:
    - name: workerReplicas
      required: true
      schema:
        openAPIV3Schema:
          type: integer
          default: 2

apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
metadata:
  name: dev-cluster-02
  namespace: default
spec:
  clusterNetwork:
    pods:
      cidrBlocks: ["192.168.0.0/16"]
  topology:
    class: standard-dev
    version: v1.31.4
    controlPlane:
      replicas: 1
    workers:
      machineDeployments:
        - class: default-worker
          name: md-0
          replicas: 3
    variables:
      - name: workerReplicas
        value: 3

git clone https://github.com/kubernetes-sigs/image-builder.git
cd image-builder/images/capi
# 例: vSphere 向け Ubuntu 22.04 + K8s v1.31 の OVA をビルド
make build-node-ova-vsphere-ubuntu-2204

+-----------+     push      +-----------+     sync      +---------------------+
| Platform  | ------------> |    Git    | ------------> | Management Cluster  |
| Team      |   PR レビュー  |  fleet-   |  Argo CD /    |  CAPI コントローラが  |
|           |               |  repo     |  Flux         |  reconcile          |
+-----------+               +-----------+               +----------+----------+
                                                                   |
                                              作成/アップグレード/復旧 v
                                              +---------------------------+
                                              | Workload Clusters (フリート)|
                                              +---------------------------+

fleet-repo/
├── clusterclasses/
│   ├── standard-prod.yaml
│   └── standard-edge.yaml
├── clusters/
│   ├── prod/
│   │   ├── prod-seoul-01.yaml      # topology ベースの薄い宣言
│   │   └── prod-tokyo-01.yaml
│   ├── stage/
│   │   └── stage-seoul-01.yaml
│   └── edge/
│       ├── store-0001.yaml
│       └── store-0002.yaml
└── addons/
    ├── cni/                        # 新規クラスタに入る基本アドオン
    └── monitoring/

ネーミング規則の例: <用途>-<リージョン>-<連番>
  prod-seoul-01, stage-tokyo-01, edge-store-0042

推奨ラベル (Cluster リソースに付与):
  env: prod | stage | dev
  region: seoul | tokyo | ...
  tier: core | edge
  team: payments | search | ...
  upgrade-wave: "1" | "2" | "3"   # アップグレードの波を制御

# 新クラスタにプロバイダをインストールしてからリソースを移行
clusterctl init --kubeconfig mgmt-real.kubeconfig --infrastructure aws
clusterctl move --to-kubeconfig mgmt-real.kubeconfig

アップグレード順序 (上から下へ)
 1. management cluster の Kubernetes バージョン
    (CAPI リリースがサポートする範囲を確認)
 2. clusterctl バイナリ
 3. CAPI コア + プロバイダ:  clusterctl upgrade plan / apply
 4. ワークロードクラスタ群の K8s バージョン (wave 単位でローリング)
    - 各クラスタ内部: コントロールプレーン → ワーカー
    - マイナーバージョンの飛び越え禁止 (1.30 → 1.32 は不可、1.31 経由)

質問 1. 管理するクラスタが 5 個未満で増える計画もない
  → CAPI は過剰。マネージド K8s + IaC で十分。

質問 2. クラスタが 10 個以上、またはテナント/エッジで増える予定
  → CAPI の有力候補。特にクラスタ作成をセルフサービス化したいなら。

質問 3. オンプレミス (vSphere/ベアメタル) やマルチクラウドが混在
  → CAPI の最も強いユースケース。単一宣言モデルの価値が最大化。

質問 4. チームに K8s コントローラ/CRD の運用経験があるか
  → なければ、まず小さな規模 (CAPD 実習、dev クラスタ) で筋肉をつける。

質問 5. プラットフォームチームが存在するか
  → CAPI はプラットフォームチームの道具。専任のオーナーがいなければ放置されて腐ります。

# 1. 全体像: どこで止まったかツリーで確認
clusterctl describe cluster dev-cluster-01 --show-conditions all

# 2. Machine の conditions とイベント
kubectl describe machine dev-cluster-01-md-0-xxxxx
kubectl get events --field-selector involvedObject.kind=Machine

# 3. インフラマシン (プロバイダ側) の状態 — VM は実際に起動したか
kubectl describe dockermachine dev-cluster-01-md-0-xxxxx
# AWS なら: kubectl describe awsmachine ...

# 4. ブートストラップシークレットは作られたか (cloud-init データ)
kubectl get secret | grep dev-cluster-01-md-0

# 5. コントローラログ — レイヤごとに
kubectl logs -n capi-system deploy/capi-controller-manager
kubectl logs -n capi-kubeadm-bootstrap-system \
  deploy/capi-kubeadm-bootstrap-controller-manager
kubectl logs -n capi-kubeadm-control-plane-system \
  deploy/capi-kubeadm-control-plane-controller-manager
kubectl logs -n capd-system deploy/capd-controller-manager

# 6. マシン内の cloud-init ログ (インフラごとにアクセス方法が異なる)
# CAPD: docker exec でコンテナに入って
#   cat /var/log/cloud-init-output.log  (または journalctl -u kubelet)

[ ] 管理対象クラスタ数/増加計画が CAPI 導入を正当化するか
[ ] インフラプロバイダ (CAPA/CAPV/Metal3 など) の成熟度を検証したか
[ ] CAPD ベースのローカル実習でチーム全員が全フローを体験したか
[ ] ゴールデンイメージのパイプライン (image-builder) を構築したか
[ ] ClusterClass で標準クラスタ形状をテンプレート化したか
[ ] MachineHealthCheck の maxUnhealthy 安全弁を設定したか
[ ] GitOps リポジトリ構成と PR レビューポリシーを定義したか
[ ] ネーミング/ラベル/アップグレード wave 戦略を文書化したか
[ ] management cluster のバックアップ (Velero など) と復旧リハーサルを完了したか
[ ] clusterctl upgrade plan に基づく定期アップグレードカレンダーがあるか
[ ] マシン停止のトラブルシューティング・ランブックを作成したか
[ ] PDB/nodeDrainTimeout ポリシーをワークロードチームと合意したか