개요

kubeadm init을 추가 옵션 없이 실행하면 기본 클러스터 이름인 kubernetes로 생성됩니다. Kubernetes cluster name을 원하는 이름으로 지정하려면 kubeadm 설정 파일에 clusterName을 명시하고 --config 옵션으로 초기화해야 합니다. 이 글에서는 kubeadm config 파일을 사용해 원하는 cluster name으로 Kubernetes를 초기화하는 방법을 정리합니다.

클러스터 이름이 중요한 이유

kubeadm으로 Kubernetes를 초기화하면 기본 cluster name인 kubernetes가 kubeconfig(~/.kube/config)에 등록됩니다. 단일 클러스터만 운영할 때는 문제가 없지만, 여러 클러스터를 동시에 관리하는 환경에서는 cluster name이 동일하면 kubeconfig 병합 시 충돌이 발생합니다. 개발(dev), 스테이징(staging), 운영(prod) 클러스터를 각각 의미있는 이름으로 구분하면 kubectl config use-context로 쉽게 전환하고 실수를 방지할 수 있습니다.

클러스터 이름은 kubeconfig의 clusters[].name, contexts[].context.cluster 필드에 반영됩니다. 이미 초기화된 클러스터에서 내부 cluster name을 변경하는 것은 etcd 데이터 수정이 필요하므로 매우 복잡합니다. 처음 kubeadm init 시점에 올바른 이름을 지정하는 것이 중요합니다.

kubeadm으로 Kubernetes를 초기화하면 기본 cluster name인 kubernetes가 kubeconfig(~/.kube/config)에 등록됩니다. 단일 클러스터만 운영할 때는 문제가 없지만, 여러 클러스터를 동시에 관리하는 환경에서는 cluster name이 동일하면 kubeconfig 병합 시 충돌이 발생합니다. 개발(dev), 스테이징(staging), 운영(prod) 클러스터를 각각 의미있는 이름으로 구분하면 kubectl config use-context로 쉽게 전환하고 실수를 방지할 수 있습니다.

kubeadm config 파일 작성

ClusterConfiguration의 clusterName 필드에 원하는 이름을 지정합니다. 이름에는 영소문자, 숫자, 하이픈(-)만 사용하는 것이 권장됩니다. cri-dockerd를 사용하는 환경에서는 InitConfiguration의 criSocket을 함께 선언합니다. cri-dockerd를 사용하는 환경에서는 InitConfiguration에 criSocket을 함께 선언합니다.

# cluster-config.yaml 생성
# criSocket 옵션이 필요한 경우 InitConfiguration을 추가합니다. 불필요 시 ClusterConfiguration만 선언하면 됩니다.
cat << EOF > cluster-config.yaml
apiVersion: kubeadm.k8s.io/v1beta3
kind: InitConfiguration
nodeRegistration:
  criSocket: /var/run/cri-dockerd.sock
---
apiVersion: kubeadm.k8s.io/v1beta3
kind: ClusterConfiguration
clusterName: my-cluster
kubernetesVersion: stable
controlPlaneEndpoint: "<master-node>:6443"
networking:
  podSubnet: "10.244.0.0/16"
EOF

Kubernetes 클러스터 초기화

작성한 config 파일을 --config 옵션으로 지정하여 kubeadm init을 실행합니다.

sudo kubeadm init --config=cluster-config.yaml

결과 확인

초기화 완료 후 kubectl config get-clusters로 cluster name이 지정한 이름으로 생성되었는지 확인합니다.

kubectl config get-clusters
NAME
my-cluster

멀티 클러스터 kubeconfig 병합

여러 클러스터의 kubeconfig를 하나의 파일로 병합하면 kubectl config use-context <name>으로 클러스터를 전환할 수 있습니다. 각 클러스터의 kubeconfig를 별도 파일로 저장한 뒤 KUBECONFIG 환경변수에 콜론으로 구분하여 나열하면 kubectl이 자동으로 병합하여 처리합니다.

# 두 kubeconfig 파일을 병합하여 새 파일 생성
KUBECONFIG=~/.kube/config-dev:~/.kube/config-prod   kubectl config view --flatten > ~/.kube/config-merged

# 병합된 config에서 context 목록 확인
kubectl --kubeconfig ~/.kube/config-merged config get-contexts

클러스터 이름을 처음부터 고유하게 설정해두면 이 병합 과정에서 충돌 없이 깔끔하게 합쳐집니다. 반면 기본값인 kubernetes를 그대로 사용하면 병합 시 cluster, context, user 항목이 모두 덮어써지는 문제가 발생합니다.

기존 클러스터의 Context name 변경 방법

이미 생성된 클러스터에서 context 이름을 변경하려면 kubectl config rename-context를 사용합니다. 이 방법은 kubeconfig 상의 context 이름만 변경하며, 클러스터 자체의 내부 이름은 변경되지 않습니다.

# 현재 context 목록 확인
kubectl config get-contexts

# context 이름 변경 (kubernetes → my-cluster)
kubectl config rename-context kubernetes my-cluster

# 변경 확인
kubectl config current-context

참고

• Kubernetes Cluster Upgrade — kubeadm 단계별 업그레이드 절차
• Kubernetes 기본 설치 v1.28 — kubeadm, cri-dockerd, Calico CNI 구성

참고 문서: kubeadm ClusterConfiguration API 레퍼런스 · kubectl config rename-context 공식 문서