Envoy

Envoy xDSで動的設定を実装 – Kubernetes DaemonSetとGo/PythonカスタムControl Plane完全ガイド

ⓘ本ページはプロモーションが含まれています

もっとスキルを活かしたいエンジニアへ

スポンサードリンク
働き方から選べる

無料で使えて良質な案件の情報収集ができるサービス

エンジニアの世界では、「いつでも動ける状態を作っておけ」とよく言われます。
技術やポートフォリオがあっても、自分に合う案件情報を日常的に見れていないと、いざ動こうと思った時に比較や判断が難しくなってしまいます。
普段から案件情報が集まる環境を作っておくと、良い案件が出た時にすぐ動きやすくなりますよ。
筆者自身も、メガベンチャー勤務時代に年収1,500万円を超えた経験があります。振り返ると、技術だけでなく「どんな案件や働き方があるか」を日頃から見ていたことが、キャリアの選択肢を広げるきっかけになりました。
このブログを読んでくれた方に感謝を込めて、実際に使っている情報収集サービスを紹介します。

フルリモート・週3日・高単価、どんな条件も妥協したくないなら

フリーランスボードに無料会員登録する

利用者10万人以上。業界最大規模45万件の案件。AIマッチ機能や無料の相場情報が人気。

年収800万円以上のキャリアアップ・ハイクラス正社員を視野に入れているなら

Beyond Careerに無料相談する

内定獲得率90%以上。紹介先企業とは役員クラスのコネクションがある安心と信頼できるエージェント。


Contents

スポンサードリンク

1. xDS API の全体像

xDS は Envoy が外部の Control Plane とやり取りするための 統一 Discovery Interface です。
リソースは独立した Service(LDS、RDS、CDS、EDS、SDS)を通じて配信され、必要なものだけを差分で更新できる点が大規模運用の鍵となります。

1.1 Listener Discovery Service (LDS)

LDS は Envoy が 受信ポートとフィルタチェーン を動的に取得するための API です。
Control Plane が Listener オブジェクトをプッシュすると、Envoy のリスナー構成が即座に反映されます。

  • 主な属性: address, filter_chains, listener_filters
  • 利用シーン: ポート追加・TLS 終端のオンデマンド切り替え

1.2 Route Discovery Service (RDS)

RDS は HTTP/HTTPS のルーティング規則RouteConfiguration)を管理します。
LDS が取得した Listener に rds 設定を埋め込むことで、ルート情報は別途配信されます。

  • 主な属性: virtual_hosts, routes, request_headers_to_add
  • 利用シーン: ホスト名・パスベースのトラフィック分岐

1.3 Cluster Discovery Service (CDS)

CDS は 上流サービス(Cluster) のロードバランシングや接続ポリシーを提供します。
Envoy が外部へリクエストするときは必ず Cluster に紐付くため、スケールやリトライ設定はここで完結します。

  • 主な属性: type, lb_policy, load_balancing_policy
  • 利用シーン: ラウンドロビン/ヘルスチェック付きのバックエンドプール

1.4 Endpoint Discovery Service (EDS)

EDS は 実際の IP:Port(Endpoint) 情報を配信し、Cluster と組み合わせて動的サービスディスカバリを実現します。
Kubernetes の Service/Pod と連携させると、ポッド増減が即座に反映されます。

  • 主な属性: lb_endpoints, health_status, metadata
  • 利用シーン: Pod IP の自動取得・ヘルスチェック結果のリアルタイム更新

1.5 Secret Discovery Service (SDS)

SDS は TLS 証明書・鍵 といった機密情報を安全に配布する API です。
mTLS 構成時は証明書ローテーションを SDS 経由で行うことで、Envoy の再起動なしにセキュリティが保たれます。

  • 主な属性: tls_certificate, validation_context
  • 利用シーン: 証明書自動更新・複数ドメインの SNI 対応

ポイント:xDS は「設定単位ごとの独立 API」を提供し、必要リソースだけを差分配信できるため、大規模クラスターでも高速かつ安全に構成変更が可能です。


2. Envoy 1.30 系のインストールと Bootstrap 設定

