k9s 사용법 - v.50.x

 

 

 

 

목차

 

 

---

1. 설치 (Windows)

# Chocolatey
choco install k9s

# Winget
winget install k9s

# Scoop
scoop install k9s

현재 최신 버전: v0.50.16

---

2. 기본 실행 옵션

k9s                              # 기본 실행
k9s --context prod-cluster       # 특정 컨텍스트로 시작
k9s -n kube-system               # 특정 네임스페이스로 시작
k9s --readonly                   # 읽기 전용 모드
k9s --kubeconfig /path/to/config # 특정 kubeconfig 사용
k9s -l debug                     # 디버그 로그 활성화
k9s info                         # 설정/로그 경로 확인

---

3. 핵심 단축키

3.1 네비게이션

 

키	동작
?	도움말 (현재 화면 단축키)
Ctrl+A	모든 리소스 별칭 표시
Esc	이전 화면으로
:q / Ctrl+C	종료
j/k 또는 ↑/↓	위/아래 이동
g / G	맨 위/맨 아래로
Enter	선택/진입
[ / ]	명령 히스토리 이전/다음

3.2 리소스 명령어

 

명령어	설명
:pod	Pod 목록
:deploy	Deployment 목록
:svc	Service 목록
:ns	Namespace 목록
:node	Node 목록
:ctx	Context 전환
:cm	ConfigMap
:secret	Secret
:ing	Ingress
:pv / :pvc	PersistentVolume
:cj	CronJob
:job	Job
:rs	ReplicaSet
:sts	StatefulSet
:ds	DaemonSet
:hpa	HorizontalPodAutoscaler
:ro	Rollout (Argo Rollouts)
:helm	Helm 릴리스

3.3 리소스 작업

 

키	동작
d	Describe (상세 정보)
e	Edit (편집)
l	Logs (로그 보기)
y	YAML 보기
v	View (상세 뷰)
s	Shell (컨테이너 접속)
a	Attach (컨테이너 연결)
Shift+f	Port Forward
Ctrl+d	Delete (확인 필요)
Ctrl+k	Kill (즉시 삭제)
r	Restart (재시작)
c	Copy (클립보드 복사)

3.4 Pod 전용

 

키	동작
l	로그 보기
p	이전 컨테이너 로그
Shift+l	로그 Follow 모드
s	Shell 접속
Shift+s	컨테이너 선택 후 Shell

---

4. 검색 & 필터링

# 기본 필터 (정규식)
/nginx           # "nginx" 포함 리소스

# 역필터
/!nginx          # "nginx" 제외

# 라벨 필터
/-l app=web      # app=web 라벨 가진 리소스
/-l app=web,env=prod  # 복수 라벨

# 퍼지 검색
/-f ngx          # fuzzy 매칭

# 네임스페이스 지정
:pod kube-system # kube-system의 Pod
:pod -A          # 모든 네임스페이스

# 컨텍스트 지정
:pod @ctx1       # 특정 컨텍스트의 Pod

---

5. 고급 기능

5.1 XRay 뷰 (리소스 관계 분석)

:xray po         # Pod XRay - 리소스 간 관계 시각화
:xray deploy     # Deployment XRay

5.2 Popeye (클러스터 상태 검사)

:popeye          # 클러스터 상태 점검 및 개선점 제안

5.3 Pulses (실시간 모니터링)

:pulses          # 실시간 리소스 변경 추적

5.4 벤치마킹

# Service 선택 후
b                # HTTP 벤치마크 실행

5.5 Screendump

:screendump      # 저장된 리소스 스냅샷 보기
Ctrl+s           # 현재 화면 저장

---

6. 설정 파일

6.1 파일 위치

Windows: %LOCALAPPDATA%\\k9s\\

%LOCALAPPDATA%\\k9s\\
├── config.yaml      # 메인 설정
├── aliases.yaml     # 사용자 정의 별칭
├── hotkeys.yaml     # 커스텀 단축키
├── plugins.yaml     # 플러그인 설정
└── skins/           # 테마 파일

6.2 config.yaml 예시

