Extensible Service Proxy V2 Beta startup options

The Extensible Service Proxy V2 Beta (ESPv2 Beta) is an Envoy-based proxy that enables Cloud Endpoints to provide API management features. To configure ESPv2 Beta, you can specify configuration flags when deploying the ESPv2 Beta service.

Setting configuration flags

The method for setting ESPv2 Beta configuration flags varies based on deployment platform, as outlined in the following sections.

Compute Engine VM

ESPv2 Beta configuration flags for Compute Engine are specified in the docker run command. For example:

sudo docker run \
    --detach \
    DOCKER_ARGUMENTS \
    gcr.io/endpoints-release/endpoints-runtime:2 \
    --service=SERVICE_NAME \
    --rollout_strategy=managed \
    --backend=YOUR_API_CONTAINER_NAME:8080

In this example, --service, --rollout_strategy and --backend are the ESPv2 Beta configuration flags.

GKE and Kubernetes

You can specify configuration flags for GKE and Kubernetes in the args field of your deployment manifest file. For example:

containers:
- name: esp
  image: gcr.io/endpoints-release/endpoints-runtime:2
  args: [
    "--listener_port=8081",
    "--backend=127.0.0.1:8080",
    "--service=SERVICE_NAME",
    "--rollout_strategy=managed"
  ]

In this example, --listener_port, --backend, --service, and --rollout_strategy are the ESPv2 Beta configuration flags.

Cloud Run for serverless platforms

To specify startup options for Cloud Run for serverless, use the ESPv2_ARGS environment variable. The variable can be set in the gcloud run deploy command by using the --set-env-vars option.

For example:

gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=--enable_debug

In this example, --enable_debug is the ESPv2 Beta configuration flag.

See Cloud Functions for OpenAPI, Cloud Run for OpenAPI, or Cloud Run for gRPC for more information on the gcloud run deploy command.

To set multiple arguments in the ESPv2_ARGS environment variable, specify a custom delimiter and use that delimiter to separate multiple arguments. Do not use a comma as a delimiter. Place the custom delimiter at the start of the ESPv2_ARGS environment variable, surrounded by carets.

The following example uses ++ as the delimiter:

gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=^++^--cors_preset=basic++--cors_allow_origin=your_host.com

If the flag you are setting contains commas, you must set the ESPv2_ARGS environment variable in the gcloud_build_image script.

For example, to add the flag --cors_allow_methods=PUT,POST,GET:

  • Download the gcloud_build_image script.
  • Edit the gcloud_build_image as shown below:
    cat <<EOF > Dockerfile
      FROM BASE_IMAGE
    
      ENV ENDPOINTS_SERVICE_PATH /etc/endpoints/service.json
      COPY service.json \ENDPOINTS_SERVICE_PATH
    
      ENV ESPv2_ARGS ^++^--cors_preset=basic++--cors_allow_method="GET,PUT,POST"++--cors_allow_credentials
    
      ENTRYPOINT ["/env_start_proxy.py"]
      EOF
  • Run the gcloud_build_image script to build the image.

ESPv2 Beta configuration flags

ESPv2 Beta configuration flags can be grouped into the following categories:

Non-Serverless Configuration

These flags are required to run ESPv2 Beta in non-serverless platforms, such as GKE, Compute Engine, and Kubernetes. They can not be set when deployed in Cloud Run for serverless platforms.

Flag Description
--service Sets the name of the Endpoints service.
--version Sets the service config ID of the Endpoints service.
--rollout_strategy Specifies the service config rollout strategy, [fixed|managed]. Default is fixed.
--listener_port Identifies the port to accept downstream connections. It supports HTTP/1.x, HTTP/2, and gRPC connections. Default is 8080.
--backend Specifies the local backend application server address. Valid schemes are http, https, grpc, and grpcs if included. Default scheme is >http.

Logging

Use these flags to configure ESPv2 Beta to write additional information to the Stackdriver log.

Flag Description
--log_request_headers

Log the values of the specified request headers, separated by commas with no spaces. For example, set this flag as:

