개요
업무를 하면서 점점 파드에 접근해서 정보를 확인할 일이 늘어나고 있다. 온콜이나 장애 상황 시에 노션에 붙여둔 명령어를 일일이 찾아보는게 허들이라 느껴져서 아예 블로그에 정리해보기로 했다!
Kubectl
Kubernetes API를 사용해서 쿠버네티스 클러스터의 컨트롤 플레인과 통신하기 위한 커맨드 라인 툴이다.
- 리소스 관리: Pod, Service, Deployment, ConfigMap 등 k8s 리소스를 생성하고 관리할 수 있다. YAML 파일을 통해 선언적으로 리소스를 정의하거나 명령형 커맨드로 직접 다룰 수 있다.
- 클러스터 상태 확인: 클러스터에서 실행 중인 애플리케이션의 상태, 노드 정보, 이벤트 로그 등을 조회할 수 있다.
- 애플리케이션 배포 및 업데이트: 컨테이너 이미지를 배포하고, 롤링 업데이트를 수행하며, 필요 시 롤백할 수 있다.
0. aws-vault 로그인
나의 경우 aws-vault를 사용하고 있기에, 클러스터 접근을 위한 특정 프로필을 사용하여 로그인을 한다.
aws-vault exec daangn/prod -- zsh
aws-vault exec daangn/alpha -- zsh
aws-vault exec daangn/data -- zsh
- ~/.aws/config 하위에 정의된 자격 증명에 관련한 프로필로 인증한 뒤, aws에 접근할 수 있다.
- —zsh : aws-vault 실행 후 zsh 셸을 시작한다는 뜻!
1. cluster contexts 확인 및 등록
1.1 cluster contexts란?
컨텍스트에는 다음과 같은 정보가 담겨있다.
- Cluster: 연결할 k8s 클러스터의 API 서버 주소와 인증서 정보
- User: 해당 클러스터에 접속할 때 사용할 사용자 인증 정보(토큰, 인증서, AWS IAM 등)
- Namespace: 기본으로 작업할 네임스페이스
작업을 하기 전에 항상 이 컨텍스트를 확인해야 한다. 그래서 나의 경우는 kube-ps1을 통해 터미널 가장 앞 쪽에 현재 접속중인 context가 표시 되도록 해두었다! 컨텍스트 실수로 인한 프로덕션 장애가 발생하는 경우가 실제로도 종종 있다. 예를 들어서, 개발 서버를 살제하려다가 실수로 프로덕션에서 실행하는..😱 실수는 누구나 할 수 있으니까 이 컨텍스트의 중요성을 알고, kube-ps1과 같은 도구를 활용하자!
1.2 cluster contexts 정보 확인하기
# 로컬 kube config 정보를 통해 로컬 환경에 등록되어 있는 컨텍스트 확인
kubectl config get-contexts
# 콘솔 eks 클러스터 확인
aws eks list-clusters --region ap-northeast-2
로컬 ↔ 콘솔에 등록된 클러스터 컨텍스트를 비교하고, 작업이 필요한 클러스터가 있다면 context를 등록해준다.
1.3 로컬 환경에 contexts 등록 및 사용하기
⚫️ eks update-kubeconfig로 로컬 config 업데이트
aws eks update-kubeconfig --name ${cluster} --region ap-northeast-2 --alias ${cluster}
나의 경우, 콘솔에 없는 kmkr 클러스터 컨텍스트를 위 명령어를 통해 추가해주었다.
- 이 kubeconfig는 개인 설정 파일(~/.kube/config)에 나의 kubectl이 클러스터에 연결하는 방법을 정의하는 명령어다.
⚫️ config use-context로 사용할 컨텍스트 지정
kubectl config use-context ${cluster}

2. Namespace 접근
use-context를 통해 특정 클러스터에 접근했다면, 이제 그 하위 namespace에 접근할 수 있다.
2.1 namespace란?
namespace는 클러스터를 하나의 큰 건물이라고 치면, 건물 내부 방이다. namespace는 동일한 물리적 클러스터를 여러 가상 클러스터로 나누는 방법으로, 단일 클러스터 내에서 리소스 그룹을 격리하는 메커니즘이다. (자세한 namespace 내용)
2.2 namespace 목록 추출 및 접근
# 모든 네임스페이스 목록 확인
kubectl get namespaces
kubectl get ns

- STATUS: namgspace 상태
- active: 정상 작동 중
- terminating: 삭제 중
- AGE: namespace가 생성된 후 경과 시간
2.3 특정 Namespace의 Pod 확인
보통 특정 namespace의 pod에 접근해서 리소스 상태를 확인하는 작업이 많다. 아래와 같은 명령어로 특정 네임스페이스의 pod들을 확인할 수 있다.
kubectl get pods -n ${namespace}