k9s:
  refreshRate: 2              # UI 새로고침 간격 (초)
  maxConnRetry: 5             # API 연결 재시도 횟수
  readOnly: false             # 읽기 전용 모드
  apiServerTimeout: 15s       # API 서버 타임아웃

  ui:
    enableMouse: false        # 마우스 지원 활성화
    headless: false           # 헤더 숨김
    logoless: true            # 로고 숨김
    skin: dracula             # 테마 선택
    noIcons: false            # 아이콘 비활성화

  logger:
    tail: 500                 # 로그 라인 수
    buffer: 5000              # 로그 버퍼 크기
    sinceSeconds: 300         # 지난 5분 로그 조회
    showTime: true            # 타임스탬프 표시

6.3 aliases.yaml (커스텀 별칭)

aliases:
  pp: v1/pods
  dp: apps/v1/deployments
  ss: apps/v1/statefulsets
  ro: argoproj.io/v1alpha1/rollouts  # Argo Rollouts
  vs: networking.istio.io/v1beta1/virtualservices  # Istio

6.4 hotkeys.yaml (커스텀 단축키)

hotKeys:
  shift-r:
    shortCut: Shift-R
    description: Restart deployment
    command: kubectl
    background: false
    args:
      - rollout
      - restart
      - $NAME

  shift-t:
    shortCut: Shift-T
    description: Top pods
    command: kubectl
    background: false
    args:
      - top
      - pods

6.5 환경변수

K9S_CONFIG_DIR=/custom/path k9s        # 설정 디렉토리 변경
K9S_LOGS_DIR=/var/log k9s              # 로그 디렉토리 변경
K9S_SKIN=dracula k9s                   # 테마 지정
K9S_DEFAULT_PF_ADDRESS=192.168.1.100   # 기본 포트포워드 주소

---

7. 실용적인 워크플로우

7.1 Pod 트러블슈팅

1. :pod [네임스페이스]  → Pod 목록
2. /문제pod            → 필터링
3. d                   → Describe로 상태 확인
4. l                   → 로그 확인
5. s                   → Shell 접속하여 디버깅

7.2 Deployment 스케일링

1. :deploy             → Deployment 목록
2. 선택 후 s           → Scale 메뉴
3. 원하는 replica 수 입력

7.3 Port Forward

1. :pod                → Pod 선택
2. Shift+f             → Port Forward 설정
3. 로컬포트:원격포트 입력 (예: 8080:80)

7.4 컨텍스트 전환 (Multi-cluster)

1. :ctx                → 컨텍스트 목록
2. Enter               → 선택한 컨텍스트로 전환

7.5 Argo Rollouts 관리

1. :ro                 → Rollout 목록
2. d                   → 상태 확인
3. r                   → Restart

7.6 로그 검색

1. :pod → 선택 → l     → 로그 진입
2. /error              → 로그 내 검색
3. n/N                 → 다음/이전 매치
4. 0                   → 처음부터 로그
5. Shift+g             → 최신 로그로

7.7 멀티 선택 작업

1. Space               → 리소스 선택/해제
2. Ctrl+Space          → 범위 선택
3. 선택 후 Ctrl+d      → 일괄 삭제

---

8. v0.50 신규 기능

 

기능	설명
GPU 벤더 확장	nvidia, nvidia-shared, amd, intel 지원
개선된 메모리 관리	대규모 클러스터 성능 향상
향상된 CRD 지원	Custom Resource 탐색 개선
Helm 통합	:helm으로 Helm 릴리스 직접 관리

---

9. 유용한 팁

9.1 빠른 네임스페이스 전환

:ns → 선택 → Enter
또는
:pod default   # 직접 지정

9.2 클립보드 복사

c              # 선택 리소스 이름 복사
y → c          # YAML 복사

9.3 로그 위치 확인

k9s info
# Logs: ~/.local/state/k9s/k9s.log (Linux)
# Logs: %LOCALAPPDATA%\\k9s\\k9s.log (Windows)

9.4 터미널 색상 문제 해결

export TERM=xterm-256color

---

10. Kubernetes 호환성

 

K9s 버전	K8s 클라이언트
>= v0.27.0	1.26.1+
v0.26.7 - v0.26.6	1.25.3
<= v0.24	1.21.3

권장: Kubernetes 1.28+

---

11. 참고 자료

• K9s 공식 사이트
• GitHub - derailed/k9s
• Chocolatey - k9s
• K9s Cheatsheet