--log_request_headers=foo,bar

If values for the "foo" and "bar" header are available in the request, then the Endpoints log contains:

request_headers: foo=foo_value;bar=bar_value

--log_response_headers

Log the values of the specified response headers, separated by commas with no spaces. For example, set this flag as:

--log_response_headers=baz,bing

If values for the "baz" and "bing" header are available in the response, then the Endpoints log contains:

response_headers: baz=baz_value;bing=bing_value

--log_jwt_payloads

Log the values of the specified JWT payload primitive fields, separated by commas with no spaces. For example, set this flag as:

--log_jwt_payload=sub,project_id,foo.foo_name

If the values are available in the JWT payload, then the Endpoints log contains:

jwt_payloads: sub=sub_value;project_id=project_id_value; foo.foo_name=foo.foo_name_value

The values in the JWT payload must be primitive fields (string, integer). JSON objects and arrays are not logged.

--access_log

If specified, the path to the local file where access log entries will be written.

--access_log_format

String format to specify the format of access log. If unset, the >default format string is used. For detailed format grammar, see the format strings reference.

Tracing

Use these flags to configure the ESPv2 Beta tracing data sent to Stackdriver. These flags only apply when tracing is enabled.

Flag Description
--disable_tracing

Disable tracing. By default, tracing is enabled.

When enabled, ESPv2 Beta samples a small number of requests to your API every second to get traces that it sends to Stackdriver Trace. By default, 1 out of 1000 requests are sampled. Use the --tracing_sample_rate flag to change the sampling rate.

--tracing_project_id

The Google project ID for Stackdriver tracing.

Tracing is a paid service. The specified project will be billed for tracing.

By default, the project ID of the deployed ESPv2 Beta service is billed.

--tracing_sample_rate

Set the trace sampling rate to a value from 0.0 to 1.0. This value specifies the fraction of requests that are sampled.

The default value is 0.001, which equates to 1 out of 1000 requests.

--tracing_incoming_context

For distributed tracing, a request header can contain a trace context which specifies a trace ID. The trace ID is used when ESPv2 creates new trace spans and sends them to Stackdriver. The trace ID can be used to search all trace spans for a request from all distributed components. If no trace context is specified in the request, and trace is enabled, a random trace ID is generated for all trace spans.

This flag specifies which HTTP headers to check for the trace context, with flag values separated by commas with no spaces. For example, set this flag as:

--tracing_incoming_context=x-cloud-trace-context

Possible values include traceparent and x-cloud-trace-context.

If omitted, the trace context is not checked.

See this Troubleshooting article for more on x-cloud-trace-context. See Trace Context HTTP Headers Format for more on traceparent.

--tracing_outgoing_context

Sets the trace context header in the request sent to the backend service, such as Cloud Functions or Cloud Run. See the description of --tracing_incoming_context above for more information on trace context.

This flag specifies which HTTP header to set, with flag values separated by commas with no spaces. For example, you set this flag as:

--tracing_outgoing_context=traceparent

Possible values include traceparent and x-cloud-trace-context.

If omitted, no trace context header is sent.

See this Troubleshooting article for more on x-cloud-trace-context. See Trace Context HTTP Headers Format for more on traceparent.

Debugging

Use these flags to configure health checks and debugging for ESPv2 Beta. These flags can be used to set up a health handler to respond to health checking calls, an Envoy admin port to fetch configuration and statistics, or run Envoy in debug mode to write debug level information to the log.

Flag Description
-z, --healthz Define a health checking endpoint. For example, -z healthz makes ESPv2 Beta returns code 200 for path /healthz.
--status_port, --admin_port Enable ESPv2 Beta Envoy admin on this port. Refer to the Envoy administration interface reference for more details. The admin port is disabled by default.
--enable_debug Enable debug level logs and add debug headers.

Non GCP Platform Deployment

If ESPv2 Beta is deployed in a non-Google Cloud Platform (GCP) environment, the following flags may be required.

Flag Description
--service_account_key

