2026년 OpenClaw Gateway Kubernetes 배포·수전 Runbook: 버전 고정, 리소스 쿼터, bind=lan, port-forward, 전형적 OOM/NotReady 롤백(FAQ + 원격 물리 Mac 베어메탈 대조)
플랫폼·SRE 팀이 Kubernetes에 OpenClaw Gateway를 올릴 때 이미지 드리프트, 프로브와 바인드 주소 불일치, 실제 트래픽과 맞지 않는 port-forward 스모크, OOM/NotReady 시 롤백 vs 재튜닝 때문에 수전이 멈추는 경우가 많습니다. 본문은 스캔 가능한 Kubernetes vs 원격 물리 Mac 매트릭스, 7단계 런북, 변경 티켓에 붙일 임계값, 증상 기반 FAQ를 제시합니다.
1. 도입: K8s 게이트웨이 수전에 네트워크·cgroup 증거가 필요한 이유
베어메탈에서는 「포트가 열렸다」가 곧 바인드 성공으로 읽히는 경우가 많습니다. Kubernetes에서는 같은 로그라도 Service 엔드포인트, kube-proxy(또는 CNI 데이터패스), NetworkPolicy, cgroup 메모리 회계를 거칩니다. 노트북에서 익숙한 127.0.0.1 모델을 그대로 가져오면 Pod 안 curl은 되는데 Service 경로는 실패하거나, 프로세스는 살아 있는데 준비성은 빨간색 같은 거짓 음성이 납니다.
이 글은 서명 가능한 증거를 연결합니다: 이미지 다이제스트와 Helm values 해시, OOM 이벤트와 맞춘 requests/limits, targetPort와 일치하는 bind=lan, port-forward 스모크와 인클러스터 프로브의 교차 검증. 글로벌 배포 트랙을 함께 보고 있다면 2026년 OpenClaw 글로벌 배포 비교 가이드: 어디가 가장 편할까?와 짝지어 「동일 버전·두 경로」 수전의 상위 틀로 쓸 수 있습니다.
2. 세 가지 페인: 버전 드리프트, 바인드·프로브, 쿼터·노이즈 트래픽
- 버전 드리프트·재현 불가: 프로덕션에
:latest나 다이제스트 없는 태그를 쓰면 같은 태그도 재빌드 시 동작이 달라질 수 있습니다. 롤백 후에도 사고 당시 바이너리와 ReplicaSet이 일치한다는 증명이 어렵습니다. - 바인드 주소·Service·프로브 충돌: 게이트웨이는 루프백인데 준비 프로브는 Pod IP로 치거나, bind=lan은 맞는데 NetworkPolicy가 Ingress CIDR만 허용해 kubelet 프로브가 드롭되는 등 NotReady와 트래픽 단절이 동시에 나올 수 있습니다.
- 리소스 쿼터와 숨은 비용: requests가 없으면 스케줄은 통과해도 노드가 꽉 찬 뒤 지연 OOM이 납니다. 한도가 너무 작으면 툴 호출 피크에 exit 137과 로그 부족이 겹쳐 누수와 정상 스파이크를 구분하기 어렵습니다.
3. 의사결정 매트릭스: Kubernetes vs 원격 물리 Mac 베어메탈
launchd 습관을 Pod에 그대로 붙여 넣지 않도록 「제약마다 무엇이 이기는지」를 맞춥니다.
| 차원 | Kubernetes(Deployment + Service) | 원격 물리 Mac / launchd |
|---|---|---|
| 리슨 바인드 | Service가 닿게 bind=lan(또는 0.0.0.0); 같은 Pod 사이드카만이면 루프백 |
nginx/Caddy TLS 종단 뒤 127.0.0.1이 흔함 |
| 버전 고정 | 이미지 다이제스트 + 차트 버전 + values 해시를 변경 기록에 | 체크섬·락파일·launchd plist 버전 필드 |
| 격리 | cgroup OOMKilled·CPU 스로틀이 감사 가능 | 통합 메모리·스왑 정책; 메모리 압력·열 스로틀 관측 |
| 임시 수전 | kubectl port-forward는 스모크용—인클러스터 경로 대체 아님 |
로컬 curl 또는 SSH 터널; 경로가 짧고 레플리카 각도는 적음 |
| 전형적 롤백 | kubectl rollout undo 또는 고정된 이전 다이제스트 |
바이너리/이미지 태그 교체 + launchctl kickstart -k; 단일 인스턴스 락 주의 |
4. 7단계 런북(bind=lan·port-forward)
- 버전 고정: CI가 이미지
repo@sha256:…, Helm 차트 버전,values.yamlGit SHA를 티켓에 남기고 떠도는 태그는 프로덕션 파이프라인에서 차단합니다. - 리소스 선언:
requests.memory는 P95 상주 워킹셋 근처,limits.memory는 툴 호출·JSON 버퍼 피크를 덮도록; CPU requests로 이미 포화한 노드 스케줄을 피합니다. - 바인드·포트 정합: 트래픽이 Service/Ingress로 오면
bind=lan(또는 문서화된 듀얼 스택)을 쓰고containerPort·targetPort·프로브 포트를 일치시킵니다. - 프로브 구성: 준비성은 실제 트래픽과 같은 프로토콜/호스트/경로 튜플을 칩니다; 스킬 로딩 등 콜드 스타트에는
initialDelaySeconds·startupProbe로 NotReady 플리커를 막습니다. - port-forward 스모크: 운영 PC에서
kubectl port-forward deploy/openclaw-gateway 18789:18789(포트는 교체)로 최소 헬스와 한 번의 툴 호출을 하고, 인클러스터 프로브를 반복해 두 경로가 합치하는지 기록합니다. - 관측·알림: 재시작 횟수, OOMKilled, readiness=false 지속 시간, 5xx, 게이트웨이 큐 깊이를 한 대시보드에 묶고 변경 전후 24시간 창을 둡니다.
- 베어메탈 대조 서명: 원격 물리 Mac에서 동일 다이제스트로 네이티브 설치 또는 Compose로 핵심 헬스를 반복하고 차이를 문서화합니다. 클라이언트—macOS 게이트웨이 정합은 2026년 OpenClaw Windows·Linux와 원격 macOS 게이트웨이: PowerShell·WSL2·프록시 Runbook과 함께 보세요.
5. 인용 가능한 임계값·파라미터
- 이미지 고정: 프로덕션 티켓에 다이제스트와 빌드 ID; 롤백 후 사고 시각과 교차 검증합니다.
- 메모리 여유: 툴 호출 스파이크가 관측될 때 한도는 설명 가능한 P95 상주보다 대략 25–40% 위를 유지; 맹목적 2배는 지양하고 스로틀을 먼저 검토합니다.
- 프로브 콜드 스타트: 30초 넘는 콜드 스타트면 startupProbe 또는 40–60초급 유예를 workspace/스킬 로드 시간에 맞춥니다.
- port-forward: 스모크 전용; SLO 서명에는 인클러스터 Service DNS와 Ingress/TLS 경로를 포함합니다.
6. FAQ: OOM, NotReady, 롤백
bind=lan이 노출면을 넓히나요?
Pod 안에서 루프백이 아닌 주소로 리슨한다고 해서 곧바로 인터넷 공개는 아닙니다. 노출은 Service 유형, Ingress, NetworkPolicy, 이그레스 정책으로 정의합니다. 「프로세스 바인드」와 「누가 Pod로 라우팅할 수 있는지」를 분리해 감사하세요.
OOMKilled 시 첫 단계는?
kubectl describe pod의 Last State, 노드 메모리 압력, exit 137을 읽고 동시 툴 호출·페이로드 크기와 상관시켜 스파이크를 누수와 혼동하지 않도록 합니다.
로그에는 리슨인데 NotReady—무엇부터?
프로브 URL 포트·경로, startupProbe 부재, kubelet 소스를 막는 NetworkPolicy, 준비 후에만 마운트되는 HTTP 라우트를 확인합니다.
컴플라이언스 관점에서 롤백은 어떻게 남기나요?
이전 다이제스트와 Helm 리비전을 보관하고 kubectl rollout undo 후 인클러스터 헬스와 최소 비즈니스 핸드셰이크 증거를 티켓에 첨부합니다.
7. 동일 게이트웨이 버전을 Mac mini에 맞추기 쉬운 이유
Kubernetes는 레플리카·롤링 업데이트·쿼터 감사를 담당하고, 원격 물리 Mac 노드—흔히 Mac mini M4—는 서명·Screen Sharing·Apple 생태계 연동에 여전히 실용적입니다. 클러스터 이미지를 승격하기 전 동일 다이제스트를 launchd 아래에서 먼저 돌리면 늦게 터지는 바인드·프로브 불일치를 줄입니다.
macOS에서는 Unix 도구와 SSH가 기본이고, Apple Silicon 통합 메모리는 소형 PC 여러 대보다 장기 게이트웨이 프로세스에 유리하며, 대기 전력 약 4W급이라 7×24 대조 테스트 비용이 낮습니다. Gatekeeper·SIP·FileVault는 일반 Windows 이미지 대비 악성코드 표면을 줄입니다. 클러스터와 베어메탈에서 같은 헬스 신호를 맞추려면 조용하고 효율적인 Mac mini M4가 강한 기준 노드입니다.
이 런북을 실제 하드웨어에서 검증하려면 Mac mini M4는 프로덕션 클러스터와 병행하기 좋은 비용 대비 표준 대조 노드입니다. 지금 구성해 두면 롤아웃 전 바인드·프로브 리스크를 크게 줄일 수 있습니다.
클러스터 밖 「골든」 대조용 Mac mini
원격 macOS에서 동일 빌드를 먼저 서명한 뒤 Kubernetes 이미지를 승격하세요—프로브·바인드 사고를 줄입니다.