kubectl 명령어 찾기

맨 아래 Events 섹션에 스케줄 실패, 이미지 풀 실패, 프로브 실패 같은 원인이 시간순으로 찍힙니다. Pod 문제의 8할은 여기서 답이 나와요.

tail -f처럼 로그를 스트리밍합니다. Deployment 전체를 보려면 kubectl logs -f deployment/<name>도 가능해요.

CrashLoopBackOff일 때 현재 로그는 비어 있기 일쑤입니다. --previous로 직전에 죽은 컨테이너의 마지막 로그를 봐야 크래시 원인이 보여요.

사이드카가 있는 Pod는 -c로 컨테이너를 지정해야 합니다. 모든 컨테이너를 한 번에 보려면 --all-containers=true를 쓰세요.

--since는 시간 기준(10m, 1h), --tail은 줄 수 기준으로 자릅니다. 로그가 수만 줄일 때 터미널이 터지는 것을 막아줘요.

기본 출력은 순서가 뒤죽박죽이라 --sort-by가 사실상 필수입니다. 특정 Pod만 보려면 --field-selector involvedObject.name=<pod>을 붙이세요.

metrics-server가 설치되어 있어야 동작합니다. --containers를 붙이면 컨테이너 단위로 쪼개 보여줘서 사이드카가 리소스를 먹는지도 알 수 있어요.

노드마다 CPU 코어/메모리 사용량과 비율을 보여줍니다. 특정 노드만 Pod가 안 뜨면 여기서 리소스 포화 여부부터 확인하세요.

-A는 --all-namespaces의 축약입니다. "분명 배포했는데 안 보인다" 싶으면 십중팔구 다른 네임스페이스에 있으니 -A로 먼저 찾으세요.

-l(--selector)로 라벨이 일치하는 리소스만 필터링합니다. app=<name>,tier!=frontend처럼 콤마로 조건을 겹칠 수도 있어요.

-w(--watch)는 상태가 바뀔 때마다 새 줄을 출력합니다. 화면을 통째로 갱신하고 싶다면 watch kubectl get pods처럼 리눅스 watch와 조합하세요.

-o wide는 기본 출력에 노드명, Pod IP, 예약된 노드 등을 추가합니다. 특정 노드에만 문제가 몰릴 때 분포 확인용으로 좋아요.

컨테이너 안에서 대화형 셸을 엽니다. bash가 설치된 이미지라면 -- bash가 편해요. 컨테이너가 여러 개면 -c <container>로 지정하세요.

-it 없이 명령만 넘기면 결과만 받아옵니다. 환경변수 확인(env), 파일 확인(ls, cat) 같은 단발성 점검에 좋아요. -- 뒤가 컨테이너에서 실행됩니다.

distroless처럼 셸이 없는 이미지에 임시(ephemeral) 컨테이너를 붙입니다. --target으로 대상 컨테이너의 프로세스 네임스페이스를 공유해 ps로 프로세스도 볼 수 있어요.

노드의 호스트 파일시스템이 /host에 마운트된 특권 Pod를 띄워줍니다. SSH 없이 노드의 로그나 설정을 확인할 수 있어요. 끝나면 생성된 디버그 Pod를 지워주세요.

컨테이너 안 파일을 로컬로, 반대로 로컬 파일을 컨테이너로 복사합니다. 컨테이너에 tar 바이너리가 있어야 동작한다는 점만 기억하세요.

Deployment/ReplicaSet이 관리하는 Pod라면 지워도 곧바로 새 Pod가 뜹니다. 사실상 "Pod 한 개 재시작"으로 쓰여요. 관리자 없는 단독 Pod는 그냥 사라지니 주의하세요.

일회용 Pod를 띄우고 셸을 엽니다. --rm 덕분에 셸을 빠져나오면 Pod가 자동 삭제돼요. 클러스터 내부 네트워크나 DNS를 테스트할 때 가장 빠른 방법입니다.