このセクションでは 再現性のあるパッケージインストール と、正しい Bootstrap の書き方 を解説します。
特に「gRPC と REST を同一リソースで混在できない」点や、HTTP/3・TLS がデフォルトで有効かどうかといった誤認を防ぎます。

2.1 バージョン固定でのパッケージインストール

再現性が求められる本番環境では、リポジトリから特定バージョンを明示的に取得することが必須です。
以下は Ubuntu と Alpine のそれぞれで Envoy 1.30.0 を固定インストールする例です。

Ubuntu (apt)

Alpine (apk)

注意:リポジトリ URL やパッケージ名は時期により変わる可能性があります。必ず公式ドキュメントで最新情報を確認してください。

2.2 Docker イメージの利用(バージョンタグ指定)

Docker 環境では タグでバージョン固定 が最も簡単です。

v1.30.0 はビルド時に HTTP/3 と TLS のサポートはオプション であり、公式イメージではデフォルトで無効です。必要なら環境変数やコンフィグで明示的に有効化します(後述)。

2.3 正しい Bootstrap ファイルの書き方

Bootstrap は Envoy 起動時に最初に読み込む JSON/YAML 設定です。
同一リソースタイプ(例: LDS)については gRPC と REST を同時指定できません が、異なるリソースでフォールバック戦略を取ることは可能 です。

2.3.1 基本構造と TLS 設定例

  • TLS 設定transport_socket に記述し、証明書は Kubernetes Secret からマウントします。
  • HTTP/3 の有効化はビルドオプションが必要なので、公式イメージでは環境変数 ENVOY_ENABLE_HTTP3=1 を設定するか、カスタムビルドを用意してください(別章で解説)。

2.3.2 REST フォールバック例(CDS のみ)

ポイントlds_configcds_config がそれぞれ異なる api_type を持つことは問題ありませんが、同一リソースで GRPCREST を混在させると起動エラーになります。

2.4 HTTP/3 の有効化(任意)

Envoy 1.30 系では HTTP/3 はデフォルト無効 です。以下のいずれかを選択してください。

方法 手順概要
環境変数 コンテナ起動時に ENVOY_ENABLE_HTTP3=1 を設定し、--define=envoy.build_http3=true が有効なイメージを使用
カスタムビルド ソースから bazel build //source:envoy --copt=-DENABLE_HTTP3 でビルドし、独自イメージを作成
フィルタ設定 http_connection_managerhttp3_protocol_options を明示的に記述

3. Kubernetes DaemonSet によるノード単位デプロイ

この章では 安全性・可観測性・ローリングアップデート を備えた DaemonSet マニフェストを提示し、各設定項目の意図を解説します。

3.1 DaemonSet マニフェスト全体像(約150 行)

以下は Envoy v1.30.0 用に最適化した DaemonSet 定義です。
hostNetworksecurityContext による権限最小化、TLS シークレットのマウント、admin API へのヘルスチェックを組み込んでいます。

3.1.1 各項目のポイント解説

  • hostNetwork – ノードの IP を直接バインドすることで、Sidecar と同等の低レイテンシを実現。
  • securityContextrunAsUser/runAsGroup による権限分離と seccompProfile: RuntimeDefault で不要な syscall をブロック。
  • readiness / liveness – Envoy の admin API (/ready, /healthz) を利用した K8s 標準のヘルスチェック。
  • TLS シークレットcerts ボリュームは Secret からマウントし、Bootstrap が自動的に参照できるように配置。

3.2 RollingUpdate と無停止アップグレード

DaemonSet の maxUnavailable: 1 により、同時に落ちているノードは最大で 1 台 です。
Envoy が /ready を true にするまで次の Pod は起動せず、段階的なロールアウトが保証されます。


4. カスタム Control Plane の実装例

以下では Go と Python で最小構成の xDS サーバーを作ります。
コードはそのまま go run / python -m uvicorn 等でコンパイル・実行でき、TLS/エラーハンドリングも含めています。

4.1 Go 言語での最小 xDS Server(完全ビルド可能版)

このサンプルは go-control-plane v0.11+google.golang.org/protobuf 系を利用します。
必要な依存パッケージは go.mod に明示し、anypb.New を使って正しい any.Any 型の Listener を埋め込んでいます。

4.1.1 go.mod

4.1.2 main.go

ポイント解説

