/

Console

• English
• Deutsch
• Español – América Latina
• Français
• Português – Brasil
• 中文 – 简体
• 日本語
• 한국어

Sign in

• Google Cloud SDK

Start free

gcloud compute backend-services create

The cache is bypassed for all cdnPolicy.cacheMode settings.

Note that requests that include these headers will always fill from origin, and may result in a large number of cache misses if the specified headers are common to many requests.

Values are case-insensitive.

The header name must be a valid HTTP header field token (per RFC 7230).

For the list of restricted headers, see the list of required header name properties in How custom headers work.

This allows you to set a shorter TTL for browsers/clients, and to have those clients revalidate content against Cloud CDN on a more regular basis, without requiring revalidation at the origin.

The value of clientTtl cannot be set to a value greater than that of maxTtl, but can be equal.

Any cacheable response has its max-age/s-maxage directives adjusted down to the client TTL value if necessary; an Expires header will be replaced with a suitable max-age directive.

The maximum allowed value is 31,622,400s (1 year).

When creating a new backend with CACHE_ALL_STATIC and the field is unset, or when switching to that mode and the field is unset, a default value of 3600 is used.

gcloud compute backend-services create NAME             --custom-request-header "header-name: value"             --custom-request-header "another-header:"

The default value is 3600s for cache modes that allow a default TTL to be defined.

The value of defaultTtl cannot be set to a value greater than that of maxTtl, but can be equal.

When the cacheMode is set to FORCE_CACHE_ALL, the defaultTtl overwrites the TTL set in all responses.

A TTL of "0" means Always revalidate.

The maximum allowed value is 31,622,400s (1 year). Infrequently accessed objects may be evicted from the cache before the defined TTL.

Can only be set if load balancing scheme is INTERNAL_SELF_MANAGED, INTERNAL_MANAGED or EXTERNAL_MANAGED.

The possible values are:

IPV4_ONLY
  Only send IPv4 traffic to the backends of the backend service,
  regardless of traffic from the client to the proxy. Only IPv4
  health checks are used to check the health of the backends.

PREFER_IPV6
  Prioritize the connection to the endpoint's IPv6 address over its IPv4
  address (provided there is a healthy IPv6 address).

IPV6_ONLY
  Only send IPv6 traffic to the backends of the backend service,
  regardless of traffic from the client to the proxy. Only IPv6
  health checks are used to check the health of the backends.

The default value is 86400 for cache modes that support a max TTL.

Cache directives that attempt to set a max-age or s-maxage higher than this, or an Expires header more than maxTtl seconds in the future, are capped at the value of maxTtl, as if it were the value of an s-maxage Cache-Control directive.

A TTL of "0" means Always revalidate.

The maximum allowed value is 31,622,400s (1 year). Infrequently accessed objects may be evicted from the cache before the defined TTL.

Negative caching applies to a set of 3xx, 4xx, and 5xx status codes that are typically useful to cache.

Status codes not listed here cannot have their TTL explicitly set and aren't cached, in order to avoid cache poisoning attacks.

HTTP success codes (HTTP 2xx) are handled by the values of defaultTtl and maxTtl.

When the cache mode is set to CACHE_ALL_STATIC or USE_ORIGIN_HEADERS, these values apply to responses with the specified response code that lack any cache-control or expires headers.

When the cache mode is set to FORCE_CACHE_ALL, these values apply to all responses with the specified response code, and override any caching headers.

Cloud CDN applies the following default TTLs to these status codes:

• HTTP 300 (Multiple Choice), 301, 308 (Permanent Redirects): 10m
• HTTP 404 (Not Found), 410 (Gone), 451 (Unavailable For Legal Reasons): 120s
• HTTP 405 (Method Not Found), 421 (Misdirected Request), 501 (Not Implemented): 60s

These defaults can be overridden in cdnPolicy.negativeCachingPolicy.

NegativeCaching must be enabled to config the negativeCachingPolicy.

If you omit the policy and leave negativeCaching enabled, Cloud CDN's default cache TTLs are used.

