Warning

The v2 xDS API is not supported in Envoy v1.18.0 and above.

gRPC services

core.GrpcService

[core.GrpcService proto]

gRPC service configuration. This is used by ApiConfigSource and filter configurations.

{
  "envoy_grpc": "{...}",
  "google_grpc": "{...}",
  "timeout": "{...}",
  "initial_metadata": []
}
envoy_grpc

(core.GrpcService.EnvoyGrpc) Envoy’s in-built gRPC client. See the gRPC services overview documentation for discussion on gRPC client selection.

Precisely one of envoy_grpc, google_grpc must be set.

google_grpc

(core.GrpcService.GoogleGrpc) Google C++ gRPC client See the gRPC services overview documentation for discussion on gRPC client selection.

Precisely one of envoy_grpc, google_grpc must be set.

timeout

(Duration) The timeout for the gRPC request. This is the timeout for a specific request.

initial_metadata

(repeated core.HeaderValue) Additional metadata to include in streams initiated to the GrpcService. This can be used for scenarios in which additional ad hoc authorization headers (e.g. x-foo-bar: baz-key) are to be injected.

core.GrpcService.EnvoyGrpc

[core.GrpcService.EnvoyGrpc proto]

{
  "cluster_name": "..."
}
cluster_name

(string, REQUIRED) The name of the upstream gRPC cluster. SSL credentials will be supplied in the Cluster transport_socket.

core.GrpcService.GoogleGrpc

[core.GrpcService.GoogleGrpc proto]

{
  "target_uri": "...",
  "channel_credentials": "{...}",
  "call_credentials": [],
  "stat_prefix": "...",
  "credentials_factory_name": "...",
  "config": "{...}"
}
target_uri

(string, REQUIRED) The target URI when using the Google C++ gRPC client. SSL credentials will be supplied in channel_credentials.

channel_credentials

(core.GrpcService.GoogleGrpc.ChannelCredentials)

call_credentials

(repeated core.GrpcService.GoogleGrpc.CallCredentials) A set of call credentials that can be composed with channel credentials.

stat_prefix

(string, REQUIRED) The human readable prefix to use when emitting statistics for the gRPC service.

Name

Type

Description

streams_total

Counter

Total number of streams opened

streams_closed_<gRPC status code>

Counter

Total streams closed with <gRPC status code>

credentials_factory_name

(string) The name of the Google gRPC credentials factory to use. This must have been registered with Envoy. If this is empty, a default credentials factory will be used that sets up channel credentials based on other configuration parameters.

config

(Struct) Additional configuration for site-specific customizations of the Google gRPC library.

core.GrpcService.GoogleGrpc.SslCredentials

[core.GrpcService.GoogleGrpc.SslCredentials proto]

See https://grpc.io/grpc/cpp/structgrpc_1_1_ssl_credentials_options.html.

{
  "root_certs": "{...}",
  "private_key": "{...}",
  "cert_chain": "{...}"
}
root_certs

(core.DataSource) PEM encoded server root certificates.

private_key

(core.DataSource) PEM encoded client private key.

cert_chain

(core.DataSource) PEM encoded client certificate chain.

core.GrpcService.GoogleGrpc.GoogleLocalCredentials

[core.GrpcService.GoogleGrpc.GoogleLocalCredentials proto]

Local channel credentials. Only UDS is supported for now. See https://github.com/grpc/grpc/pull/15909.

core.GrpcService.GoogleGrpc.ChannelCredentials

[core.GrpcService.GoogleGrpc.ChannelCredentials proto]

See https://grpc.io/docs/guides/auth.html#credential-types to understand Channel and Call credential types.

{
  "ssl_credentials": "{...}",
  "google_default": "{...}",
  "local_credentials": "{...}"
}
ssl_credentials

(core.GrpcService.GoogleGrpc.SslCredentials)

Precisely one of ssl_credentials, google_default, local_credentials must be set.

google_default

(Empty) https://grpc.io/grpc/cpp/namespacegrpc.html#a6beb3ac70ff94bd2ebbd89b8f21d1f61

Precisely one of ssl_credentials, google_default, local_credentials must be set.

local_credentials

(core.GrpcService.GoogleGrpc.GoogleLocalCredentials)

Precisely one of ssl_credentials, google_default, local_credentials must be set.

core.GrpcService.GoogleGrpc.CallCredentials

[core.GrpcService.GoogleGrpc.CallCredentials proto]

{
  "access_token": "...",
  "google_compute_engine": "{...}",
  "google_refresh_token": "...",
  "service_account_jwt_access": "{...}",
  "google_iam": "{...}",
  "from_plugin": "{...}",
  "sts_service": "{...}"
}
access_token

(string) Access token credentials. https://grpc.io/grpc/cpp/namespacegrpc.html#ad3a80da696ffdaea943f0f858d7a360d.