exec가 새 프로세스를 띄우는 반면 attach는 이미 실행 중인 메인 프로세스(PID 1)의 stdin/stdout에 붙습니다. 대화형 CLI 앱을 조작할 때 씁니다.

Pod들을 롤링 방식으로 순차 교체합니다. 다운타임 없이 ConfigMap/Secret 변경을 다시 읽게 하거나, 이상 상태를 리셋할 때 가장 안전한 재시작 방법이에요.

지정한 컨테이너의 이미지만 교체하고 롤링 업데이트를 시작합니다. 빠른 핫픽스 배포에 편리하지만, GitOps를 쓰는 팀이라면 선언된 YAML과 어긋나니 주의하세요.

롤아웃이 끝날 때까지 진행 상황을 출력하고, 완료/실패 시 종료 코드로 알려줍니다. CI/CD 파이프라인에서 배포 성공 판정 단계로 넣기 좋아요.

리비전 목록을 보여줍니다. --revision=<n>을 붙이면 해당 리비전의 상세 스펙(이미지 등)까지 확인할 수 있어요. CHANGE-CAUSE를 채우려면 apply 시 주석을 남기세요.

직전 리비전으로 롤백합니다. 특정 리비전으로 돌아가려면 --to-revision=<n>을 붙이세요. 응급 상황엔 최고지만, 롤백 후 Git의 매니페스트도 꼭 맞춰 놓아야 해요.

즉시 Pod 수를 조절합니다. --replicas=0으로 잠시 서비스를 내릴 수도 있어요. HPA가 붙어 있다면 곧 다시 조정해 버리니 HPA 설정을 함께 확인하세요.

pause 중에는 스펙을 여러 번 고쳐도 롤아웃이 시작되지 않다가, resume 시 한 번에 반영됩니다. 여러 변경을 하나의 리비전으로 묶고 싶을 때 유용해요.

현재/목표 메트릭과 레플리카 수를 보여줍니다. TARGETS가 unknown이면 metrics-server 문제이거나 리소스 requests가 없는 경우가 대부분이에요. 자세히는 describe hpa로 보세요.

CPU 사용률 기준 HPA를 명령어 한 줄로 만듭니다. 동작하려면 컨테이너에 resources.requests.cpu가 설정되어 있어야 한다는 점이 함정 포인트예요.

선언형 관리의 기본 명령입니다. 리소스가 없으면 만들고, 있으면 차이만 병합해 갱신해요. 디렉터리 전체는 -f dir/, 하위까지는 -R을 붙입니다.

create는 명령형으로 "새로 생성"만 하며 이미 있으면 에러가 납니다. 반복 반영이 필요한 운영 매니페스트는 apply, 일회성 생성이나 스크립트에서 중복 생성을 잡아내고 싶을 때는 create가 어울려요.

apply가 기존 값과 병합하는 것과 달리 replace는 리소스 전체를 파일 내용으로 덮어씁니다. 파일에 없는 필드는 날아가고, 리소스가 없으면 실패해요. --force는 삭제 후 재생성이라 더 위험합니다.

기본 에디터(KUBE_EDITOR)로 라이브 리소스를 열어 저장하면 즉시 반영됩니다. 응급 대응에는 빠르지만 Git에 남지 않는 스노우플레이크 변경이 되기 쉬우니, 조치 후 매니페스트에 꼭 반영하세요.

JSON 조각만 보내 특정 필드를 수정합니다. 에디터 없이 스크립트에서 자동화할 때 좋아요. 기본은 strategic merge patch이고, --type=json으로 JSON Patch 배열도 쓸 수 있습니다.

실제로 만들지 않고(--dry-run=client) 매니페스트만 출력합니다. > deploy.yaml로 저장해 뼈대로 쓰면 YAML을 손으로 짜는 것보다 훨씬 빠르고 오타도 없어요.

