이전 포스팅에서 집에 굴러다니는 미니PC들로 쿠버네티스 클러스터를 구축한 이야기를 했었다.

쿠버네티스 클러스터 둘러보기

그때 설치한 버전이 v1.30.4였는데, 그 뒤로 Jenkins, Kafka, MySQL InnoDB Cluster, Redis 같은 것들을 하나씩 올리면서 “잘 돌아가는데 굳이 건드려야 하나” 싶어서 업그레이드를 계속 미뤄왔다. 근데 v1.30 지원 종료(EOL)도 되었고(on-prem은 2025년에 만료), CKA 시험 준비를 하면서 kubeadm 업그레이드를 공부하다 보니 이참에 직접 해보자 싶었다.

실제 프로덕션 워크로드가 돌아가는 환경에서 하는 거라 우려했는데, 막상 절차대로 하니까 생각보다 어렵지 않았다. 그 과정을 기록해둔다.

3줄 요약

• Kubernetes는 한 번에 1 마이너 버전씩만 업그레이드할 수 있다 (v1.30 → v1.31 OK, v1.30 → v1.32 불가. 도대체 왜 이렇게 만든건가?)
• 반드시 control-plane 먼저, worker 나중에 순서를 지켜야 한다
• 업그레이드 전 etcd 백업은 필수 – 실패 시 복구할 수 있는 유일한 보험

Kubernetes 클러스터 구성

업그레이드 대상 클러스터 구성은 이렇게 생겼다:

Kubernetes Cluster v1.30.4

Control Plane (3대)

• luckys-worker0
  • ingress-nginx-controller
  • redis-node-0
  • mysql-operator
• luckys-worker1
  • ingress-nginx-controller
  • dev-mysql-cluster-0
• luckys-worker2
  • kafka-controller-2
  • redis-node-2

Worker (3대)

• luckys-worker3 – 사망
• luckys-worker4
  • kafka-controller-1
  • prod-mysql-cluster-1
  • loki (로그 수집)
• luckys-worker5
  • kafka-controller-0
  • prod-mysql-cluster-2
  • prometheus, alertmanager
  • redis-dev-master (standalone)
• luckys-worker6
  • prod-mysql-cluster-0
  • ingress-nginx-controller
  • jenkins
  • nexus, openclaw, grafana

주요 워크로드: Jenkins, Kafka, MySQL InnoDB Cluster, Redis Sentinel, Longhorn, MetalLB, Ingress-Nginx, 이외 다수 Application

OS는 Ubuntu 24.04 LTS, 컨테이너 런타임은 containerd.

사전 준비

1. 현재 버전 확인

kubeadm version
# kubeadm version: v1.30.4

kubelet --version
# Kubernetes v1.30.4

kubectl version

2. 업그레이드 가능한 버전 확인

v1.31 저장소를 추가하고 사용 가능한 버전을 확인한다:

# v1.31 저장소 추가
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring-v1.31.gpg] https://pkgs.k8s.io/core:/stable:/v1.31/deb/ /' \
  | sudo tee /etc/apt/sources.list.d/kubernetes-v1.31.list

# GPG 키 등록
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.31/deb/Release.key \
  | sudo gpg --dearmor --yes -o /etc/apt/keyrings/kubernetes-apt-keyring-v1.31.gpg

sudo apt update
sudo apt-cache madison kubeadm | head -5

참고: 기존 v1.30 저장소의 GPG 키가 만료되어 apt update 시 에러가 발생할 수 있다. v1.31 저장소만 정상이면 업그레이드 진행에 문제없다.

3. etcd 백업 (필수!)

업그레이드 전 반드시 etcd를 백업한다. 문제가 생기면 이 백업으로 클러스터를 복구할 수 있다.

# 인증서 경로 확인
kubectl describe pod etcd-luckys-worker0 -n kube-system

# etcd 백업 실행
export ETCDCTL_API=3
etcdctl snapshot save /opt/etcd-backup-before-upgrade.db \
  --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key

# 백업 확인
etcdctl snapshot status /opt/etcd-backup-before-upgrade.db --write-out=table

