デバッグ API

このデプロイメントの 1 台の CE から 2026-07-28 に取得しました。sitecli/capture-manifest.json にどのノードかが記録されており、scripts/capture-sitecli.sh --check により実行中の CE に対して コマンド一覧を再検証できます。

vpm/debug API は登録済みノード上で Site CLI コマンドを実行し、その出力を返します。 以下の内容はすべて稼働中のノードに対して確認したものであり、いずれも上流では 公開されていません。

コマンドカタログは自己記述型です

command キーを省略して exec-user に POST することで、ノードがサポートする内容を 問い合わせられます:

curl -sS -X POST \
  -H "Authorization: APIToken $XCSH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"namespace":"system","site":"<site>","node":"<node>"}' \
  "$XCSH_API_URL/api/operate/namespaces/system/sites/<site>/vpm/debug/<node>/exec-user" \
  | jq -r .output | jq .

レスポンスはコマンド名をキーとする JSON オブジェクトです:

{
  "crictl-inspect": ["System Troubleshooting", "ExecUser", " container-id"],
  "diagnosis":      ["System Troubleshooting", "ExecUser", "no argument needed", "GLOBAL"],
  "ip-link-set":    ["Network Troubleshooting", "Exec", " (<device>||<group>) (up||down)"]
}

各エントリは [category, tier, exampleArgument?, scope?] であり、これらのフィールドは ドキュメントではなく、コマンドをどのように呼び出さなければならないかを決定します。

キーは省略してください。誤った値を送らないでください

ディスカバリは command を省略することで動作します。代わりに未知の値を送信すると、 カタログではなくエラーが返ります:

{"code":3,"details":[],"message":"exec command failed: command not supported"}

このメッセージは、実在するコマンドを誤ったエンドポイントに送信した場合にも返されるため、 「このコマンドは存在しない」と誤読しやすいものです。

カタログエントリによって選択される 3 つのトランスポート

条件	メソッドとパス	ボディ	戻り値
scope が GLOBAL	GET .../vpm/debug/global/<cmd>	なし	JSON
tier が ExecUser	POST .../vpm/debug/<node>/exec-user	command 配列	テキスト
tier が Exec	POST .../vpm/debug/<node>/exec	command 配列	テキスト

ExecUser — 読み取り専用ティア 31 コマンド

一般的なケースです。コマンド名を先頭にして、コマンドとその引数を配列として渡します:

curl -sS -X POST \
  -H "Authorization: APIToken $XCSH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"namespace":"system","site":"<site>","node":"<node>","command":["crictl-ps"]}' \
  "$XCSH_API_URL/api/operate/namespaces/system/sites/<site>/vpm/debug/<node>/exec-user"

{ "return_code": 0, "output": "CONTAINER    IMAGE    CREATED    STATE ..." }

引数は単一の文字列ではなく、個別の配列要素として指定します:

{ "command": ["journalctl", "-u", "vpm", "-n", "200"] }

GLOBAL — サイト全体を対象とし、まったく異なるトランスポート 2 コマンド

health と diagnosis の 2 つのみです。これらは global パスへの GET リクエストで、 引数を取らず、ターミナルテキストではなく構造化された JSON を返します。

curl -sS -H "Authorization: APIToken $XCSH_API_TOKEN" \
  "$XCSH_API_URL/api/operate/namespaces/system/sites/<site>/vpm/debug/global/health" | jq .

GLOBAL コマンドは exec-user 経由では到達できません

これが最も時間を浪費する落とし穴です。health や diagnosis を exec-user に送信すると command not supported が返り、そのコマンドがノード上に存在しないかのように読めますが、 実際にはコマンドは存在しており、誤ったトランスポートを使用しただけです。

# 誤り。返り値: exec command failed: command not supported
-d '{"namespace":"system","site":"…","node":"…","command":["health"]}'   # POST exec-user

# 正しい方法。
GET .../vpm/debug/global/health

Exec — 特権ティア このビルドでは 1 コマンド

