소개

쿠버네티스(Kubernetes, 종종 K8s로 축약)는 컨테이너화된 애플리케이션의 배포, 확장 및 관리를 자동화하는 오픈소스 시스템입니다. 신입 개발자로서 쿠버네티스 환경에서 작업하게 된다면, kubectl이라는 강력한 커맨드 라인 인터페이스(CLI) 도구를 자주 사용하게 될 것입니다. 이 가이드는 신입 개발자가 알아야 할 필수적인 kubectl 명령어들을 상세히 설명하여 쿠버네티스 클러스터와의 상호작용을 돕고자 합니다.

kubectl 기본 설정 및 도움말

설치 확인 및 버전 정보

쿠버네티스 클러스터와 통신하기 전에 kubectl이 올바르게 설치되고 구성되었는지 확인하는 것이 중요합니다.

  • 클라이언트 및 서버 버전 확인:

    kubectl version

    이 명령어는 kubectl 클라이언트와 쿠버네티스 API 서버의 버전을 보여줍니다. --short 플래그를 추가하면 간략한 버전 정보만 볼 수 있습니다.

    kubectl version --short

설정 확인

kubectl은 ~/.kube/config 파일에 저장된 설정을 사용하여 클러스터에 연결합니다.

  • 현재 설정 보기:

    kubectl config view

  • 현재 컨텍스트 확인:

    kubectl config current-context

  • 모든 컨텍스트 나열:

    kubectl config get-contexts

  • 컨텍스트 변경:

    kubectl config use-context <context-name>

명령어 도움말

kubectl은 자체적으로 매우 유용한 도움말 기능을 제공합니다.

  • 일반 도움말:

    kubectl --help

  • 특정 명령어 도움말:

    kubectl <command> --help

    예를 들어, get 명령어에 대한 도움말을 보려면 다음을 실행합니다.

    kubectl get --help

클러스터 정보 확인

  • 클러스터 정보 보기:

    kubectl cluster-info

    이 명령어는 마스터 노드 및 클러스터 내 주요 서비스들의 주소를 보여줍니다.

  • 클러스터 이벤트 보기:

    kubectl get events

    클러스터에서 발생하는 다양한 이벤트를 시간순으로 볼 수 있어 문제 해결에 유용합니다.

네임스페이스(Namespace) 관리

네임스페이스는 단일 클러스터 내에서 리소스를 격리하는 방법입니다.

  • 모든 네임스페이스 나열:

    kubectl get namespaces

    또는 축약형으로 ns를 사용할 수 있습니다.

    kubectl get ns

  • 특정 네임스페이스의 리소스 보기: --namespace 또는 -n 플래그를 사용합니다.

    kubectl get pods --namespace <namespace-name>
kubectl get pods -n <namespace-name>

  • 기본 네임스페이스 변경: 현재 컨텍스트의 기본 네임스페이스를 변경하여 매번 -n 플래그를 입력하지 않도록 할 수 있습니다.

    kubectl config set-context --current --namespace=<namespace-name>

기본 리소스 조회 (kubectl get)

kubectl get 명령어는 가장 자주 사용되는 명령어 중 하나로, 다양한 쿠버네티스 리소스의 목록을 조회할 수 있습니다.

  • 노드(Node) 목록 보기:

    kubectl get nodes

    클러스터에 있는 모든 워커 노드의 상태를 보여줍니다. -o wide 옵션을 추가하면 더 자세한 정보를 볼 수 있습니다.

    kubectl get nodes -o wide

  • 파드(Pod) 목록 보기:

    kubectl get pods

    현재 네임스페이스의 모든 파드를 보여줍니다. 모든 네임스페이스의 파드를 보려면 -A 또는 --all-namespaces 플래그를 사용합니다.

    kubectl get pods -A
kubectl get pods --all-namespaces

    특정 파드에 대한 자세한 정보를 YAML 또는 JSON 형식으로 보려면 -o yaml 또는 -o json을 사용합니다.

    kubectl get pod <pod-name> -o yaml

  • 서비스(Service) 목록 보기:

    kubectl get services

    또는 축약형으로 svc를 사용할 수 있습니다.

    kubectl get svc

  • 디플로이먼트(Deployment) 목록 보기:

    kubectl get deployments

    또는 축약형으로 deploy를 사용할 수 있습니다.

    kubectl get deploy

  • 스테이트풀셋(StatefulSet) 목록 보기:

    kubectl get statefulsets

    또는 축약형으로 sts를 사용할 수 있습니다.

    kubectl get sts

  • 데몬셋(DaemonSet) 목록 보기:

    kubectl get daemonsets

    또는 축약형으로 ds를 사용할 수 있습니다.

    kubectl get ds

  • 컨피그맵(ConfigMap) 및 시크릿(Secret) 목록 보기:

    kubectl get configmaps
kubectl get secrets

    축약형은 각각 cm과 secret입니다.

  • 여러 리소스 동시 조회:

    kubectl get pods,services
