Contents
Envoy 基本チェックリスト – 実務で即使える手順
Envoy が稼働しているかどうかの一次判定は、障害発生時に最も早く行うべき作業です。本ガイドでは 管理 API の確認 → メトリクス・ヘルス取得 → ログと設定の検証 という流れを一本化し、環境別（OpenShift、Google Cloud Service Mesh、Docker）に合わせた具体的チェック項目を示します。各ステップで期待される数値や出力例も併記しているので、実際の作業時に「ここが違う」ことがすぐに分かります。
1. 管理 API (admin port) の一次確認
管理 API は Envoy が内部的に提供する診断用 HTTP インタフェースです。デフォルトは 9901（--admin-address-path で変更可）で、稼働判定の最初の入口となります。
1‑1. 接続テストとステータスコード確認
|
1 2 3 |
# Pod/コンテナ内部から直接実行（Kubernetes の exec 推奨） curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:9901/ready |
- 期待結果：
200が出力されること。 - 失敗例：
000（接続できない）や403などはファイアウォール／NetworkPolicy の遮断が疑われます。
1‑2. Ready エンドポイントの内容確認
|
1 2 |
curl -s http://127.0.0.1:9901/ready |
- 期待文字列：
LIVE（大文字） - 備考：
LIVEが返らない場合は Envoy プロセスが起動中でも「未初期化」状態である可能性があります。
1‑3. チェックリスト
| # | 確認項目 | 合格基準 |
|---|---|---|
| ✅ | 9901 がネットワークポリシーで遮断されていないか |
curl のステータスコードが 200 |
| ✅ | /ready が LIVE を返すか |
正確に LIVE（余計な空白なし） |
| ✅ | 管理 API が LISTEN 状態であること | netstat -tlnp | grep 9901 に LISTEN 表示 |
参考: Envoy 公式管理 API ドキュメント https://www.envoyproxy.io/docs/envoy/latest/operations/admin
2. メトリクスとヘルス情報の取得
管理 API が正常に応答したら、続いて stats と health エンドポイントで内部状態を可視化します。
2‑1. Stats の抜粋表示
|
1 2 |
curl -s http://127.0.0.1:9901/stats | head -n 20 |
- 注目指標例
listener.admin.downstream_cx_total（管理ポートの接続総数）cluster.<name>.upstream_rq_total（上流リクエスト総数）
期待結果：各指標が 0 以上 の整数で増加傾向にあること。
NaNや-1が出たら内部計測に障害があります。
2‑2. Health エンドポイントのシンプル判定
|
1 2 |
curl -s http://127.0.0.1:9901/health |
- 期待文字列：
OK FAILが返る場合は Envoy 本体がクラッシュしている、または起動フラグが欠如しています。
2‑3. チェックリスト
| # | 確認項目 | 合格基準 |
|---|---|---|
| ✅ | listener.admin.downstream_cx_total が 0 以上で増えているか |
前回取得値と比較し、増加が確認できる |
| ✅ | 任意の cluster.<name>.upstream_rq_total が 0 以上か |
正常にリクエストが流れていれば数が伸びる |
| ✅ | /health が OK を返すか |
文字列が正確に OK |
詳細は Envoy の「Stats API」ドキュメント https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/admin/v3/stats.proto を参照してください。
3. ログ取得とレベル設定
ログは障害の根本原因を示す最重要情報です。ここでは出力先別設定例と、info / debug が必要なシーンをまとめます。
3‑1. 出力先ごとの起動オプション
| 出力先 | 起動フラグ例 | 確認コマンド |
|---|---|---|
| stderr（デフォルト） | envoy -c /etc/envoy.yaml --log-level info |
kubectl logs <pod> または docker logs <container> |
| ファイル | --log-path /var/log/envoy.log |
cat /var/log/envoy.log | tail -n 20 |
| journald（systemd） | StandardOutput=journal （Unit ファイル内） |
journalctl -u envoy.service --since "5 min ago" |
3‑2. ログレベル切替のベストプラクティス
- 平常時は
infoを推奨（ノイズが少なく重要メッセージが取得できる）。 - 障害再現時は
debugに変更し、詳細スタックトレースを取得。curl -X POST http://127.0.0.1:9901/logging?level=debugで動的に切り替え可能です。
3‑3. ログチェックリスト
| # | 確認項目 | 合格基準 |
|---|---|---|
| ✅ | ログレベルが info（平常）または debug（障害再現時）か | curl http://127.0.0.1:9901/logging の出力で確認 |
| ✅ | connection refused、TLS handshake failed 等の致命エラーが無いか |
エラーパターンが 0 件 |
| ✅ | ログローテーション（logrotate や systemd‑journal の保持設定）が有効か | /etc/logrotate.d/envoy が存在、または journalctl --disk-usage が期待範囲内 |
4. 設定ファイルのバリデーションと主要要素チェック
起動時に構成ミスがあると Envoy は即座に停止します。CI パイプラインや手作業で validate モードを必ず走らせましょう。
4‑1. バリデーションコマンド
|
1 2 |
envoy -c /etc/envoy.yaml --mode validate |
- 成功時：
Configuration OKが標準出力に表示され、プロセスは終了します。 - 失敗時：エラーメッセージと行番号が返るので、該当箇所を修正。
4‑2. 主要設定要素と具体的チェックポイント
| 要素 | 確認項目 | 合格基準（例） |
|---|---|---|
| listener | address が期待 IP/Port にバインドされているか |
0.0.0.0:10000 など、リスト内に正しいエントリがある |
フィルタチェーンに http_connection_manager が含まれるか |
filter_chains[0].filters[*].name == "envoy.filters.network.http_connection_manager" |
|
| cluster | type が環境要件（EDS、STRICT_DNS 等）に合致しているか |
例: GCSM では type: XDS、K8s では type: STRICT_DNS |
load_assignment.endpoints の DNS 名が解決できるか |
nslookup <service>.svc.cluster.local が成功 |
|
| route | 仮想ホスト名とマッチング条件が正しいか | virtual_hosts[0].domains == ["example.com"] |
retry_policy.num_retries が 3 以上設定されているか |
num_retries >= 3 |
4‑3. 設定チェックリスト
| # | 確認項目 | 合格基準 |
|---|---|---|
| ✅ | バリデーションが エラーなし で終了するか | コマンドの戻り値が 0 |
| ✅ | listener のバインドポートが期待通り（例: 10000）か |
netstat -tlnp | grep <port> に LISTEN が表示 |
| ✅ | cluster の DNS 解決が成功し、エンドポイント数 > 0 |
dig +short <service>.svc.cluster.local | wc -l ≥ 1 |
| ✅ | route の domains と実際のリクエスト Host ヘッダーが一致するか |
テストリクエストで 200 が返る |
公式設定ガイドは Envoy Docs 「Configuration reference」https://www.envoyproxy.io/docs/envoy/latest/configuration/overview を参照してください。
5. 環境別トラブルシューティングフロー
以下では OpenShift（Red Hat）、Google Cloud Service Mesh（GCSM）、Docker コンテナ単体 の3つの代表的環境について、共通チェックに加えて固有の検証ポイントを示します。各サブセクションは必ず導入文で「何を確認するか」を明示しています。
5‑1. OpenShift 上での基本診断
OpenShift は独自の NetworkPolicy と Service Mesh（Istio）を併用できるため、Pod の状態と Red Hat ナレッジベースの情報が重要です。
5‑1‑a. Pod 状態とログ取得
|
1 2 3 |
oc get pods -n <namespace> -l app=envoy oc logs -n <namespace> <pod-name> |
- 期待結果：
RunningかつReadyがTrue。 - 失敗例：
CrashLoopBackOffやImagePullBackOffはイメージ・レジストリの問題。
5‑1‑b. Red Hat ナレッジベース活用
Red Hat の公式トラブルシューティングページは OpenShift Container Platform 4.x 向けにまとめられています。
- リンクテキスト: 「OpenShift Service Mesh – Envoy トラブルシューティング」
- URL（短縮表示）: https://docs.redhat.com/openshift/service-mesh/troubleshooting
5‑1‑c. OpenShift チェックリスト
| # | 確認項目 | 合格基準 |
|---|---|---|
| ✅ | oc get pods のステータスが Running / Ready か |
STATUS=Running & READY=True |
| ✅ | 管理 API が Pod 内で LISTEN されているか | oc exec <pod> -- netstat -tlnp | grep 9901 |
| ✅ | Red Hat ナレッジベースに同様症例が無いか検索済みか | キーワード envoy, proxy, CrashLoopBackOff でヒットなし |
5‑2. Google Cloud Service Mesh（GCSM）での診断
GCSM は XDS コントロールプレーンから Envoy に設定をプッシュします。VM 側で config_dump を取得し、配信状態を確認します。
5‑2‑a. VM へ SSH 接続して config_dump 取得
|
1 2 3 |
gcloud compute ssh <instance> --zone=<zone> curl -s http://127.0.0.1:9901/config_dump | jq '.configs[] | select(.type_url|contains("listener"))' | wc -l |
- 期待結果：
listeners,clusters,routesがすべて 1 以上 の数で列挙される。欠落があれば XDS 配信失敗。
5‑2‑b. 権限・ネットワークチェック
| 項目 | 確認コマンド | 想定障害 |
|---|---|---|
| サービスアカウント権限 | gcloud iam service-accounts get-iam-policy <sa> |
XDS 呼び出しが 403 でブロック |
| VPC ファイアウォール | gcloud compute firewall-rules list --filter="targetTags:envoy" |
9901 ポート遮断 → 管理 API 接続不可 |
| 起動オプション | ps -ef \| grep envoy |
--service-node-id が空、または --bootstrap-version が非推奨 |
5‑2‑c. GCSM チェックリスト
| # | 確認項目 | 合格基準 |
|---|---|---|
| ✅ | config_dump に listener / cluster / route がすべて存在するか |
各カテゴリの件数 ≥ 1 |
| ✅ | サービスアカウントに roles/meshviewer.viewer 等必要ロールが付与されているか |
IAM ポリシーで確認 |
| ✅ | VPC のファイアウォールで 9901/TCP が許可されているか | ルールに allow tcp:9901 が含まれる |
GCSM の公式トラブルシューティングは Google Cloud Docs 「Service Mesh troubleshooting」https://cloud.google.com/service-mesh/docs/troubleshooting を参照してください。
5‑3. Docker コンテナ単体でのデバッグ
ローカル環境や CI パイプラインで Envoy を直接起動する場合は、コンテナ内部からの確認が最も手軽です。
5‑3‑a. コンテナシェルとプロセス状態
|
1 2 3 4 |
docker exec -it <container> sh netstat -tlnp | grep 9901 # ポートリッスン確認 ps aux | grep envoy # 起動オプション確認 |
- 期待結果：
tcp 0 0 0.0.0.0:9901 0.0.0.0:* LISTEN <pid>/envoyが表示され、--config-path /etc/envoy.yamlが含まれる。
5‑3‑b. 代表的エラーと対処例
| エラー | 主因 | 修正手順 |
|---|---|---|
connection refused |
管理 API 未起動／ポート遮断 | 起動時に --admin-address-path /tmp/admin.socket を削除し、-l 0.0.0.0:9901 を明示 |
TLS handshake failure |
証明書不一致 | tls_context の certificate_chain, private_key が正しいファイルに指すか確認 |
routing not found |
Route 名ミスマッチ | virtual_hosts[].domains とリクエスト Host ヘッダーを比較し、正規表現の誤りを修正 |
circuit_breaker 発火 |
設定閾値過小 | cluster.circuit_breakers.thresholds.max_connections を実トラフィックに合わせて増加 |
5‑3‑c. Docker 用チェックリスト
| # | 確認項目 | 合格基準 |
|---|---|---|
| ✅ | 9901 が LISTEN 状態か | netstat 出力に LISTEN がある |
| ✅ | 起動オプションが期待通り（--config-path /etc/envoy.yaml）か |
ps -ef に正しいパスが表示 |
| ✅ | 上記エラー例のいずれもログに 出ていない か | grep -i "error" が 0 件 |
6. 実践フローとサポート活用まとめ
- 管理 API（9901） → Ready / Health を最初に確認。
- stats と config_dump で内部指標・設定の有無を検証。
- ログレベル を
infoに保ちつつ、障害再現時はdebugに切り替える。 - 構成バリデーション を CI パイプラインに組み込み、
envoy --mode validateの成功を必須条件とする。 - 環境別チェックリスト（OpenShift・GCSM・Docker）でネットワーク・権限・ポート設定を最終確認。
上記手順をすべて実施しても解決しない場合は、以下の公式サポート窓口へ問い合わせることを推奨します。
| 製品 | 公式サポートページ |
|---|---|
| Envoy（OSS） | https://www.envoyproxy.io/docs/envoy/latest/intro/support |
| OpenShift (Red Hat) | https://access.redhat.com/support |
| Google Cloud Service Mesh | https://cloud.google.com/support |
以上 が、実務で即活用できる Envoy 基本チェックリストです。各項目を チェックボックス形式 で管理すれば、障害発生時の対応漏れを防ぎ、迅速な復旧が期待できます。