An unmanaged instance group is a collection of virtual machines (VMs) that reside in a single zone, VPC network, and subnet. An unmanaged instance groups is useful for grouping together VMs that require individual configuration settings or tuning.
For VMs that require consistent configuration settings, you can use a managed instance group (MIG) with an instance template. When possible, consider using managed instance groups instead of unmanaged ones. To create a managed instance group, see Creating groups of managed instances.
You can add either type of instance group as a backend to a Google Cloud load balancer. For more information, see Cloud Load Balancing overview. For the number of VMs per instance group that Google Cloud supports, see VMs per instance group.
To learn more about instance groups, see Instance groups overview.
Before you begin
- If you want to use the command-line examples in this guide:
- Install or update to the latest version of the gcloud command-line tool.
- 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.
Working with unmanaged instance groups
Creating groups
Unlike managed instance groups, unmanaged instance groups are just collections of distinct VMs that do not share a common instance template. You simply create a group, and add individual VMs to the group.
Console
- In the Cloud Console, go to the Instance groups page.
- Click Create an instance group.
- Click New unmanaged instance group.
- Enter a name for the unmanaged instance group.
- Under Location, select a region and a zone.
- Select a Network and Subnetwork.
- Under VM instances, select the VMs to add to this group.
- Click Create.
gcloud
To create a new unmanaged instance group, use the instance-groups unmanaged create command:
gcloud compute instance-groups unmanaged create instance-group-name \ --zone=zone
Replace the following:
instance-group-name
: The name of the group you want to create.zone
: The zone where you want to create the group.
API
To create an unmanaged instance group with the API, send a POST
request using the
instanceGroups.insert
method:
POST https://compute.googleapis.com/compute/v1/projects/project-id/zones/zone/instanceGroups { "name": "instance-group-name" }
Replace the following:
instance-group-name
: The name of the group you want to create.zone
: The zone where you want to create the group.project-id
: The project ID for the project containing the group.
When you create a new unmanaged instance group with gcloud
command-line tool or the API,
no VMs are added to it automatically. You can add VMs to the unmanaged instance
group manually.
Listing and describing groups
Retrieve a list of existing unmanaged instance groups.
Console
In the Cloud Console, the Instance groups page lists existing unmanaged and managed instance groups.
gcloud
To list all unmanaged instance groups in your project with the
gcloud
command-line tool, use instance-groups unmanaged
list:
gcloud compute instance-groups unmanaged list
To see information about a specific unmanaged instance group, use the instance-groups unmanaged describe command:
gcloud compute instance-groups unmanaged describe instance-group-name \ --zone=zone
Replace the following:
instance-group-name
: The name of the group to describe.zone
: The zone of the group.
API
To list instance groups with the API, send a GET
request using the
instanceGroups.list
method:
GET https://compute.googleapis.com/compute/v1/projects/project-id/zones/zone/instanceGroups
To obtain information about a specific unmanaged instance group with the
API, send a GET
request using the
instanceGroups.get
method:
GET https://compute.googleapis.com/compute/v1/projects/project-id/zones/zone/instanceGroups/instance-group-name
Replace the following:
instance-group-name
: The name of the group to describe.zone
: The zone of the group.project-id
: The project ID for the project containing the group.
Deleting groups
Unlike a managed instance group, deleting an unmanaged instance group does not delete any of the VMs within the group. Deleting an unmanaged instance group only removes the logical grouping of VMs.
You can't delete an instance group if the group is a backend of a Google Cloud load balancer. You must first remove the backend from the backend service.
Console
- In the Cloud Console, go to the Instance groups page.
- Select one or more unmanaged instance groups from the list.
- Click Delete to remove the groups. The groups are removed, but the VMs in the groups are not deleted.
gcloud
To delete an unmanaged instance group, use the instance-groups unmanaged delete command:
gcloud compute instance-groups unmanaged delete instance-group-name \ --zone=zone
Replace the following:
instance-group-name
: The name of the group you want to delete.zone
: The zone of the group.
API
To delete an unmanaged instance group with the API, send a DELETE
request using the
instanceGroups.delete
method:
DELETE https://compute.googleapis.com/compute/v1/projects/project-id/zones/zone/instanceGroups/instance-group-name
Replace the following:
instance-group-name
: The name of the group you want to delete.zone
: The zone of the group.project-id
: The project ID for the project containing the group.
Group membership
Adding VMs
After you create an unmanaged instance group, you can add VMs to the group.
Console
- In the Cloud 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 VMs. A page opens with the instance group properties and a list of VMs that are already part of the group.
- Click Edit group to modify this unmanaged instance group.
- Under VM instances select one or more existing VMs to add to the group. You can only select VMs that are in the same zone, VPC network, and subnet as existing VMs.
- Click Save to add the new VMs to the group.
gcloud
To add instances to an unmanaged instance group, use the instance-groups unmanaged add-instances command:
gcloud compute instance-groups unmanaged add-instances instance-group-name \ --zone=zone \ --instances=list-of-VM-names
Replace the following:
instance-group-name
: The name of the group to which you want to add VMs.zone
: The zone of the group.list-of-VM-names
: A comma-delimited list of VMs in the same zone, VPC network, and subnet.
API
To add VMs to an unmanaged instance group with the API, send a POST
request using the
instanceGroups.addInstances
method:
POST https://compute.googleapis.com/compute/v1/projects/project-id/zones/zone/instanceGroups/instance-group-name/addInstances { "instances": [ { "instance": "https://www.googleapis.com/compute/v1/projects/project-id/zones/zone/instances/instance-1-name", "instance": "https://www.googleapis.com/compute/v1/projects/project-id/zones/zone/instances/instance-2-name", .... } ] }
Replace the following:
instance-group-name
: The name of the group to which you want to add VMs.zone
: The zone of the group.project-id
: The project ID for the project containing the group.instance-1-name
andinstance-2-name
: These are names of the VMs, in the same zone, VPC network, and subnet, that you want to add to the group.
Listing VMs
You can retrieve a list of member VMs in an unmanaged instance group.
Console
- In the Cloud Console, go to the Instance groups page.
- Under the Name column of the list, click the name of the unmanaged instance group that you want to view. A page with the list of instances that are included in the group appears.
gcloud
To list the VMs in an unmanaged instance group, use the instance-groups unmanaged list-instances command:
gcloud compute instance-groups unmanaged list-instances instance-group-name \ --zone=zone
Replace the following:
instance-group-name
: The name of the group whose members you want to list.zone
: The zone of the group.
API
To list VMs in an unmanaged instance group with the API, send a POST
request using the
instanceGroups.listInstances
method:
POST https://compute.googleapis.com/compute/v1/projects/project-id/zones/zone/instanceGroups/instance-group-name/listInstances
Replace the following:
instance-group-name
: The name of the group whose members you want to list.zone
: The zone of the group.project-id
: The project ID for the project containing the group.
Removing VMs
You can remove VMs from an unmanaged instance group. Removing a VM from the instance group does not delete the VM.
Console
- In the Cloud 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 VMs. A page opens with the instance group properties and a list of VMs that are included in the group.
- In the list, select one or more VMs that you want to remove from the group.
- Click Remove from group. VMs that you remove from an unmanaged instance group continue to exist and run unless you stop or delete them.
gcloud
To remove VMs from an unmanaged instance group, use the instance-groups unmanaged remove-instances command:
gcloud compute instance-groups unmanaged remove-instances instance-group-name \ --zone=zone \ --instances=list-of-VM-names
Replace the following:
instance-group-name
: The name of the group that contains instances to remove.zone
: The zone of the group.list-of-VM-names
: A comma-delimited list of VMs that you want to remove from the group.
API
To remove VMs from an unmanaged instance group with the API, send a POST
request using the
instanceGroups.removeInstances
method. You can simultaneously remove multiple VMs as shown below:
POST https://compute.googleapis.com/compute/v1/projects/project-id/zones/zone/instanceGroups/instance-group-name/removeInstances { "instances": [ { "instance": "https://www.googleapis.com/compute/v1/projects/project-id/zones/zone/instances/instance-1-name", "instance": "https://www.googleapis.com/compute/v1/projects/project-id/zones/zone/instances/instance-2-name", .... } ] }
Replace the following:
instance-group-name
: The name of the group that contains instances to remove.zone
: The zone of the group.project-id
: The project ID for the project containing the group.instance-1-name
andinstance-2-name
: These are names of the VMs that you want to disassociate from the group.
Working with named ports
Named ports are key-value pairs that represent a port's name and number. They are used in conjunction with Google Cloud load balancers. Load balancers that act as proxies subscribe to a single named port in their backend service configuration. The port's name is translated to a port number based on the named ports mapping of each instance group backend.
For example, a backend service can subscribe to a port that is named
http-port
. The backend instance group can have a port named http-port:80
.
The backend instance group instructs the load balancer to send traffic to a VM
in the group on port 80
using a protocol (such as TCP). The protocol is
defined in the load balancer's backend service.
You can define multiple named ports in an instance group. However, a load
balancer's backend service only subscribes to a single named port. Backend
instance groups on the same backend service can use different named port
mappings. To illustrate, consider an example backend service that subscribes to
the named port http-port
, and that has two backend instance groups:
instance-group-a
with a named port ofhttp-port:80
instance-group-b
with a named port ofhttp-port:79
This backend service sends traffic to port 80 for VMs in instance-group-a
and
port 79 for VMs in instance-group-b
.
Console
- In the Cloud 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.
- In the Port name mapping (Optional) section, click Add item, and enter a port name and its number. Add or remove other named ports as necessary.
- Click Save to update the list of named ports for the unmanaged instance group.
gcloud
To add named ports to an unmanaged instance group, use the instance-groups unmanaged set-named-ports command:
gcloud compute instance-groups unmanaged set-named-ports instance-group-name \ --zone=zone \ --named-ports=port-name:port-number,...
To list named ports in an unmanaged instance group use instance-groups unmanaged get-named-ports:
gcloud compute instance-groups unmanaged get-named-ports instance-group-name \ --zone=zone
To remove all named ports from an unmanaged instance group with the
gcloud
command-line tool, use instance-groups unmanaged
set-named-ports
with an empty list of named ports:
gcloud compute instance-groups unmanaged set-named-ports instance-group-name \ --zone=zone \ --named-ports=""
In all the examples above, replace the following if present:
instance-group-name
: The name of the instance group.zone
: The zone of the group.port-name
andport-number
: The port name and number represent a mapping from a name you choose to a port number. You can specify multiple mappings separated by commas; for example,port-one:80,port-two:8080
is a valid list of named ports.
API
Describe the instance group and note the fingerprint.
To add named ports with the API, send a
POST
request using the instanceGroups.setNamedPorts method. If you want to remove all named ports, setnamedPorts
to an empty list.POST https://compute.googleapis.com/compute/v1/projects/project-id/zones/zone/instanceGroups/instance-group-name/setNamedPorts { "fingerprint": "fingerprint", "namedPorts": [ { "name": "port-name", "port": port-number }, { "name": "port-name", "port": port-number }, .... ] }
Replace the following:
instance-group-name
: The name of the instance group.zone
: The zone of the group.project-id
: The project ID for the project containing the group.port-name
andport-number
: The port name and number represent a mapping from a name you choose to a port number.fingerprint
: This is the fingerprint from the previous step.
Describe the instance group again and note the configured named ports.
What's next
- Create a zonal managed instance group.
- Create a regional managed instance group.
- Learn about Cloud Load Balancing.