Kubernetes에서 OpenClaw

Kubernetes에서 OpenClaw를 실행하기 위한 최소한의 시작점입니다. 프로덕션용 배포가 아니라 핵심 리소스를 다루며 환경에 맞게 수정하도록 만들어졌습니다.

Helm을 사용하지 않는 이유

OpenClaw는 설정 파일 몇 개와 단일 컨테이너입니다. 흥미로운 커스터마이징은 에이전트 콘텐츠(마크다운 파일, 스킬, 설정 오버라이드)에 있지 인프라 템플릿이 아닙니다. Kustomize가 Helm 차트의 오버헤드 없이 오버레이를 처리합니다. 배포가 더 복잡해지면 이 매니페스트 위에 Helm 차트를 얹을 수 있습니다.

필요한 것

실행 중인 Kubernetes 클러스터 (AKS, EKS, GKE, k3s, kind, OpenShift 등)
클러스터에 연결된 kubectl
하나 이상의 모델 프로바이더 API 키

빠른 시작

# 프로바이더에 맞게 교체: ANTHROPIC, GEMINI, OPENAI, or OPENROUTER
export <PROVIDER>_API_KEY="..."
./scripts/k8s/deploy.sh

kubectl port-forward svc/openclaw 18789:18789 -n openclaw
open http://localhost:18789

게이트웨이 토큰을 가져와 Control UI에 붙여넣습니다:

kubectl get secret openclaw-secrets -n openclaw -o jsonpath='{.data.OPENCLAW_GATEWAY_TOKEN}' | base64 -d

로컬 디버깅을 위해 ./scripts/k8s/deploy.sh --show-token을 사용하면 배포 후 토큰을 출력합니다.

Kind로 로컬 테스트

클러스터가 없으면 Kind로 로컬에 생성합니다:

./scripts/k8s/create-kind.sh           # docker 또는 podman 자동 감지
./scripts/k8s/create-kind.sh --delete  # 정리

이후 ./scripts/k8s/deploy.sh로 평소처럼 배포합니다.

단계별 진행

1) 배포

옵션 A — 환경의 API 키 (한 단계):

# 프로바이더에 맞게 교체: ANTHROPIC, GEMINI, OPENAI, or OPENROUTER
export <PROVIDER>_API_KEY="..."
./scripts/k8s/deploy.sh

스크립트가 API 키와 자동 생성된 게이트웨이 토큰으로 Kubernetes Secret을 생성한 뒤 배포합니다. Secret이 이미 존재하면 현재 게이트웨이 토큰과 변경하지 않는 프로바이더 키를 유지합니다.

옵션 B — 시크릿을 별도로 생성:

export <PROVIDER>_API_KEY="..."
./scripts/k8s/deploy.sh --create-secret
./scripts/k8s/deploy.sh

로컬 테스트를 위해 토큰을 stdout에 출력하려면 --show-token을 사용하세요.

2) 게이트웨이 접속

kubectl port-forward svc/openclaw 18789:18789 -n openclaw
open http://localhost:18789

배포되는 항목

Namespace: openclaw (OPENCLAW_NAMESPACE로 변경 가능)
├── Deployment/openclaw        # 단일 Pod, init 컨테이너 + 게이트웨이
├── Service/openclaw           # 포트 18789의 ClusterIP
├── PersistentVolumeClaim      # 에이전트 상태 및 설정용 10Gi
├── ConfigMap/openclaw-config  # openclaw.json + AGENTS.md
└── Secret/openclaw-secrets    # 게이트웨이 토큰 + API 키

커스터마이징

에이전트 인스트럭션

scripts/k8s/manifests/configmap.yaml의 AGENTS.md를 편집하고 재배포합니다:

./scripts/k8s/deploy.sh

게이트웨이 설정

scripts/k8s/manifests/configmap.yaml의 openclaw.json을 편집합니다. 전체 참고 문서는 게이트웨이 구성을 참고하세요.

프로바이더 추가

추가 키를 내보내고 다시 실행합니다:

export ANTHROPIC_API_KEY="..."
export OPENAI_API_KEY="..."
./scripts/k8s/deploy.sh --create-secret
./scripts/k8s/deploy.sh

기존 프로바이더 키는 덮어쓰지 않는 한 Secret에 유지됩니다.

또는 Secret을 직접 패치합니다:

kubectl patch secret openclaw-secrets -n openclaw \
  -p '{"stringData":{"<PROVIDER>_API_KEY":"..."}}'
kubectl rollout restart deployment/openclaw -n openclaw

커스텀 네임스페이스

OPENCLAW_NAMESPACE=my-namespace ./scripts/k8s/deploy.sh

커스텀 이미지

scripts/k8s/manifests/deployment.yaml의 image 필드를 편집합니다:

image: ghcr.io/openclaw/openclaw:2026.3.1

port-forward를 넘어서 노출

기본 매니페스트는 게이트웨이를 Pod 내부의 루프백에 바인딩합니다. kubectl port-forward에서는 작동하지만, Pod IP에 접근해야 하는 Kubernetes Service나 Ingress 경로에서는 작동하지 않습니다.

Ingress나 로드 밸런서를 통해 게이트웨이를 노출하려면:

scripts/k8s/manifests/configmap.yaml의 게이트웨이 바인드를 loopback에서 배포 모델에 맞는 비루프백 바인드로 변경하세요
게이트웨이 인증을 활성화하고 적절한 TLS 종료 엔트리포인트를 사용하세요
지원되는 웹 보안 모델(예: HTTPS/Tailscale Serve 및 필요시 명시적 허용 오리진)을 사용하여 원격 접속용 Control UI를 구성하세요

재배포

./scripts/k8s/deploy.sh

모든 매니페스트를 적용하고 설정이나 시크릿 변경을 반영하기 위해 Pod를 재시작합니다.

정리

./scripts/k8s/deploy.sh --delete

PVC를 포함한 네임스페이스와 모든 리소스를 삭제합니다.

아키텍처 참고

게이트웨이는 기본적으로 Pod 내부의 루프백에 바인딩되므로, 포함된 설정은 kubectl port-forward 용도입니다
클러스터 범위 리소스 없음 — 모든 것이 단일 네임스페이스에 있습니다
보안: readOnlyRootFilesystem, drop: ALL 기능, 비루트 사용자 (UID 1000)
기본 설정은 Control UI를 더 안전한 로컬 접근 경로로 유지합니다: 루프백 바인드 + kubectl port-forward로 http://127.0.0.1:18789
localhost 접근을 넘어서려면 지원되는 원격 모델을 사용하세요: HTTPS/Tailscale + 적절한 게이트웨이 바인드 및 Control UI 오리진 설정
시크릿은 임시 디렉토리에서 생성되어 클러스터에 직접 적용됩니다 — 저장소 체크아웃에 시크릿 자료가 기록되지 않습니다

파일 구조

scripts/k8s/
├── deploy.sh                   # 네임스페이스 + 시크릿 생성, kustomize로 배포
├── create-kind.sh              # 로컬 Kind 클러스터 (docker/podman 자동 감지)
└── manifests/
    ├── kustomization.yaml      # Kustomize 베이스
    ├── configmap.yaml          # openclaw.json + AGENTS.md
    ├── deployment.yaml         # 보안 강화된 Pod 스펙
    ├── pvc.yaml                # 10Gi 영구 스토리지
    └── service.yaml            # 포트 18789의 ClusterIP