REST Resource: regionBackendServices

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
      ],
      "includeHttpHeaders": [
        string
      ],
      "includeNamedCookies": [
        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,
  "edgeSecurityPolicy": string,
  "logConfig": {
    "enable": boolean,
    "sampleRate": number
  },
  "securitySettings": {
    "clientTlsPolicy": string,
    "authentication": string,
    "subjectAltNames": [
      string
    ]
  },
  "localityLbPolicy": enum,
  "consistentHash": {
    "httpCookie": {
      "name": string,
      "path": string,
      "ttl": {
        "seconds": string,
        "nanos": integer
      }
    },
    "httpHeaderName": string,
    "minimumRingSize": string
  },
  "circuitBreakers": {
    "connectTimeout": {
      "seconds": string,
      "nanos": integer
    },
    "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,
  "subsetting": {
    "policy": enum
  },
  "connectionTrackingPolicy": {
    "trackingMode": enum,
    "connectionPersistenceOnUnhealthyBackends": enum,
    "idleTimeoutSec": integer,
    "enableStrongAffinity": boolean
  },
  "maxStreamDuration": {
    "seconds": string,
    "nanos": integer
  },
  "compressionMode": enum,
  "kind": string
}
Fields
id

string (uint64 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 must use compatible balancing modes. For more information, see Supported balancing modes and target capacity settings and Restrictions and guidance for instance groups.

Note: Currently, if you use the API to configure incompatible balancing modes, the configuration might be accepted even though it has no impact and is ignored. Specifically, Backend.maxUtilization is ignored when Backend.balancingMode is RATE. In the future, this incompatible combination will be rejected.

backends[].maxUtilization

number

Optional parameter to define a target capacity for the UTILIZATIONbalancing mode. The valid range is [0.0, 1.0].

For usage guidelines, see Utilization balancing mode.

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.