docs: final docs for 1.13.0 (#9745)

Including reorganizing the configuration overview page. Signed-off-by: Matt Klein <mklein@lyft.com>
envoyproxy · Jan 20, 2020 · bb7ceff · bb7ceff
1 parent ac88316
commit bb7ceff
Show file tree

Hide file tree

Showing 11 changed files with 798 additions and 788 deletions.
diff --git a/VERSION b/VERSION
@@ -1 +1 @@
-1.13.0-dev
+1.13.0
diff --git a/docs/root/api/api_supported_versions.rst b/docs/root/api/api_supported_versions.rst
@@ -6,10 +6,10 @@ Suported API versions
 Envoy's APIs follow a :repo:`versioning scheme <api/API_VERSIONING.md>` in which Envoy supports
 multiple major API versions at any point in time. The following versions are currently supported:
 
-* v2 xDS API (*deprecated*, end-of-life EOY 2020). This API will not accept new features after the
-  end of Q1 2020.
-* v3 xDS API (*active*, end-of-life EOY 2021). Envoy developers and operators are encouraged to be
-  actively adopting and working with v3 xDS.
+* :ref:`v2 xDS API <envoy_api_reference>` (*deprecated*, end-of-life EOY 2020). This API will not
+  accept new features after the end of Q1 2020.
+* :ref:`v3 xDS API <envoy_v3_api_reference>` (*active*, end-of-life EOY 2021). Envoy developers and
+  operators are encouraged to be actively adopting and working with v3 xDS.
 
 The following API versions are no longer supported by Envoy:
 

diff --git a/docs/root/configuration/overview/bootstrap.rst b/docs/root/configuration/overview/bootstrap.rst
@@ -0,0 +1,25 @@
+.. _config_overview_bootstrap:
+
+Bootstrap configuration
+-----------------------
+
+To use the xDS API, it's necessary to supply a bootstrap configuration file. This
+provides static server configuration and configures Envoy to access :ref:`dynamic
+configuration if needed <arch_overview_dynamic_config>`. This is supplied on the command-line via
+the :option:`-c` flag, i.e.:
+
+.. code-block:: console
+
+  ./envoy -c <path to config>.{json,yaml,pb,pb_text}
+
+where the extension reflects the underlying config representation.
+
+The :ref:`Bootstrap <envoy_api_msg_config.bootstrap.v2.Bootstrap>` message is the root of the
+configuration. A key concept in the :ref:`Bootstrap <envoy_api_msg_config.bootstrap.v2.Bootstrap>`
+message is the distinction between static and dynamic resources. Resources such
+as a :ref:`Listener <envoy_api_msg_Listener>` or :ref:`Cluster
+<envoy_api_msg_Cluster>` may be supplied either statically in
+:ref:`static_resources <envoy_api_field_config.bootstrap.v2.Bootstrap.static_resources>` or have
+an xDS service such as :ref:`LDS
+<config_listeners_lds>` or :ref:`CDS <config_cluster_manager_cds>` configured in
+:ref:`dynamic_resources <envoy_api_field_config.bootstrap.v2.Bootstrap.dynamic_resources>`.
diff --git a/docs/root/configuration/overview/examples.rst b/docs/root/configuration/overview/examples.rst
@@ -0,0 +1,282 @@
+Examples
+--------
+
+Below we will use YAML representation of the config protos and a running example
+of a service proxying HTTP from 127.0.0.1:10000 to 127.0.0.2:1234.
+
+Static
+^^^^^^
+
+A minimal fully static bootstrap config is provided below:
+
+.. code-block:: yaml
+
+  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
+
+Mostly static with dynamic EDS
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A bootstrap config that continues from the above example with :ref:`dynamic endpoint
+discovery <arch_overview_dynamic_config_eds>` via an
+:ref:`EDS<envoy_api_file_envoy/api/v2/eds.proto>` gRPC management server listening
+on 127.0.0.1:5678 is provided below:
+
+.. code-block:: yaml
+
+  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
+
+Notice above that *xds_cluster* is defined to point Envoy at the management server. Even in
+an otherwise completely dynamic configurations, some static resources need to
+be defined to point Envoy at its xDS management server(s).
+
+It's important to set appropriate :ref:`TCP Keep-Alive options <envoy_api_msg_core.TcpKeepalive>`
+in the `tcp_keepalive` block. This will help detect TCP half open connections to the xDS management
+server and re-establish a full connection.
+
+In the above example, the EDS management server could then return a proto encoding of a
+:ref:`DiscoveryResponse <envoy_api_msg_DiscoveryResponse>`:
+
+.. code-block:: yaml
+
+  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
+
+
+The versioning and type URL scheme that appear above are explained in more
+detail in the :ref:`streaming gRPC subscription protocol
+<xds_protocol_streaming_grpc_subscriptions>`
+documentation.
+
+Dynamic
+^^^^^^^
+
+A fully dynamic bootstrap configuration, in which all resources other than
+those belonging to the management server are discovered via xDS is provided
+below:
+
+.. code-block:: yaml
+
+  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
+
+The management server could respond to LDS requests with:
+
+.. code-block:: yaml
+
+  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
+
+The management server could respond to RDS requests with:
+
+.. code-block:: yaml
+
+  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 }
+
+The management server could respond to CDS requests with:
+
+.. code-block:: yaml
+
+  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
+
+The management server could respond to EDS requests with:
+
+.. code-block:: yaml
+
+  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
diff --git a/docs/root/configuration/overview/introduction.rst b/docs/root/configuration/overview/introduction.rst
@@ -0,0 +1,22 @@
+Introduction
+============
+
+The Envoy xDS APIs are defined as `proto3
+<https://developers.google.com/protocol-buffers/docs/proto3>`_ `Protocol Buffers
+<https://developers.google.com/protocol-buffers/>`_ in the :repo:`api tree <api/>`. They
+support:
+
+* Streaming delivery of :ref:`xDS <xds_protocol>` API updates via gRPC. This reduces
+  resource requirements and can lower the update latency.
+* A new REST-JSON API in which the JSON/YAML formats are derived mechanically via the `proto3
+  canonical JSON mapping
+  <https://developers.google.com/protocol-buffers/docs/proto3#json>`_.
+* Delivery of updates via the filesystem, REST-JSON or gRPC endpoints.
+* Advanced load balancing through an extended endpoint assignment API and load
+  and resource utilization reporting to management servers.
+* :ref:`Stronger consistency and ordering properties
+  <xds_protocol_eventual_consistency_considerations>`
+  when needed. The APIs still maintain a baseline eventual consistency model.
+
+See the :ref:`xDS protocol description <xds_protocol>` for
+further details on aspects of xDS message exchange between Envoy and the management server.