Specifies the service account key JSON file to access Google services. If the option is omitted, the proxy contacts the GCP metadata server to fetch an access token.

--dns_resolver_addresses The addresses of dns resolvers. Each address should be in format of IP_ADDR or IP_ADDR:PORT and separated with a semi-colon (;). For IP_ADDR, the default DNS port 52 will be used. For example: --dns_resolver_addresses=127.0.0.1;127.0.0.2;127.0.0.3:8000) If unset, ESPv2 Beta will use the default resolver configured in /etc/resolv.conf
--backend_dns_lookup_family Define the dns lookup family for all backends. The options are auto, v4only, and v6only. The default is autocode>.
--non_gcp By default, the proxy attempts to connect to the GCP Metadata Server to get VM location in the first few requests. To skip this step, set this flag to true.

Client IP Extraction

Use these flags to configure client IP extraction for ESPv2 Beta.

Flag Description
--envoy_use_remote_address

Envoy HttpConnectionManager configuration, refer to Envoy reference for detailed information. Default is off.

--envoy_xff_num_trusted_hops Envoy HttpConnectionManager configuration, refer to Envoy reference for detailed information. The default value is 2.

CORS Support

Please refer to Support CORS for a description of available CORS support options. This section describes using ESPv2 Beta startup flags to support CORS.

To enable CORS support in ESPv2 Beta, include the --cors_preset option and set it one of the following flags:

  • >--cors_preset=basic
  • >--cors_preset=cors_with_regex

When you include --cors_preset=basic or --cors_preset=cors_with_regex, ESPv2 Beta:

  • Assumes all location paths have the same CORS policy.
  • Responds to both simple requests and preflight HTTP OPTIONS requests.
  • Caches the result of the preflight OPTIONS request for up to 20 days (1728000 seconds).
  • Sets the response headers to the following values:

    Access-Control-Allow-Origin: *
    Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
    Access-Control-Allow-Headers: DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization
    Access-Control-Expose-Headers: Content-Length,Content-Range
    

To override the default value of Access-Control-Allow-Origin, specify one of the following options:

Option Description
--cors_allow_origin Use with --cors_preset=basic to set Access-Control-Allow-Origin to a specific origin.
Example:
--cors_preset=basic
--cors_allow_origin="http://example.com"
--cors_allow_origin_regex Use with --cors_preset=cors_with_regex. Allows you to use a regular expression to set Access-Control-Allow-Origin.
Example:
--cors_preset=cors_with_regex
--cors_allow_origin_regex='^https?://.+\.example\.com$'

The regular expression in the preceding example allows an origin with either http or https and any subdomain of example.com.

When you set this option in a Kubernetes configuration file, you need to add an additional backslash character to escape both instances of \. in the string, for example:

"--cors_preset","cors_with_regex",
"--cors_allow_origin_regex","^https?://.+\\.example\\.com$"

After setting --cors_preset=basic or --cors_preset=cors_with_regex to enable CORS, you can override the default values of the other response headers by specifying one or more of the following options:

Option Description
--cors_allow_methods Sets Access-Control-Allow-Methods to the specified HTTP methods. Specify the HTTP methods as a string with each HTTP method separated by a comma.
Example:
--cors_preset=basic
--cors_allow_methods="GET,POST,PUT,OPTIONS"
--cors_allow_headers Sets Access-Control-Allow-Headers to the specified HTTP headers. Specify the HTTP headers as a string with each HTTP header separated by a comma.
Example:
--cors_preset=basic
--cors_allow_headers="Origin,Content-Type,Accept"
--cors_allow_credentials Includes the Access-Control-Allow-Credentials header with the value true in responses. By default, the Access-Control-Allow-Credentials header isn't included in responses.
Example:
--cors_preset=basic
--cors_allow_credentials
--cors_expose_headers Sets Access-Control-Expose-Headers to the specified headers. Specify which headers can be exposed as part of the response as a string with each header separated by a comma.
Example:
--cors_preset=basic
--cors_expose_headers="Content-Length"

TLS Support

Use these flags to configure ESPv2 Beta to use TLS connections.

