kubectl은 Kubernetes API 서버와 통신하는 명령줄 클라이언트다. Pod와 Deployment 조회, 선언 적용, 로그 확인 등 여러 작업을 자원 이름과 하위 명령으로 표현한다. 클러스터 전체를 실행하는 서버 프로그램이나 컨테이너 런타임은 아니다. 공식 명령 안내에서 자원·이름·출력 형식의 조합을 확인할 수 있다.
접속 대상과 명령 구조
kubeconfig는 클러스터 주소와 인증 방법, 컨텍스트 등을 연결한다. 컨텍스트에는 사용할 클러스터·사용자·기본 네임스페이스가 묶인다. 동일한 명령도 현재 컨텍스트에 따라 다른 환경에 적용될 수 있으므로 실제 작업 전에 대상을 확인해야 한다. 명령의 성공 여부는 서버에서 검증한 권한과 API 처리 결과에 달려 있다.
get은 목록이나 객체를 읽고, describe는 상태와 관련 이벤트를 사람이 보기 쉽게 풀어 준다. logs는 컨테이너 로그, explain은 자원 필드의 설명을 확인하는 데 쓰인다. apply와 delete는 서버 상태를 바꾸므로 조회 명령과 구별한다. 클라이언트와 서버의 버전 지원 범위는 설치 도구 안내에서 현재 문서를 따라 확인한다.
장점과 한계
표준 API를 일관된 명령으로 다루고 JSON·YAML 출력과 레이블 선택자를 조합할 수 있어 자동화에 적합하다. 웹 화면이 제공하지 않는 세부 필드도 조회할 수 있다. 반면 익숙한 짧은 명령을 잘못된 컨텍스트에서 실행하면 영향이 넓어질 수 있고, 사람이 읽는 표 출력을 그대로 파싱하는 자동화는 형식 변화에 취약하다.
kubectl은 관찰 시점의 상태를 보여 준다. 조회 직후 상태가 달라질 수 있으므로 화면에 보인 복제본 수만으로 작업 완료를 단정하지 않는다. 여러 자원을 연이어 변경하는 스크립트도 전체가 하나의 데이터베이스 트랜잭션이 되는 것은 아니다. 일부 실패와 재시도를 고려해야 한다.
예약 서비스 조회 예시
연습 클러스터의 reading-room 네임스페이스에 app: reservation 레이블을 붙인 Pod가 있다고 가정한다. reservation.yaml은 별도로 작성해 검토한 선언 파일이다. 다음 명령은 대상 확인, 조회, 선언 차이 점검의 순서이며 실제 적용 명령은 포함하지 않는다.
kubectl config current-context
kubectl get pods -n reading-room -l app=reservation -o wide
kubectl explain deployment.spec.replicas
kubectl diff -n reading-room -f reservation.yamlwide 출력의 노드와 Pod 주소는 배치를 이해하는 자료다. diff는 현재 상태와 적용 후 예상 상태의 차이를 보여 주며, 차이가 있다는 종료 상태를 단순 실행 실패와 구별해야 한다. 서버의 지원 API나 권한 때문에 비교 자체가 실패한 경우에는 오류 내용을 먼저 확인한다.
자주 생기는 오해
기본 네임스페이스를 생략한 채 다른 팀의 자원을 찾거나, 동일한 이름이 다른 네임스페이스에도 존재함을 놓치기 쉽다. 로그와 YAML 출력에는 민감한 값이 포함될 수 있다. 공개 예시에는 실제 kubeconfig·토큰을 넣지 않고, 공유 전에 필요한 필드만 추린다.