Cluster API 딥다이브 — 클러스터를 쿠버네티스 리소스로 관리하다

+----------------------------------------------------------------------+
|                      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)  |              | e.g. DockerCluster,       |
 +----------+-----------+              |      AWSCluster: VPC/LB등 |
            |                          +---------------------------+
            | 생성/관리
            v
       +---------+     1:1      +------------------------+
       | Machine |------------- | (Infra)Machine         |
       +---------+              | e.g. 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. 항상 quorum 유지: 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/

네이밍 규칙 예: <용도>-<리전>-<일련번호>  (프로스가 아닌 규칙 문서엔 OK)
  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의 쿠버네티스 버전
    (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 정책을 워크로드 팀과 합의했는가