LoginSignup
1
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

More than 5 years have passed since last update.

@kentakozuka(Kenta Kozuka)

Envoy: Configuration reference - overview

Posted at

tldr

勉強がてらにEnvoyのドキュメントを邦訳してみました。ベースはGoogle Translateで、ところどころ不自然な箇所を直しています。

原文としたのEnvoyのドキュメントはこちらのディレクトリ以下にあります（ライセンス：Apache License 2.0, NOTICE）。

概要

Envoy v2 API は、データプレーン API リポジトリで proto3 プロトコルバッファとして定義されています。それらは以下をサポートしています。

  • gRPC による xDS API アップデートのストリーミング配信。これにより、リソース要件が軽減され、更新の待ち時間を短縮できます。
  • JSON/YAML フォーマットが proto3 標準 JSON マッピングを介して機械的に派生した新しい REST-JSON API。
  • ファイルシステム、REST-JSON または gRPC エンドポイントを介したアップデートの配信。
  • 拡張エンドポイント割り当て API と管理サーバーへの負荷およびリソース使用率レポートによる高度な負荷分散。
  • 必要に応じて、一貫性と順序付けの特性を強化します。 v2 API はまだベースラインの結果整合性モデルを維持しています。

Envoy と管理サーバー間の v2 メッセージ交換の詳細については、xDS プロトコルの説明を参照してください。

ブートストラップ設定

v2 APIを使用するには、ブートストラップ設定ファイルを用意する必要があります。これにより、静的サーバー設定が提供され、必要に応じて動的設定にアクセスするように Envoy が設定されます。これは、-c フラグを介してコマンドラインで提供されます。

./envoy -c <path to config>.{json,yaml,pb,pb_text}

拡張子が基になるv2設定表現を反映するところ。

ブートストラップメッセージは設定のルートです。ブートストラップメッセージの重要な概念は、静的リソースと動的リソースの違いです。 Listener や Cluster などのリソースは、static_resources で静的に提供されるか、dynamic_resources で LDS や CDS などの xDS サービスが構成されます。

例

以下では、設定プロトコルの YAML 表現と、127.0.0.1:10000 から 127.0.0.2:1234 までの HTTP プロキシサービスの実行例を使用します。

静的

最低限の完全に静的なブートストラップ設定を以下に示します。

admin:
  access_log_path: /tmp/admin_access.log
  address:
    socket_address: { address: 127.0.0.1, port_value: 9901 }

static_resources:
  listeners:
  - name: listener_0
    address:
      socket_address: { address: 127.0.0.1, port_value: 10000 }
    filter_chains:
    - filters:
      - name: envoy.http_connection_manager
        typed_config:
          "@type": type.googleapis.com/envoy.config.filter.network.http_connection_manager.v2.HttpConnectionManager
          stat_prefix: ingress_http
          codec_type: AUTO
          route_config:
            name: local_route
            virtual_hosts:
            - name: local_service
              domains: ["*"]
              routes:
              - match: { prefix: "/" }
                route: { cluster: some_service }
          http_filters:
          - name: envoy.router
  clusters:
  - name: some_service
    connect_timeout: 0.25s
    type: STATIC
    lb_policy: ROUND_ROBIN
    load_assignment:
      cluster_name: some_service
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: 127.0.0.1
                port_value: 1234

動的 EDS で主に静的

上記の例から続く,127.0.0.1:5678 で待機している EDS gRPC 管理サーバーを介した動的エンドポイント検出を使用したブートストラップ構成を以下に示します。

admin:
  access_log_path: /tmp/admin_access.log
  address:
    socket_address: { address: 127.0.0.1, port_value: 9901 }