別のエンドポイントであり、ティアは助言的なものではなく強制されます: exec は 同じ command not supported メッセージで ExecUser コマンドを拒否します。所属する すべてのコマンドは、ノードを変更するか、状態マーカーを読み取るかのいずれかです。

このテナントが稼働しているビルドでは、このティアには ip-link-set のみが含まれます。 より新しいビルドでは systemctl-restart-NetworkManager、systemctl-restart-crio、 systemctl-restart-kubelet、systemctl-start-crio-prune および 3 つの marker-exists-* コマンドが追加されます。

ここでは Exec コマンドを一切実行しません

キャプチャハーネスはこのティアを拒否し、ハードコードされたリストではなく稼働中の カタログからティアを読み取ります。そのため、将来のビルドがコマンドを Exec に昇格させた場合も、 誰もコードを編集することなくその内容が尊重されます。実行する場合は、意図的に、 かつ停止を許容できるノード上でのみ行ってください。

サイト名とノード名の確認方法

ノード名は Azure VM 名であり、list-service はそれをノード上で稼働しているサービスと 併せて確認する手軽な方法です:

curl -sS -H "Authorization: APIToken $XCSH_API_TOKEN" \
  "$XCSH_API_URL/api/operate/namespaces/system/sites/<site>/vpm/debug/global/list-service" \
  | jq -r '[.service[].node] | unique'

["", "f5-xc-ce-vm-01"]

一部のサービスは空のノード名を報告するため、このリスト内の空文字列は 2 台目のノードではなく レスポンスの副産物です。また list-service は 34 コマンドのカタログには含まれていません: これはカタログが公開していない global エンドポイントであり、そのためここに記載されており、 コマンドリファレンスには含まれていません。

このリポジトリのキャプチャの再現

各コマンドページには scripts/capture-sitecli.sh によって取得された出力が埋め込まれており、 このスクリプトは上記 3 つのルールすべてを実装しています。

1. テナントを指定します。XCSH_API_URL と XCSH_API_TOKEN を読み取るか、 アクティブな xcsh コンテキストにフォールバックします。

2. カタログを更新し、ドキュメントの背後でノードが変更されていないことを確認します:

   bash scripts/capture-sitecli.sh --check

   これはコミット済みのカタログとソフトウェアビルドのみを比較します。ビルドの変更は、 コマンドの追加または削除とは別に報告されます。

3. 新しい証跡が必要な場合は再キャプチャします:

   bash scripts/capture-sitecli.sh

キャプチャは証跡であり、再現可能な成果物ではありません

カウンター、稼働時間、コンテナの経過時間は実行ごとに変動するため、再キャプチャすると 必ず差分が生じます。カタログは安定した契約であり、ノードが変更されていなければ実行間で バイト単位で同一です。--check が比較するのはこの部分です。長い出力は 切り詰められ、明示的なマーカーで終わるため、切り詰められた表が完全なものとして 表示されることはありません。

顧客ノードからのキャプチャ: リダクションプロファイルを確認してください

コマンド出力にはインフラストラクチャの識別情報 — 内部アドレッシング、MAC アドレス、 AS 番号、ホスト名 — が含まれ、顧客にとってはそれが組織を特定できる情報になります。

そのためスクラブフィルターは、既定でそれらすべてを削除するstrictプロファイルになっています。 このリポジトリは sitecli/capture-manifest.json で lab を宣言しており、これによりその詳細が 保持されますが、これが妥当なのはこれらのキャプチャが F5 所有のデモインフラストラクチャから 取得されたものであるためです。

この設定を顧客のキャプチャに持ち込まないでください。 トークン、秘密鍵、テナント 識別子、オブジェクト UUID、メールアドレス、ホームディレクトリパスは、いずれのプロファイルでも 削除されます。

1 つ知っておくべき制限があります: BGP ネイバーテーブルは AS をパターンの手がかりとなる ラベルのない単なる列として出力するため、ASN は値によってプライベート範囲と照合されます。 そこにあるパブリックな ASN は strict でも残るため、公開前に show-ip-bgp* の出力を 手動でレビューする必要があります。