Unmanaged instance groups are collections of instances that exist in a single zone 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 create managed instance groups unless your applications require you to group dissimilar instances together.
To learn more about instance groups, read the instance groups overview. To create a managed instance group (MIG) instead, read Creating groups of managed instances.
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.
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 Cloud Console.
- 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
command-line tool,
use the instance-groups unmanaged create
command:
gcloud compute instance-groups unmanaged create [INSTANCE_GROUP]
API
In the API, construct a POST
request to the instanceGroups
service.
Include a group name in the request body.
POST https://compute.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 Cloud Console.
- 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 of 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://compute.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instanceGroups/[INSTANCE_GROUP]/addInstances
{
"instances": [
{
"instance": "https://compute.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[INSTANCE_NAME]",
"instance": "https://compute.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 Cloud 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://compute.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://compute.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 Cloud Console.
- 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 of 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://compute.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 Cloud Console.
- 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 of 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://compute.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instanceGroups/[INSTANCE_GROUP]/removeInstances
{
"instances": [
{
"instance": "https://compute.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[INSTANCE_NAME]",
"instance": "https://compute.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), SSL Proxy, TCP proxy, or internal load balancer. A backend service can contain multiple backends. An instance group is a type of backend. 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
, load balancing forwards 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 Cloud Console.
- 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 more 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 8080
. 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://compute.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://compute.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://compute.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://compute.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instanceGroups/[INSTANCE_GROUP]
Deleting an unmanaged instance group
Unlike a managed instance group, deleting an unmanaged instance group does not delete any of the instances within the group. Deleting an unmanaged instance group only dissolves the logical grouping of instances.
Delete an unmanaged instance group using the
gcloud
command-line tool, or the
API.
Console
- Go to the Instance groups page in the Cloud Console.
- 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://compute.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.