kubectl get all # 주요 리소스를 한번에 보여주지만, 모든 것을 의미하진 않음

리소스 상세 정보 확인 (kubectl describe)

kubectl describe 명령어는 특정 리소스에 대한 상세한 정보를 보여줍니다. 이벤트, 상태, 설정 등을 포함하여 문제 해결에 매우 유용합니다.

  • 파드 상세 정보:

    kubectl describe pod <pod-name>

    예를 들어, 파드가 왜 Pending 상태인지, 어떤 이벤트가 발생했는지 등을 확인할 수 있습니다.

  • 노드 상세 정보:

    kubectl describe node <node-name>

    노드의 현재 상태, 할당된 리소스, 실행 중인 파드 목록 등을 볼 수 있습니다.

  • 디플로이먼트 상세 정보:

    kubectl describe deployment <deployment-name>

파드 로그 확인 (kubectl logs)

애플리케이션의 동작을 이해하고 문제를 진단하는 데 필수적인 명령어입니다.

  • 파드 로그 보기:

    kubectl logs <pod-name>

  • 실시간 로그 스트리밍 (Follow): -f 또는 --follow 플래그를 사용합니다.

    kubectl logs -f <pod-name>

  • 이전 컨테이너 로그 보기 (Previous): 파드가 재시작된 경우, -p 또는 --previous 플래그로 이전 컨테이너의 로그를 볼 수 있습니다.

    kubectl logs -p <pod-name>

  • 특정 컨테이너 로그 보기 (Multi-container Pods): 파드 내에 여러 컨테이너가 있는 경우, -c 또는 --container 플래그로 특정 컨테이너를 지정해야 합니다.

    kubectl logs <pod-name> -c <container-name>

  • 최근 N줄 로그 보기: --tail 플래그를 사용합니다.

    kubectl logs <pod-name> --tail=50

파드 내 컨테이너 접근 (kubectl exec)

실행 중인 컨테이너 내부로 들어가거나 명령을 실행할 수 있습니다.

  • 컨테이너에 셸(Shell) 실행: -i (stdin) 와 -t (tty) 플래그를 함께 사용하여 인터랙티브 셸을 실행합니다.

    kubectl exec -it <pod-name> -- /bin/bash

    만약 /bin/bash가 없다면 /bin/sh을 시도해 보세요.

    kubectl exec -it <pod-name> -- /bin/sh

  • 컨테이너에 단일 명령어 실행:

    kubectl exec <pod-name> -- <command>

    예를 들어, 컨테이너 내의 환경 변수를 보려면:

    kubectl exec <pod-name> -- env

  • 특정 컨테이너에 명령어 실행 (Multi-container Pods): -c 플래그를 사용합니다.

    kubectl exec -it <pod-name> -c <container-name> -- /bin/bash

리소스 생성 및 수정 (kubectl apply, kubectl create, kubectl edit)

쿠버네티스 리소스는 주로 YAML 또는 JSON 형식의 매니페스트 파일을 통해 정의되고 관리됩니다.

  • 파일로부터 리소스 생성 또는 업데이트 (apply): kubectl apply는 선언적 방식의 명령어로, 파일에 정의된 상태를 클러스터에 적용합니다. 리소스가 없으면 생성하고, 있으면 업데이트합니다. 가장 권장되는 방식입니다.

    kubectl apply -f <filename.yaml>
kubectl apply -f <directory/>

  • 파일로부터 리소스 생성 (create): kubectl create는 명령적 방식의 명령어로, 리소스를 새로 생성합니다. 이미 리소스가 존재하면 오류가 발생합니다.

    kubectl create -f <filename.yaml>

    간단한 리소스는 직접 명령어로 생성할 수도 있습니다.

    kubectl create deployment <deployment-name> --image=<image-name>
kubectl create service clusterip <service-name> --tcp=80:8080

  • 실행 중인 리소스 수정 (edit):

    kubectl edit <resource-type>/<resource-name>

    예를 들어, 디플로이먼트를 수정하려면:

    kubectl edit deployment/<deployment-name>

    이 명령어는 기본 편집기(보통 vi)로 리소스의 YAML 정의를 열어주며, 저장 시 변경 사항이 적용됩니다.

리소스 삭제 (kubectl delete)

  • 파일로부터 리소스 삭제:

    kubectl delete -f <filename.yaml>

  • 타입과 이름으로 리소스 삭제:

    kubectl delete <resource-type> <resource-name>

    예를 들어, 특정 파드를 삭제하려면:

    kubectl delete pod <pod-name>

    디플로이먼트를 삭제하려면:

    kubectl delete deployment <deployment-name>

    디플로이먼트를 삭제하면 관련된 파드들도 함께 삭제됩니다.

  • 여러 리소스 동시 삭제:

    kubectl delete pod <pod1-name> <pod2-name>
kubectl delete pods,services --all # 현재 네임스페이스의 모든 파드와 서비스 삭제 (주의!)

디플로이먼트 관리