Precisely one of access_token, google_compute_engine, google_refresh_token, service_account_jwt_access, google_iam, from_plugin, sts_service must be set.

google_compute_engine

(Empty) Google Compute Engine credentials. https://grpc.io/grpc/cpp/namespacegrpc.html#a6beb3ac70ff94bd2ebbd89b8f21d1f61

Precisely one of access_token, google_compute_engine, google_refresh_token, service_account_jwt_access, google_iam, from_plugin, sts_service must be set.

google_refresh_token

(string) Google refresh token credentials. https://grpc.io/grpc/cpp/namespacegrpc.html#a96901c997b91bc6513b08491e0dca37c.

Precisely one of access_token, google_compute_engine, google_refresh_token, service_account_jwt_access, google_iam, from_plugin, sts_service must be set.

service_account_jwt_access

(core.GrpcService.GoogleGrpc.CallCredentials.ServiceAccountJWTAccessCredentials) Service Account JWT Access credentials. https://grpc.io/grpc/cpp/namespacegrpc.html#a92a9f959d6102461f66ee973d8e9d3aa.

Precisely one of access_token, google_compute_engine, google_refresh_token, service_account_jwt_access, google_iam, from_plugin, sts_service must be set.

google_iam

(core.GrpcService.GoogleGrpc.CallCredentials.GoogleIAMCredentials) Google IAM credentials. https://grpc.io/grpc/cpp/namespacegrpc.html#a9fc1fc101b41e680d47028166e76f9d0.

Precisely one of access_token, google_compute_engine, google_refresh_token, service_account_jwt_access, google_iam, from_plugin, sts_service must be set.

from_plugin

(core.GrpcService.GoogleGrpc.CallCredentials.MetadataCredentialsFromPlugin) Custom authenticator credentials. https://grpc.io/grpc/cpp/namespacegrpc.html#a823c6a4b19ffc71fb33e90154ee2ad07. https://grpc.io/docs/guides/auth.html#extending-grpc-to-support-other-authentication-mechanisms.

Precisely one of access_token, google_compute_engine, google_refresh_token, service_account_jwt_access, google_iam, from_plugin, sts_service must be set.

sts_service

(core.GrpcService.GoogleGrpc.CallCredentials.StsService) Custom security token service which implements OAuth 2.0 token exchange. https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-16 See https://github.com/grpc/grpc/pull/19587.

Precisely one of access_token, google_compute_engine, google_refresh_token, service_account_jwt_access, google_iam, from_plugin, sts_service must be set.

core.GrpcService.GoogleGrpc.CallCredentials.ServiceAccountJWTAccessCredentials

[core.GrpcService.GoogleGrpc.CallCredentials.ServiceAccountJWTAccessCredentials proto]

{
  "json_key": "...",
  "token_lifetime_seconds": "..."
}
json_key

(string)

token_lifetime_seconds

(uint64)

core.GrpcService.GoogleGrpc.CallCredentials.GoogleIAMCredentials

[core.GrpcService.GoogleGrpc.CallCredentials.GoogleIAMCredentials proto]

{
  "authorization_token": "...",
  "authority_selector": "..."
}
authorization_token

(string)

authority_selector

(string)

core.GrpcService.GoogleGrpc.CallCredentials.MetadataCredentialsFromPlugin

[core.GrpcService.GoogleGrpc.CallCredentials.MetadataCredentialsFromPlugin proto]

{
  "name": "...",
  "config": "{...}",
  "typed_config": "{...}"
}
name

(string)

config

(Struct)

Only one of config, typed_config may be set.

typed_config

(Any)

Only one of config, typed_config may be set.

core.GrpcService.GoogleGrpc.CallCredentials.StsService

[core.GrpcService.GoogleGrpc.CallCredentials.StsService proto]

Security token service configuration that allows Google gRPC to fetch security token from an OAuth 2.0 authorization server. See https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-16 and https://github.com/grpc/grpc/pull/19587.

{
  "token_exchange_service_uri": "...",
  "resource": "...",
  "audience": "...",
  "scope": "...",
  "requested_token_type": "...",
  "subject_token_path": "...",
  "subject_token_type": "...",
  "actor_token_path": "...",
  "actor_token_type": "..."
}
token_exchange_service_uri

(string) URI of the token exchange service that handles token exchange requests.

resource

(string) Location of the target service or resource where the client intends to use the requested security token.

audience

(string) Logical name of the target service where the client intends to use the requested security token.

scope

(string) The desired scope of the requested security token in the context of the service or resource where the token will be used.

requested_token_type

(string) Type of the requested security token.

subject_token_path

(string, REQUIRED) The path of subject token, a security token that represents the identity of the party on behalf of whom the request is being made.

subject_token_type

(string, REQUIRED) Type of the subject token.

actor_token_path

(string) The path of actor token, a security token that represents the identity of the acting party. The acting party is authorized to use the requested security token and act on behalf of the subject.

actor_token_type

(string) Type of the actor token.