kubectl: 쿠버네티스 CLI 도구

kubectl 쿠버네티스 클러스터를 제어하기 위한 커맨드 라인 인터페이스(CLI) 도구이다. 모든 클러스터 조작은 쿠버네티스 마스터의 API 서버를 통해 이루어지며, kubectl 이 API 요청을 편리하게 실행할 수 있도록 돕는다.

1. 인증 정보와 컨텍스트

kubectl 이 API 서버와 통신하기 위해서는 접속 대상 서버 정보와 인증 정보가 필요하다.

1) kubeconfig

이 정보들은 kubeconfig 파일에 저장되며, 기본 위치는 ~/.kube/config이다. kubeconfig 파일은 세 가지 주요 부분으로 구성된다.

• clusters: 접속할 클러스터의 정보(API 서버 주소 등)를 정의한다.

• users: 클러스터에 접근할 사용자의 인증 정보(인증서, 토큰 등)를 정의한다.

• contexts : clusters 와 users의 조합을 정의하며, 특정 네임스페이스를 지정할 수도 있다. current-context 는 현재 kubectl 명령이 적용될 기본 컨텍스트를 지정한다.

2) kubeconfig 설정 변경

파일 직접 수정: ~/.kube/config 파일을 직접 편집한다.

명령어 이용: kubectl config 명령어를 사용해 동적으로 설정을 추가하거나 변경할 수 있다.

• 클러스터 추가/변경:

kubectl config set-cluster <cluster-name> --server=https://<ip>:<port>

• 인증 정보 추가/변경:

kubectl config set-credentials <user-name> --client-certificate=./sample.crt --client-key=./sample.key

• 컨텍스트 추가/변경:

kubectl config set-context <context-name> --cluster=<cluster-name> --user=<user-name> --namespace=<namespace>

3) 컨텍스트 관련 명령어

• 현재 설정된 컨텍스트 확인:

kubectl config current-context

• 명령어 실행 시 특정 컨텍스트 지정:

kubectl get pods --context <context-name>

---

2. 리소스 생성/삭제/갱신(CRUD)

1) 리소스 생성

kubectl run

• 간단하게 Pod를 생성하는 명령어로, 이미지 이름 등 필요한 정보를 직접 입력한다.

• 간편하지만, 생성 정보가 파일로 남지 않아 재현성이 떨어지고 협업에 불편함이 있어 테스트 용도로 적합하다.

• 예시:

kubectl run nginx --image=nginx

kubectl create -f <file.yaml>

• YAML 형식의 매니페스트 파일을 사용하여 리소스를 생성한다.

• 이미 동일한 이름의 리소스가 존재하면 에러가 발생한다.

2) 리소스 갱신

kubectl apply -f <file.yaml>

• 매니페스트 파일을 기반으로 리소스를 관리하는 가장 권장되는 방식이다.

• 리소스가 없으면 새로 생성하고(create 와 동일), 변경 사항이 있으면 적용하며, 변경 사항이 없으면 아무 작업도 하지 않는다.

• apply 사용을 권장하는 이유:

  1. 스크립트나 CI/CD 파이프라인에서 리소스 존재 여부에 따른 조건 분기 없이 일관된 명령어를 사용할 수 있다.
  2. apply는 "이전에 적용된 매니페스트", "현재 클러스터 상태", "새로 적용할 매니페스트" 세 가지를 비교하여 변경 사항을 계산한다. create 와 혼용 시 이 정보가 없어 변경 사항 감지에 문제가 생길 수 있다.

3) 리소스 삭제

kubectl delete -f <file.yaml>

• 파일에 정의된 리소스를 삭제한다.

kubectl delete <type> <name>

• 특정 종류와 이름의 리소스를 삭제한다.

• --all 플래그를 사용하면 해당 종류의 모든 리소스를 삭제할 수 있다.

kubectl delete 명령어 옵션:

• --wait: 리소스 삭제가 완전히 끝날 때까지 대기한다.

• --force --grace-period=0 : 정상적인 종료 절차를 무시하고 리소스를 즉시 강제 삭제한다. (Kubernetes 1.8 이상에서는 --force 만 사용해도 동일하게 동작)

---

3. 고급 리소스 관리

1) Server-Side Apply

쿠버네티스에서는 kubectl 외에도 다양한 시스템 컴포넌트가 리소스를 수정할 수 있어 경합(conflict)이 발생할 수 있다.

Server-Side Apply는 이러한 충돌을 서버 측에서 감지하는 기능이다.

• 이 기능은 Kubernetes 1.18부터 서버 측에서는 기본 활성화되어 있지만, 클라이언트(kubectl)에서는 --server-side 옵션을 사용해야 한다.

