[인프라] ClusterAPI 도입으로 온프레미스 자동화 성공하기

온프레미스 Kubernetes 환경을 오래 운영하다 보면 결국 같은 고민을 하게 됩니다. 클러스터 하나 만들 때마다 문서 열고, kubeadm 옵션 다시 확인하고, 네트워크랑 인증서 맞추고, 노드 추가할 때마다 사람 손이 들어가죠. 저도 그랬습니다. 그래서 이번 글에서는 제가 실제로 정리해 본 ClusterAPI 도입 사례를 중심으로, 온프레미스 Kubernetes 환경에서 클러스터 생성과 확장을 어떻게 자동화했는지 풀어보려고 합니다. 특히 여러 팀이 같은 기준으로 클러스터를 만들고 싶을 때, 이 접근이 왜 먹히는지 말씀드릴게요.

처음엔 솔직히 이게 뭔가 싶었어요. Kubernetes 자체도 복잡한데 관리 클러스터까지 따로 둔다니 더 어려워 보였거든요. 근데 한 번 구조가 잡히고 나니까, “아 이건 사람 손을 줄이기 위한 운영 도구구나” 싶더라고요. 혹시 지금도 새 클러스터 만들 때마다 체크리스트부터 찾고 계신다면, 여기서 중요한 포인트를 같이 보시면 됩니다.

Management Cluster(관리 클러스터), Workload Cluster(운영 클러스터), 인프라 제공자와 GitOps 흐름을 한눈에 보여주는 아키텍처 이미지입니다.

1. ClusterAPI란 무엇인가요?

Cluster API(CAPI, 클러스터 수명주기 관리 프로젝트)를 쉽게 말하면, Kubernetes 방식으로 Kubernetes 클러스터를 만드는 도구예요. Deployment(디플로이먼트)를 선언적으로 관리하듯이, 클러스터 자체를 YAML로 선언하고 생성, 확장, 업그레이드까지 다루는 거죠.

핵심은 세 가지입니다.

• Management Cluster: 다른 클러스터를 생성하고 관리하는 기준 클러스터입니다.
• Workload Cluster: 실제 애플리케이션이 올라가는 대상 클러스터입니다.
• Provider: vSphere(브이스피어, 가상화 플랫폼), OpenStack(오픈스택, 프라이빗 클라우드 플랫폼), Bare Metal(베어메탈, 물리 서버) 같은 인프라와 연결해 주는 구성입니다.

제가 직접 해보니 중요한 건 “클러스터 생성 절차를 코드로 옮긴다”는 점이었어요. 이게 되면 담당자가 바뀌어도 운영 방식이 흔들리지 않거든요. ClusterAPI 도입 사례가 주목받는 이유도 결국 여기 있습니다.

2. 왜 온프레미스 Kubernetes 자동화에 잘 맞았나

클라우드는 원래 API가 잘 되어 있어서 자동화가 비교적 쉬워요. 반면 온프레미스는 가상화 플랫폼, 네트워크, IP 할당 정책, 이미지 관리, 인증서 처리까지 다 제각각인 경우가 많습니다. 그래서 클러스터 자동화가 더 절실한데, 아이러니하게도 더 어렵죠.

제가 보기에 Cluster API가 온프레미스에서 특히 좋았던 이유는 아래와 같았습니다.

특히 여러 환경을 동시에 굴릴 때 차이가 컸어요. 개발, 스테이징, 운영이 따로 있으면 사람이 일일이 맞추다가 꼭 어긋나거든요. 반면 CAPI 구축을 해두면 템플릿 하나에서 변수만 바꿔 환경을 복제할 수 있어서 훨씬 안정적이었습니다.

3. 제가 잡았던 목표와 설계 기준

이번 ClusterAPI 도입 사례에서 제가 세운 기준은 과하지 않게 명확했어요.