라이브 상태와 파일의 차이를 diff 형식으로 보여줍니다. 배포 전 마지막 안전장치로 습관 들이면 "어, 이것까지 바뀌네?" 사고를 막을 수 있어요.

key=value로 추가, key-(마이너스)로 제거합니다. 이미 있는 라벨을 바꿀 때는 --overwrite가 필요해요. 서비스 셀렉터에서 Pod를 잠시 빼는 트릭에도 쓰입니다.

파일에 정의된 리소스를 모두 삭제합니다. 여러 리소스가 든 파일이라면 전부 사라지니, 지우기 전에 파일 내용을 한 번 훑어보는 습관을 들이세요.

로컬 8080 포트를 서비스의 80 포트로 터널링합니다. Ingress 없이도 localhost:8080으로 바로 테스트할 수 있어요. Pod 하나를 집으려면 svc/ 대신 Pod 이름을 쓰면 됩니다.

ENDPOINTS가 비어 있으면 셀렉터와 Pod 라벨이 안 맞거나 Pod가 Not Ready라는 뜻입니다. "서비스가 504를 뱉어요"의 단골 원인이라 네트워크 디버깅의 1순위 확인 항목이에요.

임시 Pod에서 nslookup으로 서비스 DNS를 조회합니다. 서비스 풀네임은 <service>.<namespace>.svc.cluster.local 형식이에요. 안 풀리면 CoreDNS Pod 상태부터 확인하세요.

curl이 든 임시 Pod에서 curl http://<service>.<namespace>로 내부 통신을 테스트합니다. NetworkPolicy나 서비스 설정 문제를 로컬 환경 변수 없이 순수하게 검증할 수 있어요.

Deployment의 셀렉터를 그대로 물려받은 Service를 생성합니다. --type=NodePort나 LoadBalancer로 노출 방식도 정할 수 있어요. --dry-run=client -o yaml과 조합하면 YAML 뼈대 생성기로도 씁니다.

호스트, 경로, 백엔드 서비스 매핑을 보여줍니다. describe에서 Backends가 <none>이거나 주소가 비어 있으면 서비스 이름/포트 오타를 의심하세요.

갑자기 Pod 간 통신이 안 되면 NetworkPolicy가 기본 차단(deny-all)을 걸고 있는 경우가 많습니다. describe로 podSelector와 ingress/egress 규칙을 대조해 보세요.

STATUS가 Bound면 정상, Pending이면 아직 볼륨을 못 받은 상태입니다. Pending 원인은 describe pvc의 Events에서 StorageClass 미존재, 용량 부족 등으로 확인할 수 있어요.

Events에 "no persistent volumes available", "storageclass not found" 같은 구체적 사유가 찍힙니다. WaitForFirstConsumer 모드라면 Pod가 스케줄될 때까지 Pending이 정상이에요.

PV는 클러스터 전역 리소스라 네임스페이스가 없습니다. CLAIM 컬럼으로 바인딩된 PVC를, RECLAIM POLICY로 PVC 삭제 시 데이터 운명(Retain/Delete)을 확인하세요.

이름 옆에 (default)가 붙은 것이 storageClassName을 생략했을 때 쓰이는 기본 클래스입니다. 기본값이 없으면 PVC가 조용히 Pending에 머무니 꼭 확인하세요.

노드를 SchedulingDisabled로 표시해 새 Pod 배치만 막습니다. 이미 떠 있는 Pod는 건드리지 않아서 drain보다 훨씬 안전한 첫 단계예요.

cordon/drain으로 막았던 노드를 다시 스케줄 대상으로 되돌립니다. drain 후 재부팅했다면 uncordon을 잊는 순간 노드가 계속 놀게 되니 체크리스트에 꼭 넣으세요.

toleration이 없는 Pod는 이 노드에 스케줄되지 않습니다. GPU 노드나 전용 노드를 분리할 때 쓰는 표준 방법이에요. NoExecute를 쓰면 이미 떠 있는 Pod까지 쫓아내니 주의하세요.