static_resources:
  listeners:
  - name: listener_0
    address:
      socket_address: { address: 127.0.0.1, port_value: 10000 }
    filter_chains:
    - filters:
      - name: envoy.http_connection_manager
        typed_config:
          "@type": type.googleapis.com/envoy.config.filter.network.http_connection_manager.v2.HttpConnectionManager
          stat_prefix: ingress_http
          codec_type: AUTO
          route_config:
            name: local_route
            virtual_hosts:
            - name: local_service
              domains: ["*"]
              routes:
              - match: { prefix: "/" }
                route: { cluster: some_service }
          http_filters:
          - name: envoy.router
  clusters:
  - name: some_service
    connect_timeout: 0.25s
    lb_policy: ROUND_ROBIN
    type: EDS
    eds_cluster_config:
      eds_config:
        api_config_source:
          api_type: GRPC
          grpc_services:
            envoy_grpc:
              cluster_name: xds_cluster
  - name: xds_cluster
    connect_timeout: 0.25s
    type: STATIC
    lb_policy: ROUND_ROBIN
    http2_protocol_options: {}
    upstream_connection_options:
      # configure a TCP keep-alive to detect and reconnect to the admin
      # server in the event of a TCP socket half open connection
      tcp_keepalive: {}
    load_assignment:
      cluster_name: xds_cluster
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: 127.0.0.1
                port_value: 5678

xds_cluster が Envoy を管理サーバーに向けるように定義されていることに注意してください。それ以外の点では完全に動的な構成であっても、Envoy がその xDS 管理サーバーを指すように静的リソースを定義する必要があります。

tcp_keepalive ブロックで適切な TCP Keep-Alive オプションを設定することが重要です。これは、xDS 管理サーバーへの TCP ハーフオープン接続を検出し、完全接続を再確立するのに役立ちます。

上記の例では、EDS 管理サーバーは DiscoveryResponse のプロトエンコーディングを返すことができます。

version_info: "0"
resources:
- "@type": type.googleapis.com/envoy.api.v2.ClusterLoadAssignment
  cluster_name: some_service
  endpoints:
  - lb_endpoints:
    - endpoint:
        address:
          socket_address:
            address: 127.0.0.2
            port_value: 1234

上記のバージョン管理およびタイプ URL スキームについては、ストリーミング gRPC サブスクリプションプロトコルのドキュメントで詳しく説明しています。

動的

管理サーバーに属するもの以外のすべてのリソースが xDS を介して検出される、完全に動的なブートストラップ構成を以下に示します。

admin:
  access_log_path: /tmp/admin_access.log
  address:
    socket_address: { address: 127.0.0.1, port_value: 9901 }

dynamic_resources:
  lds_config:
    api_config_source:
      api_type: GRPC
      grpc_services:
        envoy_grpc:
          cluster_name: xds_cluster
  cds_config:
    api_config_source:
      api_type: GRPC
      grpc_services:
        envoy_grpc:
          cluster_name: xds_cluster

static_resources:
  clusters:
  - name: xds_cluster
    connect_timeout: 0.25s
    type: STATIC
    lb_policy: ROUND_ROBIN
    http2_protocol_options: {}
    upstream_connection_options:
      # configure a TCP keep-alive to detect and reconnect to the admin
      # server in the event of a TCP socket half open connection
      tcp_keepalive: {}
    load_assignment:
      cluster_name: xds_cluster
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: 127.0.0.1
                port_value: 5678

管理サーバーは LDS 要求に次のように応答します。

version_info: "0"
resources:
- "@type": type.googleapis.com/envoy.api.v2.Listener
  name: listener_0
  address:
    socket_address:
      address: 127.0.0.1
      port_value: 10000
  filter_chains:
  - filters:
    - name: envoy.http_connection_manager
      typed_config:
        "@type": type.googleapis.com/envoy.config.filter.network.http_connection_manager.v2.HttpConnectionManager
        stat_prefix: ingress_http
        codec_type: AUTO
        rds:
          route_config_name: local_route
          config_source:
            api_config_source:
              api_type: GRPC
              grpc_services:
                envoy_grpc:
                  cluster_name: xds_cluster
        http_filters:
        - name: envoy.router

管理サーバーは RDS 要求に次のように応答します。

version_info: "0"
resources:
- "@type": type.googleapis.com/envoy.api.v2.RouteConfiguration
  name: local_route
  virtual_hosts:
  - name: local_service
    domains: ["*"]
    routes:
    - match: { prefix: "/" }
      route: { cluster: some_service }

管理サーバーは CDS 要求に次のように応答します。

