Share sole-tenant node groups


Shared sole-tenant node groups are similar to local sole-tenant node groups. For example, shared node groups cost the same, consume the same quota, and reside under a parent project in the resource hierarchy.

The difference between shared node groups and local node groups is that other projects in your organization can provision virtual machine (VM) instances in the shared node groups.

Sharing a node group across multiple projects or an organization can help you do the following:

  • Consolidate node groups that you manage into a single project and then share those nodes with other projects or the entire organization

  • Decrease costs by deleting nodes after consolidating VMs from various projects into underutilized node groups

  • Manage sole-tenant nodes with a single team

  • Share sole-tenant nodes with smaller projects and retain security and access control boundaries between those projects

  • Improve the utilization of your node groups and reduce the number of reserved maintenance nodes when using the Migrate within node group maintenance policy

The following diagram shows a node group that is shared with other projects so that other departments that manage VMs in those projects can provision VMs in a shared node group.

Diagram of a node group that's shared across projects. Departments
            that manage VMs in different projects can provision VMs in a shared
            node group.

Utilization benefits of shared node groups

The following table compares projects that use local node groups with projects that use shared node groups. Notice that vCPU underutilization decreases in projects that use shared node groups.

Project configuration Local node groups Shared node groups
Projects 10 10
vCPU / project 24 24
Node groups 10 1
Nodes / node group 1 3
vCPU / node 80 80
Utilization / node group 24 80
Underutilization / node group 56 0
Total underutilization 10 x 56 = 560 vCPUs 1 x 0 = 0 vCPUs

Settings for sharing node groups

Compute Engine uses the following settings for sharing node groups and provisioning VMs in the shared node groups:

  • A share setting that you configure when you create or update the sole-tenant node group. To specify whether to share the node group with other projects or with the entire organization, use the gcloud CLI settings (--share-setting, --share-with) or the Compute Engine API settings (shareSetting, shareWith).

  • A default compute.googleapis.com/project node affinity label that you use when you provision a VM in a shared node group by using node affinity labels.

Maintenance policy considerations

When a node group uses the Migrate within node group maintenance policy, Compute Engine reserves at least 1 node for live migration events, so the node group must have at least 2 nodes. You can't schedule VMs in the reserved node, so node groups with this maintenance policy often have lower overall utilization. This makes workloads that require the Migrate within node group maintenance policy good candidates for node group sharing, as they often see the greatest benefit from improved utilization.

IAM roles and permissions

Keep in mind the following information about IAM roles and permissions when you share a node group:

  • If a node group is shared with a project, any user that can create VMs in the listed projects or in the organization can provision VMs from those projects onto the shared node group without any changes to IAM roles or permissions.

  • The compute.soleTenantViewer IAM role lets you list and view node groups. You cannot modify node groups with this role. Any user with this role or with permissions to list node groups, regardless of the IAM permissions on the VM, can view the project ID, name, machine type, and information about local SSDs and GPUs for all VMs in the node group.

Limitations

Sharing limitations

  • You must update the sharing settings from the project that owns the node group.

  • You cannot share node groups between organizations. For example, if you migrate a project that contains a shared node group from one organization to another, you must also migrate all projects that have VMs running in that shared node group.

  • You cannot change the share setting so that existing VMs in the node group lose access to the node group. For example, you cannot remove a project from from the share setting if a VM from that project is currently running in the node group.

Tool limitations

  • To switch the share setting from projects to organization or from organization to projects, you must use the gcloud CLI or the Compute Engine API. You can't use the console to switch the share setting from projects to organization or from organization to projects.

  • To share an existing node group, you must use the gcloud CLI or the Compute Engine API. You can't use the console to share an existing node group.

Compliance regime limitations

  • Projects that have VMs provisioned in shared node groups must be under the same compliance regime.

Pricing

VMs in shared node groups do not incur additional charges, and there are no additional charges for sharing node groups. For more information about sole-tenant node pricing, see Sole-tenant node pricing.

Before you begin

Create a new node group and share it

To create a new node group and share it with other projects or with the entire organization, use the gcloud CLI or the Compute Engine API.

Permissions required for this task

To perform this task, you must have the following permissions:

  • compute.nodeGroups.create permissions on the project

gcloud

To create a shared node group, use the following gcloud beta compute sole-tenancy node-groups create command.

