[K8S] 자주 사용하는 Kubernetes CLI 정리

개요

---

업무를 하면서 점점 파드에 접근해서 정보를 확인할 일이 늘어나고 있다. 온콜이나 장애 상황 시에 노션에 붙여둔 명령어를 일일이 찾아보는게 허들이라 느껴져서 아예 블로그에 정리해보기로 했다!

 

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란?

컨텍스트에는 다음과 같은 정보가 담겨있다.

1. Cluster: 연결할 k8s 클러스터의 API 서버 주소와 인증서 정보
2. User: 해당 클러스터에 접속할 때 사용할 사용자 인증 정보(토큰, 인증서, AWS IAM 등)
3. 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 명령어를 많이 사용해서 정리해보았따.

장애 일지 보면서 필요한 명령어들은 조금씩 더 추가해볼 예정이다.

쿠베 공부 부단히 해야겠다 ㅠ_ㅠ