gRPC services

This documentation is for the Envoy v3 API.

As of Envoy v1.18 the v2 API has been removed and is no longer supported.

If you are upgrading from v2 API config you may wish to view the v2 API documentation:

api/v2/core/grpc_service.proto

config.core.v3.GrpcService

[config.core.v3.GrpcService proto]

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

  1. {
  2.   "envoy_grpc": "{...}",
  3.   "google_grpc": "{...}",
  4.   "timeout": "{...}",
  5.   "initial_metadata": []
  6. }

envoy_grpc

(config.core.v3.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

(config.core.v3.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 config.core.v3.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. For more information, including details on header value syntax, see the documentation on custom request headers.

config.core.v3.GrpcService.EnvoyGrpc

[config.core.v3.GrpcService.EnvoyGrpc proto]

  1. {
  2.   "cluster_name": "...",
  3.   "authority": "..."
  4. }

cluster_name

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

authority

(string) The :authority header in the grpc request. If this field is not set, the authority header value will be cluster_name. Note that this authority does not override the SNI. The SNI is provided by the transport socket of the cluster.

config.core.v3.GrpcService.GoogleGrpc

[config.core.v3.GrpcService.GoogleGrpc proto]

  1. {
  2.   "target_uri": "...",
  3.   "channel_credentials": "{...}",
  4.   "call_credentials": [],
  5.   "stat_prefix": "...",
  6.   "credentials_factory_name": "...",
  7.   "config": "{...}",
  8.   "per_stream_buffer_limit_bytes": "{...}",
  9.   "channel_args": "{...}"
  10. }

target_uri

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

channel_credentials

(config.core.v3.GrpcService.GoogleGrpc.ChannelCredentials)

call_credentials

(repeated config.core.v3.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

streamstotal

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.

per_stream_buffer_limit_bytes

(UInt32Value) How many bytes each stream can buffer internally. If not set an implementation defined default is applied (1MiB).

channel_args

(config.core.v3.GrpcService.GoogleGrpc.ChannelArgs) Custom channels args.

config.core.v3.GrpcService.GoogleGrpc.SslCredentials

[config.core.v3.GrpcService.GoogleGrpc.SslCredentials proto]

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

  1. {
  2.   "root_certs": "{...}",
  3.   "private_key": "{...}",
  4.   "cert_chain": "{...}"
  5. }

root_certs

(config.core.v3.DataSource) PEM encoded server root certificates.

private_key

(config.core.v3.DataSource) PEM encoded client private key.

cert_chain

(config.core.v3.DataSource) PEM encoded client certificate chain.

config.core.v3.GrpcService.GoogleGrpc.GoogleLocalCredentials

[config.core.v3.GrpcService.GoogleGrpc.GoogleLocalCredentials proto]

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

config.core.v3.GrpcService.GoogleGrpc.ChannelCredentials

[config.core.v3.GrpcService.GoogleGrpc.ChannelCredentials proto]

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

  1. {
  2.   "ssl_credentials": "{...}",
  3.   "google_default": "{...}",
  4.   "local_credentials": "{...}"
  5. }

ssl_credentials

(config.core.v3.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

(config.core.v3.GrpcService.GoogleGrpc.GoogleLocalCredentials)

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

config.core.v3.GrpcService.GoogleGrpc.CallCredentials

[config.core.v3.GrpcService.GoogleGrpc.CallCredentials proto]

  1. {
  2.   "access_token": "...",
  3.   "google_compute_engine": "{...}",
  4.   "google_refresh_token": "...",
  5.   "service_account_jwt_access": "{...}",
  6.   "google_iam": "{...}",
  7.   "from_plugin": "{...}",
  8.   "sts_service": "{...}"
  9. }

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

(config.core.v3.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

(config.core.v3.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

(config.core.v3.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

(config.core.v3.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.

config.core.v3.GrpcService.GoogleGrpc.CallCredentials.ServiceAccountJWTAccessCredentials

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

  1. {
  2.   "json_key": "...",
  3.   "token_lifetime_seconds": "..."
  4. }

json_key

(string)

token_lifetime_seconds

(uint64)

config.core.v3.GrpcService.GoogleGrpc.CallCredentials.GoogleIAMCredentials

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

  1. {
  2.   "authorization_token": "...",
  3.   "authority_selector": "..."
  4. }

authorization_token

(string)

authority_selector

(string)

config.core.v3.GrpcService.GoogleGrpc.CallCredentials.MetadataCredentialsFromPlugin

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

  1. {
  2.   "name": "...",
  3.   "typed_config": "{...}"
  4. }

name

(string)

typed_config

(Any)

Tip

This extension category has the following known extensions:

config.core.v3.GrpcService.GoogleGrpc.CallCredentials.StsService

[config.core.v3.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.

  1. {
  2.   "token_exchange_service_uri": "...",
  3.   "resource": "...",
  4.   "audience": "...",
  5.   "scope": "...",
  6.   "requested_token_type": "...",
  7.   "subject_token_path": "...",
  8.   "subject_token_type": "...",
  9.   "actor_token_path": "...",
  10.   "actor_token_type": "..."
  11. }

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.

config.core.v3.GrpcService.GoogleGrpc.ChannelArgs

[config.core.v3.GrpcService.GoogleGrpc.ChannelArgs proto]

Channel arguments.

  1. {
  2.   "args": "{...}"
  3. }

args

(repeated map<string, config.core.v3.GrpcService.GoogleGrpc.ChannelArgs.Value>) See grpc_types.h GRPC_ARG #defines for keys that work here.

config.core.v3.GrpcService.GoogleGrpc.ChannelArgs.Value

[config.core.v3.GrpcService.GoogleGrpc.ChannelArgs.Value proto]

  1. {
  2.   "string_value": "...",
  3.   "int_value": "..."
  4. }

string_value

(string) Pointer values are not supported, since they don’t make any sense when delivered via the API.

Precisely one of string_value, int_value must be set.

int_value

(int64) Pointer values are not supported, since they don’t make any sense when delivered via the API.

Precisely one of string_value, int_value must be set.