項目 内容
SnapshotCache バージョン管理と差分配信の核。true は ADS (Aggregated Discovery Service) を使用する設定。
Listener の any.Any anypb.New で正しい型情報を保持しないと Envoy がデコードできません。
TLS / mTLS credentials.NewServerTLSFromFile に証明書と鍵を渡すだけでサーバー側 TLS が有効になる。クライアント認証は NewTLS のオプションで追加可能です。
エラーハンドリング すべてのステップで log.Fatalf を使用し、起動失敗時に即座に可視化します。

このサンプルをコンテナ化する場合は、/etc/certs/* を Kubernetes Secret としてマウントしてください。

4.2 Python (grpcio) による安全な xDS Server

Python 実装でも TLS / mTLS と例外処理を組み込み、実運用に耐えうる形にします。
protobuf の生成ファイルは公式リポジトリから取得し、any_pb2.Any に Listener をシリアライズして返す点が重要です。

4.2.1 必要パッケージ

envoy-control-plane は公式の proto 定義を提供します(バージョンは Envoy 1.30 に合わせてください)。

4.2.2 server.py

ポイント解説

項目 内容
any_pb2.Any().Pack 型情報 (type_url) が自動付与され、Envoy が正しくデシリアライズできる。
TLS 設定 grpc.ssl_server_credentials に証明書・鍵を渡すだけでサーバー側 TLS が有効になる。クライアント認証が必要な場合は root_certificatesrequire_client_auth=True を設定。
エラーハンドリング 例外捕捉後に context.set_code/grpc.StatusCode.INTERNAL を返し、gRPC クライアント側でエラーを検知できるようにする。

本サンプルは Dockerfile に組み込んでコンテナ化すれば、K8s の Secret から証明書をマウントして運用できます。

4.3 公式 envoycontrolplane リポジトリとの比較

項目 最小実装 (Go) 最小実装 (Python) envoycontrolplane(公式)
言語 Go Python Go
完全 xDS タイプ対応 手動で追加可能 手動で追加可能 LDS/RDS/CDS/EDS/SDS 全網羅
TLS / mTLS 実装例 標準 grpc.Creds で完結 ssl_server_credentials で実装 同様にサポート(高度なローテーション機構あり)
テストフレームワーク go test pytest ginkgo + go test
プラグイン拡張性 高(Go のインタフェース) 中(grpc interceptors) 非常に高(サンプルが豊富)
デバッグ支援 ロガーのみ 標準ロギング admin API、statsd、OpenTelemetry 連携

結論:プロトタイプや PoC であれば上記最小実装で十分です。大規模本番環境では公式リポジトリをベースに拡張することを推奨します。


5. 動的設定・セキュリティ・運用ベストプラクティス

5.1 TLS / mTLS による xDS 通信の完全手順

  1. 証明書と鍵を Kubernetes Secret として作成
    bash
    kubectl create secret tls envoy-xds-tls \
    --cert=ca.crt --key=ca.key -n networking
  2. Bootstrap の transport_socket にシークレットパスを参照させる(先述の例と同一)
  3. Control Plane 側で mTLS を有効化(Go と Python それぞれコード例あり)

ベストプラクティス:証明書は自動ローテーションツール(cert-manager 等)で管理し、Secret の更新だけで Envoy が即座に新証明書へ切り替わります。

5.2 ConfigMap → xDS Server → Envoy のリアルタイム更新フロー

フェーズ 説明
1️⃣ ConfigMap 更新 管理者が kubectl apply -f listener-config.yaml 等でリソース定義を変更
2️⃣ Control Plane が Informer で検知 client-go の SharedInformer が ConfigMap 変化を捕捉し、内部データ構造に反映
3️⃣ SnapshotCache に新スナップショット設定 バージョン番号 ("2" など) をインクリメントし、SetSnapshot(nodeID, snapshot) 呼び出し
4️⃣ Envoy が DeltaDiscoveryResponse を受信 gRPC ストリーム上で差分だけが配信され、数秒以内に設定が反映

この流れは 「再起動不要・即時反映」 という xDS の根幹的利点です。

5.3 トラブルシューティングと可観測性

手段 実施方法 主な活用シーン
admin API curl http://localhost:9901/servers/stats?format=json 現在のリスナー一覧・統計情報取得
動的ログレベル変更 POST /logging?level=debug(admin) 問題発生時に瞬時に詳細ログ取得
pprof プロファイリング 起動フラグ --enable-pprof + /debug/pprof/* エンドポイント CPU・メモリボトルネックの特定
gRPC ステータス確認 grpcurl -insecure localhost:18000 envoy.service.discovery.v3.AggregatedDiscoveryService.StreamAggregatedResources Control Plane との通信エラーコード取得

admin API はデフォルトでポート 9901 に公開されますが、外部からの直接アクセスは NetworkPolicy で制限し、内部 Pod のみから利用するようにしてください。

5.4 リソース分離・ロールバック戦略

  • Namespace / Label 分離
  • networking Namespace に Envoy DaemonSet と Control Plane を配置し、アプリケーションとは別管理。
  • 標準化されたヘルスチェック(Bootstrap の例と同一)

  • ロールバック手順
  • 新しい ConfigMap を kubectl apply -f → Control Plane が新スナップショット作成。
  • 問題が顕在化したら、以前の ConfigMap バージョンへ kubectl rollout undo daemonset/envoy-proxy
  • 同時に Control Plane のキャッシュを旧バージョンに戻す(SetSnapshot(..., oldSnapshot))。

ポイント:ConfigMap と SnapshotCache を 1 対 1 に対応させることで、K8s の kubectl rollout undo が自動的に xDS 側のロールバックもトリガーします。


6. まとめ

項目 要点
xDS API 全体像 LDS・RDS・CDS・EDS・SDS は独立した Discovery Service として機能し、差分配信で高速構成変更が可能。
Envoy 1.30 のインストール apt/apk ではバージョン固定 (=1.30.x) が必須。Docker イメージはタグ v1.30.0 を使用し、HTTP/3 はデフォルト無効であることに注意。
Bootstrap 設定 gRPC と REST はリソースタイプごとに分離して記述。TLS は必ず transport_socket で明示し、必要なら環境変数で HTTP/3 を有効化。
Kubernetes DaemonSet hostNetwork・SecurityContext・admin API ヘルスチェックを組み込み、RollingUpdate による無停止アップグレードを実現。
カスタム Control Plane Go と Python の最小サンプルは完全コンパイル可能で TLS / mTLS とエラーハンドリングを備える。公式 envoycontrolplane は拡張性が高く本番向き。
運用ベストプラクティス 証明書は Secret 経由で管理し、ConfigMap → Control Plane → Envoy のリアルタイム更新フローを活かす。admin API・pprof で可観測性を確保し、Namespace/Label によるリソース分離とロールバック手順で安全性を高める。

上記の手順とベストプラクティスに従えば、2026 年版 Envoy 1.30 系 を Kubernetes 環境で 安全・可観測・高速に デプロイでき、xDS による動的構成管理を最大限活用できます。

スポンサードリンク

もっとスキルを活かしたいエンジニアへ

スポンサードリンク
働き方から選べる

無料で使えて良質な案件の情報収集ができるサービス

エンジニアの世界では、「いつでも動ける状態を作っておけ」とよく言われます。
技術やポートフォリオがあっても、自分に合う案件情報を日常的に見れていないと、いざ動こうと思った時に比較や判断が難しくなってしまいます。
普段から案件情報が集まる環境を作っておくと、良い案件が出た時にすぐ動きやすくなりますよ。
筆者自身も、メガベンチャー勤務時代に年収1,500万円を超えた経験があります。振り返ると、技術だけでなく「どんな案件や働き方があるか」を日頃から見ていたことが、キャリアの選択肢を広げるきっかけになりました。
このブログを読んでくれた方に感謝を込めて、実際に使っている情報収集サービスを紹介します。

フルリモート・週3日・高単価、どんな条件も妥協したくないなら

フリーランスボードに無料会員登録する

利用者10万人以上。業界最大規模45万件の案件。AIマッチ機能や無料の相場情報が人気。

年収800万円以上のキャリアアップ・ハイクラス正社員を視野に入れているなら

Beyond Careerに無料相談する

内定獲得率90%以上。紹介先企業とは役員クラスのコネクションがある安心と信頼できるエージェント。


-Envoy