Method: backendServices.patch

{
  "id": string,
  "creationTimestamp": string,
  "name": string,
  "description": string,
  "selfLink": string,
  "backends": [
    {
      "description": string,
      "group": string,
      "balancingMode": enum,
      "maxUtilization": number,
      "maxRate": number,
      "maxRatePerInstance": number,
      "maxRatePerEndpoint": number,
      "maxConnections": number,
      "maxConnectionsPerInstance": number,
      "maxConnectionsPerEndpoint": number,
      "capacityScaler": number,
      "failover": boolean
    }
  ],
  "healthChecks": [
    string
  ],
  "timeoutSec": number,
  "port": number,
  "protocol": enum,
  "fingerprint": string,
  "portName": string,
  "enableCDN": boolean,
  "sessionAffinity": enum,
  "affinityCookieTtlSec": number,
  "region": string,
  "failoverPolicy": {
    "disableConnectionDrainOnFailover": boolean,
    "dropTrafficIfUnhealthy": boolean,
    "failoverRatio": number
  },
  "loadBalancingScheme": enum,
  "connectionDraining": {
    "drainingTimeoutSec": number
  },
  "iap": {
    "enabled": boolean,
    "oauth2ClientId": string,
    "oauth2ClientSecret": string,
    "oauth2ClientSecretSha256": string
  },
  "cdnPolicy": {
    "cacheKeyPolicy": ,
    "signedUrlKeyNames": [
      string
    ],
    "signedUrlCacheMaxAgeSec": string
  },
  "customRequestHeaders": [
    string
  ],
  "securityPolicy": string,
  "logConfig": {
    "enable": boolean,
    "sampleRate": number
  },
  "localityLbPolicy": enum,
  "consistentHash": {
    "httpCookie": ,
    "httpHeaderName": string,
    "minimumRingSize": string
  },
  "circuitBreakers": {
    "connectTimeout": ,
    "maxRequestsPerConnection": number,
    "maxConnections": number,
    "maxPendingRequests": number,
    "maxRequests": number,
    "maxRetries": number
  },
  "outlierDetection": {
    "consecutiveErrors": number,
    "interval": ,
    "baseEjectionTime": ,
    "maxEjectionPercent": number,
    "enforcingConsecutiveErrors": number,
    "enforcingSuccessRate": number,
    "successRateMinimumHosts": number,
    "successRateRequestVolume": number,
    "successRateStdevFactor": number,
    "consecutiveGatewayFailure": number,
    "enforcingConsecutiveGatewayFailure": number
  },
  "kind": string
}

string (fixed64 format)

[Output Only] The unique identifier for the resource. This identifier is defined by the server.

string

[Output Only] Creation timestamp in RFC3339 text format.

string

Name of the resource. Provided by the client when the resource is created. The name must be 1-63 characters long, and comply with RFC1035. Specifically, the name must be 1-63 characters long and match the regular expression [a-z]([-a-z0-9]*[a-z0-9])? which means the first character must be a lowercase letter, and all following characters must be a dash, lowercase letter, or digit, except the last character, which cannot be a dash.

string

An optional description of this resource. Provide this property when you create the resource.

string

[Output Only] Server-defined URL for the resource.

object

The list of backends that serve this BackendService.

string

An optional description of this resource. Provide this property when you create the resource.

string

The fully-qualified URL of an Instance Group or Network Endpoint Group resource. In case of instance group this defines the list of instances that serve traffic. Member virtual machine instances from each instance group must live in the same zone as the instance group itself. No two backends in a backend service are allowed to use same Instance Group resource.

For Network Endpoint Groups this defines list of endpoints. All endpoints of Network Endpoint Group must be hosted on instances located in the same zone as the Network Endpoint Group.

Backend service can not contain mix of Instance Group and Network Endpoint Group backends.

Note that you must specify an Instance Group or Network Endpoint Group resource using the fully-qualified URL, rather than a partial URL.