⚫️ Pod는 Node Group의 컨테이너인데, namespace로 접근하는 이유는?
실제로 Pod는 Node 위에서 실행되지만, 여러 이유로 다른 Node로 이동을 하게 된다.
- Node 장애 시 다른 Node로 스케줄링
- Node 유지보수를 위한 Pod drain
- 새 노드가 추가되면 Pod 재배치
📁 물리적 구조(실제 Pod가 실행되는 곳)
Cluster
ㄴ Node1 (EC2 인스턴스)
ㄴ Pod A (production namespace)
ㄴ Pod B (development namespace)
ㄴ Pod C (production namespace)
ㄴ Node2 (EC2 인스턴스)
ㄴ Pod D (monitoring namespace)
ㄴ Pod E (production namespace)
📁 논리적 구조(실제 우리가 관리하는 방식)
Cluster
ㄴ production namespace
ㄴ Pod A (Node1에서 실행 중)
ㄴ Pod C (Node1에서 실행 중)
ㄴ Pod E (Node2에서 실행 중)
ㄴ development namespace
ㄴ Pod B (Node1에서 실행 중)
ㄴ monitoring namespace
ㄴ Pod D (Node2에서 실행 중)
3. Pod 상세 정보
3.1 get으로 pod 상태 확인하기
# Pod 빠르게 확인
kubectl get pods -n ${namespace}
# Node, IP 정보까지 확인
kubectl get pods -n ${namespace} -o wide

- READY: 준비된 컨테이너 수 / 전체 컨테이너 수를 나타낸다.
- 1/2의 경우, 메인 앱은 정상이고 사이드카는 죽은 상태다.
3.2 get + grep 조합으로 Pod Status 필터링 하기
kubectl get pods -n production | grep Error
kubectl get pods -n production | grep Pending
kubectl get pods -n production | grep CrashLoopBackOff
kubectl get pods -n production | grep Terminating
- Error: 컨테이너가 exit code로 종료된 상황이다. 애플리케이션 에러로 파드가 죽은 경우
- Pending: Pod가 Scheduling 대기 중인 상태다. 주로 리소스 부족이나 노드 조건 불일치에 의해 발생한다.
- CrashLoopBackOff: 컨테이너가 시작 → 죽음 → 재시작을 반복하고 있는 상황이다.
- Terminating: Pod가 삭제 중인데 아직 완전히 사라지지 않은 상태로, 보통 graceful shutdown 대기중인 상태다.
- ImagePullBackOff: 이미지 다운로드가 실패한 상황이다.
3.3 Pod 로그 확인
kubectl logs --tail=${n} ${pod} -n ${namespace}
- --tail 옵션을 통해 최근 n줄에 대한 로그를 출력한다
3.4 Pod 리소스 사용량 확인 / 조정
kubectl top pods -n ${namespace}

top 명령어를 통해 개별 Pod의 리소스 사용량을 확인할 수 있다. CPU = 8m 이라는 것은 CPU를 0.8% 사용하고 있다는 뜻이다. 만약 CPU에 950m와 같은 수치가 보인다면 한 Pod가 CPU를 95% 사용하고 있다는 뜻으로, 리소스를 비효율적으로 사용하고 있음을 의심해볼 수 있다.
⚫️ Pod는 Node의 리소스를 할당 받아 사용한다.
Pod는 개별 CPU/Memory를 가지는 것이 아니라, Node의 리소스를 할당 받아서 사용한다. 즉, 다음과 같은 구조를 가진다.
Node (EC2 인스턴스: t3.xlarge)
├── 실제 리소스: 4 CPU cores, 16GB RAM
│
├── ⚫️ Pod A: 1 CPU, 2GB 할당받음
├── ⚫️ Pod B: 0.5 CPU, 1GB 할당받음
├── ⚫️ Pod C: 2 CPU, 4GB 할당받음
└── 남은 리소스: 0.5 CPU, 9GB
3.5 describe로 Pod 세팅 상세 확인하기
kubectl describe pod ${pod} -n ${namespace}
단순 get pod, top pod 명령어와 다르게 해당 Pod에 설정된 구체적인 내용들(IP, Port, Liveness, Readiness 등등)을 확인할 수 있다.
K8S도 GUI 환경을 제공하지만 보통 업무를 할 때 kubectl 명령어를 많이 사용해서 정리해보았따.
장애 일지 보면서 필요한 명령어들은 조금씩 더 추가해볼 예정이다.
쿠베 공부 부단히 해야겠다 ㅠ_ㅠ
'DevOps > DevOps' 카테고리의 다른 글
| [DevOps] SSH 없이 안전하게 EC2 운영하기: SSM 기반 접근 제어와 전역 정책 설계 (0) | 2025.12.07 |
|---|---|
| [DevOps] Redis 7.x → Valkey 8.x 마이그레이션 PoC (1) | 2025.08.25 |
| [DevOps] 멀티모듈 프로젝트 CI/CD 적용 - 설계 구상 편 (3) | 2024.07.22 |
| [Redis] Redis 4편. 운영 방식과 호스팅 (0) | 2024.01.08 |
| [Redis] Redis 3편. Spring Boot와 Redis | Lettuce, RedisTemplate, RedisRepository (1) | 2024.01.08 |