version_info: "0"
resources:
- "@type": type.googleapis.com/envoy.api.v2.Cluster
  name: some_service
  connect_timeout: 0.25s
  lb_policy: ROUND_ROBIN
  type: EDS
  eds_cluster_config:
    eds_config:
      api_config_source:
        api_type: GRPC
        grpc_services:
          envoy_grpc:
            cluster_name: xds_cluster

管理サーバーは EDS 要求に次のように応答します。

version_info: "0"
resources:
- "@type": type.googleapis.com/envoy.api.v2.ClusterLoadAssignment
  cluster_name: some_service
  endpoints:
  - lb_endpoints:
    - endpoint:
        address:
          socket_address:
            address: 127.0.0.2
            port_value: 1234

管理サーバー

v2 xDS 管理サーバーは、gRPC および/または REST サービングに必要な以下のエンドポイントを実装します。ストリーミング gRPC と REST-JSON のどちらの場合でも、 xDS プロトコルに従って DiscoveryRequest が送信され、DiscoveryResponse が受信されます。

gRPC ストリーミングエンドポイント

POST /envoy.api.v2.ClusterDiscoveryService/StreamClusters

サービス定義については、cds.proto を参照してください。これは Envoy によってクライアントとして使用されます。

cds_config：
  api_config_source：
    api_type：GRPC
    grpc_services：
      envoy_grpc：
        cluster_name：some_xds_cluster

Bootstrap 設定の dynamic_resources に設定されています。

POST /envoy.api.v2.EndpointDiscoveryService/StreamEndpoints

サービス定義については eds.proto を参照してください。これは Envoy によってクライアントとして使用されます。

eds_config：
  api_config_source：
    api_type：GRPC
    grpc_services：
      envoy_grpc：
        cluster_name：some_xds_cluster

クラスタ設定の eds_cluster_config フィールドに設定されます。

POST /envoy.api.v2.ListenerDiscoveryService/StreamListeners

サービス定義については、lds.proto を参照してください。これは Envoy によってクライアントとして使用されます。

lds_config：
  api_config_source：
    api_type：GRPC
    grpc_services：
      envoy_grpc：
        cluster_name：some_xds_cluster

Bootstrap 設定の dynamic_resources に設定されています。

POST /envoy.api.v2.RouteDiscoveryService/StreamRoutes

サービス定義については、rds.proto を参照してください。これは Envoy によってクライアントとして使用されます。

route_config_name：some_route_name
config_source：
  api_config_source：
    api_type：GRPC
    grpc_services：
      envoy_grpc：
        cluster_name：some_xds_cluster

HttpConnectionManager 構成の rds フィールドに設定されます。

REST エンドポイント

POST/v2/discovery：クラスタ

サービス定義については、cds.proto を参照してください。これは Envoy によってクライアントとして使用されます。

cds_config：
  api_config_source：
    api_type：REST
    cluster_names：[some_xds_cluster]

Bootstrap 設定の dynamic_resources に設定されています。

POST/v2/discovery：エンドポイント

サービス定義については eds.proto を参照してください。これは Envoy によってクライアントとして使用されます。

eds_config：
  api_config_source：
    api_type：REST
    cluster_names：[some_xds_cluster]

クラスタ設定の eds_cluster_config フィールドに設定されます。

POST/v2/discovery：リスナー

サービス定義については、lds.proto を参照してください。これは Envoy によってクライアントとして使用されます。

lds_config：
  api_config_source：
    api_type：REST
    cluster_names：[some_xds_cluster]

Bootstrap 設定の dynamic_resources に設定されています。

POST/v2/discovery：ルート

サービス定義については、rds.proto を参照してください。これは Envoy によってクライアントとして使用されます。

route_config_name：some_route_name
config_source：
  api_config_source：
    api_type：REST
    cluster_names：[some_xds_cluster]

HttpConnectionManager 構成の rds フィールドに設定されます。

集約ディスカバリーサービス

