Creating Groups of Unmanaged Instances

This page describes how to create a group of unmanaged instances, known as a unmanaged instance group. To learn about instance groups, read the Instance Groups Overview.

Unmanaged instance groups are collections of instances that are not necessarily identical and do not share a common instance template. You can use unmanaged instance groups to accommodate your pre-existing configurations for load balancing tasks. However, you should always use managed instance groups unless your applications require you to group instances together that are not identical.

Before you begin

If you want to use the command-line examples in this guide:
1. Install the gcloud command-line tool.
2. Set a default region and zone.
If you want to use the API examples in this guide, set up API access.
Read about the difference between managed and unmanaged instance groups.

Creating an unmanaged instance group

Unlike managed instance groups, unmanaged instance groups are just collections of unique instances that do not share a common instance template. Unmanaged groups do not create, delete, or scale the number of instances in the group. You simply create a group, and add individual instances to the group later.

Console

Go to the Instance Groups page in the GCP Console.
Go to the Instance Groups page
Click Create an instance group.
Enter a name for the unmanaged instance group.
Under Location, select Single-zone
Under Zone, select the zone where you want to locate the group.
Under Group type, select Unmanaged instance group.
Select the network for this group.
Under VM instances, select the instances to add to this group.
Click Create to create the new group.

gcloud

To create a new unmanaged instance group with the gcloud tool, use the instance-groups unmanaged create command:

gcloud compute instance-groups unmanaged create [INSTANCE_GROUP]

API

In the API, construct POST request to the instanceGroups service. Include a group name in the request body.

POST https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instanceGroups

{
 "name": "[INSTANCE_GROUP]"
}

When you first create an unmanaged instance group, it is empty. After you create the group, you can add specific instances to the group.

Adding instances to an unmanaged instance group

After you create an unmanaged instance group, you can add your existing instances to the group.

Note that:

An instance can only belong to one load balanced instance group. You can also add an instance to a single load balanced instance group and multiple non-load balanced instance groups.
If the instance group is being load balanced, all instances must belong to the same VPC network or subnet.

Console

Go to the Instance Groups page in the GCP Console.
Go to the Instance Groups page
Under the Name column of the list, click the name of the instance group where you want to add your instances. A page opens with the instance group properties and a list of instances that are already part of the group.
Click Edit group to modify this unmanaged instance group.
Under VM Instances select one or more existing instances to add to the group. You can select instances only if they are in the same zone as your group.
Click Save to save your changes. The selected instances join the unmanaged instance group.

gcloud

Use the add-instances subcommand that is contained in gcloud instance-groups unmanaged:

gcloud compute instance-groups unmanaged add-instances [INSTANCE_GROUP] \
  --instances [INSTANCE_NAME],[ANOTHER_INSTANCE_NAME]

API

Construct a request to the instanceGroups service with the name of the unmanaged instance group for which you want to add instances. Specify the URLs to one or more instances that you want to add to the group.

POST https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instanceGroups/[INSTANCE_GROUP]/addInstances

{
 "instances": [
  {
   "instance": "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[INSTANCE_NAME]",
   "instance": "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[INSTANCE_NAME]"
  }
 ]
}

Listing unmanaged instance groups in a project

Retrieve a list of existing unmanaged instance groups.

Console

In the GCP Console, go to the Instance Groups page.

Go to the Instance Groups page

If you have existing instance groups, the page lists those groups. Note that this page also lists managed instance groups.

gcloud

Confirm that your unmanaged instance group was successfully created using the list command:

gcloud compute instance-groups unmanaged list [INSTANCE_GROUP]

To get information about a specific group:

gcloud compute instance-groups unmanaged describe [INSTANCE_GROUP]

API

List all instance groups within a project. Construct a GET request to the instanceGroups service:

GET https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instanceGroups

Get information about a specific group. Construct a GET request to the instanceGroups service and include the name of a specific unmanaged instance group:

GET https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instanceGroups/[INSTANCE_GROUP]

Listing instances in an unmanaged instance group

