Method: regionBackendServices.update

Updates the specified regional BackendService resource with the data included in the request. For more information, see Backend services overview.

HTTP request

PUT https://compute.googleapis.com/compute/v1/projects/{project}/regions/{region}/backendServices/{resourceId}

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
project

string

Project ID for this request.

region

string

Name of the region scoping this request.

resourceId

string

Name of the BackendService resource to update.

Query parameters

Parameters
requestId

string

An optional request ID to identify requests. Specify a unique request ID so that if you must retry your request, the server will know to ignore the request if it has already been completed.

For example, consider a situation where you make an initial request and the request times out. If you make the request again with the same request ID, the server can check if original operation with the same request ID was received, and if so, will ignore the second request. This prevents clients from accidentally creating duplicate commitments.

The request ID must be a valid UUID with the exception that zero UUID is not supported (00000000-0000-0000-0000-000000000000).

Request body

The request body contains data with the following structure:

JSON representation
{
  "id": string,
  "creationTimestamp": string,
  "name": string,
  "description": string,
  "selfLink": string,
  "backends": [
    {
      "description": string,
      "group": string,
      "balancingMode": enum,
      "maxUtilization": number,
      "maxRate": integer,
      "maxRatePerInstance": number,
      "maxRatePerEndpoint": number,
      "maxConnections": integer,
      "maxConnectionsPerInstance": integer,
      "maxConnectionsPerEndpoint": integer,
      "capacityScaler": number,
      "failover": boolean
    }
  ],
  "healthChecks": [
    string
  ],
  "timeoutSec": integer,
  "port": integer,
  "protocol": enum,
  "fingerprint": string,
  "portName": string,
  "enableCDN": boolean,
  "sessionAffinity": enum,
  "affinityCookieTtlSec": integer,
  "region": string,
  "failoverPolicy": {
    "disableConnectionDrainOnFailover": boolean,
    "dropTrafficIfUnhealthy": boolean,
    "failoverRatio": number
  },
  "loadBalancingScheme": enum,
  "connectionDraining": {
    "drainingTimeoutSec": integer
  },
  "iap": {
    "enabled": boolean,
    "oauth2ClientId": string,
    "oauth2ClientSecret": string,
    "oauth2ClientSecretSha256": string
  },
  "cdnPolicy": {
    "cacheKeyPolicy": {
      "includeProtocol": boolean,
      "includeHost": boolean,
      "includeQueryString": boolean,
      "queryStringWhitelist": [
        string
      ],
      "queryStringBlacklist": [
        string
      ]
    },
    "signedUrlKeyNames": [
      string
    ],
    "signedUrlCacheMaxAgeSec": string,
    "requestCoalescing": boolean,
    "cacheMode": enum,
    "defaultTtl": integer,
    "maxTtl": integer,
    "clientTtl": integer,
    "negativeCaching": boolean,
    "negativeCachingPolicy": [
      {
        "code": integer,
        "ttl": integer
      }
    ],
    "bypassCacheOnRequestHeaders": [
      {
        "headerName": string
      }
    ],
    "serveWhileStale": integer
  },
  "customRequestHeaders": [
    string
  ],
  "customResponseHeaders": [
    string
  ],
  "securityPolicy": string,
  "logConfig": {
    "enable": boolean,
    "sampleRate": number
  },
  "securitySettings": {
    "clientTlsPolicy": string,
    "subjectAltNames": [
      string
    ]
  },
  "localityLbPolicy": enum,
  "consistentHash": {
    "httpCookie": {
      "name": string,
      "path": string,
      "ttl": {
        "seconds": string,
        "nanos": integer
      }
    },
    "httpHeaderName": string,
    "minimumRingSize": string
  },
  "circuitBreakers": {
    "maxRequestsPerConnection": integer,
    "maxConnections": integer,
    "maxPendingRequests": integer,
    "maxRequests": integer,
    "maxRetries": integer
  },
  "outlierDetection": {
    "consecutiveErrors": integer,
    "interval": {
      "seconds": string,
      "nanos": integer
    },
    "baseEjectionTime": {
      "seconds": string,
      "nanos": integer
    },
    "maxEjectionPercent": integer,
    "enforcingConsecutiveErrors": integer,
    "enforcingSuccessRate": integer,
    "successRateMinimumHosts": integer,
    "successRateRequestVolume": integer,
    "successRateStdevFactor": integer,
    "consecutiveGatewayFailure": integer,
    "enforcingConsecutiveGatewayFailure": integer
  },
  "network": string,
  "maxStreamDuration": {
    "seconds": string,
    "nanos": integer
  },
  "kind": string
}
Fields
id

string (fixed64 format)

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

creationTimestamp

string

[Output Only] Creation timestamp in RFC3339 text format.

name

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.

description

string

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

backends[]

object

The list of backends that serve this BackendService.

backends[].description

string

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

backends[].group

string

The fully-qualified URL of an instance group or network endpoint group (NEG) resource. To determine what types of backends a load balancer supports, see the Backend services overview.

You must use the fully-qualified URL (starting with https://www.googleapis.com/) to specify the instance group or NEG. Partial URLs are not supported.

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

  • compute.instanceGroups.use
  • compute.networkEndpointGroups.use
backends[].balancingMode

enum

Specifies how to determine whether the backend of a load balancer can handle additional traffic or is fully loaded. For usage guidelines, see Connection balancing mode.

backends[].maxUtilization

number

backends[].maxRate

integer

Defines a maximum number of HTTP requests per second (RPS). For usage guidelines, see Rate balancing mode and Utilization balancing mode.

Not available if the backend's balancingMode is CONNECTION.

backends[].maxRatePerInstance

number

Defines a maximum target for requests per second (RPS). For usage guidelines, see Rate balancing mode and Utilization balancing mode.

Not available if the backend's balancingMode is CONNECTION.

backends[].maxRatePerEndpoint

number

Defines a maximum target for requests per second (RPS). For usage guidelines, see Rate balancing mode and Utilization balancing mode.

Not available if the backend's balancingMode is CONNECTION.

backends[].maxConnections

integer

Defines a target maximum number of simultaneous connections. For usage guidelines, see Connection balancing mode and Utilization balancing mode. Not available if the backend's balancingMode is RATE.

backends[].maxConnectionsPerInstance

integer

Defines a target maximum number of simultaneous connections. For usage guidelines, see Connection balancing mode and Utilization balancing mode.

Not available if the backend's balancingMode is RATE.

backends[].maxConnectionsPerEndpoint

integer

Defines a target maximum number of simultaneous connections. For usage guidelines, see Connection balancing mode and Utilization balancing mode.

Not available if the backend's balancingMode is RATE.

backends[].capacityScaler

number

A multiplier applied to the backend's target capacity of its balancing mode. The default value is 1, which means the group serves 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. The valid ranges are 0.0 and [0.1,1.0]. You cannot configure a setting larger than 0 and smaller than 0.1. You cannot configure a setting of 0 when there is only one backend attached to the backend service.

backends[].failover

boolean

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

healthChecks[]

string

The list of URLs to the healthChecks, httpHealthChecks (legacy), or httpsHealthChecks (legacy) resource for health checking this backend service. Not all backend services support legacy health checks. See Load balancer guide. Currently, at most one health check can be specified for each backend service. Backend services with instance group or zonal NEG backends must have a health check. Backend services with internet or serverless NEG backends must not have a health check.

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

  • compute.healthChecks.useReadOnly
  • compute.httpHealthChecks.useReadOnly
  • compute.httpsHealthChecks.useReadOnly
  • compute.regionHealthChecks.useReadOnly
timeoutSec

integer

Not supported when the backend service is referenced by a URL map that is bound to target gRPC proxy that has validateForProxyless field set to true. Instead, use maxStreamDuration.

port
(deprecated)

integer

Deprecated in favor of portName. The TCP port to connect on the backend. The default value is 80. For Internal TCP/UDP Load Balancing and Network Load Balancing, omit port.

protocol

enum

The protocol this BackendService uses to communicate with backends.

Possible values are HTTP, HTTPS, HTTP2, TCP, SSL, UDP or GRPC. depending on the chosen load balancer or Traffic Director configuration. Refer to the documentation for the load balancers or for Traffic Director for more information.

Must be set to GRPC when the backend service is referenced by a URL map that is bound to target gRPC proxy.

fingerprint

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.

portName

string

A named port on a backend instance group representing the port for communication to the backend VMs in that group. The named port must be defined on each backend instance group. This parameter has no meaning if the backends are NEGs. For Internal TCP/UDP Load Balancing and Network Load Balancing, omit portName.

enableCDN

boolean

If true, enables Cloud CDN for the backend service of an external HTTP(S) load balancer.

sessionAffinity

enum

Type of session affinity to use. The default is NONE. For a detailed description of session affinity options, see: Session affinity.

Not supported when the backend service is referenced by a URL map that is bound to target gRPC proxy that has validateForProxyless field set to true.

region

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.

failoverPolicy

object

Requires at least one backend instance group to be defined as a backup (failover) backend. For load balancers that have configurable failover: Internal TCP/UDP Load Balancing and external TCP/UDP Load Balancing.

failoverPolicy.disableConnectionDrainOnFailover

boolean

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

The default is false.

failoverPolicy.dropTrafficIfUnhealthy

boolean

If set to true, connections to the load balancer are dropped when all primary and all backup backend VMs are unhealthy.If set to false, connections are distributed among all primary VMs when all primary and all backup backend VMs are unhealthy. For load balancers that have configurable failover: Internal TCP/UDP Load Balancing and external TCP/UDP Load Balancing. The default is false.

failoverPolicy.failoverRatio

number

The value of the field must be in the range [0, 1]. If the value is 0, the load balancer performs a failover when the number of healthy primary VMs equals zero. For all other values, the load balancer performs a failover when the total number of healthy primary VMs is less than this ratio. For load balancers that have configurable failover: Internal TCP/UDP Load Balancing and external TCP/UDP Load Balancing.

loadBalancingScheme

enum

Specifies the load balancer type. A backend service created for one type of load balancer cannot be used with another. For more information, refer to Choosing a load balancer.

connectionDraining

object

connectionDraining.drainingTimeoutSec

integer

Configures a duration timeout for existing requests on a removed backend instance. For supported load balancers and protocols, as described in Enabling connection draining.

iap

object

The configurations for Identity-Aware Proxy on this resource. Not available for Internal TCP/UDP Load Balancing and Network Load Balancing.

iap.enabled

boolean

Whether the serving infrastructure will authenticate and authorize all incoming requests. If true, the oauth2ClientId and oauth2ClientSecret fields must be non-empty.

iap.oauth2ClientId

string

OAuth2 client ID to use for the authentication flow.

iap.oauth2ClientSecret

string

OAuth2 client secret to use for the authentication flow. For security reasons, this value cannot be retrieved via the API. Instead, the SHA-256 hash of the value is returned in the oauth2ClientSecretSha256 field.

@InputOnly

iap.oauth2ClientSecretSha256

string

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

cdnPolicy

object

Cloud CDN configuration for this BackendService. Only available for specified load balancer types.

cdnPolicy.cacheKeyPolicy

object

The CacheKeyPolicy for this CdnPolicy.

cdnPolicy.cacheKeyPolicy.includeProtocol

boolean

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

cdnPolicy.cacheKeyPolicy.includeHost

boolean

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

cdnPolicy.cacheKeyPolicy.includeQueryString

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.

cdnPolicy.cacheKeyPolicy.queryStringWhitelist[]

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.

cdnPolicy.cacheKeyPolicy.queryStringBlacklist[]

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.

cdnPolicy.signedUrlKeyNames[]

string

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

cdnPolicy.signedUrlCacheMaxAgeSec

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.

cdnPolicy.requestCoalescing

boolean

If true then Cloud CDN will combine multiple concurrent cache fill requests into a small number of requests to the origin.

cdnPolicy.cacheMode

enum

Specifies the cache setting for all responses from this backend. The possible values are: USE_ORIGIN_HEADERS Requires the origin to set valid caching headers to cache content. Responses without these headers will not be cached at Google's edge, and will require a full trip to the origin on every request, potentially impacting performance and increasing load on the origin server. FORCE_CACHE_ALL Cache all content, ignoring any "private", "no-store" or "no-cache" directives in Cache-Control response headers. Warning: this may result in Cloud CDN caching private, per-user (user identifiable) content. CACHE_ALL_STATIC Automatically cache static content, including common image formats, media (video and audio), and web assets (JavaScript and CSS). Requests and responses that are marked as uncacheable, as well as dynamic content (including HTML), will not be cached.

cdnPolicy.defaultTtl

integer

Specifies the default TTL for cached content served by this origin for responses that do not have an existing valid TTL (max-age or s-max-age). Setting a TTL of "0" means "always revalidate". 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 will overwrite the TTL set in all responses. The maximum allowed value is 31,622,400s (1 year), noting that infrequently accessed objects may be evicted from the cache before the defined TTL.