Customer Edge の診断

Customer Edge (CE) とは、本リポジトリが Azure 上にプロビジョニングする F5 Distributed Cloud ノードです（terraform/modules/ce-node。マーケットプレイスイメージ volterraedgeservices/volterra-node から構築されます）。

このノードでは、データプレーン (Argo)、コントロールプレーン (Vega)、Envoy プロキシ、Kubernetes スタック、そしてノードを登録しノード上のその他すべてを管理するエージェントである vpm が動作します。

CE に問題が発生した際の計測器となるのが Site CLI です。最初に判断すべきは、どのアクセス経路が該当するかであり、これを誤ると、ノードが壊れているように見える形で時間を浪費することになります。

4つのアクセス経路。互換性はありません

デバッグ APIONLINE のノード向け。スクリプト化可能で読み取り専用、34 個のコマンドを網羅します。

Site ConsoleAzure Bastion トンネル経由で使う、F5 独自のノード単位トラブルシューティング UI。SSH キーも踏み台ホストも不要です。

SSHオンボックスの Site CLI をすべて利用できます。初回起動時からキーが存在していること、および VNet 内のホストが必要です。

シリアルコンソール登録が一度も完了しなかったノード向け。ノードにネットワーク経路がない場合の唯一の手段です。

デバッグ API は、F5 Distributed Cloud のコントロールプレーンを経由してノードに到達します。この区別が重要なのはまさにそのためです。API は、ノードが登録を完了し ONLINE を報告している場合にのみ応答できます。

登録に失敗したノード（不正な cloud-init、期限切れのトークン、register.ves.volterra.io への経路がない、など）は、まさに診断が必要なケースであり、同時にまさに API では対応できないケースです。

Site Console は、特定のコマンドではなく F5 独自のトラブルシューティング UI を使いたい場合に最初に試すべき経路です。要求するものが最も少なく（キー不要、踏み台ホスト不要、ノードへのパブリック IP 不要）、接続を許可する相手の判断は Azure RBAC に委ねられ、サイトが登録済みかどうかにかかわらず応答します。必要となるのは Azure Bastion であり、本デプロイメントでは enable_bastion で制御され、デフォルトではデプロイされません。

SSH は、アプライアンスのコマンド面全体に到達できる唯一の経路です。デバッグ API が公開するのは 34 個のコマンドですが、ノード自体はさらに多くを提供します。制約は 2 つあります。 sshd はノードの内部 (SLI) アドレスでのみ応答するため、VNet 内のホストが必要です。また、キーは初回起動時に cloud-init によって書き込まれます。サイトオブジェクトの ssh_key フィールドは無効であり、vpm は admin ユーザーをスキップして一切適用しないためです。したがって、稼働中のノードで有効化するにはノードを再作成することになります。

つまり、サイトが ONLINE で 34 個のコマンドで十分ならデバッグ API を使います。UI が必要な場合、あるいは登録は完了していないもののネットワーク経路は生きているノードの場合は Site Console を使います。それ以外のコマンド面が必要で VNet に到達できるなら SSH を使います。ノードに機能するネットワーク経路がまったくない場合は、シリアルコンソールが唯一の手段です。

1 回のリクエストで、どの経路をたどるべきかがわかります。

curl -sS -H "Authorization: APIToken $XCSH_API_TOKEN" \
  "$XCSH_API_URL/api/config/namespaces/system/sites/<site>" \
  | jq -r '.spec.site_state'

ONLINE であればデバッグ API が使えます。それ以外の場合は Site Console またはシリアルコンソールです。

サイトが存在しない場合、「一度も登録されていない」より前に検討すべき説明がもう 1 つあります。誤ったテナントを指している可能性です。本デプロイメントは f5-sales-demo (https://<XC_TENANT>.console.ves.volterra.io) に存在し、var.expected_xc_tenant で固定されています。 cd terraform && terraform output -raw xc_tenant を実行すれば、何も変更せずに確認できます。別のテナント向けに発行された資格情報は素の 401 を返すため、トークンの期限切れのように見えます。

安全に関するルール

以下のルールは、このページ以下のすべてのページのすべてのコマンドに当てはまります。

確信がない限り読み取り専用にとどめること。 コマンド面は 2 つの権限階層に分かれており、 Exec 階層はノードを変更するか、状態マーカーを読み取ります。これらのページでは Exec コマンドを一切実行しませんし、キャプチャ用ハーネスも実行しません。
コマンド名から安全だと決めつけないこと。 ip-link-set は問い合わせのように見えますが、インターフェイスをダウンさせます。systemctl-restart-crio は、稼働中のデータプレーンの下でコンテナランタイムを再起動します。
疑問に答えられる最も範囲の狭いコマンドを選ぶこと。 health と diagnosis は低コストでノードの概要を示します。flow-l は生きているすべてのフローをダンプしますが、flow-l-match は 1 つの接続について同じ疑問に答えます。
CE は実トラフィックを処理しています。 これらは共有のデモ環境です。デバッグ対象のサイトから誰かがプレゼンテーションを行っていると想定してください。

ここで文書化している内容

本テナントが稼働させているソフトウェアビルドにおいて、デバッグ API から到達できるすべてのコマンドを、他所から転記するのではなく稼働中のノードから取得した出力とともに掲載しています。

コマンドリファレンスはそれらすべてをカテゴリ、権限階層、トランスポートとともに一覧化します。ワークフローは、問題が発生した際に実際に使用する順序へとそれらをつなぎ合わせます。

Site CLI のオンボックス専用の部分（configure、configure-network、factory-reset、upgrade、およびおよそ 60 個のさらなる ExecCLI コマンド）は対象外です。以下の各ページのように、稼働中のノードから出力をキャプチャしていないためです。

ただし、もはや手が届かないわけではありません。scripts/sitecli_ssh_harvest.py は SSH 経由でアプライアンス自身の補完メニューを操作し、各コマンドについてアプライアンスが示す説明を記録します。これにより、コマンド面を推測ではなく計測できます。その実行はデフォルトで拒否されます。すべてを列挙し、許可リストに含まれるものだけを実行します。検証されていないコマンド構文、そして検証されていないコマンドの影響こそが、本ドキュメントが繰り返しを避けようとしている欠陥だからです。