끝에 마이너스(-)를 붙이면 해당 taint가 제거됩니다. 어떤 taint가 걸려 있는지는 kubectl describe node의 Taints 항목에서 확인할 수 있어요.

Conditions(MemoryPressure, DiskPressure 등), Taints, 그리고 Allocated resources에서 requests 합계를 보여줍니다. "리소스는 남는데 왜 못 뜨지?"의 답은 대부분 requests 초과 예약이에요.

yes/no로 바로 답해줍니다. 전체 권한 목록은 kubectl auth can-i --list -n <namespace>로 확인할 수 있어요. Forbidden 에러가 났을 때 첫 번째로 두드려 볼 명령입니다.

--as로 특정 주체를 가장해 권한을 점검합니다. RBAC Role을 만든 뒤 실제로 의도대로 동작하는지 배포 전에 검증하는 필수 절차예요.

--from-literal로 키-값을, --from-file로 파일 내용을 담습니다. 셸 히스토리에 비밀값이 남을 수 있으니 운영에서는 --from-file이나 외부 시크릿 매니저를 권장해요.

Secret 데이터는 base64 인코딩일 뿐 암호화가 아닙니다. jsonpath로 키 하나를 뽑아 base64 -d로 풀면 원문이 보여요. 화면 공유 중에는 조심하세요.

파일 전체를 하나의 키로 담습니다. --from-literal=key=value로 개별 값도 추가할 수 있어요. 변경 후에는 Pod가 자동 반영하지 않는 경우가 많아 rollout restart가 필요합니다.

data 섹션에서 실제 설정 내용을 확인합니다. Pod에 마운트된 값과 ConfigMap 원본이 다르면 마운트 이후 갱신 전파(최대 1분가량) 또는 subPath 마운트(갱신 안 됨)를 의심하세요.

단기 만료 토큰을 즉석에서 발급합니다(k8s 1.24+ 표준 방식). CI나 외부 시스템에서 임시로 API를 호출할 때 시크릿을 영구 저장하는 것보다 안전해요.

kubeconfig에 등록된 컨텍스트를 전환합니다. 지금 어디에 붙어 있는지는 kubectl config current-context로 확인하세요. 운영/개발 클러스터를 헷갈리는 사고의 예방책이기도 합니다.

현재 컨텍스트에 *가 표시됩니다. 컨텍스트별 클러스터, 사용자, 기본 네임스페이스까지 한 줄로 보여줘서 kubeconfig 정리 상태를 점검하기 좋아요.

현재 컨텍스트의 기본 네임스페이스를 바꿉니다. 이후 -n 없이 친 명령이 모두 이 네임스페이스를 대상으로 하니, 운영 클러스터에서는 바꿔 둔 사실 자체를 잊지 않도록 주의하세요.

KUBECONFIG에 콜론으로 파일들을 이어주면 view --flatten이 하나로 합쳐줍니다. 완성본을 확인한 뒤 ~/.kube/config로 교체하세요. 원본은 반드시 백업해 두는 것이 안전합니다.

리소스 이름, 축약어(po, svc, deploy...), API 그룹, 네임스페이스 소속 여부를 보여줍니다. CRD 설치 후 새 리소스가 등록됐는지 확인할 때도 유용해요.

API 서버와 CoreDNS 엔드포인트를 보여줍니다. 연결 자체가 안 될 때 "내가 지금 어느 클러스터를 보고 있나"를 확인하는 첫 명령으로 좋아요.

리소스 스키마 문서를 터미널에서 바로 조회합니다. --recursive를 붙이면 하위 필드 트리를 통째로 보여줘서 브라우저 없이도 YAML 구조를 파악할 수 있어요.

위험한 명령을 치기 전 습관처럼 확인하세요. 네임스페이스까지 보려면 kubectl config get-contexts에서 현재(*) 줄을 보면 됩니다. 프롬프트에 표시해 주는 kube-ps1 같은 도구도 좋아요.