Envoy は基本的に最終的な整合性モデルを採用していますが、ADS は API 更新プッシュを順序付けし、単一の管理サーバーと Envoy ノードの API 更新の親和性を保証する機会を提供します。 ADS では、1つ以上の API とそのリソースを、管理サーバーによって単一の双方向 gRPC ストリームで配信できます。これがないと、RDS や EDS などの一部の API では、複数のストリームの管理と個別の管理サーバーへの接続が必要になる場合があります。

ADS は適切な順序付けによって構成のヒットレス更新を可能にします。たとえば、foo.comがクラスタXにマッピングされたとします。ルートテーブル内のマッピングをクラスタYのfoo.comを指すように変更します。これを行うには、最初に両方のクラスタを含むCDS / EDSアップデートを配信する必要があります。 XとY

ADSがないと、CDS / EDS / RDSストリームは別々の管理サーバーを指すことも、同じ管理サーバー上にある場合は調整が必要な別々のgRPCストリーム/接続を指すこともあります。 EDSリソース要求は、X用とY用の2つの異なるストリームに分割できます。ADSを使用すると、これらを単一の管理サーバーへの単一のストリームに合体させることができます。 ADSでは、管理サーバーはCDS、EDS、そしてRDSの更新を単一のストリームで配信します。

ADSは（RESTではなく）gRPCストリーミングでのみ使用可能であり、このドキュメントでより詳しく説明されています。 gRPCエンドポイントは以下のとおりです。

POST /envoy.service.discovery.v2.AggregatedDiscoveryService/StreamAggregatedResources

サービス定義についてはdiscovery.protoを参照してください。これはEnvoyによってクライアントとして使用されます。

ads_config：
  api_type：GRPC
  grpc_services：
    envoy_grpc：
      cluster_name：some_ads_cluster

Bootstrap設定のdynamic_resourcesに設定されています。

これが設定されている場合、上記の設定ソースのいずれもADSチャネルを使用するように設定できます。たとえば、LDS設定は次のように変更できます。

lds_config：
  api_config_source：
    api_type：REST
    cluster_names：[some_xds_cluster]

に

lds_config：{ads：{}}

LDSストリームは共有ADSチャネルを介してsome_ads_clusterに送信されます。

管理サーバーにアクセスできない

Envoyインスタンスが管理サーバーとの接続を失うと、Envoyはバックグラウンドでアクティブに再試行しながら管理サーバーとの接続を再確立しながら、前の設定にラッチします。

Envoy debugは、接続を試みるたびに管理サーバーとの接続を確立できないという事実をログに記録します。

connected_state統計は、この動作を監視するためのシグナルを提供します。

統計

管理サーバーには、control_planeをルートとする統計ツリーがあります。次のような統計があります。

名前 タイプ 説明
connected_state Gauge 管理サーバーとの現在の接続状態を示すブール値（1は接続済み、0は切断済み）
rate_limit_enforced Counter 管理サーバー要求に対してレート制限が実施された合計回数
pending_requests Gauge レート制限が適用されたときの保留中の要求の総数

状態

特に記載がない限り、v2 APIリファレンスに記載されているすべての機能が実装されています。 v2 APIリファレンスおよびv2 APIレポジトリでは、すべてのプロトはドラフトまたは実験用としてタグ付けされていない限り凍結されています。ここで凍結とは、ワイヤフォーマットの互換性を壊さないことを意味します。

凍結プロトはさらに拡張することができる。後方互換性を損なわない方法で、新しいフィールドを追加することによって。上記のプロトタイプのフィールドは、関連する機能が不要になったときに、重大な変更ポリシーの影響を受けて、後で非推奨になる可能性があります。凍結されたAPIはワイヤフォーマットの互換性が維持されていますが、プロトネームスペース、ファイルの場所、およびネスト関係を変更する権利を留保します。私たちはここで解約を最小限に抑えることを目指します。

Protosタグ付きドラフトは、ほぼ完成していることを意味し、Envoyでは少なくとも部分的に実装されている可能性がありますが、フリーズ前にワイヤフォーマットの変更が行われる可能性があります。

protosは実験的なタグ付きで、ドラフトのprotosと同じ警告があり、Envoyの実装と凍結の前に大きな変更が加えられているかもしれません。

現在開いているv2 APIの問題はここで追跡されます。

1
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
1
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?