gcloud beta compute sole-tenancy node-groups create NODE_GROUP \
    --zone=ZONE \
    --node-template=NODE_TEMPLATE \
    --target-size=SIZE \
    --share-setting=SHARE_SETTING \
    --share-with=PROJECTS

Replace the following:

  • NODE_GROUP: the name of the node group.

  • ZONE: the zone to create the node group in.

  • NODE_TEMPLATE: the name of the previously created node template.

  • SIZE: the number of nodes in the node group.

  • SHARE_SETTING: the share setting for the node group. Set to projects to share with specific projects, or set to organization to share with the entire organization.

  • PROJECTS: a list of project IDs or project numbers to share the node group with. Only required if you set SHARE_SETTING to projects.

API

To create a shared node group, use the following nodeGroups.insert method.

POST https://compute.googleapis.com/compute/beta/projects/PROJECT/zones/ZONE/nodeGroups

{
    ...
    "name": NODE_GROUP,
    "nodeTemplate": NODE_TEMPLATE,
    "size": SIZE,
    "shareSetting": SHARE_SETTING,
    "shareWith": PROJECTS
    ...
}

Replace the following:

  • PROJECT: the name of project to create the node group in.

  • ZONE: the zone to create the node group in.

  • NODE_GROUP: the name of the node group.

  • NODE_TEMPLATE: the name of the previously created node template.

  • SIZE: the number of nodes in the node group.

  • SHARE_SETTING: the share setting for the node group. Set to projects to share with specific projects, or set to organization to share with the entire organization.

  • PROJECTS: a list of project IDs or project numbers to share the node group with. Only required if you set SHARE_SETTING to projects.

View the sharing settings of a node group

To view the sharing settings of a node group, use the gcloud CLI or the Compute Engine API.

Permissions required for this task

To perform this task, you must have the following permissions:

  • compute.nodeGroups.list permissions on the project

gcloud

To view the sharing settings of a node group, use the following gcloud beta compute sole-tenancy node-groups describe command.

gcloud beta compute sole-tenancy node-groups describe NODE_GROUP

Replace NODE_GROUP with the name of the node group to view the sharing settings of.

API

To view the sharing settings of a node group, use the following nodeGroups.get method.

GET https://compute.googleapis.com/compute/beta/projects/PROJECT/zones/ZONE/nodeGroups

Replace the following:

  • PROJECT: the name of project with the node group to view the sharing settings of

  • ZONE: the zone containing the node group to view the sharing settings of

Share an existing node group

To share an existing node group with other projects or the entire organization, use the gcloud CLI or the Compute Engine API.

Permissions required for this task

To perform this task, you must have the following permissions:

  • compute.nodeGroups.update permissions on the project in which you created the node group

gcloud

To update the sharing settings of a node group, use the following gcloud beta compute sole-tenancy node-groups update command.

gcloud beta compute sole-tenancy node-groups update NODE_GROUP \
    --zone=ZONE \
    --share-setting=SHARE_SETTING \
    --share-with=PROJECTS

Replace the following:

  • NODE_GROUP: the name of the node group to update the sharing settings of.

  • SHARE_SETTING: the share setting for the node group. Set to projects to share with specific projects, or set to organization to share with the entire organization.

  • PROJECTS: a list of project IDs or project numbers to share the node group with. Only required if you set SHARE_SETTING to projects.

API

To update the sharing settings of a node group, use the following nodeGroups.patch method.

PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT/zones/ZONE/nodeGroups/NODE_GROUP

{
    "shareSetting": SHARE_SETTING,
    "shareWith": PROJECTS
}

Replace the following:

  • PROJECT: the name of the project with the node groups to update the sharing settings of.

  • ZONE: the zone containing the node groups to update the sharing settings of.

  • NODE_GROUP: the name of the node group to update the sharing settings of.

  • SHARE_SETTING: the share setting for the node group. Set to projects to share with specific projects, or set to organization to share with the entire organization.

  • PROJECTS: a list of project IDs or project numbers to share the node group with. Only required if you set SHARE_SETTING to projects.

Stop sharing a node group

To stop sharing a node group with other projects or the entire organization, use the gcloud CLI or the Compute Engine API.

Permissions required for this task

To perform this task, you must have the following permissions:

  • compute.nodeGroups.update permissions on the project in which you created the node group

