kubectl 명령줄 도구

kubectl 명령줄 도구 (The kubectl command-line tool)

쿠버네티스는 쿠버네티스 클러스터의 제어 플레인과 통신하기 위한 명령줄 도구를 제공해요. 이 도구는 쿠버네티스 API를 사용해요.

kubectl 도구는 쿠버네티스 API를 통해 클러스터와 통신해요. 구성에 대해 kubectl은 $HOME/.kube 디렉터리에서 config라는 파일을 찾아요. 다른 kubeconfig 파일을 지정하려면 KUBECONFIG 환경 변수를 설정하거나 --kubeconfig 플래그를 설정하면 돼요.

출처: 문서

본문

kubectl의 역할 (Role of kubectl)

kubectl 도구는 쿠버네티스 객체를 만들고, 검사하고, 업데이트하고, 삭제하는 기본 인터페이스예요. 이는 클러스터 안에서 실행되는 쿠버네티스 구성 요소와, 그 구성 요소들이 구현하는 쿠버네티스 API를 보완해요. kubectl을 노트북에서 실행하든 클러스터 안의 파드에서 실행하든, API 서버로 요청을 보내요. 클라이언트 라이브러리나 Headlamp 같은 웹 대시보드 같은 다른 클라이언트도 같은 API를 통해 통신해요.

kubectl이 동작하는 방식 (How kubectl works)

kubectl 도구는 API 서버에 연결해서 kubeconfig 파일에 정의된 클러스터, 사용자, 컨텍스트를 이용해 인증해요. 클러스터 밖에서 kubectl을 실행하면 kubeconfig 파일을 사용해 API 서버 주소와 자격 증명을 찾아요. kubectl이 파드 안에서(CI/CD 파이프라인처럼) 실행될 때는 파드에 마운트된 ServiceAccount 토큰을 기반으로 클러스터 내부 인증(in-cluster authentication)을 사용할 수 있어요.

명령을 실행하면 kubectl은 사용자의 의도를 쿠버네티스 API에 대한 하나 이상의 HTTP 요청으로 변환해요. API 서버는 각 요청을 검증하고, etcd에 저장된 클러스터 상태에 적용한 뒤 결과를 반환해요. 즉 Deployment를 만들든 로그를 읽든, 모든 kubectl 동작은 같은 API 주도 경로를 따라간다는 뜻이에요.

kubeconfig가 여러 클러스터, 사용자, 컨텍스트를 정의할 수 있기 때문에, 환경을 재구성하지 않고도 kubectl로 클러스터 사이를 전환할 수 있어요. 활성 컨텍스트를 바꾸려면 kubectl config use-context를 실행하세요.

kubectl로 할 수 있는 일 (What you can do with kubectl)

kubectl 도구는 많은 작업을 지원하며, 이들은 크게 다음과 같이 분류돼요.

  • 리소스 관리 – Pod, Deployment, Service 같은 객체를 만들고, 업데이트하고, 삭제해요. 구성 파일로부터의 선언적 관리를 위해 kubectl apply를 사용해요.
  • 클러스터 상태 검사 – 객체를 나열하고 설명하며, 이벤트를 보고, 리소스 사용량을 확인해요.
  • 디버그 – 컨테이너의 로그를 보고, 실행 중인 컨테이너 안에서 명령을 실행하거나, 파드로 포트 포워딩해요.
  • 클러스터 작업 – 유지보수를 위해 노드를 드레인하고, 새 워크로드를 막기 위해 노드를 cordon하며, 클러스터 구성을 관리해요.
  • 스크립트 및 자동화 – 스크립트와 파이프라인에서 사용하기 위해 JSON, YAML, 또는 JSONPath를 이용한 사용자 지정 컬럼으로 출력을 포맷해요.

구문, 명령 참조, 예제는 kubectl 참조 문서를 참고하세요.

선언적 vs 명령적 (Declarative vs imperative)

프로덕션 워크로드에서는 버전 관리되는 구성 파일과 함께 kubectl apply를 사용하는 선언적 객체 관리를 선호해요. 선언적 관리는 변경 사항 추적, 협업, GitOps 워크플로와의 통합에 도움이 돼요. 명령적 커맨드(kubectl create, kubectl run 등)는 개발과 실험에 유용하지만, 재현하고 감사하기가 더 어려워요.

플러그인으로 kubectl 확장하기

새 하위 명령을 추가하는 플러그인으로 kubectl을 확장할 수 있어요. 플러그인은 kubectl-<plugin-name> 명명 규칙을 따르는 독립 실행 바이너리예요. 쿠버네티스 커뮤니티는 많은 플러그인을 유지 관리하며, Krew 플러그인 매니저로 관리할 수 있어요.

버전 호환성 (Version compatibility)

kubectl 도구는 클러스터의 제어 플레인에 대해 마이너 버전 더하기/빼기 하나의 버전 스큐(skew)를 지원해요. 예를 들어 kubectl v1.32는 v1.31, v1.32, v1.33의 제어 플레인과 함께 동작해요. 호환되는 버전을 사용하면 예상치 못한 동작을 피할 수 있어요. 자세한 내용은 버전 스큐 정책을 참고하세요.

더 알아보기 (Learn more)