G1Joshi/Agent-Skills

K9s CLI 전문가 지원: 터미널 기반 쿠버네티스 클러스터 탐색, 실시간 로그 스트리밍, 포트 포워딩, 파드 디버깅. 빠르게 쿠버네티스 클러스터를 관리하고 문제를 해결할 때 사용하세요.

Agent-Skills란 무엇인가요?

이 스킬은 K9s 터미널 UI를 통해 쿠버네티스 클러스터를 빠르고 효율적으로 관리하고 디버깅하는 방법을 제공합니다. K9s는 웹 대시보드보다 빠르고 kubectl보다 직관적인 인터페이스를 제공하여 파드, 서비스, 디플로이먼트 등을 실시간으로 탐색하고 모니터링할 수 있습니다. 주요 기능으로 실시간 로그 스트리밍, 리소스별 CPU/메모리 정렬, 포트 포워딩, 사용자 정의 플러그인 및 별칭 설정, 읽기 전용 모드를 통한 안전한 프로덕션 디버깅을 지원합니다. SKILL.md 문서는 K9s의 핵심 개념, 네비게이션 단축키, 사용자 정의 플러그인 설정(yaml), 보안 모드 실행 방법, 모범 사례, 일반적인 오류 해결 방법을 상세히 설명하여 쿠버네티스 관리자와 개발자에게 유용한 가이드를 제공합니다.

지원 대상~Claude Code~Codex CLI~Cursor

npx skills add https://github.com/G1Joshi/Agent-Skills/tree/HEAD/skills/tools/k9s

문서

K9s

K9s는 쿠버네티스를 위한 터미널 UI(TUI)입니다. 웹 대시보드에서 클릭하는 것보다 빠르고, raw kubectl보다 탐색하기 쉽습니다.

사용 시기

터미널 기반 쿠버네티스 클러스터 관리: 파드, 서비스, 디플로이먼트를 탐색하기 위한 빠르고 상호작용적인 curses UI.
실시간 로그 스트리밍 및 리소스 모니터링: 다중 파드 로그 테일링, CPU/메모리별 정렬, 포트 포워딩.
사용자 정의 K9s 플러그인 및 별칭: 사용자 정의 셸 명령어(예: stern, cert-manager 상태 실행)로 CLI 확장.
읽기 전용 검사 및 문제 해결: 읽기 전용 모드로 프로덕션 클러스터를 안전하게 디버깅.

빠른 시작

# 활성 kubeconfig로 k9s 실행
k9s

# k9s의 네비게이션 단축키:
# :pods      - 네임스페이스 전체의 모든 파드 보기
# :deploy    - 디플로이먼트 보기
# :svc       - 서비스 보기
# /<term>    - 활성 뷰에서 항목 필터링
# l          - 선택한 파드의 로그 스트리밍
# s          - 선택한 컨테이너 내부에서 셸(exec) 열기

핵심 개념

#사용자 정의 플러그인 설정 (plugins.yaml)

빠른 디버깅을 위한 사용자 정의 키보드 명령어 추가:

# ~/.config/k9s/plugins.yaml
plugin:
  # 디플로이먼트에서 'Shift-D'를 누르면 상세 롤아웃 기록 보기
  rollout-history:
    shortCut: Shift-D
    confirm: false
    description: "롤아웃 기록"
    scopes:
      - deployments
    command: kubectl
    background: false
    args:
      - rollout
      - history
      - deployment/$NAME
      - -n
      - $NAMESPACE

  # 파드에서 'Shift-F'를 누르면 대화형 디버그 컨테이너 실행
  debug-pod:
    shortCut: Shift-F
    confirm: true
    description: "디버그 파드"
    scopes:
      - pods
    command: kubectl
    background: false
    args:
      - debug
      - -it
      - $NAME
      - --image=nicolaka/netshoot
      - -n
      - $NAMESPACE

#필수 네비게이션 및 키보드 단축키

클러스터 관리 속도 향상:

:pod: 네임스페이스 전체의 파드 뷰로 이동.
:svc, :deploy, :ing: 서비스, 디플로이먼트, 인그레스 뷰로 이동.
/: 이름이나 상태로 리소스 검색 및 필터링.
l: 선택한 파드 또는 컨테이너의 로그 테일링.
s: 선택한 컨테이너 내부에서 대화형 셸(sh / bash) 열기.
Shift-F: 로컬 포트를 선택한 파드 서비스 포트로 포워딩.
y: 선택한 리소스의 전체 YAML 매니페스트 보기.

#사용자 정의 옵션으로 K9s 실행하기

보안 모드로 K9s 시작:

# 읽기 전용 모드로 실행하여 프로덕션에서 실수로 파드 삭제 방지
k9s --readonly --namespace production

# 사용자 정의 컨텍스트 및 새로고침 주기 지정
k9s --context prod-eks-cluster --refresh 2

일반적인 패턴

#사용자 정의 K9s 단축키 및 플러그인 문제: 여러 네임스페이스에서 사용자 정의 kubectl 명령어를 자주 실행해야 함. 해결책: ~/.config/k9s/plugin.yaml에 사용자 정의 플러그인 정의.

# ~/.config/k9s/plugin.yaml
plugin:
  raw-logs:
    shortCut: Shift-L
    description: "자르지 않은 로그 테일링"
    scopes:
      - pods
    command: kubectl
    background: false
    args:
      - logs
      - -f
      - $NAME
      - -n
      - $NAMESPACE
      - --context
      - $CONTEXT

모범 사례 (2026)

권장: 프로덕션 환경에 연결할 때는 k9s --readonly를 사용하여 실수로 삭제하는 것을 방지하세요.
권장: 반복적인 kubectl 명령어를 위해 ~/.config/k9s/plugins.yaml에 사용자 정의 플러그인을 구성하세요.
권장: 긴 kubectl port-forward 명령어 대신 포트 포워드 단축키(Shift-F)를 사용하세요.
권장: <all> 네임스페이스 또는 특정 네임스페이스로 뷰를 필터링하여 API 서버 쿼리 부하를 줄이세요.
권장하지 않음: 수십 개의 활성 포트 포워드를 열어두지 마세요. :portforwards 뷰에서 관리하고 종료하세요.
권장하지 않음: 대규모 엔터프라이즈 클러스터에서 적절한 --refresh 간격을 설정하지 않고 K9s를 실행하지 마세요.
권장하지 않음: 백업을 확인하지 않고 K9s를 통해 PVC(Persistent Volume Claim)를 삭제하지 마세요.

문제 해결

오류	원인	해결책
`Boom!! K9s cannot connect to cluster`	활성 kubeconfig 컨텍스트가 유효하지 않거나 클러스터 엔드포인트에 연결할 수 없음.	연결 확인: `kubectl cluster-info`, `kubectl config use-context`로 컨텍스트 전환.
`Pod logs failing to stream in k9s`	파드 컨테이너가 충돌했거나 사용자에게 RBAC `pods/log` 권한이 없음.	컨테이너 상태 확인 및 클러스터 역할 권한 확인.
`Terminal display corrupted / artifacts`	호환되지 않는 터미널 terminfo 또는 작은 터미널 창.	`export TERM=xterm-256color` 실행 후 터미널 창 최대화.

참고 자료

K9s 문서