Retrieve a list of instances that are included in an unmanaged instance group.

Console

Go to the Instance Groups page in the GCP Console.
Go to the Instance Groups page
Under the Name column of the list, click the name of the unmanaged instance group that contains the instances you want to view. A page opens with the instance group properties and a list of instances that are included in the group.

gcloud

To list the instances in an unmanaged instance group, use the list-instances subcommand, contained within the instances command group of gcloud compute instance-groups unmanaged:

gcloud compute instance-groups unmanaged list-instances [INSTANCE_GROUP]

API

Construct a request to the instanceGroups service with the name of the unmanaged instance group from which you want to list instances. Optionally, you can include filters in the request body.

POST https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instanceGroups/[INSTANCE_GROUP]/listInstances

Removing instances from a group

Separate instances from their groups without deleting them.

If the group is part of a backend service that has enabled connection draining, it can take up to 60 seconds after the connection draining duration has elapsed before the VM instance is removed or deleted.

Console

Go to the Instance Groups page in the GCP Console.
Go to the Instance Groups page
Under the Name column of the list, click the name of the instance group from which you want to remove instances. A page opens with the instance group properties and a list of instances that are included in the group.
On the list of instances, select one or more instances that you want to remove from the group.
Click Remove from group. The selected instances leave the group, but continue to run outside of the group.

gcloud

To remove instances from an unmanaged instance group, use the remove subcommand, contained within gcloud compute instance-groups unmanaged:

gcloud compute instance-groups unmanaged remove-instances [INSTANCE_GROUP] \
  --instances [INSTANCE_NAME],[ANOTHER_INSTANCE_NAME],[INSTANCES ...]

API

Construct a request to the instanceGroups service with the name of the unmanaged instance group from which you want to remove instances. Specify the URLs to one or more instances that you want to remove from the group.

POST https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instanceGroups/[INSTANCE_GROUP]/removeInstances

{
 "instances": [
  {
   "instance": "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[INSTANCE_NAME]",
   "instance": "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[ANOTHER_INSTANCE_NAME]"
  }
 ]
}

Adding an unmanaged instance group to a backend service

A backend service is necessary for creating an HTTP(S), internal, or SSL load balancer. A backend service contains individual backends that each contain one instance group, either managed or unmanaged. The instances in the instance group respond to traffic from the load balancer. The backend service in turn knows which instances it can use, how much traffic they can handle, and how much traffic they are currently handling. In addition, the backend service monitors health checking and does not send new connections to unhealthy instances.

For instructions to add an instance group to a backend service, read Adding instance groups to a backend service.

Assigning named ports to unmanaged instance groups

Named ports are key:value pairs that represent a service name and the port number that the service runs on. Named ports are used by load balancing services to direct traffic to specific ports on individual instances. For example, if you set a named port as http:80 and then configure your backend service to send traffic to a port named http, the load balancing will forward traffic to port 80 of individual instances that are part of the instance group.

Named ports are simple metadata used by load balancing. Named ports do not control network or firewall resources in Compute Engine.

You can assign multiple ports for each service name, and multiple service names for each port. However, keep in mind that a given backend service can only forward traffic to one named port at a time.

Console

Go to the Instance Groups page in the GCP Console.
Go to the Instance Groups page
Under the Name column of the list, click the name of the instance group where you want to specify named ports. A page opens with the instance group properties.
Click Edit group to modify this unmanaged instance group.
Click Specify port name mapping to expand the named ports options.
Click Add item, and enter the desired port name and the port numbers that you want to associate with that name. Click Add item again to add additional entries if necessary.
Click Save to save your changes and apply the named ports to the instances in the unmanaged instance group.

gcloud

Set one or more named ports using the set-named-ports command:

gcloud compute instance-groups unmanaged set-named-ports [INSTANCE_GROUP] \
  --named-ports [PORT_NAME]:[PORT],[PORT_NAME]:[PORT]

For example:

gcloud compute instance-groups unmanaged set-named-ports [INSTANCE_GROUP] \
  --named-ports name1:80,name2:8080