• Server-Side Apply를 사용하면 필드별로 관리 주체(manager)가 기록되어 충돌 발생 시 에러를 출력한다.

• 충돌을 감지했을 때, --force-conflicts 옵션으로 강제 덮어쓰기가 가능하다.

2) generateName

• 매니페스트에서 metadata.name 대신 metadata.generateName 을 사용하면, 지정된 접두사(prefix) 뒤에 임의의 난수가 붙은 이름으로 리소스가 생성된다.

• kubectl create 명령어로 실행할 때마다 고유한 이름의 리소스가 생성되므로, 이름 충돌을 피하면서 여러 개의 동일한 템플릿 기반 리소스를 생성해야 할 때 유용하다.

실습 sample-generatename.yaml

# sample-generatename.yaml
apiVersion: 1
kind: Pod
metadata:
  generateName: sample-generatename-
spec:
  containers:
    - name: nginx-container
      image: nginx

kubectl create -f sample-generatename.yaml 실행 시 sample-generatename-xxxxx 형태의 고유한 파드가 생성된다.

---

4. 관리 자동화 및 스크립팅

1) Prune 옵션을 활용한 리소스 자동 삭제

GitOps 등 자동화된 파이프라인에서 kubectl apply 를 사용할 때, Git 저장소에서 매니페스트 파일을 삭제해도 클러스터의 리소스는 자동으로 삭제되지 않는다.

이를 해결하려면 삭제된 리소스를 감지하고 kubectl delete를 실행하는 별도의 로직이 필요하다.

이때, kubectl apply --prune 옵션은 이 문제를 해결한다.

• 현재 적용하려는 매니페스트 목록과 클러스터에 배포된 리소스를 비교하여, 매니페스트에서 삭제된 리소스를 자동으로 감지하고 삭제한다.

• 주의: 의도치 않은 삭제를 방지하기 위해, -l (레이블) 옵션과 함께 사용하여 작업 범위를 명확히 한정해야 한다.

Prune 옵션 실습

1. system: a 레이블을 가진 sample-pod1.yaml, sample-pod2.yaml 파일을 prune 디렉터리에 생성한다.

# prune/sample-pod1.yaml
apiVersion: v1
kind: Pod
metadata:
  name: sample-pod1
  labels:
    system: a
spec:
  containers:
  - name: nginx-container
    image: nginx:1.16

# prune/sample-pod2.yaml
apiVersion: v1
kind: Pod
metadata:
  name: sample-pod2
  labels:
    system: a
spec:
  containers:
  - name: nginx-container
    image: nginx:1.16

2. --prune 옵션으로 두 파드를 생성한다.

# system=a 레이블을 기준으로 prune을 적용
kubectl apply -f ./prune --prune -l system=a
# 결과:
# pod/sample-pod1 created
# pod/sample-pod2 created

3. prune 디렉터리에서 sample-pod2.yaml 파일을 삭제한다.

4. 동일한 --prune 명령어를 다시 실행한다.

kubectl apply -f ./prune --prune -l system=a
# 결과:
# pod/sample-pod1 unchanged
# pod/sample-pod2 pruned  <-- pod2가 자동 삭제됨

5. 파드 목록을 확인해보면 sample-pod2가 성공적으로 삭제된 것을 확인할 수 있다.

kubectl get pods

이처럼 kubectl apply --prune 은 GitOps와 같은 선언적 리소스 관리 방식에서 매니페스트와 클러스터의 상태를 일관되게 유지하는 강력하고 필수적인 기능이다.

2) 리소스 상태 체크와 대기 : kubectl wait

스크립트에서 리소스가 'Running' 상태가 되기 전에 다음 명령어가 실행되는 것을 방지해야 한다. kubectl wait 는 특정 리소스가 원하는 상태가 될 때까지 대기한다.

• --for: 대기할 조건을 지정한다. (예: condition=Ready, delete)

• --timeout: 지정한 시간 동안 조건이 충족되지 않으면 오류를 반환한다. 기본값은 30초이다.

kubectl wait 실습

1. sample-pod가 Ready 상태가 될 때까지 대기:

kubectl wait --for=condition=Ready pod/sample-pod

# 출력:
# pod/sample-pod condition met

2. 클러스터 내의 모든 파드가 노드에 스케줄링될 때까지(PodScheduled 상태) 대기합니다.

kubectl wait --for=condition=PodScheduled pod --all

# 출력:
# pod/sample-generatename-h6qpz condition met
# pod/sample-generatename-kppck condition met
# pod/sample-pod condition met