Flag Description
--ssl_server_cert_path Proxy's server cert path. When configured, ESPv2 Beta only accepts HTTP/1.x and HTTP/2 secure connections on listener_port. Requires the certificate and key files "server.crt" and "server.key" within this path.
--ssl_backend_client_cert_path Proxy's client cert path. When configured, ESPv2 Beta enables TLS mutual authentication for HTTPS backends. Requires the certificate and key files "client.crt" and "client.key" within this path.
--ssl_backend_client_root_certs_file The file path of root certificates that ESPv2 Beta uses to verify backend server certificate. If not specified, ESPv2 Beta uses "/etc/ssl/certs/ca-certificates.crt" by default.
--ssl_minimum_protocol Minimum TLS protocol version for client side connection. Please refer to this
--ssl_maximum_protocol Maximum TLS protocol version for client side connection. Please refer to this
--enable_strict_transport_security Enable HSTS (HTTP Strict Transport Security). "Strict-Transport-Security" response header with value "max-age=31536000; includeSubdomains;" is added for all responses from local backend. Not valid for remote backends.
--generate_self_signed_cert Generate a self-signed certificate and key at start, then store them in "/tmp/ssl/endpoints/server.crt" and "/tmp/ssl/endpoints/server.key". This is useful when only a random self-sign cert is needed to serve HTTPS requests. Generated certificate will have Common Name "localhost" and valid for 10 years.

Timeout and Retries

Use these flags to configure remote HTTP call timeout and retries for ESPv2 Beta.

Flag Description
--http_request_timeout_s

Set the timeout in seconds for requests made to external services except Backend and Google Service Control. It includes Google ServiceManagement, Metadata server, and Google IAM server. Must be > 0 and the default is 30 seconds if not set.

--service_control_network_fail_open

In case of network failures when connecting to Google service control, the requests will be allowed if this flag is on. The default is on.

--service_control_check_timeout_ms Set the timeout in millisecond for service control Check request. Must be > 0 and the default is 1000 if not set.
--service_control_report_timeout_ms Set the timeout in millisecond for service control Report request. Must be > 0 and the default is 1000 if not set.
--service_control_quota_timeout_ms Set the timeout in millisecond for service control Quota request. Must be > 0 and the default is 1000 if not set.
--service_control_check_retries Set the retry times for service control Check request. Must be >= 0 and the default is 3 if not set
--service_control_report_retries Set the retry times for service control Report request. Must be >= 0 and the default is 5 if not set
--service_control_quota_retries Set the retry times for service control Quota request. Must be >= 0 and the default is 1 if not set

gRPC Transcoding

Use these flags to configure ESPv2 Beta for HTTP/JSON to gRPC transcoding.

Flag Description
--transcoding_always_print_primitive_fields

Specifies whether to print primitive fields for grpc-json transcoding. By default, primitive fields with default values will be omitted in JSON output. For example, an int32 field set to 0 will be omitted. Setting this flag to true will override the default behavior and print primitive fields regardless of their values. Defaults to false.

--transcoding_always_print_enums_as_ints

Specifies whether to print enums as ints for grpc-json transcoding. By default they are rendered as strings. Defaults to false.

--transcoding_preserve_proto_field_names

Specifies whether to preserve proto field names for grpc-json transcoding. By default, protobuf will generate JSON field names using the json_name option, or lower camel case, in that order. Setting this flag will preserve the original field names. Defaults to false.

--transcoding_ignore_query_parameters

A list of comma-separated query parameters to be ignored for transcoding method mapping in grpc-json transcoding. By default, the transcoder filter will not transcode a request with unknown/invalid query parameters.

--transcoding_ignore_unknown_query_parameters

Specifies whether to ignore query parameters that cannot be mapped to a corresponding protobuf field in grpc-json transcoding. Use this if you cannot control the query parameters and do not know them beforehand. Otherwise, use --transcoding_ignore_query_parameters. Defaults to false.

Additional generic examples and help text for ESPv2 Beta flags can be found found in the GitHub repository.

What's next

Learn about: