Instance Groups

Google Compute Engine Instance Groups allow you to collectively manage groups of virtual machine instances. Instance groups are required for certain Google Cloud services, such as autoscaling and HTTP load balancing.

Some Google Cloud services automatically create instance groups for you, while other services require that you create instance groups separately. For example, the Instance Group Manager service creates an instance group for each manager you create.

You can use the instance group API to create and update user-defined instance groups. For those instance groups created by the Instance Group Manager service, only service endpoints can be updated; to add or remove instances from these groups, use the Instance Group Manager service.

Contents

Getting started

Before you can use the Instance Groups service, you must complete the following steps.

Enable the Compute Engine API

The Instance Groups service requires access to Compute Engine resources. You must first enable the Compute Engine API before enabling Instance Groups.

Enable the Compute Engine API

Enable the Instance Groups API

Next, you must enable the Instance Groups API in the Google Developers Console. If you have multiple projects in the Google Developers Console, make sure that you enable the Instance Groups API and the Compute Engine API in the same project.

Enable the Instance Groups API

Install the command line interface

If you'll be using the command line to interact with the Instance Groups service, you must first:

1. Install the gcloud tool.

2. Enable preview features in the gcloud tool:

   $ gcloud components update preview
   

3. Tell the command line interface which Google Developers Console project to use:

   $ gcloud config set project PROJECT
   

To find the value of PROJECT, visit https://console.developers.google.com//project and refer to the Project ID column.

This document shows examples using the command line interface. For information on the REST API, refer to the API reference.

Download a client library

Google provides client libraries for a number of languages. To learn more, visit the Google APIs Client Libraries documentation.

Quotas

The Instance Groups API enforces the following API rate limits:

• 1 000 000 queries/day
• 20 queries/sec

The Instance Groups API rate limits are independent of Compute Engine API rate limits. All requests to the Instance Groups API are subject to the rate limits above.

The Instance Group resource

An Instance Group resource is represented as:

{
  "name" : string,
  "id" : string,
  "description" : string,
  "kind" : string,
  "creationTimestamp" : string,
  "size" : int,
  "selfLink" : string,
  "endpoints" : [
      string: [
        int
      ],
  ],
  "resources" : [
    string
  ],
  "network" : string,
  "fingerprint" : string
 }

Where:

• name is the name of the instance group. The name must be unique in this project, and from 1 to 63 characters long. It must match the regular expression [a-z]([-a-z0-9]*[a-z0-9])?, which means that the first character must be a lowercase letter. Each following character must be a dash, a lowercase letter, or a digit, except the last character, which cannot be a dash.
• id (output only) is the system-assigned unique ID for this instance group.
• description is the user-supplied description of the instance group.
• kind (output only) is always resourceviews#resourceView.
• creationTimestamp (output only) contains the time at which the instance group was created, in RFC3339 format (yyyy-mm-ddThh:mm:ssTZD).
• size (output only) is the number of Google Compute Engine instances in the instance group.
• selfLink (output only) is the self-referential URL of this instance group.
• endpoints is an array of key:value pairs representing services common to all instances, and the ports on which those services are running. See Specifying service endpoints for more information.
• resources (output only) is an array containing the full URL to each instance in the group.
• network is the network that all the resources in the view belong to.
• fingerprint (output only) is the fingerprint (hash) of the endpoints values.

Creating an instance group

To create a new instance group using the gcloud preview tool, use the instance-groups create command:

$ gcloud preview instance-groups --zone ZONE \
  create NAME \
  [--network NETWORK]

Important flags and parameters

--zone ZONE

[Required] Provide a zone for this instance group.

--network NETWORK

[Optional] The name of the Compute Engine network to associate with this group.

NAME

[Required] The name of this instance group. The name must be unique in this project, and from 1 to 63 characters long. It must match the regular expression [a-z]([-a-z0-9]*[a-z0-9])?, which means that the first character must be a lowercase letter. Each following character must be a dash, a lowercase letter, or a digit, except the last character, which cannot be a dash.

You can confirm that your instance group was successfully created using the get command:

$ gcloud preview instance-groups --zone ZONE get NAME

The response looks similar to the example below:

---
creationTimestamp: '2014-09-02T09:00:00.000Z'
fingerprint: dfba54cf583111db
id: '-5136092226211339579'
kind: resourceviews#resourceView
name: docs
network: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/networks/default
selfLink: https://www.googleapis.com/resourceviews/v1beta2/projects/PROJECT_ID/zones/us-central1-a/resourceViews/docs
size: 0

Adding instances to an instance group

Once you have created your instance group, you can start adding instances. Use the add sub-command, contained in the instances command group of gcloud preview instance-groups:

$ gcloud preview instance-groups --zone ZONE \
  instances --group GROUP \
  add INSTANCE [INSTANCES ...] \
  [--urls]

Note that the --group flag must be set before the add sub-command is passed.

Important flags and parameters

--zone ZONE

[Required] The zone or region for this instance group.

--group GROUP

[Required] The name of the instance group.

INSTANCE [INSTANCES ...]

[Required] The name(s) of the virtual machine instance(s) to add to this instance group. You may add any number of instances, but the instances must already exist. Separate instance names with a space. If you're specifying the instances using their full URLs, include the --urls flag.

--urls

[Optional] Use this flag to specify that the instance identifiers are URLs, and not instance names.

Listing instances

To list the instances in an instance group, use the list sub-command, contained within the instances command group of gcloud preview instance-groups:

$ gcloud preview instance-groups --zone ZONE \
  instances --group GROUP \
  list

Note that the --group flag must be set before the list sub-command is passed.

Important flags and parameters

--zone ZONE

[Required] The zone or region for this instance group.

--group GROUP

[Required] The name of the instance group whose members you're listing.

Removing instances

To remove instances from an instance group, use the remove sub-command, contained within the instances command group of gcloud preview instance-groups:

$ gcloud preview instance-groups --zone ZONE \
  instances --group GROUP \
  remove INSTANCE [INSTANCES ...] \
  [--urls]

Important flags and parameters

--zone ZONE

[Required] The zone for this instance group.

--group GROUP

[Required] The name of this instance group.

INSTANCE [INSTANCES ...]

[Required] The name(s) of the virtual machine instance(s) to remove from this instance group. If you're using instance URLs to specify the instances, also include the --urls flag.

--urls

[Optional] Use this flag to specify that the instance identifiers are URLs, and not instance names.

Deleting an instance group

To delete an instance group, use the delete command:

$ gcloud preview instance-groups --zone ZONE \
  delete NAME

Important flags and parameters

--zone ZONE

[Required] The zone for this instance group.

NAME

[Required] The name of the instance group to delete.

Deleting an instance group does not delete any of the instances within the group.

Rebooting instances in an instance group

You can reboot all of the instances in an instance group with the rolling-updates start command, which is part of the Instance Group Updater feature. The following command reboots the instances in your instance group one at a time.

$ gcloud preview rolling-updates start --action REBOOT \
--group GROUP --zone ZONE

The status of the rolling reboot is included in the list of rolling updates. You can also pause, resume, or cancel a rolling reboot. The REBOOT action works only for non-managed instance groups.

Specifying service endpoints

You can add service labels to one or all instances in a group by passing key:value pairs representing the service name and the port that it is running on. This information is simple metadata used by the Load Balancing service. It does not relate to network or firewall resources.

Setting a service endpoint

To set a service endpoint, use the add-service command:

$ gcloud preview instance-groups --zone ZONE \
  add-service NAME \
  --port PORT \
  --service SERVICE

Important flags and parameters

--port PORT

[Required] The port number of the service.

--service SERVICE

[Required] The name of the service.

--zone ZONE

[Required] The zone for this instance group.

NAME

[Required] The name of the instance group.

Listing services

To list the services on the instance group or a specific instance, use the list-services command:

$ gcloud preview instance-groups --zone ZONE \
  list-services NAME

Important flags and parameters

--zone ZONE

[Required] The zone for this instance group.

NAME

[Required] The name of the instance group.

Removing a service

To remove a service using gcloud preview, use the instance-groups remove-service sub-command:

$ gcloud preview instance-groups --zone ZONE \
  remove-service NAME \
  --service SERVICE

Important flags and parameters

--service SERVICE

[Required] The name of the service to remove.

--zone ZONE

[Required] The zone for this instance group.

NAME

[Required] The name of the instance group.

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.