feat(ai-env): write runbooks and prompt context in Japanese, set HITL_LANG=ja
ランブック 11 本と prompts/topology.md・slo.md を日本語で書き直し、 system.md に「根拠と判断理由は日本語で書く」指示を追加した。 Discord ボットの文言も HITL_LANG=ja で日本語になる。 識別子（action id、ラベル、メトリクス名、オブジェクト名）は英語のまま。
This commit is contained in:
seon committed
1 parent
027e896f30
commit
364654bb2c
16 files changed
+48
-45
No files matched your search
@@ -1,5 +1,5 @@
|
||||
# db_primary_down: primary unreachable (layer 3)
|
||||
# db_primary_down: プライマリに到達できない（層 3）
|
||||
|
||||
Symptoms: probe_success{target="db-primary"} = 0, api 5xx on /api/orders and /api/price, legacy-api logs show connection refused or timeout to 10.20.0.20:5432.
|
||||
症状: probe_success{target="db-primary"} = 0、/api/orders と /api/price で api が 5xx、legacy-api のログに 10.20.0.20:5432 への connection refused か timeout が出ます。
|
||||
|
||||
Decision tree for the human: 1) Is the VM RUNNING and only PostgreSQL down? Restart PostgreSQL on the primary (service restart; layer 1 systemd handles crashes). 2) Is the VM stopped or lost? gce.instance_reset or recreate through Terraform. 3) Only if the primary cannot come back: promote the replica (`SELECT pg_promote()` on selfheal-db-replica) and switch the application DSN to 10.20.0.21; this is irreversible (timeline fork), the old primary must be re-cloned. The agent must escalate, never propose promotion.
|
||||
人が判断する手順は次の順です。1) VM は RUNNING で PostgreSQL だけが落ちていますか。その場合はプライマリで PostgreSQL を再起動します（service restart。クラッシュは層 1 の systemd が拾います）。2) VM が停止しているか失われていますか。その場合は gce.instance_reset か、Terraform で作り直します。3) プライマリがどうしても戻らない場合に限り、レプリカを昇格します（selfheal-db-replica で `SELECT pg_promote()`）。あわせてアプリケーションの DSN を 10.20.0.21 に切り替えます。これは不可逆です（タイムラインが分岐します）。旧プライマリは再クローンが必要です。エージェントは必ずエスカレーションし、昇格を提案してはいけません。
|
||||
@@ -1,5 +1,5 @@
|
||||
# db.replay_resume (layer 2, small impact, reversible)
|
||||
# db.replay_resume（層 2、影響小、元に戻せる）
|
||||
|
||||
When: DbReplicationLag fires with pg_is_wal_replay_paused = 1 on selfheal-db-replica (replay was paused by an experiment or an operator). Lag alone with replay not paused points to network or load; do not propose this action then.
|
||||
使う場面: DbReplicationLag が発火し、selfheal-db-replica で pg_is_wal_replay_paused = 1 になっているときです（実験かオペレーターが replay を一時停止した状態）。replay が止まっていないのに遅延だけがある場合はネットワークか負荷の問題なので、この action は提案しないでください。
|
||||
|
||||
Procedure (harness action db.replay_resume, target {host: db-replica}): the harness runs `SELECT pg_wal_replay_resume()` as role harness over TLS. Verify pg_replication_lag_seconds falling to near 0 within a minute. Undo: `pg_wal_replay_pause()` (only for experiments).
|
||||
手順（ハーネスの action db.replay_resume、target {host: db-replica}）: ハーネスがロール harness で TLS 経由により `SELECT pg_wal_replay_resume()` を実行します。pg_replication_lag_seconds が 1 分以内にほぼ 0 まで下がることを確認してください。取り消しは `pg_wal_replay_pause()` です（実験のときだけ）。
|
||||
@@ -1,5 +1,5 @@
|
||||
# Layer-3 queue: how a human acts
|
||||
# 層 3 のキュー: 人はどう動くか
|
||||
|
||||
Every escalation lands in the Discord escalation channel with the diagnosis and the matching runbook in a thread. The human either follows the runbook directly or calls the harness with the operator token (Secret Manager selfheal-harness-token): `POST http://10.20.0.11:8080/actions/execute {"action_id": "...", "target": {...}, "token": "<operator token>", "note": "..."}`. Both paths are recorded in the harness events as actor=human, which feeds the human-path MTTR.
|
||||
エスカレーションはすべて Discord の escalation チャンネルに届きます。診断と、対応するランブックがスレッドに付きます。人はランブックに沿って直接対処するか、オペレーター用トークン（Secret Manager の selfheal-harness-token）でハーネスを呼び出します: `POST http://10.20.0.11:8080/actions/execute {"action_id": "...", "target": {...}, "token": "<operator token>", "note": "..."}`。どちらの経路もハーネスのイベントに actor=human として記録され、人の経路の MTTR に反映されます。
|
||||
|
||||
Proposals that receive no decision within 15 minutes are moved here automatically; the original message is marked expired.
|
||||
15 分以内に判断されなかった提案は自動でここへ移り、元のメッセージには期限切れの印が付きます。
|
||||
@@ -1,5 +1,5 @@
|
||||
# gce.instance_reset (layer 2, large impact, reversible)
|
||||
# gce.instance_reset（層 2、影響大、元に戻せる）
|
||||
|
||||
When: a pet VM (selfheal-obs, selfheal-harness, selfheal-db-replica) is hung: no SSH, no metrics, docker not responding, while the instance status is RUNNING. Do not reset selfheal-db-primary on a suspicion; a primary outage is a layer-3 decision (db-primary-down.md).
|
||||
使う場面: ペット VM（selfheal-obs、selfheal-harness、selfheal-db-replica）が固まっているときです。インスタンスの状態は RUNNING なのに、SSH が通らない、メトリクスが来ない、docker が応答しない、という状況です。疑いだけで selfheal-db-primary をリセットしてはいけません。プライマリの障害は層 3 の判断です（db-primary-down.md）。
|
||||
|
||||
Procedure (harness action gce.instance_reset, target {instance: selfheal-db-replica}): `gcloud compute instances reset`; the startup script re-runs vm/<role>/apply.sh and services come back in 2 to 4 minutes. Undo: none; the disk is kept.
|
||||
手順（ハーネスの action gce.instance_reset、target {instance: selfheal-db-replica}）: `gcloud compute instances reset` を実行します。起動スクリプトが vm/<role>/apply.sh を再実行し、サービスは 2〜4 分で戻ります。取り消しはありません。ディスクは保持されます。
|
||||
@@ -1,5 +1,5 @@
|
||||
# k8s.node_drain and k8s.node_uncordon (layer 2, large impact, reversible)
|
||||
# k8s.node_drain と k8s.node_uncordon（層 2、影響大、元に戻せる）
|
||||
|
||||
When: one worker is unhealthy (NotReady, kubelet errors, pods on that node failing while other nodes are fine). Draining moves the pods to the other two workers.
|
||||
使う場面: ワーカー 1 台だけが不健全なときです。NotReady になっている、kubelet がエラーを出している、そのノード上の pod だけ失敗していて他のノードは正常、といった状態です。drain すると pod は残り 2 台のワーカーへ移ります。
|
||||
|
||||
Procedure (harness action k8s.node_drain, target {node: ip-10-10-10-11}): cordon + drain with eviction (PDB respected, may take minutes). Afterwards investigate the node. Undo: k8s.node_uncordon with the same target. Only drain one worker at a time; the api PDB needs two replicas available.
|
||||
手順（ハーネスの action k8s.node_drain、target {node: ip-10-10-10-11}）: cordon したうえで eviction による drain を行います（PDB を尊重するため、数分かかることがあります）。そのあとノードを調査してください。取り消しは、同じ target で k8s.node_uncordon を実行します。drain は一度に 1 台だけにしてください。api の PDB は 2 replicas が利用可能であることを要求します。
|
||||
@@ -1,5 +1,5 @@
|
||||
# k8s.rollout_restart (layer 1 with signature, layer 2 in the gray zone)
|
||||
# k8s.rollout_restart（シグネチャありなら層 1、グレーゾーンでは層 2）
|
||||
|
||||
When: api or front pods are degraded without a configuration change (readiness failing, stale connections after a network incident, memory stress that cleared). Impact small, reversible.
|
||||
使う場面: 設定変更がないのに api や front の pod が劣化しているときです。readiness が失敗している、ネットワーク障害のあとに古いコネクションが残っている、メモリ負荷が収まったあとに pod が不安定、といった状況が当てはまります。影響は小さく、元に戻せます。
|
||||
|
||||
Procedure (harness action k8s.rollout_restart, target {namespace: demo, deployment: api}): the harness runs the equivalent of `kubectl -n demo rollout restart deployment/api`; pods are replaced one by one under the PodDisruptionBudget. Verify with `kubectl -n demo rollout status deployment/api` and probe_success{target="alb"} back to 1 within 2 minutes. Undo: none needed.
|
||||
手順（ハーネスの action k8s.rollout_restart、target {namespace: demo, deployment: api}）: ハーネスが `kubectl -n demo rollout restart deployment/api` に相当する操作を行い、pod は PodDisruptionBudget の範囲で 1 つずつ入れ替わります。確認は `kubectl -n demo rollout status deployment/api` と、probe_success{target="alb"} が 2 分以内に 1 へ戻ることで行います。取り消しは不要です。
|
||||
@@ -1,5 +1,5 @@
|
||||
# k8s.rollout_undo (layer 2, large impact, reversible)
|
||||
# k8s.rollout_undo（層 2、影響大、元に戻せる）
|
||||
|
||||
When: a new revision of api or front started failing (ReplicaSet of the latest revision has ready < desired while the previous revision was healthy). Check `get_k8s replicasets` revisions and events before proposing.
|
||||
使う場面: api や front の新しいリビジョンが失敗し始めたときです。最新リビジョンの ReplicaSet で ready < desired になっていて、1 つ前のリビジョンは正常だった、という状態が目安です。提案する前に `get_k8s replicasets` でリビジョンとイベントを確認してください。
|
||||
|
||||
Procedure (harness action k8s.rollout_undo, target {namespace: demo, deployment: api}): the harness runs `kubectl rollout undo deployment/<name>`. Note that Argo CD selfHeal will re-apply the Git revision; a lasting fix needs a Git commit. Undo: run rollout undo again.
|
||||
手順（ハーネスの action k8s.rollout_undo、target {namespace: demo, deployment: api}）: ハーネスが `kubectl rollout undo deployment/<name>` を実行します。ただし Argo CD の selfHeal が Git のリビジョンを再適用するため、恒久的に直すには Git へのコミットが要ります。取り消しは、もう一度 rollout undo を実行します。
|
||||
@@ -1,5 +1,5 @@
|
||||
# k8s.scale (layer 2, small impact, reversible, costs resources)
|
||||
# k8s.scale（層 2、影響小、元に戻せる、リソースを消費する）
|
||||
|
||||
When: latency or error ratio is caused by capacity (all api pods Running, CPU or memory saturated, no crashes) and more replicas would absorb the load. Not for crashes or DB problems.
|
||||
使う場面: レイテンシやエラー率の原因が容量不足のときです。api の pod がすべて Running で、CPU かメモリが飽和していて、クラッシュはなく、replicas を増やせば負荷を吸収できる、という状況です。クラッシュや DB の問題には使いません。
|
||||
|
||||
Procedure (harness action k8s.scale, target {namespace: demo, deployment: api, replicas: N}): the harness sets spec.replicas. Argo CD selfHeal restores the Git value (3) at the next sync unless the change is committed, so this is a temporary relief. Undo: scale back to the original replicas.
|
||||
手順（ハーネスの action k8s.scale、target {namespace: demo, deployment: api, replicas: N}）: ハーネスが spec.replicas を設定します。ただし一時しのぎです。変更をコミットしない限り、次の同期で Argo CD の selfHeal が Git の値（3）に戻します。取り消しは、元の replicas に戻すだけです。
|
||||
@@ -1,5 +1,5 @@
|
||||
# mig.recreate_instance and mig.resize (layer 2, small impact, reversible)
|
||||
# mig.recreate_instance と mig.resize（層 2、影響小、元に戻せる）
|
||||
|
||||
When: one legacy-api instance serves errors or is unreachable but the MIG health check has not (yet) replaced it; or the MIG target size is below 2 after an experiment.
|
||||
使う場面: legacy-api のインスタンス 1 台がエラーを返すか到達不能なのに、MIG のヘルスチェックが（まだ）置き換えていないときです。実験のあとで MIG のターゲットサイズが 2 を下回っているときにも使います。
|
||||
|
||||
Procedure (harness action mig.recreate_instance, target {instance: legacy-xxxx} or {instance: "legacy:0"}): the instance is deleted and recreated from the template; the new instance clones the gitops repository and starts compose. 2 to 3 minutes. mig.resize target {mig: selfheal-legacy-mig, size: 2} restores the standard size. Undo: resize back to 2 before the end of the session (ownership rule).
|
||||
手順（ハーネスの action mig.recreate_instance、target {instance: legacy-xxxx} または {instance: "legacy:0"}）: インスタンスは削除され、テンプレートから作り直されます。新しいインスタンスは gitops リポジトリを clone して compose を起動します。2〜3 分かかります。mig.resize は target {mig: selfheal-legacy-mig, size: 2} で標準サイズに戻します。取り消しは、セッション終了前にサイズを 2 へ戻すことです（所有権の決まり）。
|
||||
@@ -1,5 +1,5 @@
|
||||
# net.route_change (layer 2, large impact, reversible, Terraform path)
|
||||
# net.route_change（層 2、影響大、元に戻せる、Terraform 経由）
|
||||
|
||||
When: the cross-cloud path (api pods -> VPN -> ILB -> legacy) is broken by a route or firewall problem that is not transient (BGP sessions down, routes missing on one side). Transient partitions and packet loss that already cleared need no action.
|
||||
使う場面: クラウド間の経路（api pod -> VPN -> ILB -> legacy）が、一時的でないルートかファイアウォールの問題で壊れているときです。BGP セッションが落ちている、片側でルートが欠けている、といった状態です。すでに収まった一時的な分断やパケットロスには対処は要りません。
|
||||
|
||||
Procedure: the harness records the proposal; the change itself is applied by an operator through Terraform (stacks/10-network). Undo: Terraform apply of the previous revision.
|
||||
手順: ハーネスは提案を記録するだけです。実際の変更は、オペレーターが Terraform（stacks/10-network）で適用します。戻すときも同じです。1 つ前のリビジョンを Terraform apply してください。
|
||||
@@ -1,5 +1,5 @@
|
||||
# schema_mismatch: application errors after a schema or data change (layer 3)
|
||||
# schema_mismatch: スキーマかデータの変更後にアプリケーションがエラーを返す（層 3）
|
||||
|
||||
Symptoms: api or legacy-api 5xx with SQL errors in the logs (column does not exist, relation missing, constraint violation) while the database is reachable and replication is fine.
|
||||
症状: api か legacy-api が 5xx を返し、ログに SQL エラー（column does not exist、relation missing、constraint violation）が出ています。一方でデータベースには到達でき、レプリケーションも正常です。
|
||||
|
||||
Decision for the human: identify the change (ask who ran it, check recent DDL), then either roll the application forward to a matching version through Git or repair the schema/data with SQL (db.data_fix, irreversible). Restarting pods does not help. The agent must escalate.
|
||||
人の判断: まず変更を特定します（誰が実行したかを確認し、最近の DDL を調べます）。そのうえで、Git を通してアプリケーションを対応するバージョンへ進めるか、SQL でスキーマかデータを修復します（db.data_fix、不可逆）。pod を再起動しても直りません。エージェントは必ずエスカレーションします。
|
||||
@@ -1,7 +1,7 @@
|
||||
# Topology and ownership
|
||||
# トポロジと所有権
|
||||
|
||||
Container layer on AWS (kubeadm cluster: control plane 10.10.0.10, three workers 10.10.10.11, 10.10.10.12, 10.10.11.11). Workloads in namespace demo: api (3 replicas) and front (2 replicas), exposed through ingress-nginx and the ALB. Argo CD keeps the cluster equal to the gitops repository (selfHeal, prune).
|
||||
コンテナ層は AWS 上の kubeadm クラスタです（コントロールプレーン 10.10.0.10、ワーカー 3 台 10.10.10.11、10.10.10.12、10.10.11.11）。namespace demo のワークロードは api（3 replicas）と front（2 replicas）で、ingress-nginx と ALB を通して公開しています。Argo CD がクラスタを gitops リポジトリと同じ状態に保ちます（selfHeal、prune）。
|
||||
|
||||
VM layer on GCP (subnet 10.20.0.0/20): selfheal-obs 10.20.0.10 (Mimir, Loki, Tempo, Grafana), selfheal-harness 10.20.0.11 (runner, probes, k6), selfheal-ai 10.20.0.12 (diagnosis agent and Discord bot), selfheal-db-primary 10.20.0.20, selfheal-db-replica 10.20.0.21 (streaming replication, slot replica1), legacy MIG selfheal-legacy-mig (instances legacy-xxxx, docker compose legacy-api on 8080) behind the ILB 10.20.0.100:8080.
|
||||
VM 層は GCP 上です（サブネット 10.20.0.0/20）。selfheal-obs 10.20.0.10（Mimir、Loki、Tempo、Grafana）、selfheal-harness 10.20.0.11（runner、プローブ、k6）、selfheal-ai 10.20.0.12（診断エージェントと Discord ボット）、selfheal-db-primary 10.20.0.20、selfheal-db-replica 10.20.0.21（ストリーミングレプリケーション、スロット replica1）、legacy MIG selfheal-legacy-mig（インスタンス legacy-xxxx、docker compose の legacy-api がポート 8080）が ILB 10.20.0.100:8080 の後ろにあります。
|
||||
|
||||
Ownership: Terraform owns instances, networks and the MIG target size (restore 2 before the end of a session). Git owns everything inside the cluster. Operators change VM services only through the gitops vm/<role>/apply.sh scripts.
|
||||
所有権の決まりは次のとおりです。インスタンス、ネットワーク、MIG のターゲットサイズは Terraform が持ちます（セッション終了前に 2 へ戻してください）。クラスタの中身はすべて Git が持ちます。VM 上のサービスは、オペレーターが gitops の vm/<role>/apply.sh を通してだけ変更します。
|
||||
Reference in new issue
Block a user