디플로이먼트는 애플리케이션의 선언적 업데이트를 관리합니다.

  • 디플로이먼트 확장/축소 (Scale):

    kubectl scale deployment <deployment-name> --replicas=<count>

    예를 들어, my-app 디플로이먼트의 파드 수를 3개로 조절하려면:

    kubectl scale deployment my-app --replicas=3

  • 롤아웃 상태 확인:

    kubectl rollout status deployment/<deployment-name>

    배포가 성공적으로 완료될 때까지 상태를 모니터링합니다.

  • 롤아웃 히스토리 보기:

    kubectl rollout history deployment/<deployment-name>

  • 롤백 (Rollback): 문제가 발생했을 때 이전 버전으로 되돌릴 수 있습니다.

    # 이전 버전으로 롤백
kubectl rollout undo deployment/<deployment-name>

# 특정 리비전으로 롤백
kubectl rollout undo deployment/<deployment-name> --to-revision=<revision-number>

  • 롤아웃 일시정지 및 재개:

    kubectl rollout pause deployment/<deployment-name>
kubectl rollout resume deployment/<deployment-name>

포트 포워딩 (kubectl port-forward)

로컬 머신의 포트를 파드 또는 서비스의 포트로 전달하여, 외부에서 직접 접근할 수 없는 내부 서비스를 테스트하거나 디버깅할 때 유용합니다.

  • 파드로 포트 포워딩:

    kubectl port-forward pod/<pod-name> <local-port>:<pod-port>

    예를 들어, 로컬의 8080 포트를 my-pod의 80 포트로 전달:

    kubectl port-forward pod/my-pod 8080:80

    이제 브라우저에서 http://localhost:8080으로 접근하면 my-pod의 80 포트로 연결됩니다.

  • 서비스로 포트 포워딩:

    kubectl port-forward service/<service-name> <local-port>:<service-port>

  • 디플로이먼트의 파드로 포트 포워딩: 디플로이먼트가 관리하는 파드 중 하나로 포워딩합니다.

    kubectl port-forward deployment/<deployment-name> <local-port>:<target-port>

레이블(Label) 및 어노테이션(Annotation) 관리

레이블은 리소스를 식별하고 선택하는 데 사용되는 키-값 쌍입니다. 어노테이션은 비식별 메타데이터를 추가하는 데 사용됩니다.

  • 리소스에 레이블 추가/업데이트: --overwrite 플래그는 기존 레이블이 있을 경우 덮어씁니다.

    kubectl label <resource-type> <resource-name> <label-key>=<label-value> --overwrite

    예:

    kubectl label pod my-pod environment=production --overwrite

  • 레이블로 리소스 조회: -l 또는 --selector 플래그를 사용합니다.

    kubectl get pods -l environment=production
kubectl get pods -l 'app=nginx,tier=frontend'

  • 레이블 삭제: 레이블 키 뒤에 -를 붙입니다.

    kubectl label <resource-type> <resource-name> <label-key>-

    예:

    kubectl label pod my-pod environment-

  • 리소스에 어노테이션 추가/업데이트:

    kubectl annotate <resource-type> <resource-name> <annotation-key>=<annotation-value> --overwrite

유용한 팁 및 추가 명령어

  • kubectl 자동 완성 설정: 셸 환경에 따라 kubectl completion <shell> 명령어로 자동 완성 스크립트를 생성하고 설정할 수 있습니다. 이는 생산성을 크게 향상시킵니다. (예: kubectl completion bash)

  • 출력 형식 변경 (-o): -o wide, -o yaml, -o json, -o custom-columns, -o jsonpath 등 다양한 출력 형식을 지원합니다.

    kubectl get pods -o wide
kubectl get pod <pod-name> -o yaml
kubectl get nodes -o custom-columns=NAME:.metadata.name,OS-IMAGE:.status.nodeInfo.osImage

  • 리소스 사용량 확인 (kubectl top): 메트릭 서버(Metrics Server)가 클러스터에 설치되어 있어야 합니다.

    # 노드 리소스 사용량
kubectl top node

# 파드 리소스 사용량
kubectl top pod
kubectl top pod -n <namespace-name>

  • API 리소스 목록 보기:

    kubectl api-resources

    클러스터에서 사용 가능한 모든 API 리소스 유형과 축약형, API 그룹, 네임스페이스 여부 등을 보여줍니다.

  • API 버전 정보 보기:

    kubectl api-versions

    사용 가능한 API 그룹과 버전 목록을 보여줍니다.

마무리

이 가이드에서 소개된 kubectl 명령어들은 쿠버네티스를 사용하는 신입 개발자에게 훌륭한 출발점이 될 것입니다. 각 명령어의 다양한 옵션과 하위 명령어들을 --help 플래그를 통해 탐색하며 익숙해지는 것이 중요합니다. 쿠버네티스는 방대하고 강력한 시스템이므로, 꾸준한 학습과 실습을 통해 전문성을 키워나가시길 바랍니다.

참고