순서가 중요합니다. 먼저 --previous로 죽기 직전 로그(앱 에러)를 보고, describe의 Events와 Last State(Exit Code, OOMKilled 여부)로 인프라 원인을 교차 확인하세요.

Events에 "Insufficient cpu/memory"(리소스 부족), "didn't match node selector"(노드 조건 불일치), "unbound PVC"(볼륨 문제) 같은 스케줄 실패 사유가 그대로 적혀 있습니다.

Events에서 원인이 갈립니다. "not found"면 이미지명/태그 오타, "unauthorized"면 imagePullSecrets 누락, 타임아웃이면 레지스트리 네트워크 문제예요. 노드에서 직접 pull해 보는 것도 좋은 분리 실험입니다.

OOMKilled가 출력되면 메모리 limits를 초과해 커널이 죽인 겁니다. limits를 올리거나 앱의 메모리 사용을 줄여야 해요. Exit Code 137도 같은 신호입니다.

구식 get componentstatuses는 deprecated라 이 방법이 표준입니다. etcd, 각 컨트롤러의 체크 항목별 ok 여부를 보여줘요. livez, healthz 엔드포인트도 같은 방식으로 조회할 수 있습니다.

재시작 횟수 순으로 정렬해 문제아를 바로 찾습니다. 맨 아래(가장 많은 재시작)부터 --previous 로그와 describe로 파고들면 돼요.

라이브 상태를 YAML로 덤프합니다. status나 managedFields 같은 런타임 필드가 섞여 있으니, 재사용할 매니페스트로 쓰려면 해당 부분을 정리한 뒤 저장하세요.

JSONPath로 특정 필드만 추출합니다. range를 쓰면 줄바꿈 포함 반복 출력도 가능해요: '{range .items[*]}{.metadata.name}{"\n"}{end}'. 셸 스크립트 자동화의 핵심 도구입니다.

jsonpath보다 읽기 좋은 표 형태로 커스텀 뷰를 만듭니다. 자주 쓰는 조합은 셸 alias로 등록해 두면 나만의 대시보드가 돼요.

Operator들이 설치한 커스텀 리소스 정의 목록입니다. 특정 CRD의 인스턴스는 kubectl get <crd-name>으로, 스키마는 kubectl explain <crd-name>으로 조회하세요.

라벨이 아닌 리소스 필드로 필터링합니다. spec.nodeName=<node>로 특정 노드의 Pod만 보는 것도 단골 패턴이에요. 지원 필드가 제한적이라 안 되면 jsonpath로 우회합니다.

노드 압박으로 쫓겨난(Evicted) Pod 기록들이 목록을 어지럽힐 때 일괄 삭제합니다. 실행 중인 Pod는 Failed가 아니라 안전하지만, -A 범위이니 결과 목록을 한 번 확인하고 지우는 것을 추천해요.

가장 오래된 Pod부터 정렬됩니다. 최근에 뜬 Pod를 찾거나, 배포가 실제로 Pod를 교체했는지 확인할 때 유용해요. 메모리 사용 순 정렬은 top pod와 조합하세요.

-v=6~9로 요청 URL, 헤더, 응답 본문까지 단계별로 보여줍니다. kubectl 동작을 컨트롤러/스크립트 코드로 옮길 때 API 경로를 알아내는 최고의 학습 도구예요.

kubeconfig 인증을 대신 처리해 주는 로컬 프록시를 엽니다. curl localhost:8001/api/v1/namespaces처럼 REST API를 탐험할 수 있어요. 학습과 디버깅용으로만 쓰고 외부 노출은 금물입니다.

클러스터가 지원하는 API 그룹/버전 목록입니다. 클러스터 업그레이드 후 "no matches for kind" 에러가 나면 여기서 해당 버전이 사라졌는지 확인하세요.