When the BackendService has load balancing scheme INTERNAL, the instance group must be within the same region as the BackendService. Network Endpoint Groups are not supported for INTERNAL load balancing scheme.

Authorization requires one or more of the following Google IAM permissions on the specified resource group:

• compute.instanceGroups.use
• compute.networkEndpointGroups.use

enum

Specifies the balancing mode for this backend. For global HTTP(S) or TCP/SSL load balancing, the default is UTILIZATION. Valid values are UTILIZATION, RATE (for HTTP(S)) and CONNECTION (for TCP/SSL).

For Internal Load Balancing, the default and only supported mode is CONNECTION.

number

Used when balancingMode is UTILIZATION. This ratio defines the CPU utilization target for the group. The default is 0.8. Valid range is [0.0, 1.0].

This cannot be used for internal load balancing.

number

The max requests per second (RPS) of the group. Can be used with either RATE or UTILIZATION balancing modes, but required if RATE mode. For RATE mode, either maxRate or maxRatePerInstance must be set.

This cannot be used for internal load balancing.

number

The max requests per second (RPS) that a single backend instance can handle. This is used to calculate the capacity of the group. Can be used in either balancing mode. For RATE mode, either maxRate or maxRatePerInstance must be set.

This cannot be used for internal load balancing.

number

The max requests per second (RPS) that a single backend network endpoint can handle. This is used to calculate the capacity of the group. Can be used in either balancing mode. For RATE mode, either maxRate or maxRatePerEndpoint must be set.

This cannot be used for internal load balancing.

number

The max number of simultaneous connections for the group. Can be used with either CONNECTION or UTILIZATION balancing modes. For CONNECTION mode, either maxConnections or maxConnectionsPerInstance must be set.

This cannot be used for internal load balancing.

number

The max number of simultaneous connections that a single backend instance can handle. This is used to calculate the capacity of the group. Can be used in either CONNECTION or UTILIZATION balancing modes. For CONNECTION mode, either maxConnections or maxConnectionsPerInstance must be set.

This cannot be used for internal load balancing.

number

The max number of simultaneous connections that a single backend network endpoint can handle. This is used to calculate the capacity of the group. Can be used in either CONNECTION or UTILIZATION balancing modes. For CONNECTION mode, either maxConnections or maxConnectionsPerEndpoint must be set.

This cannot be used for internal load balancing.

number

A multiplier applied to the group's maximum servicing capacity (based on UTILIZATION, RATE or CONNECTION). Default value is 1, which means the group will serve up to 100% of its configured capacity (depending on balancingMode). A setting of 0 means the group is completely drained, offering 0% of its available Capacity. Valid range is [0.0,1.0].

This cannot be used for internal load balancing.

boolean

This field designates whether this is a failover backend. More than one failover backend can be configured for a given BackendService.

string

The list of URLs to the HttpHealthCheck or HttpsHealthCheck resource for health checking this BackendService. Currently at most one health check can be specified, and a health check is required for Compute Engine backend services. A health check must not be specified for App Engine backend and Cloud Function backend.

For internal load balancing, a URL to a HealthCheck resource must be specified instead.

Authorization requires one or more of the following Google IAM permissions on the specified resource healthChecks:

• compute.healthChecks.useReadOnly
• compute.httpHealthChecks.useReadOnly
• compute.httpsHealthChecks.useReadOnly

number

How many seconds to wait for the backend before considering it a failed request. Default is 30 seconds.

number

Deprecated in favor of portName. The TCP port to connect on the backend. The default value is 80.

This cannot be used for internal load balancing.

enum

The protocol this BackendService uses to communicate with backends.

Possible values are HTTP, HTTPS, TCP, and SSL. The default is HTTP.

For internal load balancing, the possible values are TCP and UDP, and the default is TCP.

string (bytes format)

Fingerprint of this resource. A hash of the contents stored in this object. This field is used in optimistic locking. This field will be ignored when inserting a BackendService. An up-to-date fingerprint must be provided in order to update the BackendService, otherwise the request will fail with error 412 conditionNotMet.

To see the latest fingerprint, make a get() request to retrieve a BackendService.

A base64-encoded string.

string

Name of backend port. The same name should appear in the instance groups referenced by this service. Required when the load balancing scheme is EXTERNAL.

When the load balancing scheme is INTERNAL, this field is not used.

boolean

If true, enable Cloud CDN for this BackendService.

When the load balancing scheme is INTERNAL, this field is not used.

enum

Type of session affinity to use. The default is NONE.

When the load balancing scheme is EXTERNAL, can be NONE, CLIENT_IP, or GENERATED_COOKIE.

When the load balancing scheme is INTERNAL, can be NONE, CLIENT_IP, CLIENT_IP_PROTO, or CLIENT_IP_PORT_PROTO.

When the protocol is UDP, this field is not used.

number

Lifetime of cookies in seconds if sessionAffinity is GENERATED_COOKIE. If set to 0, the cookie is non-persistent and lasts only until the end of the browser session (or equivalent). The maximum allowed value for TTL is one day.

When the load balancing scheme is INTERNAL, this field is not used.

string

[Output Only] URL of the region where the regional backend service resides. This field is not applicable to global backend services. You must specify this field as part of the HTTP request URL. It is not settable as a field in the request body.

object

boolean

On failover or failback, this field indicates whether connection drain will be honored. Setting this to true has the following effect: connections to the old active pool are not drained. Connections to the new active pool use the timeout of 10 min (currently fixed). Setting to false has the following effect: both old and new connections will have a drain timeout of 10 min.

This can be set to true only if the protocol is TCP.

The default is false.

boolean

This option is used only when no healthy VMs are detected in the primary and backup instance groups. When set to true, traffic is dropped. When set to false, new connections are sent across all VMs in the primary group.

The default is false.

number

The value of the field must be in [0, 1]. If the ratio of the healthy VMs in the primary backend is at or below this number, traffic arriving at the load-balanced IP will be directed to the failover backend.

In case where 'failoverRatio' is not set or all the VMs in the backup backend are unhealthy, the traffic will be directed back to the primary backend in the "force" mode, where traffic will be spread to the healthy VMs with the best effort, or to all VMs when no VM is healthy.

This field is only used with l4 load balancing.

enum

Indicates whether the backend service will be used with internal or external load balancing. A backend service created for one type of load balancing cannot be used with the other. Possible values are INTERNAL and EXTERNAL.

object

number

Time for which instance will be drained (not accept new connections, but still work to finish started).

object

boolean

string

string

string

[Output Only] SHA256 hash value for the field oauth2ClientSecret above.

object

Cloud CDN configuration for this BackendService.

object

The CacheKeyPolicy for this CdnPolicy.

boolean

If true, http and https requests will be cached separately.

boolean

If true, requests to different hosts will be cached separately.

boolean

If true, include query string parameters in the cache key according to queryStringWhitelist and queryStringBlacklist. If neither is set, the entire query string will be included. If false, the query string will be excluded from the cache key entirely.

string

Names of query string parameters to include in cache keys. All other parameters will be excluded. Either specify queryStringWhitelist or queryStringBlacklist, not both. '&' and '=' will be percent encoded and not treated as delimiters.

string

Names of query string parameters to exclude in cache keys. All other parameters will be included. Either specify queryStringWhitelist or queryStringBlacklist, not both. '&' and '=' will be percent encoded and not treated as delimiters.

string

[Output Only] Names of the keys for signing request URLs.

string (int64 format)

Maximum number of seconds the response to a signed URL request will be considered fresh. After this time period, the response will be revalidated before being served. Defaults to 1hr (3600s). When serving responses to signed URL requests, Cloud CDN will internally behave as though all responses from this backend had a "Cache-Control: public, max-age=[TTL]" header, regardless of any existing Cache-Control header. The actual headers served in responses will not be altered.

string

Headers that the HTTP/S load balancer should add to proxied requests.

string

[Output Only] The resource URL for the security policy associated with this backend service.

object

This field denotes the logging options for the load balancer traffic served by this backend service. If logging is enabled, logs will be exported to Stackdriver.

boolean

This field denotes whether to enable logging for the load balancer traffic served by this backend service.

number

This field can only be specified if logging is enabled for this backend service. The value of the field must be in [0, 1]. This configures the sampling rate of requests to the load balancer where 1.0 means all logged requests are reported and 0.0 means no logged requests are reported. The default value is 1.0.

enum

The load balancing algorithm used within the scope of the locality. The possible values are:

• ROUND_ROBIN: This is a simple policy in which each healthy backend is selected in round robin order. This is the default.
• LEAST_REQUEST: An O(1) algorithm which selects two random healthy hosts and picks the host which has fewer active requests.
• RING_HASH: The ring/modulo hash load balancer implements consistent hashing to backends. The algorithm has the property that the addition/removal of a host from a set of N hosts only affects 1/N of the requests.
• RANDOM: The load balancer selects a random healthy host.
• ORIGINAL_DESTINATION: Backend host is selected based on the client connection metadata, i.e., connections are opened to the same address as the destination address of the incoming connection before the connection was redirected to the load balancer.
• MAGLEV: used as a drop in replacement for the ring hash load balancer. Maglev is not as stable as ring hash but has faster table lookup build times and host selection times. For more information about Maglev, refer to https://ai.google/research/pubs/pub44824

This field is applicable to either:

• A regional backend service with the serviceProtocol set to HTTP, HTTPS, or HTTP2, and loadBalancingScheme set to INTERNAL_MANAGED.
• A global backend service with the loadBalancingScheme set to INTERNAL_SELF_MANAGED.

object

Consistent Hash-based load balancing can be used to provide soft session affinity based on HTTP headers, cookies or other properties. This load balancing policy is applicable only for HTTP connections. The affinity to a particular destination host will be lost when one or more hosts are added/removed from the destination service. This field specifies parameters that control consistent hashing. This field is only applicable when localityLbPolicy is set to MAGLEV or RING_HASH.

This field is applicable to either:

• A regional backend service with the serviceProtocol set to HTTP, HTTPS, or HTTP2, and loadBalancingScheme set to INTERNAL_MANAGED.
• A global backend service with the loadBalancingScheme set to INTERNAL_SELF_MANAGED.

object

Hash is based on HTTP Cookie. This field describes a HTTP cookie that will be used as the hash key for the consistent hash load balancer. If the cookie is not present, it will be generated. This field is applicable if the sessionAffinity is set to HTTP_COOKIE.

string

Name of the cookie.

string

Path to set for the cookie.

object

Lifetime of the cookie.

string (int64 format)

Span of time at a resolution of a second. Must be from 0 to 315,576,000,000 inclusive. Note: these bounds are computed from: 60 sec/min * 60 min/hr * 24 hr/day * 365.25 days/year * 10000 years

number

Span of time that's a fraction of a second at nanosecond resolution. Durations less than one second are represented with a 0 seconds field and a positive nanos field. Must be from 0 to 999,999,999 inclusive.

string

The hash based on the value of the specified header field. This field is applicable if the sessionAffinity is set to HEADER_FIELD.

string (int64 format)

The minimum number of virtual nodes to use for the hash ring. Defaults to 1024. Larger ring sizes result in more granular load distributions. If the number of hosts in the load balancing pool is larger than the ring size, each host will be assigned a single virtual node.

object

Settings controlling the volume of connections to a backend service.

This field is applicable to either:

• A regional backend service with the serviceProtocol set to HTTP, HTTPS, or HTTP2, and loadBalancingScheme set to INTERNAL_MANAGED.
• A global backend service with the loadBalancingScheme set to INTERNAL_SELF_MANAGED.

object

The timeout for new network connections to hosts.

string (int64 format)

Span of time at a resolution of a second. Must be from 0 to 315,576,000,000 inclusive. Note: these bounds are computed from: 60 sec/min * 60 min/hr * 24 hr/day * 365.25 days/year * 10000 years

number

Span of time that's a fraction of a second at nanosecond resolution. Durations less than one second are represented with a 0 seconds field and a positive nanos field. Must be from 0 to 999,999,999 inclusive.

number

Maximum requests for a single backend connection. This parameter is respected by both the HTTP/1.1 and HTTP/2 implementations. If not specified, there is no limit. Setting this parameter to 1 will effectively disable keep alive.

number

The maximum number of connections to the backend cluster. If not specified, the default is 1024.

number

The maximum number of pending requests allowed to the backend cluster. If not specified, the default is 1024.

number

The maximum number of parallel requests that allowed to the backend cluster. If not specified, the default is 1024.

number

The maximum number of parallel retries allowed to the backend cluster. If not specified, the default is 3.

object

Settings controlling eviction of unhealthy hosts from the load balancing pool. This field is applicable to either:

• A regional backend service with the serviceProtocol set to HTTP, HTTPS, or HTTP2, and loadBalancingScheme set to INTERNAL_MANAGED.
• A global backend service with the loadBalancingScheme set to INTERNAL_SELF_MANAGED.

number

Number of errors before a host is ejected from the connection pool. When the backend host is accessed over HTTP, a 5xx return code qualifies as an error. Defaults to 5.

object

Time interval between ejection sweep analysis. This can result in both new ejections as well as hosts being returned to service. Defaults to 10 seconds.

string (int64 format)

Span of time at a resolution of a second. Must be from 0 to 315,576,000,000 inclusive. Note: these bounds are computed from: 60 sec/min * 60 min/hr * 24 hr/day * 365.25 days/year * 10000 years

number

Span of time that's a fraction of a second at nanosecond resolution. Durations less than one second are represented with a 0 seconds field and a positive nanos field. Must be from 0 to 999,999,999 inclusive.

object

The base time that a host is ejected for. The real time is equal to the base time multiplied by the number of times the host has been ejected. Defaults to 30000ms or 30s.

string (int64 format)

Span of time at a resolution of a second. Must be from 0 to 315,576,000,000 inclusive. Note: these bounds are computed from: 60 sec/min * 60 min/hr * 24 hr/day * 365.25 days/year * 10000 years

number

Span of time that's a fraction of a second at nanosecond resolution. Durations less than one second are represented with a 0 seconds field and a positive nanos field. Must be from 0 to 999,999,999 inclusive.

number

Maximum percentage of hosts in the load balancing pool for the backend service that can be ejected. Defaults to 10%.

number

The percentage chance that a host will be actually ejected when an outlier status is detected through consecutive 5xx. This setting can be used to disable ejection or to ramp it up slowly. Defaults to 100.

number

The percentage chance that a host will be actually ejected when an outlier status is detected through success rate statistics. This setting can be used to disable ejection or to ramp it up slowly. Defaults to 100.

number

The number of hosts in a cluster that must have enough request volume to detect success rate outliers. If the number of hosts is less than this setting, outlier detection via success rate statistics is not performed for any host in the cluster. Defaults to 5.

number

The minimum number of total requests that must be collected in one interval (as defined by the interval duration above) to include this host in success rate based outlier detection. If the volume is lower than this setting, outlier detection via success rate statistics is not performed for that host. Defaults to 100.

number

This factor is used to determine the ejection threshold for success rate outlier ejection. The ejection threshold is the difference between the mean success rate, and the product of this factor and the standard deviation of the mean success rate: mean - (stdev * successRateStdevFactor). This factor is divided by a thousand to get a double. That is, if the desired factor is 1.9, the runtime value should be 1900. Defaults to 1900.

number

The number of consecutive gateway failures (502, 503, 504 status or connection errors that are mapped to one of those status codes) before a consecutive gateway failure ejection occurs. Defaults to 5.

number

The percentage chance that a host will be actually ejected when an outlier status is detected through consecutive gateway failures. This setting can be used to disable ejection or to ramp it up slowly. Defaults to 0.

string

[Output Only] Type of resource. Always compute#backendService for backend services.