3. 모든 파드가 삭제 완료될 때까지 대기:

# 먼저 모든 파드를 삭제 요청 (--wait=false로 바로 리턴)
kubectl delete pod --all --wait=false

# 이후 모든 파드가 실제로 삭제 완료될 때까지 대기
kubectl wait --for=delete pod --all

4. 매니페스트 파일을 이용한 대기
   kubectl wait 명령어는 리소스 이름 대신 -f 옵션으로 매니페스트 파일을 직접 지정할 수도 있다.

# 먼저 매니페스트로 파드 생성
kubectl apply -f sample-pod.yaml

# 해당 매니페스트의 파드가 Ready 상태가 될 때까지 대기
kubectl wait --for=condition=Ready -f sample-pod.yaml

# 출력:
# pod/sample-pod condition met

3) 파드 재시작 (rollout restart)

• Deployment , StatefulSet 등 컨트롤러에 의해 관리되는 모든 파드를 순차적으로 재기동할 때 사용하는 명령어다.

• 환경 변수 변경 사항을 적용하거나, 파드 기동 시의 초기화 로직을 다시 실행하고 싶을 때 유용하다.

• 주의: 이 명령어는 컨트롤러와 연결되지 않은 단독 파드에는 사용할 수 없다.

# 성공
kubectl rollout restart deployment <deployment-name>

# 실패
kubectl rollout restart pod <pod-name>

---

5. 리소스 직접 수정 및 변경 확인

1) 편집기로 리소스 직접 수정 : kubectl edit

kubectl edit 명령어는 클러스터에 배포된 리소스의 정의(YAML)를 시스템의 기본 편집기(예: vi, nano)로 직접 열어 수정할 수 있게 해준다.

kubectl edit 리소스종류 리소스이름

편집기에서 내용을 수정한 뒤 저장하고 종료하면, 변경 사항이 즉시 클러스터의 리소스에 반영된다. 매니페스트 파일을 별도로 관리하지 않고 간단한 수정을 빠르게 적용하고 싶을 때 유용하다.

2) 리소스의 특정 필드 업데이트 : kubectl set

kubectl set 명령어는 매니페스트 파일이나 편집기를 열지 않고, 특정 리소스의 일부 정보를 직접 변경할 때 사용한다.

kubectl set 변경할정보 리소스종류 리소스이름 실제값

주로 변경 가능한 정보는 다음과 같다.

• image: 컨테이너 이미지 변경

• env: 환경 변수 설정

• resources : 리소스 요청(requests) 및 제한(limits) 설정

• selector: 셀렉터 변경

• serviceaccount: 서비스 어카운트 지정

• subject: RoleBinding/ClusterRoleBinding의 주체(사용자, 그룹 등) 설정

실습 : 파드 이미지 변경

sample-pod.yaml 로 파드를 생성한 후, kubectl set image 명령어로 해당 파드의 컨테이너 이미지를 nginx:1.17 로 변경한다.

# 파드 생성
kubectl apply -f sample-pod.yaml
# 결과: pod/sample-pod created

# 파드 이미지 변경 1.17 -> 1.16
kubectl set image pod sample-pod nginx-container=nginx:1.16
# 결과: pod/sample-pod image updated

3) 적용 전 변경 사항 미리보기 : kubectl diff

kubectl diff 명령어는 로컬에 있는 매니페스트 파일과 현재 클러스터에 배포된 리소스의 설정 정보를 비교하여 차이점을 보여준다.

kubectl apply 를 실행하기 전에 어떤 부분이 변경될지 미리 확인할 수 있어 안전한 배포에 도움이 된다.

kubectl diff -f sample-pod.yaml

출력 결과:

diff -u -N /tmp/LIVE-2926808943/v1.Pod.default.sample-pod /tmp/MERGED-1018098655/v1.Pod.default.sample-pod
--- /tmp/LIVE-2926808943/v1.Pod.default.sample-pod      2025-07-01 06:46:30.943786672 +0000
+++ /tmp/MERGED-1018098655/v1.Pod.default.sample-pod    2025-07-01 06:46:30.949786692 +0000
@@ -11,7 +11,7 @@
   uid: d312eb6d-f729-43d7-84b3-3167047a80b7
 spec:
   containers:
-  - image: nginx:1.16
+  - image: nginx:1.17
     imagePullPolicy: IfNotPresent
     name: nginx-container
     resources: {}

위 예시는 현재 클러스터의 image 가 1.16이지만, 로컬 sample-pod.yaml 파일에는 nginx:1.17으로 정의되어 있어 apply 시 업그레이드될 것임을 보여준다.

---