REST Resource: backendServices

Resource: BackendService

Represents a Backend Service resource.

A backend service defines how Google Cloud load balancers distribute traffic. The backend service configuration contains a set of values, such as the protocol used to connect to backends, various distribution and session settings, health checks, and timeouts. These settings provide fine-grained control over how your load balancer behaves. Most of the settings have default values that allow for easy configuration if you need to get started quickly.

Backend services in Google Compute Engine can be either regionally or globally scoped.

For more information, see Backend Services.

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.

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.

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.

cdnPolicy.maxTtl

integer

Specifies the maximum allowed TTL for cached content served by this origin. 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 will be capped at the value of maxTTL, as if it were the value of an s-maxage Cache-Control directive. Headers sent to the client will not be modified. Setting a TTL of "0" means "always revalidate". 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.

cdnPolicy.clientTtl

integer

Specifies a separate client (e.g. browser client) maximum TTL. This is used to clamp the max-age (or Expires) value sent to the client. With FORCE_CACHE_ALL,