etcdctl이 설치되어 있지 않다면 kubectl exec으로 etcd Pod 안에서 실행하거나, etcd 바이너리를 직접 설치하면 된다.

4. 노드별 워크로드 분포 확인

drain 하면 영향받는 워크로드를 미리 파악해야 한다:

# 각 노드에서 돌아가는 Pod 확인
kubectl get pods -A -o wide --field-selector spec.nodeName=luckys-worker0 | grep -v kube-system

# Taint 확인 (control-plane에 Taint가 없으면 일반 워크로드도 올라가 있을 수 있음)
kubectl describe node luckys-worker0 | grep -i taint

내 클러스터는 control-plane에 Taint가 설정되어 있지 않아서(마스터도 예외 없다) 일반 워크로드도 control-plane 노드에서 실행되고 있었다. MySQL InnoDB Cluster, Redis, Ingress 등의 분포를 확인하고 drain해도 프로덕션에 영향이 없는지 검증한 후 진행했다.

업그레이드 시 안전도

비교적 안전

• luckys-worker0 (prod 1개뿐, MySQL/Kafka 없음)
• luckys-worker2 (워크로드 적음)

우려됨

• luckys-worker1 (prod 앱 + ingress)
• luckys-worker5 (모니터링 + MySQL + Kafka)

매우 우려됨

• luckys-worker4 (워크로드 최다 + MySQL + Kafka)
• luckys-worker6 (prod 앱 많음 + MySQL + Jenkins + Ingress)

사실 다른 것도 그렇지만, Longhorn 으로 데이터가 서로 다른 노드에 동기화 되어야 하는데, upgrade로 인한 중단 시 쓰기 지연이 발생할 경우 클러스터 전체의 성능이 대폭 하락하는 문제가 있어서 이 지점이 가장 골머리 아프다.

업그레이드 순서

반드시 control-plane → worker 순서로 해야한다. kubelet은 apiserver보다 높은 버전일 수 없기 때문이다.

1. Control Plane #1 (luckys-worker0) ← 첫 번째는 kubeadm upgrade apply
2. Control Plane #2 (luckys-worker1) ← 이후는 kubeadm upgrade node
3. Control Plane #3 (luckys-worker2)
4. Worker #1 (luckys-worker4)        ← 전부 kubeadm upgrade node
5. Worker #2 (luckys-worker5)
6. Worker #3 (luckys-worker6)

Control Plane 첫 번째 노드 업그레이드

첫 번째 control-plane 노드만 kubeadm upgrade apply를 사용한다. 나머지는 전부 kubeadm upgrade node를 쓴다.

Step 1: kubeadm 업그레이드

# kubeadm 패키지 잠금 해제 → 설치 → 다시 잠금
apt-mark unhold kubeadm && \
apt-get update && apt-get install -y kubeadm=1.31.14-1.1 && \
apt-mark hold kubeadm

Step 2: 업그레이드 계획 확인 및 실행

# 버전 확인
kubeadm version

# 업그레이드 계획 확인
sudo kubeadm upgrade plan

# 업그레이드 실행
sudo kubeadm upgrade apply v1.31.14

kubeadm upgrade plan은 현재 상태를 분석해서 업그레이드 가능 여부를 보여준다. 문제가 없으면 apply로 실제 업그레이드를 진행한다.

Step 3: 노드에서 Pod 퇴거 (drain)

kubeadm upgrade 후, kubelet 업그레이드 전에 drain한다.

kubectl drain luckys-worker0 --ignore-daemonsets

• --ignore-daemonsets: DaemonSet Pod(모니터링, 네트워크 등)은 무시
• emptyDir 사용하는 Pod 때문에 실패하면 --delete-emptydir-data 추가

Step 4: kubelet & kubectl 업그레이드

# 패키지 잠금 해제 → 설치 → 다시 잠금
apt-mark unhold kubelet kubectl && \
apt-get update && apt-get install -y kubelet=1.31.14-1.1 kubectl=1.31.14-1.1 && \
apt-mark hold kubelet kubectl

# kubelet 재시작
sudo systemctl daemon-reload
sudo systemctl restart kubelet

Step 5: 노드 복귀 (uncordon)

kubectl uncordon luckys-worker0