1. 클러스터 생성 절차를 문서가 아니라 Git 저장소 기준으로 관리할 것
2. Control Plane(컨트롤 플레인, 클러스터 제어 영역)과 Worker Node(워커 노드, 실제 워크로드 실행 서버) 확장을 분리할 것
3. 온프레미스 Kubernetes 환경에서도 동일한 템플릿을 재사용할 것
4. 장애가 나더라도 다시 만들 수 있는 구조를 우선할 것

여기서 중요한 포인트는 “처음부터 모든 걸 자동화하려고 하지 않는다”는 점이에요. 저도 처음엔 네트워크, 스토리지, 로드밸런서까지 한 번에 묶으려다가 삽질 좀 했습니다 ㅎㅎ 결국 성공한 방식은 클러스터 수명주기부터 먼저 자동화하고, 그 다음에 GitOps와 운영 도구를 붙이는 순서였어요.

4. CAPI 구축 전 준비: Management Cluster부터 정리

실전 구현은 예시로 vSphere 기반 온프레미스 환경을 기준으로 설명드릴게요. 다만 구조 자체는 다른 인프라 제공자에도 비슷하게 적용됩니다. 준비 단계에서 필요한 건 대략 이 정도입니다.

• kubectl(쿠버네티스 CLI), clusterctl(Cluster API CLI)
• 부트스트랩용 Kubernetes 클러스터 1개
• vSphere API 접근 정보 또는 사용하는 온프레미스 인프라 자격 정보
• 템플릿에서 참조할 VM 이미지와 네트워크 정책
• 로드밸런서 또는 API 서버 엔드포인트 전략

저는 먼저 management cluster를 아주 작게 올리고, 여기에 Cluster API Controller(컨트롤러, 상태를 맞추는 구성요소)를 설치했어요. 이 관리 클러스터가 있어야 이후 workload cluster를 선언형으로 찍어낼 수 있거든요.

export CLUSTER_TOPOLOGY=true
export EXP_CLUSTER_RESOURCE_SET=true

clusterctl init --infrastructure vsphere
clusterctl version
kubectl get pods -A

이 단계에서 pod가 전부 Running 상태로 올라오는지 꼭 확인하셔야 합니다. 컨트롤러가 불안정하면 뒤 단계에서 증상이 꼬여서 원인 파악이 더 어려워져요.

5. 실전 구현: 온프레미스 Kubernetes 클러스터 자동화 흐름

이제 본격적으로 CAPI 구축을 진행합니다. 제 경험상 아래 순서가 가장 덜 꼬였습니다.

1. 클러스터 템플릿 생성
2. 환경 변수 주입
3. 매니페스트 검토
4. 적용 후 상태 확인
5. 노드 확장 및 업그레이드 테스트

export VSPHERE_SERVER=vc.example.local
export VSPHERE_USERNAME=svc_clusterapi
export VSPHERE_PASSWORD='change-me'
export VSPHERE_DATACENTER=DC1
export VSPHERE_DATASTORE=datastore01
export VSPHERE_NETWORK=VM_Network
export VSPHERE_RESOURCE_POOL=/DC1/host/Cluster/Resources
export VSPHERE_FOLDER=/DC1/vm/k8s
export VSPHERE_TEMPLATE=ubuntu-k8s-template
export KUBERNETES_VERSION=v1.29.0
export CONTROL_PLANE_MACHINE_COUNT=3
export WORKER_MACHINE_COUNT=3
export CLUSTER_NAME=onprem-prod-01

clusterctl generate cluster ${CLUSTER_NAME} \
  --kubernetes-version ${KUBERNETES_VERSION} \
  --control-plane-machine-count=${CONTROL_PLANE_MACHINE_COUNT} \
  --worker-machine-count=${WORKER_MACHINE_COUNT} \
  > ${CLUSTER_NAME}.yaml

생성된 YAML은 바로 적용하지 말고 한 번 읽어보시는 걸 권장합니다. 처음엔 귀찮아 보여도, 여기서 네트워크 이름이나 템플릿 참조가 틀린 걸 많이 잡더라고요.

clusterctl로 템플릿을 생성하고, management cluster에서 이를 해석해 workload cluster를 만드는 흐름을 설명하는 이미지입니다.

apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
metadata:
  name: onprem-prod-01
spec:
  clusterNetwork:
    pods:
      cidrBlocks:
        - 192.168.0.0/16
    services:
      cidrBlocks:
        - 10.96.0.0/12
  controlPlaneRef:
    apiVersion: controlplane.cluster.x-k8s.io/v1beta1
    kind: KubeadmControlPlane
    name: onprem-prod-01-control-plane
  infrastructureRef:
    apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
    kind: VSphereCluster
    name: onprem-prod-01

kubectl apply -f onprem-prod-01.yaml
kubectl get cluster
kubectl get machines
kubectl get kubeadmcontrolplane
kubectl describe cluster onprem-prod-01

여기서 진짜 편한 점이 나와요. 워커 노드 늘릴 때도 별도 설치 문서가 아니라 replica 값을 조정하는 식으로 접근하게 되거든요. 사람이 SSH 들어가서 하나씩 붙이는 방식에서 벗어나는 거죠.

apiVersion: cluster.x-k8s.io/v1beta1
kind: MachineDeployment
metadata:
  name: onprem-prod-01-md-0
spec:
  replicas: 5

이런 식으로 선언 상태를 바꾸면 컨트롤러가 맞춰 줘요. 실제로 써보니까 운영자가 해야 할 일이 “절차 수행”에서 “원하는 상태 정의”로 바뀌더라고요.

6. ⚠️ 트러블슈팅: 제가 실제로 막혔던 지점들

자동화라고 해서 처음부터 매끈하진 않았어요. 오히려 수동 설치보다 어디서 실패했는지 감이 안 잡혀서 더 답답할 때도 있었죠. 특히 아래 세 가지는 자주 만났습니다.

6-1. VM은 생성됐는데 Kubernetes 노드로 안 붙는 문제

이건 대부분 템플릿 이미지 문제였어요. cloud-init(클라우드 이닛, 초기 설정 자동화) 또는 kubeadm bootstrap 과정이 템플릿과 안 맞는 경우가 있더라고요. 저는 골든 이미지 재생성 후 해결했습니다.

kubectl get kubeadmconfigs
kubectl describe machine <machine-name>
kubectl logs -n capv-system deployment/capv-controller-manager

6-2. API 엔드포인트는 열렸는데 Control Plane이 Ready로 안 가는 문제

로드밸런서 health check 조건과 kube-apiserver 준비 상태가 안 맞으면 이런 현상이 생겨요. 겉으로는 포트가 열려 보여도 Cluster API 쪽에서는 준비가 덜 된 걸로 판단할 수 있습니다.

6-3. 머신 삭제가 느리거나 걸리는 문제

finalizer(파이널라이저, 정리 작업 보장 메커니즘)와 인프라 자원 정리가 꼬일 때가 있어요. 이때는 무작정 리소스부터 지우지 말고, 어떤 컨트롤러가 막고 있는지 이벤트를 먼저 봐야 합니다.

• ⚠️ 경고: 수동으로 VM만 먼저 삭제하면 CAPI 상태와 실제 인프라 상태가 어긋날 수 있습니다.
• 💡 팁: 문제 상황은 이벤트, controller log, Machine 상태를 함께 봐야 빨리 풀려요.
• 💡 팁: 운영 전 테스트 환경에서 scale-out, scale-in, control plane 교체를 꼭 해보세요.

저도 처음엔 “왜 선언형인데 선언대로 안 되지?” 싶었는데, 결국 선언형도 기반 인프라와 부트스트랩 준비가 맞아야 돌아가더라고요. 이건 정말 직접 해봐야 감이 와요.

7. 검증과 결과: 운영 방식이 어떻게 달라졌나

검증은 단순히 클러스터가 떠 있느냐만 보면 부족합니다. 저는 아래 순서로 확인했어요.