gcloud

To stop sharing a node group with other projects or the entire organization, use the following gcloud beta compute sole-tenancy node-groups update command.

gcloud beta compute sole-tenancy node-groups update NODE_GROUP \
    --zone=ZONE \
    --share-setting=local

Replace the NODE_GROUP with the name of the node group to stop sharing.

API

To stop sharing a node group with other projects or the entire organization, use the following nodeGroups.patch method.

PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT/zones/ZONE/nodeGroups/NODE_GROUP

{
    "shareSetting": "local"
}

Replace the following:

  • PROJECT: the name of the project with the node group to stop sharing

  • ZONE: the zone containing the node group to stop sharing

  • NODE_GROUP: the name of the node group to stop sharing

Delete a shared node group

To delete a shared node group, use the gcloud CLI or the Compute Engine API from the owning project. Before deleting a node group, stop all VMs that are running in the node group.

Permissions required for this task

To perform this task, you must have the following permissions:

  • compute.nodeGroups.delete permissions on the project in which you created the node group

gcloud

To delete a shared node group from the owning project, use the following gcloud beta compute sole-tenancy node-groups delete command.

gcloud beta compute sole-tenancy node-groups delete NODE_GROUP

Replace NODE_GROUP with the name of the node group to delete.

API

To delete a shared node group from the owning project, use the following nodeGroups.delete method.

DELETE https://compute.googleapis.com/compute/beta/projects/PROJECT/zones/ZONE/nodeGroups/NODE_GROUP

Replace the following:

  • PROJECT: the name of the project with the node group to delete

  • ZONE: the zone containing the node group to delete

  • NODE_GROUP: the name of the node group to delete

Provision a sole-tenant VM in a shared node group

To provision a sole-tenant VM into a shared node group, use the gcloud CLI or the Compute Engine API.

gcloud

Provision a VM in a shared node group by using the node group name

To provision a sole-tenant VM in a shared node group by using the node group name, use the following gcloud beta compute instances create command.

gcloud beta compute instances create VM_NAME \
    --machine-type=MACHINE_TYPE \
    --node-group=NODE_GROUP \
    --node-project=NODE_PROJECT

Replace the following:

  • VM_NAME: the name of the new sole-tenant VM to create in a shared node group

  • MACHINE_TYPE: the machine type for the new sole-tenant VM

  • NODE_GROUP: the name of the shared node group to create the sole-tenant VM in

  • NODE_PROJECT: the project containing the node group to provision the VM in

Provision a VM in a shared node group by using a node affinity file

To provision a sole-tenant VM in a shared node group by using a node affinity file, use the following gcloud beta compute instances create command.

gcloud beta compute instances create VM_NAME \
    --machine-type=MACHINE_TYPE \
    --node-affinity-file=NODE_AFFINITY_FILE

Replace the following:

  • VM_NAME: the name of the sole-tenant VM to create in a shared node group by using an affinity label.

  • MACHINE_TYPE: the machine type of the sole-tenant VM to create in a shared node group.

  • NODE_AFFINITY_FILE: the name of the .json file containing the node affinity information. For more information about how to configure node affinity, see Configure node affinity labels.

API

To provision a sole-tenant VM in a shared node group by using a node affinity file, use the following nodeGroups.insert method.

POST https://compute.googleapis.com/compute/beta/projects/PROJECT/zones/ZONE/instances
{
    ...
    "name": VM_NAME,
    "machineType": MACHINE_TYPE,
    "scheduling": {
        ...
        "nodeAffinities": [
            {
                "key": KEY,
                "operator": OPERATOR,
                "values": [
                    VALUE
                ]
            }
        ],
        ...
    },
    ...
}

Replace the following:

  • PROJECT: the name of the project that owns the node group.

  • ZONE: the zone of the node group.

  • VM_NAME: the name of the sole-tenant VM to create in a shared node group by using an affinity label.

  • MACHINE_TYPE: the machine type of the sole-tenant VM to create in a shared node group.

  • KEY: the affinity label. Set to "compute.googleapis.com/project".

  • OPERATOR: the affinity label operator. Set to "IN".

  • VALUE: the project containing the node group to provision the VM in. Specify one project by using either the project name or project ID.

For more information about how to configure node affinity, see Configure node affinity labels.

What's next