Step 6: 업그레이드 확인

kubectl get nodes
# luckys-worker0의 VERSION이 v1.31.14로 변경되었는지 확인

나머지 Control Plane 노드 업그레이드

두 번째, 세 번째 control-plane 노드는 kubeadm upgrade node를 사용한다. apply가 아닌 점에 주의. kubeadm upgrade plan도 불필요하다.

각 노드에 SSH 접속 후:

# 1. kubeadm 업그레이드
apt-mark unhold kubeadm && \
apt-get update && apt-get install -y kubeadm=1.31.14-1.1 && \
apt-mark hold kubeadm

# 2. 노드 업그레이드
sudo kubeadm upgrade node          # ← apply가 아닌 node!

# 3. drain (다른 control-plane 노드에서 실행)
kubectl drain luckys-worker1 --ignore-daemonsets

# 4. kubelet & kubectl 업그레이드
apt-mark unhold kubelet kubectl && \
apt-get update && apt-get install -y kubelet=1.31.14-1.1 kubectl=1.31.14-1.1 && \
apt-mark hold kubelet kubectl

sudo systemctl daemon-reload
sudo systemctl restart kubelet

# 5. uncordon (다른 노드에서 실행)
kubectl uncordon luckys-worker1

luckys-worker2도 동일하게 진행한다.

Worker 노드 업그레이드

Worker 노드도 거의 동일하다. kubeadm upgrade node를 사용한다.

# 1. kubeadm 업그레이드
apt-mark unhold kubeadm && \
apt-get update && apt-get install -y kubeadm=1.31.14-1.1 && \
apt-mark hold kubeadm

# 2. 노드 업그레이드
sudo kubeadm upgrade node

# 3. drain (control-plane에서 실행)
kubectl drain luckys-worker4 --ignore-daemonsets

# 4. kubelet & kubectl
apt-mark unhold kubelet kubectl && \
apt-get update && apt-get install -y kubelet=1.31.14-1.1 kubectl=1.31.14-1.1 && \
apt-mark hold kubelet kubectl

sudo systemctl daemon-reload
sudo systemctl restart kubelet

# 5. uncordon (control-plane에서 실행)
kubectl uncordon luckys-worker4

luckys-worker5, luckys-worker6도 동일하게 진행한다.

전체 업그레이드 완료 확인

kubectl get nodes -o wide

NAME             STATUS   ROLES           VERSION    OS-IMAGE
luckys-worker0   Ready    control-plane   v1.31.14   Ubuntu 24.04 LTS
luckys-worker1   Ready    control-plane   v1.31.14   Ubuntu 24.04 LTS
luckys-worker2   Ready    control-plane   v1.31.14   Ubuntu 24.04 LTS
luckys-worker4   Ready    <none>          v1.31.14   Ubuntu 24.04 LTS
luckys-worker5   Ready    <none>          v1.31.14   Ubuntu 24.04 LTS
luckys-worker6   Ready    <none>          v1.31.14   Ubuntu 24.04 LTS

주의사항 & 삽질 기록

GPG 키 만료 문제

v1.30 저장소의 GPG 키가 만료되어 apt update 시 에러가 났다:

EXPKEYSIG 234654DA9A296436 isv:kubernetes OBS Project

v1.31 저장소를 새로 추가하고 키를 등록하면 해결된다. 기존 v1.30 저장소 에러는 무시해도 된다.

1. v1.31 GPG 키 다운로드 및 등록

curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.31/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring-v1.31.gpg

2. v1.31 저장소 추가

echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring-v1.31.gpg] https://pkgs.k8s.io/core:/stable:/v1.31/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes-v1.31.list

control-plane에 Taint가 없는 경우

일반적으로 control-plane 노드에는 NoSchedule Taint가 설정되어 있어서 일반 워크로드가 배치되지 않는다. 근데 내 클러스터처럼 Taint가 없으면 MySQL, Redis, Ingress 등이 control-plane에서도 실행된다.(Taint를 설정하기엔 비용 이슈가..)

drain 전에 반드시 해당 노드의 워크로드를 확인하고, 프로덕션 영향을 검토해야 한다:

kubectl get pods -A -o wide --field-selector spec.nodeName=<노드명> | grep -v kube-system

drain vs cordon

• kubectl drain: 기존 Pod를 다른 노드로 퇴거시키고 스케줄 차단
• kubectl cordon: 새 Pod 스케줄만 차단, 기존 Pod는 그대로

프로덕션 영향이 걱정되면 cordon만 하고 업그레이드를 진행하는 방법도 있다. kubelet 재시작 시 잠깐 중단되지만 Pod가 다른 노드로 이동하지는 않는다.

MySQL InnoDB Cluster 고려

MySQL InnoDB Cluster는 3개 인스턴스가 서로 다른 노드에 분산되어 있어서, 한 노드를 drain해도 나머지 2개가 쿼럼을 유지한다. drain 전에 어떤 노드에 어떤 인스턴스가 있는지 확인하자:

kubectl get pods -A -o wide | grep mysql
kubectl get innodbcluster -A

한 대씩, 확인하면서

절대 여러 노드를 동시에 drain하지 말자. 특히 control-plane은 etcd 쿼럼(과반수) 유지가 필수다. 3대 중 2대가 동시에 내려가면 클러스터가 멈춘다.

한 대 업그레이드 완료 → kubectl get nodes로 Ready 확인 → 다음 노드

업그레이드 절차 요약

[사전 준비]
  etcd 백업 → 저장소 추가 → 워크로드 분포 확인

[Control Plane 첫 번째 노드]
  kubeadm 설치 → kubeadm upgrade apply → drain → kubelet kubectl 설치 → restart → uncordon

[Control Plane 나머지 + Worker 전체]
  kubeadm 설치 → kubeadm upgrade node → drain → kubelet kubectl 설치 → restart → uncordon

[완료]
  kubectl get nodes로 전체 버전 확인

마치며

막상 해보니 절차만 지키면 크게 어렵지 않아서 이걸 왜이리 미뤄왔나 싶다.

핵심은 세 가지다:

1. etcd 백업: 만약을 위한 보험
2. 순서 준수: control-plane 먼저, worker 나중에
3. 한 대씩: 확인하고 넘어가기

CKA 시험에서도 kubeadm 업그레이드는 거의 매번 출제되는 문제라고 한다. 실제 클러스터에서 한 번 해보면 시험에서도 별 문제 없이 풀 수 있을 것 같다.

참고 링크

• Kubernetes 공식 문서 – Upgrading kubeadm clusters
• Kubernetes Version Skew Policy
• CKA 시험 공식 페이지
• 홈 서버 쿠버네티스 클러스터 구축기

The post Kubernetes 온프레미스 클러스터 업그레이드하기 appeared first on .

“AI에게 서버 관리를 맡길 수 있을까?”

최근 AI 에이전트 기술이 빠르게 발전하면서, 단순한 챗봇을 넘어 실제 인프라를 관리하는 AI에 대한 관심이 높아지고 있습니다. 이번 글에서는 오픈소스 AI 자동화 프레임워크인 OpenClaw을 Kubernetes 클러스터에 설치하고, 코드 작성 → GitHub 푸시 → Jenkins 빌드 → K8s 배포까지 자율적으로 수행하는 DevOps 에이전트를 구축한 과정을 공유합니다.

전체 구현 과정은 Claude Code(Anthropic의 CLI 기반 AI 코딩 도구)와 함께 진행했으며, 설정 파일 작성부터 트러블슈팅까지 실시간으로 협업하며 완성했습니다.

핵심요약

• 쿠버네티스 클러스터 내에 pod 로 실행중
• 슬랙과 연동해서 대화형으로 구성
• GLM-4.7 (영균매니저님이 소개해준 Z.AI)을 main model 로 사용
• pod 에서 상위 레벨인 node 상태와 클러스터 제어를 위해 권한 부여(service account의 RBAC 설정)
• GLM 모델 특성(원래 느림)도 있겠지만 상호작용이 개느림, 답답

OpenClaw ?

OpenClaw은 2026년 초 등장한 오픈소스 AI 자동화 프레임워크입니다. 주요 특징은 다음과 같습니다:

• 다양한 LLM 지원: Anthropic Claude, OpenAI GPT, Google Gemini, Z.AI GLM 등
• 멀티 채널: 웹 UI, Slack, Discord, WhatsApp 등으로 대화 가능
• 도구 실행: 셸 명령어, 파일 조작, 웹 브라우저 자동화 기능 내장
• Helm Chart 제공: Kubernetes 배포를 위한 공식 Helm 차트 지원

핵심은 AI가 단순히 텍스트를 생성하는 것을 넘어, 실제 명령어를 실행하고 시스템을 제어할 수 있다는 점입니다.

최종 아키텍처

구축 완료 후의 전체 아키텍처는 다음과 같습니다:

┌─────────────────────────────────────────────────────────┐
│  Kubernetes Cluster (v1.30.4, 6 nodes)                  │
│                                                         │
│  ┌─────────── openclaw namespace ──────────┐            │
│  │  ┌──────────────────────────────────┐   │            │
│  │  │  OpenClaw Pod (2 containers)     │   │            │
│  │  │  ├─ main: OpenClaw Agent         │   │            │
│  │  │  │   ├─ kubectl (RBAC)    ──────────────→ K8s API │
│  │  │  │   ├─ helm              ──────────────→ K8s API │
│  │  │  │   ├─ git               ──────────────→ GitHub  │
│  │  │  │   └─ curl              ──────────────→ Jenkins │
│  │  │  └─ chromium: Browser Sidecar    │   │            │
│  │  └──────────────────────────────────┘   │            │
│  │  ServiceAccount: openclaw-sa            │            │
│  │  ClusterRole: Full K8s Access           │            │
│  └─────────────────────────────────────────┘            │
│                                                         │
│  ┌─── corpbreak-com-ingress ns ───┐                     │
│  │  ExternalName Svc + Ingress    │                     │
│  │  → openclaw.corpbreak.com      │                     │
│  └────────────────────────────────┘                     │
└─────────────────────────────────────────────────────────┘
         ↕                    ↕                ↕
    [Slack Bot]         [Web UI HTTPS]    [Jenkins API]

주요 구성 요소

구현 과정

Step 1: Helm으로 기본 설치

먼저 OpenClaw의 공식 Helm 차트를 이용하여 기본 설치를 진행했습니다.

# Helm 레포지토리 추가
helm repo add openclaw https://serhanekicii.github.io/openclaw-helm
helm repo update

# 네임스페이스 생성 및 설치
kubectl create namespace openclaw
helm install openclaw openclaw/openclaw -n openclaw -f values.yaml

LLM은 Z.AI의 GLM 4.7 모델을 선택했습니다. OpenClaw은 zai를 빌트인 프로바이더로 지원하기 때문에, API 키만 환경변수로 설정하면 됩니다.

Step 2: 첫 번째 장애 – Gateway Token

설치 직후 Pod가 CrashLoopBackOff 상태에 빠졌습니다.

Config invalid
Problem: Gateway auth is set to token, but no token is configured

OpenClaw의 Gateway는 인증 토큰이 필수입니다. openssl rand -hex 32로 토큰을 생성하고 Secret에 추가한 후, 설정 파일에서 환경변수로 참조하도록 수정했습니다.

"gateway": {
  "auth": {
    "token": "${GATEWAY_TOKEN}"
  }
}

Step 3: HTTPS Ingress 구성

기존 인프라의 패턴에 맞춰 ExternalName Service + Ingress 조합으로 외부 접근을 구성했습니다.

# ExternalName Service (cross-namespace routing)
apiVersion: v1
kind: Service
metadata:
  name: openclaw-external
  namespace: corpbreak-com-ingress
spec:
  type: ExternalName
  externalName: openclaw.openclaw.svc.cluster.local

OpenClaw의 WebUI는 WebSocket을 사용하므로, Ingress에 다음 annotation이 필수입니다:

nginx.ingress.kubernetes.io/proxy-http-version: "1.1"
nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"

Step 4: WebSocket 연결 오류 해결

접속 시도 시 여러 WebSocket 에러가 연이어 발생했습니다:

각 오류를 하나씩 해결한 끝에 웹 UI 접속에 성공했습니다.

Step 5: Slack 연동

OpenClaw은 Slack Socket Mode를 지원합니다. Slack App을 생성하고 다음 두 토큰을 Secret에 추가하면 됩니다:

• App-Level Token (xapp-): Socket Mode 연결용
• Bot Token (xoxb-): 메시지 송수신용

"channels": {
  "slack": {
    "enabled": true,
    "appToken": "${SLACK_APP_TOKEN}",
    "botToken": "${SLACK_BOT_TOKEN}"
  }
}

설정 후 OpenClaw 로그에서 socket mode connected 메시지를 확인할 수 있습니다.

Step 6: 브라우저 자동화 설정

OpenClaw의 브라우저 기능을 활성화하려면 두 가지가 필요합니다:

1. Chromium Sidecar Container: CDP(Chrome DevTools Protocol) 서버 제공
2. Playwright 브라우저 바이너리: Main 컨테이너에서 직접 브라우저 실행

Chromium Sidecar는 Helm Chart에서 자동 생성되지만, Playwright 바이너리는 Init Container로 별도 설치가 필요했습니다.

initContainers:
  install-browser:
    image:
      repository: ghcr.io/openclaw/openclaw
      tag: "2026.2.3"
    command:
      - sh
      - -c
      - |
        PLAYWRIGHT_BROWSERS_PATH=/home/node/.openclaw/browsers \
        node /app/node_modules/playwright-core/cli.js install chromium

Step 7: DevOps 도구 설치 (kubectl, helm)

OpenClaw Pod 안에서 클러스터를 관리하려면 kubectl과 helm이 필요합니다. 이들도 Init Container로 설치했습니다.

initContainers:
  install-tools:
    image:
      repository: alpine
      tag: "3.21"
    command:
      - sh
      - -c
      - |
        # kubectl 설치
        wget -q "https://dl.k8s.io/release/v1.30.4/bin/linux/amd64/kubectl" \
          -O /home/node/.openclaw/bin/kubectl
        chmod +x /home/node/.openclaw/bin/kubectl

        # helm 설치
        wget -q "https://get.helm.sh/helm-v3.17.1-linux-amd64.tar.gz" \
          -O /tmp/helm.tar.gz
        tar -xzf /tmp/helm.tar.gz -C /tmp
        mv /tmp/linux-amd64/helm /home/node/.openclaw/bin/helm

이 바이너리들은 PVC에 저장되므로, Pod가 재시작되어도 다시 다운로드할 필요가 없습니다.

Step 8: RBAC 설정 – Pod에서 클러스터 제어하기

Kubernetes에서 Pod가 클러스터 API에 접근하려면 ServiceAccount + ClusterRole + ClusterRoleBinding이 필요합니다.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: openclaw-cluster-role
rules:
  - apiGroups: [""]
    resources: ["nodes", "pods", "pods/log", "services",
                "configmaps", "secrets", "namespaces"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
  - apiGroups: ["apps"]
    resources: ["deployments", "replicasets", "statefulsets"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
  - apiGroups: ["networking.k8s.io"]
    resources: ["ingresses"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]

이렇게 설정하면 OpenClaw이 Pod 내부에서 kubectl get nodes, kubectl get pods -A 등을 자유롭게 실행할 수 있습니다.

Step 9: 시스템 프롬프트 주입 (Bootstrap File)

OpenClaw이 DevOps 작업을 정확히 수행하려면, 프로젝트 구조와 CI/CD 파이프라인에 대한 지식이 필요합니다.

처음에는 에이전트 설정에 systemPrompt 필드를 직접 추가했으나, “Unrecognized key” 오류로 Pod가 크래시했습니다. OpenClaw은 시스템 프롬프트를 설정 파일이 아닌 Bootstrap 파일로 주입하는 방식을 사용합니다.

Workspace 디렉토리에 AGENTS.md 파일을 생성하면, OpenClaw이 자동으로 이를 감지하여 시스템 프롬프트에 포함시킵니다.

/home/node/.openclaw/workspace/AGENTS.md

이 파일에 다음 정보를 포함했습니다:

• 도구 경로 (kubectl, helm, git)
• 클러스터 정보 (노드 구성, StorageClass, Registry)
• GitHub 인증 방법
• 전체 서비스 목록과 도메인 매핑
• Jenkins API 사용법 (빌드 트리거, 상태 확인, Job 생성)
• Blue-Green 배포 파이프라인 구조
• deploy-config YAML 템플릿

주요 설정 파일 구조

values.yaml (Helm Values)

최종 values.yaml의 핵심 구조는 다음과 같습니다:

configMode: overwrite

app-template:
  controllers:
    main:
      serviceAccount:
        name: openclaw-sa          # RBAC 연결
      containers:
        main:
          envFrom:
            - secretRef:
                name: openclaw-env-secret  # API 키, 토큰
          env:
            PATH: /home/node/.openclaw/bin:...  # kubectl, helm 경로

      initContainers:
        install-browser: ...       # Playwright Chromium
        install-tools: ...         # kubectl, helm + AGENTS.md

  configMaps:
    config:
      data:
        openclaw.json: |
          {
            "gateway": { ... },
            "browser": { ... },
            "agents": {
              "defaults": {
                "workspace": "/home/node/.openclaw/workspace",
                "model": { "primary": "zai/glm-4.7" }
              }
            },
            "channels": {
              "slack": { "enabled": true, ... }
            }
          }

  persistence:
    data:
      type: persistentVolumeClaim
      size: 5Gi
      storageClass: longhorn

Secret 구성

# openclaw-env-secret에 포함된 키들
ZAI_API_KEY: ...          # GLM 4.7 API 키
GATEWAY_TOKEN: ...        # Gateway 인증 토큰
SLACK_APP_TOKEN: ...      # Slack Socket Mode
SLACK_BOT_TOKEN: ...      # Slack Bot
GITHUB_TOKEN: ...         # GitHub PAT (코드 push)
JENKINS_URL: ...          # Jenkins API URL
JENKINS_USER: ...         # Jenkins 사용자
JENKINS_TOKEN: ...        # Jenkins API 토큰

OpenClaw이 할 수 있는 일

구축이 완료된 후, OpenClaw은 Slack 메시지 하나로 다음 작업들을 수행할 수 있습니다:

1. 클러스터 모니터링

사용자: "현재 corpbreak-dev 네임스페이스 Pod 상태 확인해줘"
OpenClaw: kubectl get pods -n corpbreak-dev 실행 → 결과 보고

2. 코드 작성 및 GitHub Push

사용자: "exchange-service에 새 API 엔드포인트 추가해줘"
OpenClaw: git clone → 코드 수정 → git commit → git push

3. Jenkins 빌드 트리거

사용자: "checklist 서비스 dev 환경에 배포해줘"
OpenClaw: Jenkins API 호출 → 빌드 트리거 → 상태 모니터링

4. 새 서비스 생성 (E2E)

사용자: "새로운 survey-service를 만들어줘"
OpenClaw:
  1. 스켈레톤 프로젝트 클론
  2. 패키지명/설정 변경
  3. deploy-config YAML 작성
  4. GitHub에 Push
  5. Jenkins Job 생성
  6. 빌드 트리거 및 배포 확인

Claude Code와 함께한 구현 과정

이번 구축의 특별한 점은, 전체 과정을 Claude Code와 실시간으로 협업하며 진행했다는 것입니다.

Claude Code는 Anthropic이 만든 CLI 기반 AI 코딩 도구로, 터미널에서 직접 파일을 읽고, 수정하고, 명령어를 실행할 수 있습니다. 이번 작업에서 Claude Code가 수행한 역할:

• 리서치: OpenClaw 설치 방법 웹 검색 및 문서 분석
• 설정 파일 작성: values.yaml, RBAC, Ingress 등 모든 K8s 매니페스트 생성
• Helm 명령 실행: helm install, helm upgrade 직접 실행
• 트러블슈팅: Pod 로그 분석, 에러 원인 파악, 설정 수정
• 검증: kubectl exec로 Pod 내부 확인, API 테스트

사실상 Claude Code가 모든 것을 만들었다..!

총 10번의 Helm revision을 거치며, 각 단계에서 발생한 오류를 Claude Code가 실시간으로 진단하고 수정했습니다. 특히 “systemPrompt 필드가 인식되지 않는 문제”처럼 공식 문서에도 명확히 나와있지 않은 이슈를 웹 검색과 문서 분석을 통해 해결한 과정이 인상적이었습니다.

삽질 기록: 이것만은 알고 시작하세요

구축 과정에서 겪은 주요 실수들을 정리합니다:

1. bjw-s app-template의 ServiceAccount 설정

OpenClaw Helm 차트는 내부적으로 bjw-s app-template 차트를 사용합니다. ServiceAccount를 연결할 때 일반적인 spec.serviceAccountName이 아닌, 차트 고유의 경로를 사용해야 합니다.

# 틀린 방법들
defaultPodOptions:
  serviceAccountName: openclaw-sa  # Error: additional properties not allowed

serviceAccount:
  name: openclaw-sa  # Error: got string, want object

# 정답
controllers:
  main:
    serviceAccount:
      name: openclaw-sa

2. OpenClaw 에이전트 설정

에이전트 설정을 위해서는 workspace의 Bootstrap 파일(AGENTS.md, SOUL.md 등)을 사용해야 합니다.

3. nginx-ingress의 configuration-snippet 차단

nginx-ingress v1.11.2부터 보안상 configuration-snippet annotation이 기본 차단됩니다. WebSocket 지원은 proxy-http-version: "1.1" annotation만으로 충분합니다.

4. Alpine에서 git 바이너리 복사 불가

Alpine Linux에서 설치한 git은 공유 라이브러리에 의존하므로, 바이너리만 복사하면 동작하지 않습니다. 다행히 OpenClaw 이미지에는 /usr/bin/git이 이미 포함되어 있었습니다.

보안 고려사항

AI 에이전트에게 클러스터 접근 권한을 부여할 때는 보안에 특별히 주의해야 합니다:

• 최소 권한 원칙: 필요한 리소스와 동작만 RBAC으로 허용
• 프로덕션 보호: 시스템 프롬프트에 “prod 배포는 반드시 사용자 확인 후 진행” 명시
• Secret 관리: API 키와 토큰은 모두 Kubernetes Secret으로 관리
• 감사 추적: OpenClaw의 로깅 설정으로 모든 도구 실행 기록 보관
• 네트워크 격리: OpenClaw이 접근할 수 있는 외부 엔드포인트 제한 고려

마치며

AI 에이전트가 실제 인프라를 관리하는 시대가 이미 시작되었습니다. OpenClaw은 아직 초기 단계의 프로젝트이지만, Kubernetes 클러스터 위에서 실제 DevOps 작업을 수행할 수 있다는 가능성을 보여주었습니다.

물론 아직 개선할 점이 있습니다. 브라우저 스크린샷 기능이 완벽하지 않고, 복잡한 멀티스텝 작업에서 간혹 컨텍스트를 놓치기도 합니다. 하지만 “Slack으로 메시지 하나 보내면 서비스가 배포된다”는 경험은 충분히 인상적입니다.

단, 이미 충분히 지식이 있고, Claude Code 를 이용한 자동화를 구축해둔 상황이라면, 굳이 OpenClaw 를 설치해서 사용할 필요가 있나? 싶은 생각도 들었습니다. (아직 사용을 제대로 해보지 못해서 그런 것인지.. 맥미니가 다시 중고로 쏟아지지 않을까.!?)

이번 구축 과정에서 Claude Code의 역할도 매우 컸습니다. Helm 차트 분석, YAML 설정 작성, 실시간 트러블슈팅까지 – AI와 함께 AI를 설치하는 재미있는 경험이었습니다.

혹시 비슷한 환경을 구축해보고 싶으신 분이 계시다면, 이 글이 시행착오를 줄이는 데 도움이 되길 바랍니다.

참고 링크

• OpenClaw GitHub: https://github.com/openclaw/openclaw
• OpenClaw Helm Chart: https://github.com/serhanekicii/openclaw-helm
• OpenClaw 공식 문서: https://docs.openclaw.ai
• Claude Code: https://claude.com/claude-code

The post OpenClaw – Kubernetes 클러스터에 구축기 with Claude Code appeared first on .