1. Control Plane 3대가 정상 Ready 상태인지 확인
2. Worker Node 증설/축소가 선언대로 반영되는지 확인
3. kubeconfig 추출 후 실제 워크로드 배포 테스트
4. 클러스터 재생성 시 동일한 결과가 나오는지 확인

clusterctl get kubeconfig onprem-prod-01 > onprem-prod-01.kubeconfig
export KUBECONFIG=$(pwd)/onprem-prod-01.kubeconfig
kubectl get nodes
kubectl create deployment nginx --image=nginx
kubectl get pods -o wide

이 검증이 끝나고 나면 체감이 확 와요. 새 환경이 필요할 때 “며칠 잡아야 하나”가 아니라 “템플릿 변수 뭘 바꿔야 하나”로 대화가 바뀌거든요. 이게 제가 느낀 가장 큰 성과였어요. 숫자를 과장할 필요도 없이, 운영 피로도가 확실히 줄었습니다.

노드가 Ready 상태로 정렬되고 테스트 워크로드가 배포된 모습을 보여주는 결과 검증 이미지입니다.

🎉 성과 정리

• 클러스터 생성 절차가 사람 의존에서 Git 기반 표준 절차로 바뀜
• 온프레미스 Kubernetes 환경에서도 재현 가능한 배포 흐름 확보
• 운영팀 간 작업 편차 감소
• 추후 GitOps, 모니터링, 정책 관리 연계가 쉬워짐

8. 정리: ClusterAPI 도입 사례에서 배운 점

이번 ClusterAPI 도입 사례를 통해 제가 가장 크게 배운 건, 자동화의 핵심은 도구보다 기준이라는 점이었어요. Cluster API는 만능 마법봉은 아니지만, 클러스터 생성과 확장을 운영 표준으로 묶는 데는 정말 강력했습니다. 특히 클러스터 자동화를 사람 손이 아니라 선언 상태 중심으로 옮긴다는 점에서, 장기 운영에 큰 차이를 만들더라고요.

다만 처음부터 모든 걸 얹지는 마세요. Management cluster 안정화, 템플릿 검증, 네트워크 정책 정리, 골든 이미지 검증 순으로 가는 게 좋아요. 저도 처음엔 욕심냤다가 다시 돌아왔거든요. 근데 그렇게 한 바퀴 돌고 나니 구조가 훨씬 단단해졌습니다.

수동 구축과 선언형 자동화의 차이를 한눈에 보여주는 비교 이미지입니다.

다음 글에서는 ClusterClass(클래스 기반 클러스터 템플릿)와 GitOps를 묶어서 운영 표준화를 더 밀어붙이는 방법도 다뤄볼 예정입니다. 이전 글에서 정리한 kubeadm 기반 수동 설치 방식과 비교해서 보시면 왜 CAPI 구축이 가치 있는지 더 선명하게 보이실 겁니다.

FAQ. ClusterAPI 도입 시 자주 묻는 질문

Q1. 작은 팀도 Cluster API가 필요할까요?

클러스터 수가 1개뿐이면 당장 절실하지 않을 수 있어요. 다만 환경이 늘어날 계획이 있거나 표준화가 필요하다면 일찍 검토할 가치가 있습니다.

Q2. 베어메탈에서도 가능한가요?

가능합니다. 다만 사용하는 인프라 제공자와 네트워크 자동화 수준에 따라 난이도가 확 달라져요. 그래서 처음엔 가상화 환경에서 개념을 먼저 익히는 걸 추천드립니다.

Q3. 업그레이드도 선언형으로 할 수 있나요?

네, Kubernetes 버전과 관련 리소스 정의를 통해 관리하는 방식이 일반적이에요. 다만 운영 적용 전에는 테스트 클러스터에서 롤링 동작을 꼭 검증해 보셔야 합니다.

✅ 한 줄 정리: 온프레미스 Kubernetes를 반복해서 만들고 운영해야 한다면, Cluster API는 복잡함을 늘리는 도구가 아니라 반복 작업을 구조화하는 도구예요.