To assign multiple ports to each service name or multiple names for each service, create more than one entry for each name or port. For example, assign name1 to ports 10, 20, and 80. Then, assign both name2 and name3 to port 80. Finally, assign port 9000 to name4.

gcloud compute instance-groups unmanaged set-named-ports [INSTANCE_GROUP] \
  --named-ports name1:10,name1:20,name1:80,\
                name2:8080,name3:8080,\
                name4:9000

Check the named ports assignments for an unmanaged instance group using the get-named-ports command:

gcloud compute instance-groups unmanaged get-named-ports [INSTANCE_GROUP]

NAME  PORT
name1 10
name1 20
name1 80
name2 8080
name3 8080
name4 9000

API

Construct a request to the instanceGroups service and include the name of a specific unmanaged instance group. Obtain the current fingerprint value for the unmanaged instance group by getting information about a specific group. Include the fingerprint and one or more namedPorts value pairs in the request body:

POST https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instanceGroups/[INSTANCE_GROUP]/setNamedPorts

{
 "fingerprint": "42WmSpB8rSM=",
 "namedPorts": [
  {
   "name": "[PORT_NAME]",
   "port": [PORT_NUMBER]
  },
  {
   "name": "[PORT_NAME]",
   "port": [PORT_NUMBER]
  }
 ]
}

For example:

POST https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instanceGroups/example-group/setNamedPorts

{
 "fingerprint": "42WmSpB8rSM=",
 "namedPorts": [
  {
   "name": "name1",
   "port": 80
  },
  {
   "name": "name2",
   "port": 8080
  }
 ]
}

To assign multiple ports to each service name, create multiple entries for that service name. For example, you can assign ports 10, 20, and 80 to name1. Also assign port 8080 to name2.

POST https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instanceGroups/example-group/setNamedPorts

{
 "fingerprint": "42WmSpB8rSM=",
 "namedPorts": [
  {
   "name": "name1",
   "port": 10
  },
  {
   "name": "name1",
   "port": 20
  }
  {
   "name": "name1",
   "port": 80
  }
  {
   "name": "name2",
   "port": 8080
  }
  {
   "name": "name3",
   "port": 80
  }
  {
   "name": "name4",
   "port": 8080
  }
 ]
}

To list the named ports that are already assigned to an unmanaged instance group, construct a GET request that points to the group:

GET https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instanceGroups/[INSTANCE_GROUP]

Deleting an unmanaged instance group

Unlike a managed instance groups, deleting an unmanaged instance group does not delete any of the instances within the group. Deleting an unmanaged instance group simply dissolves the logical grouping of instances.

Delete an unmanaged instance group using the gcloud compute tool, or the API.

Console

Go to the Instance Groups page in the GCP Console.
Go to the Instance Groups page
Select one or more groups on the list that you want to delete.
Click Delete to delete the group. The instances in the group are not deleted.

gcloud

To delete an unmanaged instance group, use the delete command:

gcloud compute instance-groups unmanaged delete [INSTANCE_GROUP]

API

Construct a DELETE request to the instanceGroups service and include the name of a specific unmanaged instance group that you want to delete:

DELETE https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instanceGroups/[INSTANCE_GROUP]

What's next

Create a zonal managed instance group.
Create a regional managed instance group.
Enable load balancing for your managed 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. Java is a registered trademark of Oracle and/or its affiliates.

Last updated February 22, 2018.

Creating Groups of Unmanaged Instances

Before you begin

Creating an unmanaged instance group

Console

gcloud

API

Adding instances to an unmanaged instance group

Console

gcloud

API

Listing unmanaged instance groups in a project

Console

gcloud

API

Listing instances in an unmanaged instance group

Console

gcloud

API

Removing instances from a group

Console

gcloud

API

Adding an unmanaged instance group to a backend service

Assigning named ports to unmanaged instance groups

Console

gcloud

API

Deleting an unmanaged instance group

Console

gcloud

API

What's next

Send feedback about...