OpenClaw Kubernetes 스킬 가이드

OpenClaw Kubernetes 스킬 개요

Kubernetes 스킬은 kubectl과 클러스터 관리 유틸리티 모음을 통해 OpenClaw를 Kubernetes 클러스터에 연결합니다. 설치 후 OpenClaw 에이전트는 애플리케이션 배포, 파드(Pod) 장애 문제 해결, 워크로드 스케일링, 매니페스트(Manifest) 생성, 보안 감사를 수행할 수 있습니다 — 모두 자연어 명령으로 완료됩니다.

Kubernetes는 컨테이너 오케스트레이션(Container Orchestration)의 업계 표준이지만, CLI 명령어의 범위가 매우 방대합니다. OpenClaw Kubernetes 스킬은 수백 가지 kubectl 하위 명령어와 플래그를 외울 필요를 없애줍니다. 터미널 창과 문서 사이를 전환하는 대신, 필요한 것을 설명하면 에이전트가 나머지를 처리합니다.

일반적인 워크플로:

1. OpenClaw에 프로덕션 클러스터의 상태를 확인하도록 요청합니다.
2. 에이전트가 백그라운드에서 kubectl get nodes, kubectl top pods, 상태 점검 스크립트를 실행합니다.
3. 결과가 실행 가능한 권장 사항과 함께 읽기 쉬운 요약으로 반환됩니다 — 컨텍스트 전환이 필요 없습니다.

이 스킬은 Kubernetes 1.31+, OpenShift 4.17+, 그리고 Amazon EKS, Azure AKS, Google GKE를 포함한 관리형 서비스를 지원합니다. 완전한 컨테이너 워크플로를 위해 Docker Essentials 스킬과 자연스럽게 연동됩니다.

Kubernetes 스킬 사전 요구 사항

Kubernetes 스킬을 설치하기 전에 다음 사항을 확인하세요:

• OpenClaw 설치 및 실행 중 (v1.0+)
• kubectl 설치됨 (v1.20+) — 설치 가이드
• 최소 하나의 클러스터를 가리키는 유효한 kubeconfig 파일
• 스킬 관리를 위한 clawhub CLI 설치됨

설정을 확인합니다:

# OpenClaw 버전 확인
openclaw --version

# kubectl 버전 확인
kubectl version --client

# 클러스터 연결 확인
kubectl cluster-info

# 사용 가능한 컨텍스트 목록 조회
kubectl config get-contexts

kubectl cluster-info가 오류를 반환하면 kubeconfig가 올바르게 구성되어 있는지 확인하세요. 관리형 클러스터의 경우 공급자의 CLI를 사용하여 자격 증명을 생성합니다 (예: aws eks update-kubeconfig, az aks get-credentials, 또는 gcloud container clusters get-credentials).

Kubernetes 스킬 설치 방법

단일 명령어로 Kubernetes 스킬을 설치합니다:

npx clawhub@latest install kubernetes

설치를 확인합니다:

clawhub list

설치된 스킬 목록에 kubernetes가 표시되어야 합니다. 이 스킬은 클러스터 상태 점검, 보안 감사, 노드 유지 관리, 매니페스트 생성을 위한 헬퍼 스크립트를 번들로 포함합니다.

Kubernetes 스킬 구성

Kubernetes 스킬은 인증을 위해 기존 kubeconfig를 사용합니다. 추가 API 키나 토큰이 필요 없습니다 — kubectl이 머신에서 작동하면 스킬도 작동합니다.

Kubeconfig 설정

스킬은 ~/.kube/config에 있는 기본 kubeconfig를 읽습니다. 다른 파일을 사용하거나 여러 클러스터를 관리하려면:

# 사용자 정의 kubeconfig 경로 설정
export KUBECONFIG=/path/to/your/kubeconfig

# 여러 kubeconfig 파일 병합
export KUBECONFIG=~/.kube/config:~/.kube/staging-config

# 컨텍스트 간 전환
kubectl config use-context production-cluster

네임스페이스 범위 지정

안전을 위해 클러스터 전체 접근 권한을 부여하는 대신 특정 네임스페이스로 스킬의 범위를 제한하는 것을 권장합니다:

# 현재 컨텍스트에 기본 네임스페이스 설정
kubectl config set-context --current --namespace=my-app

# 활성 네임스페이스 확인
kubectl config view --minify --output 'jsonpath={..namespace}'

중요: 프로덕션 환경에서 스킬에 cluster-admin 권한을 부여하지 마세요. 실제로 필요한 네임스페이스와 리소스로 범위가 지정된 RBAC 역할을 사용하세요. 아래 보안 및 모범 사례 섹션을 검토하세요.

Kubernetes 스킬 사용 예시

1. 파드 크래시 진단

사용자: "payments 네임스페이스에서 파드가 왜 크래시되나요?"

에이전트가 kubectl get pods -n payments를 실행하고, CrashLoopBackOff 상태의 파드를 식별하고, kubectl logs로 로그를 가져오고, kubectl describe pod로 이벤트를 확인합니다. "OOMKilled — 컨테이너가 256Mi 메모리 제한을 초과했습니다. 512Mi로 증가시키는 것을 권장합니다."와 같은 진단 결과를 반환합니다.