Note that when specifying an explicit negative caching policy, make sure that you specify a cache TTL for all response codes that you want to cache. Cloud CDN doesn't apply any default negative caching when a policy exists.

CODE is the HTTP status code to define a TTL against. Only HTTP status codes 300, 301, 308, 404, 405, 410, 421, 451, and 501 can be specified as values, and you cannot specify a status code more than once.

Each instance group backend exports one or more named ports, which map a user-configurable name to a port number. The backend service's named port subscribes to one named port on each instance group. The resolved port number can differ among instance group backends, based on each instance group's named port list.

When omitted, a backend service subscribes to a named port called http.

The named port for a backend service is either ignored or cannot be set for these load balancing configurations:

• For any load balancer, if the backends are not instance groups (for example, GCE_VM_IP_PORT NEGs).
• For any type of backend on a backend service for internal or external passthrough Network Load Balancers.

If the load-balancing-scheme is INTERNAL (Internal passthrough Network Load Balancer), the protocol must be one of: TCP, UDP, UNSPECIFIED.

If the load-balancing-scheme is INTERNAL_SELF_MANAGED (Traffic Director), the protocol must be one of: HTTP, HTTPS, HTTP2, GRPC, H2C.

If the load-balancing-scheme is INTERNAL_MANAGED (Internal Application Load Balancer), the protocol must be one of: HTTP, HTTPS, HTTP2, H2C.

If the load-balancing-scheme is INTERNAL_MANAGED (Internal proxy Network Load Balancer), the protocol must be only TCP.

If the load-balancing-scheme is EXTERNAL and region is not set (Classic Application Load Balancer and Classic proxy Network Load Balancer), the protocol must be one of: HTTP, HTTPS, HTTP2, TCP, SSL.

If the load-balancing-scheme is EXTERNAL and region is set (External passthrough Network Load Balancer), the protocol must be one of: TCP, UDP, UNSPECIFIED.

If the load-balancing-scheme is EXTERNAL_MANAGED (Global external Application Load Balancer and regional external Application Load Balancer), the protocol must be one of: HTTP, HTTPS, HTTP2, H2C.

If the load-balancing-scheme is EXTERNAL_MANAGED (Global external proxy Network Load Balancer), the protocol must be one of: TCP, SSL.

Request coalescing (or collapsing) combines multiple concurrent cache fill requests into a small number of requests to the origin. This can improve performance by putting less load on the origin and backend infrastructure. However, coalescing adds a small amount of latency when multiple requests to the same URL are processed, so for latency-critical applications it may not be desirable.

Defaults to true.

This setting defines the default serve-stale duration for any cached responses that do not specify a stale-while-revalidate directive. Stale responses that exceed the TTL configured here will not be served without first being revalidated with the origin. The default limit is 86400s (1 day), which will allow stale content to be served up to this limit beyond the max-age (or s-max-age) of a cached response.

The maximum allowed value is 604800 (1 week).

For example, specifying 12h will cause the responses to signed URL requests to be cached in the CDN up to 12 hours. See $ gcloud topic datetimes for information on duration formats.

If the protocol is HTTP, HTTPS, HTTP2 or H2C, timeout is a request/response timeout for HTTP(S) traffic, meaning the amount of time that the load balancer waits for a backend to return a full response to a request. If WebSockets traffic is supported, the timeout parameter sets the maximum amount of time that a WebSocket can be open (idle or not).

For example, for HTTP, HTTPS, HTTP2 or H2C traffic, specifying a timeout of 10s means that backends have 10 seconds to respond to the load balancer's requests. The load balancer retries the HTTP GET request one time if the backend closes the connection or times out before sending response headers to the load balancer. If the backend sends response headers or if the request sent to the backend is not an HTTP GET request, the load balancer does not retry. If the backend does not reply at all, the load balancer returns a 502 Bad Gateway error to the client.

If the protocol is SSL or TCP, timeout is an idle timeout.

Can only be set if load balancing scheme is INTERNAL,

The possible values are:

ZONAL_AFFINITY_DISABLED
  Default Value. Zonal Affinity is disabled. The load balancer
  distributes new connections to all healthy backend VMs across all
  zones.

ZONAL_AFFINITY_STAY_WITHIN_ZONE
  Zonal Affinity is enabled. The load balancer distributes new
  connections to all healthy backend VMs in the client VM's zone only.
  If there are no healthy backend VMs in the client VM's zone, the load
  balancer distributes new connections to all backend VMs in the client
  VM's zone.

ZONAL_AFFINITY_SPILL_CROSS_ZONE
  Zonal Affinity is enabled. The load balancer distributes new
  connections to all healthy backend VMs in the client VM's zone only.
  If there aren't enough healthy backend VMs in the client VM's zone,
  the load balancer distributes some new connections to backend VMs in
  zones other than the client VM's zone. This distribution depends on a
  configurable spillover ratio that determines when traffic starts
  spilling over to backend VMs in other zones.

This ratio indicates the threshold value for keeping traffic in the client VM's zone. If the proportion of healthy backend VMs in a zone falls below the configured spillover ratio, some new connections from the client VM are distributed to healthy backend VMs in zones other than the client VM's zone.

--cache-key-query-string-blacklist=[QUERY_STRING,…]

Specifies a comma separated list of query string parameters to exclude in cache keys. All other parameters will be included. Either specify --cache-key-query-string-whitelist or --cache-key-query-string-blacklist, not both. '&' and '=' will be percent encoded and not treated as delimiters. Can only be applied for global resources.

--cache-key-query-string-whitelist=QUERY_STRING,[…]

Specifies a comma separated list of query string parameters to include in cache keys. All other parameters will be excluded. Either specify --cache-key-query-string-whitelist or --cache-key-query-string-blacklist, not both. '&' and '=' will be percent encoded and not treated as delimiters. Can only be applied for global resources.

--custom-metrics=[CUSTOM_METRICS,…]

List of custom metrics that are used for WEIGHTED_ROUND_ROBIN locality load balancing policy.

Example:

gcloud compute backend-services create --custom-metrics='name=my-signal,dryRun=true'
gcloud compute backend-services create --custom-metrics='name=my-signal,dryRun=true' --custom-metrics='name=my-signal2'
gcloud compute backend-services create --custom-metrics='[{"name" : "my-signal", "dryRun" : true},
 {"name" : "my-signal2"}]'

Sets custom_metrics value.

dryRun

Sets dryRun value.

name

Required, sets name value.

Shorthand Example:

--custom-metrics=dryRun=boolean,name=string --custom-metrics=dryRun=boolean,name=string

JSON Example:

--custom-metrics='[{"dryRun": boolean, "name": "string"}]'

File Example:

--custom-metrics=path_to_file.(yaml|json)

--custom-metrics-file=[CUSTOM_METRICS,…]

File path to json file with custom metrics that are used for WEIGHTED_ROUND_ROBIN locality load balancing policy.

Example:

gcloud compute backend-services create --custom-metrics-file='customMetric.json'

Sets custom_metrics_file value.

dryRun

Sets dryRun value.

name

Required, sets name value.

Shorthand Example:

--custom-metrics-file=dryRun=boolean,name=string --custom-metrics-file=dryRun=boolean,name=string

JSON Example:

--custom-metrics-file='[{"dryRun": boolean, "name": "string"}]'

File Example:

--custom-metrics-file=path_to_file.(yaml|json)

--global

If set, the backend service is global.

--region=REGION

Region of the backend service to create. Overrides the default compute/region property value for this command invocation.

To avoid prompting when this flag is omitted, you can set the compute/region property:

gcloud config set compute/region REGION

A list of regions can be fetched by running:

gcloud compute regions list

To unset the property, run:

gcloud config unset compute/region

Run $ gcloud help for details.

gcloud alpha compute backend-services create

gcloud beta compute backend-services create

gcloud preview compute backend-services create