A backend service defines one or more groups of instances and their service capacities, which can be based on CPU utilization or requests per second ( RPS ). Each backend service also specifies any health check that should be performed against the available instances.

Instances are assigned to a backend service by adding resource views. Instances can not be added directly to a backend service.

Backend service properties

See the BackendServices resource for descriptions of the properties that are available when working with URL maps through either the REST API or the gcloud command-line tool.

Creating a backend service

To create a backend service with gcloud compute , use the backend-services create command.

$ gcloud compute backend-services create NAME \
  --http-health-check HTTP_HEALTH_CHECK \
  [--description DESCRIPTION] \
  [--port PORT; default="80"] \
  [--timeout TIMEOUT; default="30s"] \

This creates the backend service but does not fully define it - you must also specify a resource view to handle requests sent to this service.

Adding resource views to a backend service

To define the instances that are included in a backend service, you must add one or more resource views to each backend service.

To do so, specify the resource view's fully qualified URI as the value of the --group flag to the backend-services add-backend command:

$ gcloud compute backend-services add-backend NAME --group RESOURCE_VIEW \
    [--balancing-mode BALANCING_MODE] \
    [--capacity-scaler CAPACITY_SCALER] \
    [--description DESCRIPTION] \
    [--max-rate MAX_RATE | --max-rate-per-task MAX_RATE_PER_TASK] \
    [--max-utilization MAX_UTILIZATION]

To create a backend service with the API, send a POST request to:

POST https://www.googleapis.com/v1/compute/projects/<project-id>/global/backendServices

{
  "name": NAME,
  "backends": [
    {
      "group": "https://www.googleapis.com/resourceviews/v1beta1/projects/<project-id>/zones/<zone>/resourceViews/<resource-view>"
    }
  ]
  "healthChecks": ["https://www.googleapis.com/compute/v1/projects/<project-id>/global/httpHealthChecks/<health-check>"]
}

The group and healthChecks values must contain the fully qualified URI for the resources.

Health checking

Every backend service must have a health check associated with it. This health check is run continuously and its results are used to determine which instances should receive new requests. (For more information, read the Health Checks chapter.)

To view the results of the latest health check with gcloud compute , use the backend-services get-health command.

gcloud compute backend-services get-health NAME
  [--fields FIELDS [FIELDS ...]]
  [--format FORMAT; default="yaml"]
  [--limit LIMIT]
  [--raw-links]
  [--sort-by SORT_BY]

The command returns a healthState value for all instances in the backend service, with a value of either HEALTHY or UNHEALTHY :

healthStatus:
- healthState: UNHEALTHY
  instance: us-central1-b/instances/www-video1
- healthState: HEALTHY
  instance: us-central1-b/instances/www-video2
kind: compute#backendServiceGroupHealth

Backend services that do not have a valid global forwarding rule referencing it will not be health checked and so will have no health status.

To check health with the API, send a POST request to the following URI, with the resource view URI as the value of a group key in the JSON body:

POST https://www.googleapis.com/compute/v1/projects/<project-id>/global/backendServices/<backend>/getHealth

{
  "group": RESOURCE_VIEW
}

Listing backend services

To list existing backend services with gcloud compute , use the backend-services list command:

$ gcloud compute backend-services list

In the API, send an empty GET request to:

https://www.googleapis.com/compute/v1/projects/<project-id>/global/backendServices

Getting a backend service

To get information about a single backend service with gcloud compute , use the backend-services describe command:

$ gcloud compute backend-services describe [BACKEND]

Note that the backed name is optional; omitting it returns verbose information about all backend services in the project.

In the API, send an empty GET request to:

https://www.googleapis.com/compute/v1/projects/<project-id>/global/backendServices/<backend>

Deleting backend services

To delete a backend service, you must first make sure that the backend service is not being referenced by any URL maps. If a URL map is currently referencing a backend service, you must delete the URL map to remove the reference.

To delete a backend service with gcloud compute , use the backend-services delete command:

$ gcloud compute backend-services delete NAME

In the API, send an empty DELETE request to:

https://www.googleapis.com/compute/v1/projects/<project-id>/global/backendServices/<backend>

Updating a backend service

To edit an existing backend service with gcloud compute , use the backend-services edit command. This launches a text editor containing the backend service file:

$ gcloud compute backend-services edit NAME

A sample resource is included in the file comments to indicate the required format. You can uncomment any line by deleting the leading hash (#).

In the API, you can update the backend service using the update method or the patch method. With the update method, you must reproduce the entire contents of the backend service object in the request body that you send as a POST request. The patch method accepts a partial resource representation as the body of a PATCH request. In both cases, send the requests to the following URI:

https://www.googleapis.com/compute/v1/projects/<project-id>/global/backendServices/<backend>

The body of your request must define the resource representation fields that are appropriate for either the update or patch methods.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License , and code samples are licensed under the Apache 2.0 License . For details, see our Site Policies .

Last updated August 13, 2014.