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 Cloud Run service.

ESPv2 Beta flags are available for the following categories:

Setting configuration flags

Use the gcloud run deploy command to deploy the ESPv2 Beta to Cloud Run. To configure ESPv2 Beta, use the ESPv2_ARGS environment variable to specify configuration flags to the gcloud --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

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

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

The following example use ++ 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 contains commas, for example --cors_allow_methods=PUT,POST,GET, you must set the ESPv2_ARGS environment variable in the downloaded gcloud_build_image script. Edit gcloud_build_image as shown below. Note that a custom delimiter is still used to separate multiple arguments:

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.

Logging

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, you 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, you 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, you 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 field (string, integer). JSON objects and arrays are not logged.

Tracing

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 corresponding to 1 out of 1000 requests being sampled.

--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 the trace backend (Stackdriver). This trace ID can then 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 header to check for the trace context, separated by commas with no spaces. For example, you set this flag as:

--tracing_incoming_context=x-cloud-trace-context

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

If omitted, no check is made for the trace context.

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

--tracing_outgoing_context

Specifies to set 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, 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.

Enabling debug mode

Configure ESPv2 Beta to run in debug mode and to write debug level information to the log.

Flag Description
--enable_debug Enable debug level mode logs for Envoy and enable ConfigManager to log service config details.

Adding CORS support

CORS (Cross-origin resource sharing) is a standard mechanism that allows XMLHttpRequest (XHR) calls executed in a web page to interact with resources from different origins. Without CORS, the same-origin policy that is enforced by all browsers prevents cross-origin requests. For more background information on CORS, see the Mozilla Developer Network (MDN) web docs.

If your backend supports CORS, and you need ESPv2 Beta to pass the CORS request to your backend, you can specify it in the OpenApi spec for your API as shown below:

swagger: "2.0"
host: "my-cool-api.endpoints.my-project-id.cloud.goog"
x-google-endpoints:
- name: "my-cool-api.endpoints.my-project-id.cloud.goog"
  allowCors: True

If your backend does not support CORS, and you need ESPv2 Beta to support it, you have to enable CORS support in ESPv2 Beta.

To enable CORS support in ESPv2 Beta, include the --cors_preset option and set it to either basic or 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 the 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"

What's next

Learn about: