이 글은 강의 내용을 바탕으로 kubeconfig가 왜 필요한지, 구조가 어떻게 생겼는지, kubectl이 어떤 순서로 kubeconfig를 읽는지, 그리고 실무에서 자주 쓰는 명령/패턴까지 초보자 관점에서 정리한 글입니다.

1) 문제: 인증서로 API 서버 호출은 가능한데, 매번 옵션 치기 너무 번거롭다

앞에서 인증서 기반 인증을 배웠다면, 이런 형태로 Kubernetes API 서버에 직접 요청할 수 있습니다.

curl --cacert ca.crt \
  --cert admin.crt \
  --key admin.key \
  https://<API_SERVER>:6443/api/v1/pods

원리는 간단합니다.

  • --cacert ca.crt : “내가 신뢰하는 CA(= 서버 인증서 검증용)”
  • --cert admin.crt : “내 클라이언트 인증서(내 신분증)”
  • --key admin.key : “내 개인키(신분증의 주인임을 증명)”

그런데 이걸 kubectl로 매번 치려면?

kubectl get pods \
  --server=https://<API_SERVER>:6443 \
  --certificate-authority=ca.crt \
  --client-certificate=admin.crt \
  --client-key=admin.key

현실적으로 매번 치기 어렵습니다.
그래서 이 정보(서버 주소/CA/클라이언트 인증서/키)를 파일로 묶어둔 것이 바로 kubeconfig입니다.

2) kubeconfig란?

kubectl(및 Kubernetes 클라이언트들이) 접속에 필요한 정보를 읽는 설정 파일(YAML)입니다.

  • 서버 주소(API Server endpoint)
  • 서버 검증용 CA
  • 내 클라이언트 인증서/개인키(또는 토큰)
  • “어떤 클러스터에 어떤 사용자로 들어갈지”에 대한 매핑

즉, kubeconfig는 “접속 프로필” 같은 개념입니다.

3) kubeconfig 기본 위치 (왜 지금까지 옵션을 안 쳤나?)

kubectl은 기본적으로 아래 경로의 파일을 자동으로 찾습니다.

  • ~/.kube/config

그래서 그 파일이 이미 존재하면, --server, --cert 같은 옵션을 안 쳐도 kubectl이 알아서 연결됩니다.

다른 kubeconfig를 쓰고 싶으면:

kubectl get pods --kubeconfig /path/to/custom-config

4) kubeconfig의 3대 구성요소: clusters / users / contexts

강의에서 가장 중요한 포인트입니다.

4.1 clusters

“접속할 Kubernetes 클러스터 정보”

  • API 서버 주소(server)
  • CA 인증서(certificate-authority 또는 certificate-authority-data)

4.2 users

“클러스터에 접속할 때 사용할 사용자(자격 증명)”

  • 인증서/키(client-certificate, client-key)
  • 또는 토큰 등(환경에 따라 다름)

주의: 여기서 “users”는 Kubernetes 내부에 유저를 만드는 기능이 아닙니다.
kubeconfig는 “내가 가진 자격증명으로 어떻게 접속할지”를 저장하는 파일입니다.

4.3 contexts

“어떤 클러스터 + 어떤 사용자 조합을 쓸지”

  • cluster: 어떤 clusters 엔트리를 쓸지
  • user: 어떤 users 엔트리를 쓸지
  • (옵션) namespace: 들어가자마자 기본 namespace를 어디로 할지

5) kubeconfig 예시 (가장 기본 형태)

apiVersion: v1
kind: Config

clusters:
- name: my-kube-playground
  cluster:
    server: https://10.0.0.10:6443
    certificate-authority: /etc/kubernetes/pki/ca.crt

users:
- name: my-kube-admin
  user:
    client-certificate: /home/user/admin.crt
    client-key: /home/user/admin.key

contexts:
- name: my-kube-admin@my-kube-playground
  context:
    cluster: my-kube-playground
    user: my-kube-admin
    namespace: default

current-context: my-kube-admin@my-kube-playground

핵심은:

  • clusters에 서버/CA
  • users에 내 인증서/키
  • contexts가 둘을 연결
  • current-context가 “기본으로 쓸 context”

6) current-context가 중요한 이유

kubeconfig에 context가 여러 개 있을 수 있습니다.

예)

  • dev@dev-cluster
  • admin@prod-cluster
  • readonly@prod-cluster

이 중 기본으로 어떤 걸 쓸지가 current-context입니다.

그래서 “내가 지금 prod를 보고 있었네?” 같은 사고가 생길 수 있습니다.

7) kubectl로 kubeconfig 보기/바꾸기 (실무에서 가장 많이 씀)

7.1 현재 kubeconfig 내용 보기

kubectl config view

“정확히 어떤 파일을 쓰는지”가 헷갈리면:

echo $KUBECONFIG
  • 설정되어 있으면 그 경로(들)를 사용합니다.
  • 없으면 기본값 ~/.kube/config

7.2 현재 context 확인

kubectl config current-context

7.3 context 목록 보기

kubectl config get-contexts

7.4 context 변경

kubectl config use-context my-kube-admin@my-kube-playground

8) namespace를 context에 박아두는 방법

매번 -n kube-system 치기 싫으면 context에 기본 namespace를 지정할 수 있습니다.

kubectl config set-context --current --namespace=kube-system

또는 YAML에서 context에 namespace: 필드를 추가해도 됩니다.

9) 파일 경로 대신 *-data를 쓰는 방식 (certificate-authority-data 등)

강의 후반 핵심입니다.

kubeconfig는 인증서/키를 두 가지 방식으로 저장할 수 있습니다.

A) 파일 경로로 지정

certificate-authority: /path/to/ca.crt
client-certificate: /path/to/admin.crt
client-key: /path/to/admin.key

B) 파일 내용을 base64로 “내장(Embed)”

certificate-authority-data: <base64(ca.crt)>
client-certificate-data: <base64(admin.crt)>
client-key-data: <base64(admin.key)>

실무에서 B가 자주 나오는 이유:

  • kubeconfig 파일 하나만 옮겨도 동작(이동성이 좋음)
  • 단점: 파일 자체가 민감해짐(특히 client-key-data)

확인/디코딩 예시:

kubectl config view --raw

10) 초보자가 가장 자주 겪는 트러블 3가지

(1) 인증서 SAN 불일치

에러 예:

  • x509: certificate is valid for ..., not <주소>

→ kubeconfig의 server: 주소가 인증서 SAN에 들어있어야 합니다.

(2) unknown authority

에러 예:

  • x509: certificate signed by unknown authority

→ certificate-authority 또는 certificate-authority-data가 올바른 CA인지 확인.

(3) current-context 실수

“나는 dev로 테스트하는 줄 알았는데 prod에 배포함” 유형

→ kubectl config current-context 습관화.

11) 한 줄 요약

  • kubeconfig는 kubectl이 서버 주소 + CA + 내 자격증명을 매번 옵션으로 받지 않게 해주는 파일
  • 구조는 clusters / users / contexts
  • context는 “클러스터-유저 매핑”이고 current-context가 기본 선택값
  • 인증서 경로 대신 *-data로 base64 내장도 가능

 

'CKA' 카테고리의 다른 글

Security - API Groups  (0) 2026.01.01
Security - 정리(1)  (2) 2026.01.01
Security - CSR API  (0) 2026.01.01
Security - 인증서 상태 점검 방법  (1) 2026.01.01
Security - 인증서 생성 방법  (0) 2026.01.01

티스토리툴바