2026年 OpenClaw Gateway の Kubernetes デプロイと検収 Runbook：バージョン固定、リソース割当、bind=lan、port-forward、典型 OOM／NotReady ロールバック（FAQ＋リモート物理 Mac ベアメタル対照）
プラットフォーム／SRE チームが Kubernetes 上に OpenClaw Gateway を載せるとき、イメージの漂流、プローブとバインド先の不一致、実トラフィックと噛み合わない port-forward スモーク、OOM／NotReady 時に戻すかチューニングするかで検収が止まりがちです。本稿では Kubernetes とリモート物理 Mac の対照表、七ステップの Runbook、変更票に貼れる 閾値、症状ベースの FAQ を整理します。
1. はじめに：なぜゲートウェイ検収にネットワークと cgroup の根拠が要るか
ベアメタルでは「ポートが立った」ことがしばしばバインド成功と同義になります。Kubernetes では同じログ行でも、Service エンドポイント、kube-proxy（または CNI のデータパス）、NetworkPolicy、cgroup のメモリ計上を通過します。ノート PC 由来の 127.0.0.1 思考のままだと、Pod 内 curl は通るのに Service 経由は失敗する、プロセスは生きているのに Ready が赤のままといった偽陰性が出ます。
本ガイドは変更票に貼れる根拠の鎖を示します：イメージダイジェストと Helm values のハッシュ、OOM イベントと整合した requests／limits、targetPort と一致した bind=lan、port-forward スモークとクラスタ内プローブの突き合わせ。グローバルな macOS ノード配置も検討している場合は、2026年グローバル展開ガイド｜地域別・最適なmacOSノードの選び方 とあわせ、「同一バージョン・二トラック」の親テンプレートとして使えます。
2. 三つの痛点：バージョン漂流、bind とプローブ、クォータとノイズ
- バージョン漂流と再現不能：本番が
:latestやダイジェストのないタグだと、数週間後に同じタグでも挙動が変わります。ロールバックしても、インシデント当時の ReplicaSet とバイナリが一致したと証明しづらくなります。 - バインド先、Service、プローブの衝突：ゲートウェイがループバックで聴き、Readiness が Pod IP を叩く／あるいは bind=lan は正しいが NetworkPolicy が Ingress 側 CIDR しか許さず kubelet プローブが落ちる——NotReady とトラフィック停止が同居します。
- リソースクォータと隠れたコスト：requests 未設定だとスケジュールは「成功」し続け、ノード詰めのあと遅延 OOM。limits が小さすぎるとツール呼び出しのピークで exit 137 とログに残りにくい再起動が続き、メトリクスがないとリークと正常スパイクの区別がつきません。
3. 意思決定表：Kubernetes とリモート物理 Mac ベアメタル
「どの制約のもとでどちらが勝つか」を揃え、launchd の習慣を Pod にそのまま貼り付けないようにします。
| 観点 | Kubernetes（Deployment＋Service） | リモート物理 Mac／launchd |
|---|---|---|
| リッスンバインド | Service から届くには bind=lan（または 0.0.0.0）。同一 Pod 内サイドカーだけならループバック |
nginx／Caddy 背後ではしばしば 127.0.0.1 |
| バージョン固定 | イメージダイジェスト＋チャート版＋values の git SHA を変更票に | チェックサム、ロックファイル、launchd plist の版フィールド |
| 隔離 | cgroup の OOMKilled と CPU スロットルが監査しやすい | ユニファイドメモリとスワップ方針。メモリ圧と熱スロットルに注意 |
| アドホック検収 | kubectl port-forward はスモーク用——クラスタ内経路の代替ではない |
ローカル curl や SSH トンネル。経路が短くレプリカ角度が少ない |
| 典型ロールバック | kubectl rollout undo または固定した前ダイジェスト |
バイナリ／タグ差し替え＋launchctl kickstart -k。単一インスタンスロックに注意 |
4. 七ステップ Runbook（bind=lan と port-forward）
- バージョン固定：CI がイメージ
repo@sha256:…、Helm チャート版、values.yamlの git SHA をチケットに書き、浮動タグの本番パイプラインをブロックする。 - リソース宣言：
requests.memoryは P95 常駐に近づけ、limits.memoryはツール呼び出しと JSON バッファを含める。CPU requests で過密ノードへのスケジュールを避ける。 - バインドとポート整合：トラフィックが Service／Ingress 経由なら
bind=lan（または文書化したデュアルスタック）とし、containerPort、targetPort、プローブのポートを一致させる。 - プローブ設定：Readiness は実トラフィックと同じプロトコル／ホスト／パスの組み合わせ。cold start には
initialDelaySecondsまたはstartupProbeを入れ、スキル読み込みで NotReady がフラップしないようにする。 - port-forward スモーク：運用端末から
kubectl port-forward deploy/openclaw-gateway 18789:18789（ポートは置換）で最小ヘルスと 1 回のツール呼び出しを完了。続けてクラスタ内プローブを実行し、両経路が一致するか記録する。 - 観測とアラート：再起動回数、OOMKilled、readiness=false の継続時間、5xx、ゲートウェイキュー深さを一枚のダッシュボードに。変更の前後 24 時間の窓を残す。
- ベアメタル対照検収：リモート物理 Mac で同一ダイジェストをネイティブまたは Compose で繰り返し、主要ヘルスシグナルの差分を文書化——クライアントから macOS ゲートウェイへの整合は 2026年 OpenClaw：Windows／Linux への導入とリモート macOS ゲートウェイ接続 — PowerShell と WSL2 の二系統、企業 HTTPS プロキシと Node 版固定の Runbook も参照。
5. 引用しやすい閾値とパラメータ
- イメージ固定：本番チケットにダイジェストとビルド ID を含め、ロールバックはインシデント時刻と突き合わせる。
- メモリ余裕：観測されたツール呼び出しスパイクでは、説明可能な P95 常駐より limits をおおよそ 25〜40% 上に。無制限に倍増する前にスロットルを優先。
- プローブ起動：cold start が 30 秒超のゲートウェイは startupProbe か ≥40〜60 秒の猶予を、OpenClaw のワークスペース／スキル読み込み時間に合わせる。
- port-forward：スモーク専用。検収 SLO にはクラスタ内 Service DNS と Ingress／TLS 経路を必ず含める。
6. FAQ：OOM、NotReady、ロールバック
bind=lan は露出を広げませんか？
Pod 内でループバック以外で聴くこと自体がインターネット公開と同義ではありません。表面積は Service 種別、Ingress、NetworkPolicy、egress で決まります。「プロセスのバインド」と「Pod に誰がルーティングできるか」は別監査です。
OOMKilled の第一歩は？
kubectl describe pod の Last State、ノードのメモリ圧、exit 137 を読み、同時ツール呼び出しやペイロードサイズと相関させて、スパイクをリークと取り違えないようにする。
ログでは listening なのに NotReady——まず何を直す？
プローブ URL のポート／パス、startupProbe 不足、kubelet 元を落とす NetworkPolicy、Ready になるまで HTTP ルートを掛けない設計を確認する。
コンプライアンス向けにロールバックをどう記録する？
前ダイジェストと Helm リビジョンを保持し、kubectl rollout undo 後にクラスタ内ヘルスと最小ビジネスハンドシェイクを実行、証跡をチケットに添付する。
7. 同一ゲートウェイ版を Mac mini に揃える利点
Kubernetes はレプリカ、ローリング更新、クォータ監査を担いますが、署名や Screen Sharing、Apple エコシステム連携では リモート物理 Mac——多くの場合 Mac mini M4——が現実的な基準ノードです。クラスタイメージを昇格する前に、同一 ダイジェスト を launchd 下で先に通すと、後からのバインドとプローブの驚きが減ります。
macOS では Unix ツールチェインと SSH がそのまま使え、Apple Silicon のユニファイドメモリは長寿命ゲートウェイに有利で、アイドル級数ワットの消費で 7×24 の対照試験も現実的です。Gatekeeper、SIP、FileVault は一般的な Windows フリートより脅威面を抑えやすくなります。クラスタとベアメタルで同等のヘルスシグナルを揃えたいなら、静音で効率的な Mac mini M4 は強い参照ノードになります。
本 Runbook を実ハードで検証する準備ができたら、Mac mini M4 は本番クラスタと並行して走らせるコスト効率の良い標準対照ノードです。ZoneMac の専用ノードで同じ手順を Apple Silicon 上に再現できます。今が手の届きやすいタイミングです。
クラスタ外の「ゴールデン」対照に Mac mini を
先にリモート macOS で同一ビルドを検収してから Kubernetes イメージを昇格——プローブとバインドのインシデントを減らします。