From 21028bb1f522177efabcb7ae902a879ba1102b90 Mon Sep 17 00:00:00 2001 From: Easwar Swaminathan Date: Tue, 25 Jun 2024 13:55:43 -0700 Subject: [PATCH] doc: add a document to specify the xDS bootstrap file format (#36926) Closes #36926 COPYBARA_INTEGRATE_REVIEW=https://github.com/grpc/grpc/pull/36926 from easwars:xds_bootstrap_format 73ce55eab32c914bbd54bf56152dc66696f300a7 PiperOrigin-RevId: 646595984 --- doc/grpc_xds_bootstrap_format.md | 265 +++++++++++++++++++++++++++ tools/doxygen/Doxyfile.c++ | 1 + tools/doxygen/Doxyfile.c++.internal | 1 + tools/doxygen/Doxyfile.core | 1 + tools/doxygen/Doxyfile.core.internal | 1 + tools/doxygen/Doxyfile.objc | 1 + tools/doxygen/Doxyfile.objc.internal | 1 + tools/doxygen/Doxyfile.php | 1 + 8 files changed, 272 insertions(+) create mode 100644 doc/grpc_xds_bootstrap_format.md diff --git a/doc/grpc_xds_bootstrap_format.md b/doc/grpc_xds_bootstrap_format.md new file mode 100644 index 00000000000..7b46761f296 --- /dev/null +++ b/doc/grpc_xds_bootstrap_format.md @@ -0,0 +1,265 @@ +# xDS Bootstrap File Format in gRPC + +This document specifies the xDS bootstrap file format supported by gRPC. + +## Background + +gRPC expects the xDS bootstrap configuration to be specified as a JSON string. +The xDS bootstrap file location may be specified using the environment variable +`GRPC_XDS_BOOTSTRAP`. Alternatively, the bootstrap file contents may be +specified using the environment variable `GRPC_XDS_BOOTSTRAP_CONFIG`. If both +are specified, the former takes precendence. + +The xDS client inside of gRPC parses the bootstrap configuration specified by +one of the above means when it is created to configure itself. + +The following sections describe the bootstrap file format, including links to +gRFCs where support for appropriate fields was added. + +## File Format + +``` +{ + // The xDS server to talk to. The value is an ordered array of server + // configurations, to support failing over to a secondary xDS server if the + // primary is down. + // + // Prior to gRFC A71, all but the first entry was ignored. + "xds_servers": [ + { + + // A target URI string suitable for creating a gRPC channel. + "server_uri": , + + // List of channel creds; client will stop at the first type it + // supports. This field is required and must contain at least one + // channel creds type that the client supports. + // + // See section titled "Supported Channel Credentials". + "channel_creds": [ + { + "type": , + + // The "config" field is optional; it may be missing if the + // credential type does not require config parameters. + "config": + } + ], + + // A list of features supported by the server. New values will + // be added over time. For forward compatibility reasons, the + // client will ignore any entry in the list that it does not + // understand, regardless of type. + // + // See section titled "Supported Server Features". + "server_features": [ ... ] + } + ], + + // Identifies a specific gRPC instance. + "node": { + + // Opaque identifier for the gRPC instance. + "id": , + + // Identifier for the local service cluster where the gRPC instance is + // running. + "cluster": , + + // Specifies where the gRPC instance is running. + "locality": { + "region": , + "zone": , + "sub_zone": , + }, + + // Opaque metadata extending the node identifier. + "metadata": , + } + + // Map of supported certificate providers, keyed by the provider instance + // name. + // See section titled "Supported certificate providers". + "certificate_providers": { + + // Certificate provider instance name, specified by the + // control plane, to fetch certificates from. + "": { + + // Name of the plugin implementation. + "plugin_name": , + + // A JSON object containing the configuration for the plugin, whose schema + // is defined by the plugin. The "config" field is optional; it may be + // missing if the credential type does not require config parameters. + "config": + } + } + + // A template for the name of the Listener resource to subscribe to for a gRPC + // server. If the token `%s` is present in the string, all instances of the + // token will be replaced with the server's listening "IP:port" (e.g., + // "0.0.0.0:8080", "[::]:8080"). + "server_listener_resource_name_template": "example/resource/%s", + + // A template for the name of the Listener resource to subscribe to for a gRPC + // client channel. Used only when the channel is created with an "xds:" URI + // with no authority. + // + // If starts with "xdstp:", will be interpreted as a new-style name, in which + // case the authority of the URI will be used to select the relevant + // configuration in the "authorities" map. + // + // The token "%s", if present in this string, will be replaced with the + // service authority (i.e., the path part of the target URI used to create the + // gRPC channel). If the template starts with "xdstp:", the replaced string + // will be percent-encoded. In that case, the replacement string must include + // only characters allowed in a URI path as per RFC-3986 section 3.3 (which + // includes '/'), and all other characters must be percent-encoded. + // + // Defaults to "%s". + "client_default_listener_resource_name_template": , + + // A map of authority name to corresponding configuration. + // + // This is used in the following cases: + // - A gRPC client channel is created using an "xds:" URI that includes + // an authority. + // - A gRPC client channel is created using an "xds:" URI with no + // authority, but the "client_default_listener_resource_name_template" + // field turns it into an "xdstp:" URI. + // - A gRPC server is created and the + // "server_listener_resource_name_template" field is an "xdstp:" URI. + // + // In any of those cases, it is an error if the specified authority is + // not present in this map. + "authorities": { + // Entries are keyed by authority name. + // Note: If a new-style resource name has no authority, we will use + // the empty string here as the key. + "": { + + // A template for the name of the Listener resource to subscribe + // to for a gRPC client channel. Used only when the channel is + // created using an "xds:" URI with this authority name. + // + // The token "%s", if present in this string, will be replaced + // with percent-encoded service authority (i.e., the path part of the + // target URI used to create the gRPC channel). The replacement string + // must include only characters allowed in a URI path as per RFC-3986 + // section 3.3 (which includes '/'), and all other characters must be + // percent-encoded. + // + // Must start with "xdstp:///". If it does not, + // that is considered a bootstrap file parsing error. + // + // If not present in the bootstrap file, defaults to + // "xdstp:///envoy.config.listener.v3.Listener/%s". + "client_listener_resource_name_template": , + + // Ordered list of xDS servers to contact for this authority. + // Format is exactly the same as the top level "xds_servers" field. + // + // If the same server is listed in multiple authorities, the + // entries will be de-duped (i.e., resources for both authorities + // will be fetched on the same ADS stream). + // + // If not specified, the top-level server list is used. + "xds_servers": [ ... ] + } + } +} +``` + +### Supported Channel Credentials + +gRPC supports the following channel credentials as part of the `channel_creds` +field of `xds_servers`. + +#### Insecure credentials + +- **Type Name**: `insecure` +- **Config**: Accepts no configuration + +#### Google Default credentials + +- **Type Name**: `google_default` +- **Config**: Accepts no configuration + +#### mTLS credentials + +- **Type Name**: `tls` +- **Config**: As described in [gRFC A65](a65): +``` +{ + // Path to CA certificate file. + // If unset, system-wide root certs are used. + "ca_certificate_file": , + + // Paths to identity certificate file and private key file. + // If either of these fields are set, both must be set. + // If set, mTLS will be used; if unset, normal TLS will be used. + "certificate_file": , + "private_key_file": , + + // How often to re-read the certificate files. + // Value is the JSON format described for a google.protobuf.Duration + // message in https://protobuf.dev/programming-guides/proto3/#json. + // If unset, defaults to "600s". + "refresh_interval": +} +``` + +### Supported Certificate Provider Instances + +gRPC supports the following Certificate Provider instances as part of the +`certificate_providers` field: + +#### PEM file watcher + +- **Plugin Name**: `file_watcher` +- **Config**: As described in [gRFC A29](a29): +``` +{ + "certificate_file": "", + "private_key_file": "", + "ca_certificate_file": "", + "refresh_interval": "" +} +``` + +### Supported Server Features + +gRPC supports the following server features in the `server_features` field +inside `xds_servers`: +- `xds_v3`: Added in gRFC A30. Supported in older versions of gRPC. See +[here](grpc_xds_features.md) for when gRPC added support for xDS transport +protocol v3, and when support for xDS transport protocol v2 was dropped. +- `ignore_resource_deletion`: Added in [gRFC A53](a53) + + +### When were fields added? + +| Bootstrap Field | Relevant gRFCs +------------------|--------------- +`xds_servers` | [A27](a27), [A71](a71) +`google_default` channel credentials | [A27](a27) +`insecure` channel credentials | [A27](a27) +`node` | [A27](a27) +`certificate_providers` | [A29](a29) +`file_watcher`certificate provider | [A29](a29) +`xds_servers.server_features` | [A30](a30) +`server_listener_resource_name_template` | [A36](a36), [A47](a47) +`client_default_listener_resource_name_template` | [A47](a47) +`authorities` | [A47](a47) +`tls` channel credentials | [A65](a65) + + +[a27]: https://github.com/grpc/proposal/blob/master/A27-xds-global-load-balancing.md +[a29]: https://github.com/grpc/proposal/blob/master/A29-xds-tls-security.md#file_watcher-certificate-provider +[a30]: https://github.com/grpc/proposal/blob/master/A30-xds-v3.md +[a36]: https://github.com/grpc/proposal/blob/master/A36-xds-for-servers.md +[a47]: https://github.com/grpc/proposal/blob/master/A47-xds-federation.md +[a53]: https://github.com/grpc/proposal/blob/master/A53-xds-ignore-resource-deletion.md +[a65]: https://github.com/grpc/proposal/blob/master/A65-xds-mtls-creds-in-bootstrap.md#proposal +[a71]: https://github.com/grpc/proposal/blob/master/A71-xds-fallback.md \ No newline at end of file diff --git a/tools/doxygen/Doxyfile.c++ b/tools/doxygen/Doxyfile.c++ index 91c0954574a..1ef3371ccf5 100644 --- a/tools/doxygen/Doxyfile.c++ +++ b/tools/doxygen/Doxyfile.c++ @@ -779,6 +779,7 @@ doc/fail_fast.md \ doc/fork_support.md \ doc/g_stands_for.md \ doc/grpc_release_schedule.md \ +doc/grpc_xds_bootstrap_format.md \ doc/grpc_xds_features.md \ doc/health-checking.md \ doc/http-grpc-status-mapping.md \ diff --git a/tools/doxygen/Doxyfile.c++.internal b/tools/doxygen/Doxyfile.c++.internal index ab12d2dc09e..a3b4c83cbec 100644 --- a/tools/doxygen/Doxyfile.c++.internal +++ b/tools/doxygen/Doxyfile.c++.internal @@ -779,6 +779,7 @@ doc/fail_fast.md \ doc/fork_support.md \ doc/g_stands_for.md \ doc/grpc_release_schedule.md \ +doc/grpc_xds_bootstrap_format.md \ doc/grpc_xds_features.md \ doc/health-checking.md \ doc/http-grpc-status-mapping.md \ diff --git a/tools/doxygen/Doxyfile.core b/tools/doxygen/Doxyfile.core index b22e4e30761..2453f576cb9 100644 --- a/tools/doxygen/Doxyfile.core +++ b/tools/doxygen/Doxyfile.core @@ -786,6 +786,7 @@ doc/fail_fast.md \ doc/fork_support.md \ doc/g_stands_for.md \ doc/grpc_release_schedule.md \ +doc/grpc_xds_bootstrap_format.md \ doc/grpc_xds_features.md \ doc/health-checking.md \ doc/http-grpc-status-mapping.md \ diff --git a/tools/doxygen/Doxyfile.core.internal b/tools/doxygen/Doxyfile.core.internal index e08c9737443..1e05cb5fce8 100644 --- a/tools/doxygen/Doxyfile.core.internal +++ b/tools/doxygen/Doxyfile.core.internal @@ -786,6 +786,7 @@ doc/fail_fast.md \ doc/fork_support.md \ doc/g_stands_for.md \ doc/grpc_release_schedule.md \ +doc/grpc_xds_bootstrap_format.md \ doc/grpc_xds_features.md \ doc/health-checking.md \ doc/http-grpc-status-mapping.md \ diff --git a/tools/doxygen/Doxyfile.objc b/tools/doxygen/Doxyfile.objc index 02b3f3b6fff..c62c68fb8d1 100644 --- a/tools/doxygen/Doxyfile.objc +++ b/tools/doxygen/Doxyfile.objc @@ -777,6 +777,7 @@ doc/fail_fast.md \ doc/fork_support.md \ doc/g_stands_for.md \ doc/grpc_release_schedule.md \ +doc/grpc_xds_bootstrap_format.md \ doc/grpc_xds_features.md \ doc/health-checking.md \ doc/http-grpc-status-mapping.md \ diff --git a/tools/doxygen/Doxyfile.objc.internal b/tools/doxygen/Doxyfile.objc.internal index 5b38b0690f4..a73b22399e3 100644 --- a/tools/doxygen/Doxyfile.objc.internal +++ b/tools/doxygen/Doxyfile.objc.internal @@ -777,6 +777,7 @@ doc/fail_fast.md \ doc/fork_support.md \ doc/g_stands_for.md \ doc/grpc_release_schedule.md \ +doc/grpc_xds_bootstrap_format.md \ doc/grpc_xds_features.md \ doc/health-checking.md \ doc/http-grpc-status-mapping.md \ diff --git a/tools/doxygen/Doxyfile.php b/tools/doxygen/Doxyfile.php index c71e3d6d640..4e8a641ca56 100644 --- a/tools/doxygen/Doxyfile.php +++ b/tools/doxygen/Doxyfile.php @@ -777,6 +777,7 @@ doc/fail_fast.md \ doc/fork_support.md \ doc/g_stands_for.md \ doc/grpc_release_schedule.md \ +doc/grpc_xds_bootstrap_format.md \ doc/grpc_xds_features.md \ doc/health-checking.md \ doc/http-grpc-status-mapping.md \