2. 디플로이먼트 스케일링

사용자: "스테이징에서 API 디플로이먼트를 5개 레플리카로 스케일링해주세요."

에이전트가 kubectl scale deployment api --replicas=5 -n staging을 실행하고, kubectl rollout status로 롤아웃을 모니터링하며, 5개 파드가 모두 실행 중이고 정상인지 확인합니다.

3. 프로덕션 매니페스트 생성

사용자: "Node.js 앱을 위한 디플로이먼트 매니페스트를 만들어주세요. 3개 레플리카, 256Mi 메모리 제한, 헬스 체크, ClusterIP 서비스를 포함해주세요."

에이전트가 내장된 매니페스트 생성기를 사용하여 보안 기본값이 적용된 완전한 YAML 파일을 생성합니다 — 비루트 사용자, 읽기 전용 파일 시스템, 리소스 제한, 라이브니스 및 레디니스 프로브, 그리고 매칭되는 Service 정의가 포함됩니다.

4. 보안 감사 실행

사용자: "default 네임스페이스의 보안 문제를 감사해주세요."

에이전트가 번들된 보안 감사 스크립트를 실행하여 루트로 실행되는 컨테이너, 누락된 리소스 제한, 과도하게 허용적인 RBAC 바인딩, Pod Security Standards 라벨이 없는 파드를 검사합니다. 결과는 수정 단계와 함께 우선순위가 지정된 발견 목록으로 반환됩니다.

5. 롤링 업데이트 수행

사용자: "web 디플로이먼트를 이미지 v2.3.1로 업데이트하고 롤아웃을 모니터링해주세요."

에이전트가 kubectl set image deployment/web web=myregistry/web:v2.3.1을 실행한 다음 kubectl rollout status를 실시간으로 모니터링합니다. 롤아웃이 정체되거나 파드가 헬스 체크에 실패하면 알림을 보내고 되돌리기 위해 kubectl rollout undo를 제안합니다.

보안 및 모범 사례

Kubernetes 작업은 실행 중인 프로덕션 워크로드에 영향을 줄 수 있습니다. 안전하게 사용하려면 다음 가이드라인을 따르세요:

• 최소 권한으로 RBAC를 사용하세요. 필요한 권한만 가진 전용 ServiceAccount를 생성하세요. 일상적인 작업에 cluster-admin을 사용하지 마세요. Kubernetes RBAC 문서에서 역할 생성에 대해 자세히 다룹니다.
• 네임스페이스로 범위를 제한하세요. kubeconfig 컨텍스트에 기본 네임스페이스를 설정하여 스킬이 다른 네임스페이스의 리소스를 실수로 수정할 수 없도록 하세요.
• 적용 전에 검토하세요. OpenClaw는 파드 삭제, 0으로 스케일링, 노드 드레인과 같은 파괴적인 작업 전에 확인을 요청합니다. 항상 제안된 변경 사항을 검토하세요.
• 드라이런(dry-run) 모드를 사용하세요. 매니페스트 생성 및 적용 작업에서 스킬은 --dry-run=client를 지원하여 클러스터에 영향을 주지 않고 변경 사항을 미리 볼 수 있습니다.
• 자격 증명을 정기적으로 교체하세요. 서비스 계정 토큰을 사용하는 경우 만료 정책을 설정하세요. 관리형 클러스터의 경우 단기 클라우드 공급자 자격 증명을 사용하세요.
• 감사 로깅(Audit Logging)을 활성화하세요. 스킬을 통해 수행된 모든 API 호출을 추적하기 위해 Kubernetes 감사 로깅을 구성하세요. 일반적인 OpenClaw 보안 가이드는 안전 체크리스트를 참고하세요.

일반적인 오류 해결

"error: You must be logged in to the server (Unauthorized)"

kubeconfig 자격 증명이 만료되었거나 유효하지 않습니다.

# AWS EKS의 경우
aws eks update-kubeconfig --name my-cluster --region us-east-1

# Azure AKS의 경우
az aks get-credentials --resource-group myRG --name my-cluster

# Google GKE의 경우
gcloud container clusters get-credentials my-cluster --zone us-central1-a

"error: the server doesn't have a resource type 'deployments'"

API 서버에 연결할 수 없거나 RBAC 권한이 부족합니다.

1. kubectl cluster-info를 실행하여 연결을 확인합니다.
2. 역할에 apps/v1 API 그룹에 대한 get, list, watch 권한이 있는지 확인합니다.
3. 클러스터 관리자에게 RoleBinding을 검토하도록 요청합니다.

"pod has unbound immediate PersistentVolumeClaims"

파드가 존재하지 않거나 아직 프로비저닝되지 않은 PersistentVolume을 필요로 합니다.

1. kubectl get pvc -n <namespace>를 실행하여 클레임 상태를 확인합니다.
2. StorageClass가 존재하는지 확인합니다: kubectl get storageclass.
3. 클라우드 공급자의 경우 CSI 드라이버가 설치되어 있고 스토리지 쿼터가 초과되지 않았는지 확인합니다.