Provision Shared VPC

Shared VPC lets you export subnets from aVirtual Private Cloud (VPC) network in ahost project tootherservice projects inthe sameorganization.Instances in the service projects can have network connections in the sharedsubnets of the host project. This page describes how to set up and useShared VPC, including some necessary administrative preparation foryour organization.

Note: If you're getting started with Google Cloud, you can create an initialShared VPC network as part of theGoogle Cloud setup process.

Shared VPC supports exporting subnets of anystack type.

For information about detaching service projects or removing theShared VPC configuration completely, seeDeprovision Shared VPC.

Shared VPC is also referred to as "XPN" in the API andcommand-line interface.

Quotas, limits, and eligible resources

Before you begin, make sure that you are familiar withShared VPC andIAM, specifically:

Prepare your organization

Keep the following information in mind, when you prepare your organization.

Administrators and IAM

Preparing your organization, setting up Shared VPC host projects, andusing Shared VPC networks involves a minimum of three differentadministrative Identity and Access Management (IAM) roles. For more details about eachrole and information about optional ones, see theadministrators and IAMsection of the Shared VPC overview.

Important: The Network User and Network Admin roles are different. For details,see theNetwork and Security Admins sectionof the Shared VPC overview.

Organization policy constraints

Organization policy constraints can protect Shared VPC resources at theproject, folder, or organization level. The following sections describe eachpolicy.

Prevent accidental deletion of host projects

The accidental deletion of a host project would lead to outages in all serviceprojects attached to it. When a project is configured to be a Shared VPChost project, a special lock—called alien—is placed upon it. Aslong as the lien is present, it prevents the project from being deletedaccidentally. The lien is automatically removed from the host project when it isno longer configured for Shared VPC.

Caution: By default, a project owner can remove a lien from a project, includinga Shared VPC host project, unless an organization-level policy isdefined to limit lien removal. (Specifically, lien removal requires anIAM principal with theresourcemanager.projects.get andresourcemanager.projects.updateLiens permissions on the project.) The projectowner for the host project could remove the lien then delete theShared VPC project. To prevent this from happening, follow thedirections in this section.

A user with theorgpolicy.policyAdmin role can define an organization-levelpolicy constraint (constraints/compute.restrictXpnProjectLienRemoval) thatlimits the removal of liens to just the following roles:

  • Users withroles/owner orroles/resourcemanager.lienModifier at theorganization level
  • User with custom roles that include theresourcemanager.projects.getandresourcemanager.projects.updateLiens permissions at the organization level

This effectively prevents a project owner who does not have theroles/ownerrole at the organization level or theresourcemanager.lienModifier role atthe organization level from being able to accidentally delete aShared VPC host project. For more information about the permissionsassociated with theresourcemanager.lienModifier role, refer toPlacing alien on aproject inthe Resource Manager documentation.

Because an organization policy applies to all projects in the organization, youonly need to follow these steps once to restrict lien removal.

  1. Authenticate togcloud as an Organization Admin or IAMprincipal with theorgpolicy.policyAdmin role. ReplaceORG_ADMIN with the name of an Organization Admin:

    gcloud auth loginORG_ADMIN

  2. Determine your organization ID number by looking at the output of thiscommand.

    gcloud organizations list

  3. Enforce thecompute.restrictXpnProjectLienRemoval policy for yourorganization by running this command. ReplaceORG_ID withthe number you determined from the previous step.

    gcloud resource-manager org-policies enable-enforce \    --organizationORG_ID compute.restrictXpnProjectLienRemoval

  4. Log out ofgcloud if you are finished performing tasks as an OrganizationAdmin to protect your account.

    gcloud auth revokeORG_ADMIN

Constrain host project attachments

By default, a Shared VPC Admin can attach a non-host to any hostproject in the same organization. An organization policy administrator canlimit the set of hosts projects to which a non-host project or non-hostprojects in a folder or organization can be attached. For more information,see theconstraints/compute.restrictSharedVpcHostProjects constraint.

Constrain the subnets in the host project that a service project can use

By default, after you configure Shared VPC, IAMprincipals in service projects can use any subnet in the host project if theyhave theappropriate IAM permissions.In addition to managing individual user permissions, an organization policyadministrator can set a policy to define the set of subnets that can beaccessed by a particular project or by projects in a folder or organization.For more information, see theconstraints/compute.restrictSharedVpcSubnetworks constraint.

Prevent accidental shutdown of host projects

Disconnecting billing on a Shared VPC network can lead to a completeshutdown of all dependent resources including service projects. To prevent apossible occurrence of an accidental Shared VPC shutdown due toinactive or disabled billing,secure the link between the host project andits billing account.

Nominate Shared VPC Admins

An Organization Admin can grant one or more IAM principals theShared VPC AdminandProject IAM Admin roles.

The Project IAM Admin role grants Shared VPC Adminspermission to share all existing and future subnets, not just individualsubnets. This grant creates a binding at the organization or folder level, notthe project level. So the IAM principals must be defined in theorganization, not just a project therein.

Console

To grant the Shared VPC Admin role at the organization level

  1. Log into the Google Cloud console as an Organization Admin, then go to theIAM page.

    Go to the IAM page

  2. From the project menu, select your organization.

    If you select a project, theRoles menu shows incorrect entries.

  3. ClickAdd.

  4. Enter the email addresses of theNew principals.

  5. In theRoles menu, selectCompute Engine >Compute Shared VPC Admin.

    Note: If you don't see theCompute Shared VPC Admin role asan option, you might not be logged in to the Google Cloud console as anOrganization Admin, or you might have selected a project instead of thewhole organization.

  6. ClickAdd another role.

  7. In theRoles drop down, selectResource Manager >Project IAMAdmin.

  8. ClickSave.

To grant the Shared VPC Admin role at the folder level

  1. Log into the Google Cloud console as an Organization Admin, then go to theIAM page.

    Go to the IAM page

  2. From the project menu, select your folder.

    If you select a project or organization, the options you see areincorrect.

  3. ClickAdd.

  4. Enter the email addresses of theNew principals.

  5. UnderSelect a role, selectCompute Engine > Compute Shared VPC Admin.

  6. ClickAdd another role.

  7. In theRoles menu, selectResource Manager >Project IAM Admin.

  8. ClickAdd another role.

  9. In theRoles menu, selectResource Manager >Compute Network Viewer.

  10. ClickSave.

gcloud

  1. Authenticate togcloud as an Organization Admin. ReplaceORG_ADMIN with the name of an Organization Admin:

    gcloud auth loginORG_ADMIN

  2. Determine your organization ID number by looking at the output ofthis command.

    gcloud organizations list

  3. To assign the Shared VPC Admin role at theorganizationlevel, do the following:

    1. Apply Shared VPC Admin role to an existingIAM principal. ReplaceORG_ID with the organization ID number from theprevious step, andEMAIL_ADDRESS with the emailaddress of the user to whom you are granting the Shared VPCAdmin role.

      gcloud organizations add-iam-policy-bindingORG_ID \  --member='user:EMAIL_ADDRESS' \  --role="roles/compute.xpnAdmin"
      gcloud organizations add-iam-policy-bindingORG_ID \  --member='user:EMAIL_ADDRESS' \  --role="roles/resourcemanager.projectIamAdmin"

  4. To assign the Shared VPC Admin role at thefolder level, do the following:

    1. Determine your folder ID by looking at the output of this command.

      gcloud resource-manager folders list --organization=ORG_ID

    2. Apply Shared VPC Admin role to an existingIAM principal. ReplaceORG_IDwith the organization ID number from the previous step, andEMAIL_ADDRESS with the email address of theuser to whom you are granting the Shared VPC Admin role.

      gcloud resource-manager folders add-iam-policy-bindingFOLDER_ID \   --member='user:EMAIL_ADDRESS' \   --role="roles/compute.xpnAdmin"
      gcloud resource-manager folders add-iam-policy-bindingFOLDER_ID \   --member='user:EMAIL_ADDRESS' \   --role="roles/resourcemanager.projectIamAdmin"
      gcloud resource-manager folders add-iam-policy-bindingFOLDER_ID \   --member='user:EMAIL_ADDRESS' \   --role="roles/compute.networkViewer"

  5. Revoke your Organization Admin account token for in thegcloudcommand-line tool when you are finished performing tasks to protectyour account.

    gcloud auth revokeORG_ADMIN

API

  • To assign the Shared VPC Admin role at theorganizationlevel, use the following procedure:

    1. Determine your organization ID number.

      POST https://cloudresourcemanager.googleapis.com/v1/organizations

    2. Describe and then record the details of your existing organizationpolicy.

      POST https://cloudresourcemanager.googleapis.com/v1/organizations/ORG_ID:getIamPolicy

      ReplaceORG_ID with the ID of your organization.

    3. Assign the Shared VPC Admin role.

      POST https://cloudresourcemanager.googleapis.com/v1/organizations/ORG_ID:setIamPolicy{  "bindings": [    ...copy existing bindings    {      "members": [        "user:EMAIL_ADDRESS"      ],      "role": "roles/compute.xpnAdmin"    },    {      "members": [        "user:EMAIL_ADDRESS"      ],      "role": "roles/resourcemanager.projectIamAdmin"    }  ],  "etag": "ETAG",  "version": 1,  ...other existing policy details}

      Replace the following:

      • ORG_ID: the ID of the organization thatcontains the user who you're granting the Shared VPCAdmin role.
      • EMAIL_ADDRESS: the email address of the user.
      • ETAG: a unique identifier that you got whenyou described the existing policy. It prevents collisions ifmultiple updates requests are sent at the same time.

      For more information, see theorganizations.setIamPolicy method.

  • To assign the Shared VPC Admin role at thefolder level, usethe following request:

    1. Determine your organization ID number.

      POST https://cloudresourcemanager.googleapis.com/v1/organizations

    2. Find your folder ID.

      GET https://cloudresourcemanager.googleapis.com/v2/folders?parent=organizations/ORG_ID

      ReplaceORG_ID with the ID of your organization.

    3. Describe and then record the details of your existing folder policy.

      POST https://cloudresourcemanager.googleapis.com/v2/folders/FOLDER_ID:getIamPolicy

      ReplaceFOLDER_ID with the ID of your folder.

    4. Assign the Shared VPC Admin role.

      POST https://cloudresourcemanager.googleapis.com/v1/organizations/FOLDER_ID:setIamPolicy{  "bindings": [    ...copy existing bindings    {      "members": [        "user:EMAIL_ADDRESS"      ],      "role": "roles/compute.xpnAdmin"    },    {      "members": [        "user:EMAIL_ADDRESS"      ],      "role": "roles/resourcemanager.projectIamAdmin"    },    {      "members": [        "user:EMAIL_ADDRESS"      ],      "role": "roles/compute.networkViewer"    }  ],  "etag": "ETAG",  "version": 1,  ...other existing policy details}

      Replace the following:

      • FOLDER_ID: the ID of the organization thatcontains the user to whom you're granting the Shared VPCAdmin role.
      • EMAIL_ADDRESS: the email address of the user.
      • ETAG: a unique identifier that you got when youdescribed the existing policy. It prevents collisions if multipleupdates requests are sent at the same time.

      For more information, see thefolders.setIamPolicy method.

Set up Shared VPC

All tasks in this section must be performed by a Shared VPC Admin.

Enable a host project

Within an organization, Shared VPC Admins can designate projects asShared VPChost projects, subject toquotas and limits, by following this procedure.Shared VPC Admins can also create and delete projects if they have theProject Creator role and Project Deleter role(roles/resourcemanager.projectCreator androles/resourcemanager.projectDeleter)for your organization.

When you enable a host project, the project's network resources are notautomatically shared with service projects. You need toattachservice projects to the host project to share selectednetworks and subnets with the service projects.

Note: TheCompute Engine APImust be enabled for the project that becomes the Shared VPC host projectand for any service projects that will attach to it. For more information,see theCompute Engine API documentation.Caution: To prevent outages caused by accidental deletion or shutdown of ahost project, seePrevent accidental deletion of hostprojects andPrevent accidental shutdown of hostprojects.

Console

If you don't yet have theCompute Shared VPC Admin role (roles/compute.xpnAdmin), then youcannot view this page in the Google Cloud console.

  1. In the Google Cloud console, go to theShared VPC page.

    Go to Shared VPC

  2. Sign in as a Shared VPC Admin.

  3. Select the project you want to enable as a Shared VPC host project fromthe project picker.

  4. ClickSet up Shared VPC.

  5. On the next page, clickSave & continue underEnable host project.

  6. UnderSelect subnets, do one of the following:

    1. ClickShare all subnets (project-level permissions) if you needto share all current and future subnets in the VPC networks ofthe host project with service projects and Service Project Adminsspecified in the next steps.
    2. ClickIndividual subnets (subnet-level permissions) if you needto selectively share subnets from the VPC networks of thehost project with service projects and Service Project Admins. Then,selectSubnets to share.

  7. ClickContinue.
    The next screen is displayed.

  8. InProject names, specify the service projects to attach to thehost project. Note that attaching service projects does not define anyService Project Admins; that is done in the next step.

  9. In theSelect users by role section, add Service Project Admins.These users will be granted the IAM role ofcompute.networkUser for the shared subnets. Only Service ProjectAdmins can create resources in the subnets of the Shared VPChost project.

  10. ClickSave.

gcloud

Note: These steps designate a project as a Shared VPC host project.Unlike the Console directions, no serviceprojects are attached to the host project, and no Service Project Adminsare defined. After you complete these steps, you canattach serviceprojects.

  1. Authenticate togcloud as a Shared VPC Admin. ReplaceSHARED_VPC_ADMIN with the name of theShared VPC Admin:

    gcloud auth loginSHARED_VPC_ADMIN

  2. Enable Shared VPC for the project that you need to become a hostproject. ReplaceHOST_PROJECT_ID with the ID of theproject.

    gcloud compute shared-vpc enableHOST_PROJECT_ID

  3. Confirm that the project is listed as a host project for yourorganization. ReplaceORG_ID with your organization ID(determined bygcloud organizations list).

    gcloud compute shared-vpc organizations list-host-projectsORG_ID

  4. If you only needed to enable a host project, you can log out ofgcloud to protect your Shared VPC Admin account credentials.Otherwise, skip this step and continue with the steps toattach serviceprojects.

    gcloud auth revokeSHARED_VPC_ADMIN

API

  1. Enable Shared VPC for the project by using credentials withShared VPC Admin permissions.

    POST https://compute.googleapis.com/compute/v1/projects/HOST_PROJECT_ID/enableXpnHost

    ReplaceHOST_PROJECT_ID with the ID of the projectthat will be a Shared VPC host project.

    For more information, see theprojects.enableXpnHost method.

  2. Confirm that the project is listed as a host project.

    POST https://compute.googleapis.com/compute/v1/projects/HOST_PROJECT_ID/listXpnHosts

    ReplaceHOST_PROJECT_ID with the ID of theShared VPC host project.

    For more information, see theprojects.listXpnHosts method.

Terraform

You can use aTerraform resourceto enable a host project.

resource "google_compute_shared_vpc_host_project" "host" {  project = var.project # Replace this with your host project ID in quotes}

To learn how to apply or remove a Terraform configuration, seeBasic Terraform commands.

Attach service projects

A service project must attach to a host project before its Service ProjectAdmins can use the Shared VPC. A Shared VPC Admin must performthe following steps to complete the attachment.

A service project can only attach to one host project, but a host projectsupports multiple service project attachments. Refer tolimits specific to Shared VPCon the VPC quotas page for details.

Note: Before you can attach to a host project, you must enable theComputeEngine API for the serviceproject.

Console

Note: If you used the Console toenable a hostproject, you already attached one or more serviceprojects to it. The following directions detail how to modify theconfiguration of an existing host project.
  1. Log into the Google Cloud console as a Shared VPC Admin.
  2. In the Google Cloud console, go to theShared VPC page.
    Go to the Shared VPC page
  3. Click theAttached projects tab.
  4. Under theAttached projects tab, click theAttach projectsbutton.
  5. Check the boxes for the service projects to attach in theProjectnames section. Note that attaching service projects does not define anyService Project Admins; that is done in the next step.
  6. In theVPC network permissions section, select the roles whoseprincipals will get thecompute.networkUser role. IAMprincipals are granted the Network User role for the entire host project orcertain subnets in the host project, based on theVPC network sharingmode. These principals are known as Service Project Admins in theirrespective service projects.
  7. In theVPC network sharing mode section, select one of the following:
    1. ClickShare all subnets (project-level permissions) to share allcurrent and future subnets in VPC networks of the hostproject with all service projects and Service Project Admins.
    2. ClickIndividual subnets (subnet-level permissions) if you needto selectively share subnets from VPC networks of thehost project with service projects and Service Project Admins. Then,selectSubnets to share.
  8. ClickSave.

gcloud

Note: These steps only cover attaching a service project to a hostproject. You must first haveenabled a hostproject.

  1. If you have not already, authenticate togcloud as aShared VPC Admin. ReplaceSHARED_VPC_ADMINwith the name of the Shared VPC Admin:

    gcloud auth loginSHARED_VPC_ADMIN

  2. Attach a service project to a previously enabled host project. ReplaceSERVICE_PROJECT_ID with the project ID for the serviceproject andHOST_PROJECT_ID with the project ID forthe host project.

    gcloud compute shared-vpc associated-projects addSERVICE_PROJECT_ID \    --host-projectHOST_PROJECT_ID

  3. Confirm that the service project has been attached.

    gcloud compute shared-vpc get-host-projectSERVICE_PROJECT_ID

  4. Optionally, you can list the service projects that are attached to thehost project:

    gcloud compute shared-vpc list-associated-resourcesHOST_PROJECT_ID

  5. If you only needed to attach a service project, you can log out ofgcloud to protect your Shared VPC Admin account credentials.Otherwise, skip this step and define Service Project Adminsfor allsubnets orfor just somesubnets.

    gcloud auth revokeSHARED_VPC_ADMIN

API

Note: These steps only cover attaching a service project to a hostproject. You must first haveenabled a hostproject.

  1. Attach a service project to the Shared VPC host project.

    POST https://compute.googleapis.com/compute/v1/projects/HOST_PROJECT_ID/enableXpnResource{  "xpnResource": {    "id": "SERVICE_PROJECT"  }}

    Replace the following:

    • HOST_PROJECT_ID: the ID of theShared VPC host project.
    • SERVICE_PROJECT: the ID of the service projectto attach.

    For more information, see theprojects.enableXpnResource method.

  2. Confirm that the service projects are attached to the host project.

    GET https://compute.googleapis.com/compute/v1/projects/HOST_PROJECT_ID/getXpnResources

    Replace the following:

    • HOST_PROJECT_ID: the ID of theShared VPC host project.

    For more information, see theprojects.getXpnResources method.

Terraform

You can use aTerraformresourceto attach a service project.

resource "google_compute_shared_vpc_service_project" "service1" {  host_project    = google_compute_shared_vpc_host_project.host.project  service_project = var.service_project # Replace this with your service project ID in quotes}

To learn how to apply or remove a Terraform configuration, seeBasic Terraform commands.

Service Project Admins for all subnets

A Shared VPC Admin can assign an IAM principal from aservice project to be aService Project Admin with access to all subnets inthe host project. Service Project Admins of this type are granted the role ofcompute.networkUser forthe whole host project. This means that they haveaccess to all of the defined and future subnets in the host project.

A user who has thecompute.networkUser role in the hostproject can see all subnets within attached service projects.

Note: If you cannot create new resources in a particular subnet, an organizationpolicy might be constraining the subnets that this project can use. For moreinformation, seeconstraints/compute.restrictSharedVpcSubnetworks constraint.

Console

To define an IAM principal from a service project as ServiceProject Admin with access to all subnets in a host project using theGoogle Cloud console, see theattach service projects section.

gcloud

These steps cover defining an IAM principal from a serviceproject as a Service Project Admin with access to all subnets in a hostproject. Before you can perform these steps, you must haveenabled a host project andattached the service project to the host project.

  1. If you have not already, authenticate togcloud as aShared VPC Admin. ReplaceSHARED_VPC_ADMINwith the name of the Shared VPC Admin:

    gcloud auth loginSHARED_VPC_ADMIN

  2. Create a policy binding to make an IAM principal from theservice project a Service Project Admin. ReplaceHOST_PROJECT_ID with the project ID for the hostproject andSERVICE_PROJECT_ADMIN with the emailaddress of the Service Project Admin user.

    gcloud projects add-iam-policy-bindingHOST_PROJECT_ID \--member "user:SERVICE_PROJECT_ADMIN" \--role "roles/compute.networkUser"

    You can specify different types of principals bychanging the format of the--member argument:

    • Usegroup: to specify a Google group (by email address) as a principal.
    • Usedomain: to specify a Google domain as a principal.
    • UseserviceAccount: to specify a service account.Refer toService Accounts as Service Project Admins for moreinformation about this use case.

  3. Repeat the previous step for each additional Service Project Admin youneed to define.

  4. If you are finished defining Service Project Admins, you can log outofgcloud to protect your Shared VPC Admin accountcredentials.

    gcloud auth revokeSHARED_VPC_ADMIN

API

  1. Describe and then record the details of your existing project policy.You'll need the existing policy andetag value.

    POST https://cloudresourcemanager.googleapis.com/v2/projects/HOST_PROJECT_ID:getIamPolicy

    ReplaceHOST_PROJECT_ID with the ID of the Shared VPC host project.

  2. Create a policy binding to designate IAM principals inthe service project as Service Project Admins.

    POST https://cloudresourcemanager.googleapis.com/v1/projects/HOST_PROJECT_ID:setIamPolicy{  "bindings": [    ...copy existing bindings    {      "members": [PRINCIPAL,        ...additional principals      ],      "role": "roles/compute.networkUser"    },  ],  "etag": "ETAG",  "version": 1,  ...other existing policy details}

    Replace the following:

    • HOST_PROJECT_ID: the ID of the host project thatcontains the Shared VPC network.
    • PRINCIPAL: an identity thatthe role is associated with, such as a user, group, domain, orservice account. For more information, see themembersfield in the Resource Manager documentation.
    • ETAG: a unique identifier that you got when youdescribed the existing policy. It prevents collisions if multipleupdates requests are sent at the same time.

    For more information, see theprojects.setIamPolicy method.

Service Project Admins for some subnets

A Shared VPC Admin can assign an IAM principal from aservice project to be aService Project Admin with access to only some of thesubnets in the host project. This option provides a more granular means todefine Service Project Admins by granting them thecompute.networkUser rolefor only some subnets in the host project.

A user who has thecompute.networkUser role in the hostproject can see all subnets within attached service projects.

Console

To define an IAM principal from a service project as ServiceProject Admin with access to only some subnets in a host project using theGoogle Cloud console, see theattach service projectssection.

gcloud

These steps cover defining IAM principals from a serviceproject as Service Project Admins with access to only some subnets in ahost project. Before you can define them, you must haveenabled a host project andattached the service project to the host project.

  1. If you have not already, authenticate togcloud as aShared VPC Admin. ReplaceSHARED_VPC_ADMINwith the name of the Shared VPC Admin:

    gcloud auth loginSHARED_VPC_ADMIN

  2. Choose the subnet in the host project to which the Service ProjectAdmins should have access. Get its current IAM policy inJSON format. ReplaceSUBNET_NAME with the name ofthe subnet in the host project andHOST_PROJECT_IDwith the project ID for the host project.

    gcloud compute networks subnets get-iam-policySUBNET_NAME \    --regionSUBNET_REGION \    --projectHOST_PROJECT_ID \    --format json

  3. Copy the JSON output from the previous step and save it to a file. Forinstructional clarity, these steps save it to a file namedsubnet-policy.json.

  4. Modify thesubnet-policy.json file, adding the IAMprincipals who will become Service Project Admins with access to thesubnet. Replace eachSERVICE_PROJECT_ADMIN with theemail address of an IAM user from the service project.

    {  "bindings": [  {     "members": [           "user:[SERVICE_PROJECT_ADMIN]",           "user:[SERVICE_PROJECT_ADMIN]"        ],        "role": "roles/compute.networkUser"  }  ],  "etag": "[ETAG_STRING]"}

    Note that you can specify different types of IAMprincipals (other than users) inthe policy:

    • Switchuser: withgroup: to specify a Google group (by emailaddress) as a principal.
    • Switchuser: withdomain: to specify a Google domain as aprincipal.
    • UseserviceAccount: to specify a service account.Refer toService Accounts as Service ProjectAdmins for more information for this use case.

  5. Update the policy binding for the subnet using the contents of thesubnet-policy.json file.

    gcloud compute networks subnets set-iam-policySUBNET_NAME subnet-policy.json \    --regionSUBNET_REGION \    --projectHOST_PROJECT_ID

  6. If you are finished defining Service Project Admins, you can log outofgcloud to protect your Shared VPC Admin accountcredentials.

    gcloud auth revokeSHARED_VPC_ADMIN

API

  1. Describe and then record the details of your existing subnet policy.You'll need the existing policy andetag value.

    GET https://compute.googleapis.com/compute/v1/projects/HOST_PROJECT_ID/regions/SUBNET_REGION/subnetworks/SUBNET_NAME/getIamPolicy

    Replace the following:

    • HOST_PROJECT_ID: the ID of the host project thatcontains the Shared VPC network.
    • SUBNET_NAME: the name of the subnet to share.
    • SUBNET_REGION: the region in which the subnet islocated.

  2. Grant Service Project Admins access to subnets in the host project byupdating the subnet policy.

    POST https://compute.googleapis.com/compute/v1/projects/HOST_PROJECT_ID/regions/SUBNET_REGION/subnetworks/SUBNET_NAME/setIamPolicy{  "bindings": [    ...copy existing bindings    {      "members": [PRINCIPAL,        ...additional principals      ],      "role": "roles/compute.networkUser"    },  ],  "etag": "ETAG",  "version": 1,  ...other existing policy details}

    Replace the following:

    • ETAG: a unique identifier that you got when youdescribed the existing policy. It prevents collisions if multipleupdates requests are sent at the same time.
    • HOST_PROJECT_ID: the ID of the host project thatcontains the Shared VPC network.
    • PRINCIPAL: an identity thatthe role is associated with, such as a user, group, domain, orservice account. For more information, see themembersfield in the Resource Manager documentation.
    • SUBNET_NAME: the name of the subnet to share.
    • SUBNET_REGION: the region in which the subnet islocated.

    For more information, see thesubnetworks.setIamPolicy method.

Service Accounts as Service Project Admins

A Shared VPC Admin can also defineserviceaccounts from service projects as Service ProjectAdmins. This section illustrates how to definetwo different types of serviceaccounts as Service Project Admins:

The Service Project Admin role (compute.networkUser)can be granted forall subnets oronly some subnets of the host project. However, forinstructional simplicity, this section only illustrates how to define each ofthe two service account types as Service Project Admins forall subnets of the host project.

User-managed service accounts as Service Project Admins

These directions describe how to define a user-managed service account as aService Project Admin for all subnets of the Shared VPC host project.

Console

  1. Log into the Google Cloud console as a Shared VPC Admin.
  2. In the Google Cloud console, go to theSettings page.
    Go to the Settings page
  3. Change the project to the service project that contains the service accountthat needs to be defined as a Service Project Admin.
  4. Copy theProject ID of the service project. For instructionalclarity, this procedure refers to the service project ID asSERVICE_PROJECT_ID.
  5. Change the project to the Shared VPC host project.
  6. Go to the IAM page in the Google Cloud console.
    Go to the IAM page
  7. ClickAdd.
  8. AddSERVICE_ACCOUNT_NAME@SERVICE_PROJECT_ID.iam.gserviceaccount.comto thePrincipals field, replacingSERVICE_ACCOUNT_NAME with the name of the serviceaccount.
  9. SelectCompute Engine > Compute Network User from theRolesmenu.
  10. ClickAdd.

gcloud

  1. If you have not already, authenticate togcloud as aShared VPC Admin. ReplaceSHARED_VPC_ADMINwith the name of the Shared VPC Admin:

    gcloud auth loginSHARED_VPC_ADMIN

  2. If you don't know the project ID for the service project, you canlist all projects in your organization. This list shows the projectID for each.

    gcloud projects list

  3. Create a policy binding to make the service account a Service ProjectAdmin. ReplaceHOST_PROJECT_ID with the project IDfor the host project,SERVICE_ACCOUNT_NAME with thename of the service account, andSERVICE_PROJECT_IDwith the service project ID.

    gcloud projects add-iam-policy-bindingHOST_PROJECT_ID \    --member "serviceAccount:SERVICE_ACCOUNT_NAME@SERVICE_PROJECT_ID.iam.gserviceaccount.com" \    --role "roles/compute.networkUser"

API

  1. Describe and then record the details of your existing project policy.You'll need the existing policy andetag value.

    POST https://cloudresourcemanager.googleapis.com/v2/projects/HOST_PROJECT_ID:getIamPolicy

    ReplaceHOST_PROJECT_ID with the ID of theShared VPC host project.

  2. Create a policy binding to designate service accounts as Service ProjectAdmins.

    POST https://cloudresourcemanager.googleapis.com/v1/projects/HOST_PROJECT_ID:setIamPolicy{  "bindings": [    ...copy existing bindings    {      "members": [        "serviceAccount:SERVICE_ACCOUNT_NAME@SERVICE_PROJECT_ID.iam.gserviceaccount.com",        ...include additional service accounts      ],      "role": "roles/compute.networkUser"    },  ],  "etag": "ETAG",  "version": 1,  ...other existing policy details}

    Replace the following:

    • HOST_PROJECT_ID: the ID of the host project thatcontains the Shared VPC network.
    • SERVICE_ACCOUNT_NAME: the name of the serviceaccount.
    • SERVICE_PROJECT_ID: the ID of the serviceproject that contains the service account.
    • ETAG: a unique identifier that you got when youdescribed the existing policy. It prevents collisions if multipleupdates requests are sent at the same time.

    For more information, see theprojects.setIamPolicy method.

Google APIs service account as a Service Project Admin

These directions describe how to define theGoogle APIs serviceaccount as a Service Project Admin for all subnets of the Shared VPChost project. Making the Google APIs service account a Service ProjectAdmin is a requirement formanaged instancegroups used with Shared VPC becausetasks like instance creation are performed by this type of service account.For more information about this relationship, seeManaged Instance Groups andIAM.

Console

  1. Log into the Google Cloud console as a Shared VPC Admin.
  2. In the Google Cloud console, go to theSettings page.
    Go to the Settings page
  3. Change the project to the service project that contains the service accountthat needs to be defined as a Service Project Admin.
  4. Copy theProject number of the service project. For instructionalclarity, this procedure refers to the service project number asSERVICE_PROJECT_NUMBER.
  5. Change the project to the Shared VPC host project.
  6. Go to the IAM page in the Google Cloud console.
    Go to the IAM page
  7. ClickAdd.
  8. AddSERVICE_PROJECT_NUMBER@cloudservices.gserviceaccount.comto theMembers field.
  9. SelectCompute Engine > Compute Network User from theRolesmenu.
  10. ClickAdd.

gcloud

  1. If you have not already, authenticate togcloud as aShared VPC Admin. ReplaceSHARED_VPC_ADMINwith the name of the Shared VPC Admin:

    gcloud auth loginSHARED_VPC_ADMIN

  2. Determine theproject number for the service project. Forinstructional clarity, this procedure refers to the service projectnumber asSERVICE_PROJECT_NUMBER. ReplaceSERVICE_PROJECT_ID with the project ID for theservice project.

    gcloud projects describeSERVICE_PROJECT_ID --format='get(projectNumber)'

    • If you don't know the project ID for the service project, you can listall projects in your organization. This list shows the project numberfor each.

      gcloud projects list

  3. Create a policy binding to make the service account a Service ProjectAdmin. ReplaceHOST_PROJECT_ID with the project IDfor the host project andSERVICE_PROJECT_NUMBER withthe service project number.

    gcloud projects add-iam-policy-bindingHOST_PROJECT_ID \    --member "serviceAccount:SERVICE_PROJECT_NUMBER@cloudservices.gserviceaccount.com" \    --role "roles/compute.networkUser"

API

  1. Describe and then record the details of your existing project policy.You'll need the existing policy andetag value.

    POST https://cloudresourcemanager.googleapis.com/v2/projects/HOST_PROJECT_ID:getIamPolicy

    ReplaceHOST_PROJECT_ID with the ID of theShared VPC host project.

  2. List your project to find its project number.

    GET https://cloudresourcemanager.googleapis.com/v1/projects?filter=projectId="SERVICE_PROJECT_ID"

    ReplaceSERVICE_PROJECT_ID with the ID of theservice project where the service account is located.

  3. Create a policy binding to designate service accounts as Service ProjectAdmins.

    POST https://cloudresourcemanager.googleapis.com/v1/projects/HOST_PROJECT_ID:setIamPolicy{  "bindings": [    ...copy existing bindings    {      "members": [        "serviceAccount:SERVICE_PROJECT_NUMBER@cloudservices.gserviceaccount.com"      ],      "role": "roles/compute.networkUser"    },  ],  "etag": "ETAG",  "version": 1,  ...other existing policy details}

    Replace the following:

    • HOST_PROJECT_ID: the ID of the host project thatcontains the Shared VPC network.
    • SERVICE_PROJECT_NUMBER: the number of theservice project that contains the service account.
    • ETAG: a unique identifier that you got when youdescribed the existing policy. It prevents collisions if multipleupdates requests are sent at the same time.

    For more information, see theprojects.setIamPolicy method.

Use Shared VPC

After a Shared VPC Admin completes the tasks ofenabling a hostproject,attaching the necessary service projects toit, and defining Service Project Admins forall orsome of the host projectsubnets, the Service Project Admins can create instances, templates, andinternal load balancers in the service projects by using the subnets of the hostproject.

All tasks in this section must be performed by a Service Project Admin.

It's important to note that a Shared VPC Admin only grants the ServiceProject Admins theCompute Network User role(roles/compute.networkUser) to either the entire host project or only some ofits subnets. Service Project Admins should also have the other roles necessary toadminister their respective service projects. For example, a Service Project Admincould also be aproject owner or should atleast have theCompute Instance Admin role(roles/compute.instanceAdmin) for the project.

Caution: The Compute Network User role and theCompute Network Admin role(roles/compute.networkAdmin) have different permission sets. The ComputeNetwork User role includes permissions that are not available in theCompute Network Admin role. An IAM principal that has theCompute Network Admin role for an organization or project but lacks theCompute Network User role for the host project, or at least one of the subnetsin the host project, is not a Service Project Admin.

List available subnets

Service Project Admins can list the subnets to which they have been givenpermission by following these steps.

Console

In the Google Cloud console, go to theShared VPC page.

Go to Shared VPC

gcloud

  1. If you have not already, authenticate togcloud as a Service ProjectAdmin. ReplaceSERVICE_PROJECT_ADMIN with the nameof the Service Project Admin:

    gcloud auth loginSERVICE_PROJECT_ADMIN

  2. Run the following command, replacingHOST_PROJECT_IDwith the project ID of the Shared VPC host project:

    gcloud compute networks subnets list-usable --projectHOST_PROJECT_ID

    The following example lists the available subnets in theproject-1host project:

    $ gcloud compute networks subnets list-usable --project project-1PROJECT    REGION       NETWORK  SUBNET    RANGE          SECONDARY_RANGESproject-1  us-west1     net-1    subnet-1  10.138.0.0/20project-1  us-central1  net-1    subnet-2  10.128.0.0/20  r-1 192.168.2.0/24                                                          r-2 192.168.3.0/24project-1  us-east1     net-1    subnet-3  10.142.0.0/20

For more information, see thelist-usable commandin the SDK documentation.

API

List the available subnets in the host project. Make the request as aService Project Admin.

GET https://compute.googleapis.com/compute/v1/projects/HOST_PROJECT_ID/aggregated/subnetworks/listUsable

ReplaceHOST_PROJECT_ID with the ID of theShared VPC host project.

For more information, see thesubnetworks.listUsable method.

Reserve a static internal IPv4 or IPv6 address

Service Project Admins can reserve an internal IPv4 or IPv6 address in a subnet of aShared VPC network. The IP address configuration object iscreatedin the service project, while its value comes from the range ofavailable IPv4 addresses in the chosen shared subnet.

Important: A static internal IPv6 address that is reserved in a service projectcan be used only by resources within the same service project. Resources in thehost project can't use a static internal IPv6 address that is reserved in aservice project.

To reserve a standalone internal IP address in the service project,complete the following steps.

Console

  1. Set up Shared VPC.

  2. In the Google Cloud console, go to theShared VPC page.

    Go to Shared VPC

  3. Sign in as a Shared VPC Admin.

  4. Select the service project from the project picker.

  5. Go to theIP addresses page by selectingVPC network > IP addresses.

  6. ClickReserve internal static IP address.

  7. In theName field, enter an IP address name.

  8. In theIP version list, select the required IP version:

    • To reserve a static internal IPv4 address, selectIPv4.
    • To reserve a static internal IPv6 address, selectIPv6.

  9. Click theNetworks shared with me button.

  10. In theNetwork andSubnetwork lists, select a VPC network and a subnet respectively.

  11. Specify how you want to reserve the IP address:

    • For IPv4 addresses, to specify a static internal IPv4 address to reserve, inStatic IP address, selectLet me choose, and then enter acustom IP address. Otherwise, the system automatically assigns a static internalIPv4 address in the subnet for you.
    • For IPv6 addresses, the system automatically assigns a static internalIPv6 address from the subnet's internal IPv6 address range.

  12. Optional: If you want to share the static internal IPv4 address in different frontends, forPurpose, chooseShared. The default selection isNon-shared.

    Note: You can't share a static internal IPv6 address across multiple load balancer frontends.

  13. ClickReserve.

gcloud

  1. If you have not already, authenticate to the Google Cloud CLI as a Service ProjectAdmin. ReplaceSERVICE_PROJECT_ADMIN with the nameof the Service Project Admin:

    gcloud auth loginSERVICE_PROJECT_ADMIN

  2. Use thecompute addresses create command.

    • Reserve IPv4 addresses:

      gcloud compute addresses createIP_ADDR_NAME \    --projectSERVICE_PROJECT_ID \    --subnet projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET \    --region=REGION    --ip-version=IPV4

    • Reserve IPv6 addresses:

      gcloud compute addresses createIP_ADDR_NAME \    --projectSERVICE_PROJECT_ID \    --subnet projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET \    --region=REGION    --ip-version=IPV6

    Replace the following:

    • IP_ADDR_NAME: a name for the IPv4 address object.
    • SERVICE_PROJECT_ID: the ID of the serviceproject.
    • HOST_PROJECT_ID: the ID of theShared VPC host project.
    • REGION: the region that contains the shared subnet.
    • SUBNET: the name of the shared subnet.

Additional details for creating IP addresses are published in theSDK documentation.

API

Use theaddresses.insert method.

  • Reserve a static internal IPv4 address as a Service Project Admin:

    POST https://compute.googleapis.com/compute/v1/projects/SERVICE_PROJECT_ID/regions/REGION/addresses{"name": "ADDRESS_NAME","subnetwork": "projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME","addressType": "INTERNAL"}

Replace the following:

  • ADDRESS_NAME: a name for the reserved internal IPaddress.
  • HOST_PROJECT_ID: the ID of theShared VPC host project.
  • REGION: the region where the reserved IPv4 address willbe located and where the shared subnet is located.
  • SERVICE_PROJECT_ID: the ID of the service projectwhere you are reserving the IPv4 address.
  • SUBNET_NAME: the name of the shared subnet.

For more information, see theaddresses.insert method.

Terraform

You can use a Terraform data block to specify thehost subnetinformation.Then use aTerraform resourceto reserve a static internal IPv4 address. If you omit the optionaladdress argument, an available IPv4 address is selected and reserved.

Specify the host subnet:

data "google_compute_subnetwork" "subnet" {  name    = "my-subnet-123"  project = var.project  region  = "us-central1"}

Reserve an IPv4 address from the host project's subnet to use in the serviceproject:

resource "google_compute_address" "internal" {  project      = var.service_project  region       = "us-central1"  name         = "int-ip"  address_type = "INTERNAL"  address      = "10.0.0.8"  subnetwork   = data.google_compute_subnetwork.subnet.self_link}

To learn how to apply or remove a Terraform configuration, seeBasic Terraform commands.

Reserve a static external IPv4 address

A resource in a service project can use a regional static external IPv4 addressthat is defined in either the service project or the host project. Therefore,a resource in the attached service projects can use a regional staticexternal IPv4 address that is reservedin the host project.

Reserve a static external IPv6 address

Service Project Admins can reserve a static external IPv6 address in a serviceproject. The IPv6 address configuration object iscreatedin the service project, while its value comes from the range ofavailable IPv6 addresses in the chosen shared subnet.

Console

You can reserve a standalone external IPv6 address in the service project using theGoogle Cloud console:

  1. Set up Shared VPC.
  2. In the Google Cloud console, go to the Shared VPC page.
    Go to the Shared VPC page
  3. Sign in as a Shared VPC Admin.
  4. Select the service project from the project picker.
  5. To go to theIP addresses page, selectVPC network > IP addresses.
  6. ClickReserve external static IP address.
  7. Choose a name for the new address.
  8. Specify whether the network service tier isPremium orStandard. IPv6 static address reservation is supported only in the Premium tier.
  9. UnderIP version, selectIPv6.
  10. Specify whether this IP address isRegional orGlobal.
    • If you are reserving a static IP address for a global load balancer, chooseGlobal.
    • If you are reserving a static IP address for an instance or for a regional load balancer, chooseRegional, and then select the region to create the address in.
  11. Choose the following:
    • Networks in this project: choose this option if you want to reservean external IPv6 address in a subnet of the same Virtual Private Cloud (VPC)network where you are reserving the IPv6 address.
    • Networks shared with me: choose this option if you want to reservean external IPv6 address in a subnet of a Shared VPC network.

  12. Based on your choice, choose the following:

    • Network: the VPC network
    • Subnetwork: the subnet from which to assign the static regional IPv6 address
    • Endpoint type: chooseVM instance orNetwork Load Balancer

  13. Optional: If you have chosenVM instance as the endpoint type, then select a VM instance to attach the IPv6 address to.

  14. ClickReserve.

gcloud

  1. If you have not already, authenticate togcloud as a Service ProjectAdmin. ReplaceSERVICE_PROJECT_ADMIN with the nameof the Service Project Admin:

    gcloud auth loginSERVICE_PROJECT_ADMIN

  2. Use thegcloud compute addresses create command:

    gcloud compute addresses createIP_ADDR_NAME \    --projectSERVICE_PROJECT_ID \    --subnet projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET \    --region=REGION \    --ip-version=IPV6 \    --endpoint-type=[VM |NETLB]

    Replace the following:

    • IP_ADDR_NAME: a name for the IPv6 address object.
    • SERVICE_PROJECT_ID: the ID of the service project.
    • HOST_PROJECT_ID: the ID of theShared VPC host project.
    • SUBNET: the name of the shared subnet.
    • REGION: the region that contains the shared subnet.

API

To reserve a static internal IPv6 address as a Service Project Admin, use theaddresses.insert method:

POST https://compute.googleapis.com/compute/v1/projects/SERVICE_PROJECT_ID/regions/REGION/addresses{  "name": "ADDRESS_NAME",  "ipVersion": "IPV6",  "ipv6EndpointType": "VM|LB",  "networkTier": "PREMIUM",  "subnetwork": "projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME",  "addressType": "EXTERNAL"}

Replace the following:

  • SERVICE_PROJECT_ID: the ID of the service projectwhere you are reserving the IPv6 address.
  • REGION: the region where the reserved IPv6 address andthe shared subnet are located.
  • ADDRESS_NAME: a name for the reserved static external IPv6address.
  • HOST_PROJECT_ID: the ID of theShared VPC host project.
  • SUBNET_NAME: the name of the shared subnet.

Create an instance

Keep the following in mind when you use Shared VPCto create an instance:

  • The standard process forcreating aninstance involves selecting azone, a network, and a subnet. Both the selected subnet and the selected zonemust be in the same region. When a Service Project Admin creates an instanceby using a subnet from a Shared VPC network, the zone selected for thatinstance must be in the same region as the selected subnet.

    When you create an instance with a reserved static internal IPv4 address,the subnet and region are already selectedwhen the static IPv4 addressis created. Agcloud example for creating aninstance with a static internal IPv4 address is given in this section.

  • Service Project Admins can only create instances by using subnets to whichthey have been granted permission. To determine which subnets are available,seeList available subnets.

  • When Google Cloud receives a request to create an instance in a subnetof a Shared VPC network, it checks to see if the IAMprincipal making the request has permission to use that shared subnet. Ifthe check fails, the instance is not created, and Google Cloudreturns a permissions error. For assistance, contact the Shared VPCAdmin.

  • The stack type of the instance that you create must be supported by the sharedsubnetwork in which you create the instance. For more information, seeTypes of subnets. For instances with IPv6addresses, the IPv6 access typeof the subnet determines whether the IPv6 address assigned to the instance isan internal or external IPv6 address.

Console

  1. Set up Shared VPC.

  2. In the Google Cloud console, go to theShared VPC page.

    Go to Shared VPC

  3. Sign in as a Shared VPC Admin.

  4. Select the service project from the project picker.

  5. To go to theCreate an instance page, selectCompute Engine > VM instances >Create instance.

  6. Specify aName for the instance.

  7. ForRegion, select a region that contains a shared subnetwork.

  8. ClickNetworking underAdvanced options.

  9. UnderNetwork interfaces, click theNetworks shared with me radio button.

  10. In theShared subnetwork list, select the required subnet where youwant to create the instance:

    • For an IPv4-only instance, select an IPv4-only or dual-stack(IPv4 and IPv6) subnet.
    • For a dual-stack instance, select a dual-stack subnet with the requiredIPv6 access type.
    • For an IPv6-only instance, select a dual-stack subnet or an IPv6-onlysubnet with the required IPv6 access type.

  11. Select theIP stack type:

    • IPv4 (single-stack)
    • IPv4 and IPv6 (dual-stack)
    • IPv6 (single-stack)

  12. Specify any other necessary parameters for the instance.

  13. ClickCreate.

gcloud

See the following examples:

  • Create an instance with an ephemeral internal IPv4 address in a sharedsubnet of a Shared VPC network:

    gcloud compute instances createINSTANCE_NAME \    --projectSERVICE_PROJECT_ID \    --subnet projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET \    --zoneZONE

    Replace the following:

    • INSTANCE_NAME: the name of the instance.
    • SERVICE_PROJECT_ID: the ID of the serviceproject.
    • HOST_PROJECT_ID: the ID of theShared VPC host project.
    • REGION: the region that contains the shared subnet.
    • SUBNET: the name of the shared subnet.
    • ZONE: a zone in the specified region.

  • Create an instance with a reserved static internal IPv4 address in aShared VPC network:

    1. Reserve a static internal IPv4 address in theservice project from the range of available addresses of the host project.

    2. Create the instance:

      gcloud compute instances createINSTANCE_NAME \    --projectSERVICE_PROJECT_ID \    --private-network-ipIP_ADDR_NAME \    --zoneZONE \    --subnet projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET

      Replace the following:

      • INSTANCE_NAME: the name of the instance.
      • SERVICE_PROJECT_ID: the ID of the serviceproject.
      • IP_ADDR_NAME: the name of the static IPaddress.
      • ZONE: a zone in the same region asIP_ADDR_NAME.
      • HOST_PROJECT_ID: the ID of theShared VPC host project.
      • REGION: the region that contains the sharedsubnet.
      • SUBNET: the name of the shared subnetthat's associated with the static internal IPv4 address.

  • Create an instance with an ephemeral internal IPv4 address and anephemeral IPv6 address:

    gcloud compute instances createINSTANCE_NAME \    --projectSERVICE_PROJECT_ID \    --stack-type IPV4_IPV6 \    --subnet projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET \    --zoneZONE

    Replace the following:

    • INSTANCE_NAME: the name of the instance.
    • SERVICE_PROJECT_ID: the ID of the serviceproject.
    • HOST_PROJECT_ID: the ID of theShared VPC host project.
    • REGION: the region that contains the shared subnet.
    • SUBNET: the name of the shared subnet.
    • ZONE: a zone in the specified region.

  • Create an instance with a reserved static external IPv6 address:

    gcloud compute instances createINSTANCE_NAME \    --projectSERVICE_PROJECT_ID \    --stack-typeSTACK_TYPE \    --subnet projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET \    --ipv6-addressIPV6_ADDRESS \    --external-ipv6-prefix-length=96 \    --ipv6-network-tier PREMIUM \    --zoneZONE

    Replace the following:

    • INSTANCE_NAME: the name of the instance.
    • SERVICE_PROJECT_ID: the ID of the serviceproject.
    • STACK_TYPE:IPV4_IPV6 orIPV6_ONLY (Preview),depending on whether you want the instance to also have an IPv4address.
    • HOST_PROJECT_ID: the ID of theShared VPC host project.
    • REGION: the region that contains the shared subnet.
    • SUBNET: the name of the shared subnet.
    • IPV6_ADDRESS: the IPv6 address to assign to the VM.
    • ZONE: a zone in the specified region.

API

See the following examples:

  • To create an instance with an ephemeral internal IPv4 address, specifyonly the subnet:

    POST https://compute.googleapis.com/compute/v1/projects/SERVICE_PROJECT_ID/zones/ZONE/instances{  "machineType": "MACHINE_TYPE",  "name": "INSTANCE_NAME",  "networkInterfaces": [    {      "subnetwork": "projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME"    }  ],  "disks": [    {      "boot": true,      "initializeParams": {        "sourceImage": "SOURCE_IMAGE"      }    }  ]}

    Replace the following:

    • SERVICE_PROJECT_ID: the ID of the serviceproject.
    • ZONE: a zone in the specified region.
    • MACHINE_TYPE: a machine type for the instance.
    • INSTANCE_NAME: a name for the instance.
    • HOST_PROJECT_ID: the ID of theShared VPC host project.
    • REGION: the region that contains the shared subnet.
    • SUBNET: the name of the shared subnet.
    • SOURCE_IMAGE: an image for the instance.

    For more information, see theinstances.insert method.

  • To create an instance with a reserved internal IPv4 address, specify thesubnet and the name of the reserved IPv4 address:

    POST https://compute.googleapis.com/compute/v1/projects/SERVICE_PROJECT_ID/zones/ZONE/instances{  "machineType": "MACHINE_TYPE",  "name": "INSTANCE_NAME",  "networkInterfaces": [    {      "subnetwork": "projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME",      "networkIP": "projects/SERVICE_PROJECT_ID/regions/REGION/addresses/ADDRESS_NAME"    }  ],  "disks": [    {      "boot": true,      "initializeParams": {        "sourceImage": "SOURCE_IMAGE"      }    }  ]}

    Replace the following:

    • SERVICE_PROJECT_ID: the ID of the serviceproject.
    • ZONE: a zone in the specified region.
    • MACHINE_TYPE: a machine type for the instance.
    • INSTANCE_NAME: a name for the instance.
    • HOST_PROJECT_ID: the ID of theShared VPC host project.
    • REGION: the region that contains the shared subnet.
    • SUBNET_NAME: the name of the shared subnet.
    • ADDRESS_NAME: the name of the reserved internalIPv4 address.
    • SOURCE_IMAGE: an image for the instance.

    For more information, see theinstances.insert method.

  • To create an instance with an ephemeral internal IPv4 address and anephemeral IPv6 address, specify the subnet and the stack type:

    POST https://compute.googleapis.com/compute/v1/projects/SERVICE_PROJECT_ID/zones/ZONE/instances{  "machineType": "MACHINE_TYPE",  "name": "INSTANCE_NAME",  "networkInterfaces": [    {      "subnetwork": "projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME",      "stackType": "IPV4_IPV6"    }  ],  "disks": [    {      "boot": true,      "initializeParams": {        "sourceImage": "SOURCE_IMAGE"      }    }  ]}

    Replace the following:

    • SERVICE_PROJECT_ID: the ID of the serviceproject.
    • ZONE: a zone in the specified region.
    • MACHINE_TYPE: a machine type for the instance.
    • INSTANCE_NAME: a name for the instance.
    • HOST_PROJECT_ID: the ID of theShared VPC host project.
    • REGION: the region that contains the shared subnet.
    • SUBNET: the name of the shared subnet.
    • SOURCE_IMAGE: an image for the instance.

    For more information, see theinstances.insert method.

  • To create an instance with an ephemeral IPv6 address, specify the subnetand the stack type:

    POST https://compute.googleapis.com/compute/v1/projects/SERVICE_PROJECT_ID/zones/ZONE/instances{  "machineType": "MACHINE_TYPE",  "name": "INSTANCE_NAME",  "networkInterfaces": [    {      "subnetwork": "projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME",      "stackType": "IPV6_ONLY"    }  ],  "disks": [    {      "boot": true,      "initializeParams": {        "sourceImage": "SOURCE_IMAGE"      }    }  ]}

    Replace the following:

    • SERVICE_PROJECT_ID: the ID of the serviceproject.
    • ZONE: a zone in the specified region.
    • MACHINE_TYPE: a machine type for the instance.
    • INSTANCE_NAME: a name for the instance.
    • HOST_PROJECT_ID: the ID of theShared VPC host project.
    • REGION: the region that contains the shared subnet.
    • SUBNET: the name of the shared subnet.
    • SOURCE_IMAGE: an image for the instance.

    For more information, see theinstances.insert method.

Terraform

You can use a Terraform data block to specify thehost subnetinformation. Then use aTerraform resource to create a VM instance in a service project.

Specify the host subnet:

data "google_compute_subnetwork" "subnet" {  name    = "my-subnet-123"  project = var.project  region  = "us-central1"}

Create a VM instance in a service project with an ephemeral IPv4 address fromthe host project's shared subnet:

resource "google_compute_instance" "ephemeral_ip" {  project      = var.service_project  zone         = "us-central1-a"  name         = "my-vm"  machine_type = "e2-medium"  boot_disk {    initialize_params {      image = "debian-cloud/debian-9"    }  }  network_interface {    subnetwork = data.google_compute_subnetwork.subnet.self_link  }}

Create a VM instance in a service project with areserved static IPv4 address from the host project's shared subnet:

resource "google_compute_instance" "reserved_ip" {  project      = var.service_project  zone         = "us-central1-a"  name         = "reserved-ip-instance"  machine_type = "e2-medium"  boot_disk {    initialize_params {      image = "debian-cloud/debian-9"    }  }  network_interface {    subnetwork = data.google_compute_subnetwork.subnet.self_link    network_ip = google_compute_address.internal.address  }}

To learn how to apply or remove a Terraform configuration, seeBasic Terraform commands.

Create an instance template

Note: Connecting to aShared VPC network by using interfaces other thannic0 is supported for the followingconfigurations:

  • Instance templates: supported in the gcloud CLI and the API.
  • Managed instance groups: supported in the gcloud CLI and the API.

    • Keep the following in mind when you use Shared VPC to createan instance template:

    • The process forcreating an instancetemplate involvesselecting a network and a subnet.

      • Templates created for use in a custom mode Shared VPC network mustspecify both the network and a subnet.

      • Templates created for use in anauto modeShared VPC network may optionally defer selecting a subnet. Inthese cases, a subnet is automatically selected in the same region asany managed instance group that uses the template. (Auto mode networkshave a subnet in every region by definition.)

    • When an IAM principal creates an instance template,Google Cloud does not perform a permissions check to see if theprincipal can use the specified subnet. This permissions check is alwaysdeferred to when a managed instance group that uses the template is requested.

    • The stack type of the instance template that you create must be supported bythe shared subnetwork in which you create the instance template. For moreinformation, seeTypes of subnets. For instanceswith IPv6 addresses, the IPv6 access type of the subnet determines whether theIPv6 address assigned to the instance is an internal or external IPv6 address.

    Console

    1. Set up Shared VPC.
    2. In the Google Cloud console, go to the Shared VPC page.
      Go to the Shared VPC page
    3. Sign in as a Shared VPC Admin.
    4. Select the service project from the project picker.
    5. To go to theCreate an instance template page, selectCompute Engine > Instance templates >Create instance templates.
    6. Specify aName for the instance template.
    7. In theAdvanced options section, clickNetworking.
    8. In theNetwork interfaces section, click theNetworks shared with me radio button.
    9. In theShared subnetwork list, select the required subnet where youwant to create the instance template:
      • For an IPv4-only instance template, select an IPv4-only or dual-stack(IPv4 and IPv6) subnet.
      • For a dual-stack instance template, select a dual-stack subnet withthe required IPv6 access type.
      • For an IPv6-only instance template,select a dual-stack subnet or an IPv6-only subnetwith the required IPv6 access type.
    10. Select theIP stack type of the instance template:
      • IPv4 (single-stack)
      • IPv4 and IPv6 (dual-stack)
      • IPv6 (single-stack)
    11. Specify any other necessary parameters for the instance template.
    12. ClickCreate.

    gcloud

    • Create an IPv4-only instance template for use in anyautomatically created subnet of an auto mode Shared VPC network:

      gcloud compute instance-templates createTEMPLATE_NAME \    --projectSERVICE_PROJECT_ID \    --network projects/HOST_PROJECT_ID/global/networks/NETWORK

      Replace the following:

      • TEMPLATE_NAME: the name of the template.
      • SERVICE_PROJECT_ID: the ID of the serviceproject.
      • HOST_PROJECT_ID: the ID of theShared VPC host project.
      • NETWORK: the name of the Shared VPCnetwork.

    • To create an IPv4-only instance template for a manually created subnet ina Shared VPC network (either auto or custom mode):

      gcloud compute instance-templates createTEMPLATE_NAME \    --projectSERVICE_PROJECT_ID \    --regionREGION \    --subnet projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET

      Replace the following:

      • TEMPLATE_NAME: the name of the template.
      • SERVICE_PROJECT_ID: the ID of the serviceproject.
      • REGION: the region that contains the shared subnet.
      • HOST_PROJECT_ID: the ID of theShared VPC host project.
      • SUBNET: the name of the shared subnet.

    • Create a dual-stack instance template that uses a subnet in acustom mode Shared VPC network:

      gcloud compute instance-templates createTEMPLATE_NAME \    --projectSERVICE_PROJECT_ID \    --stack-type IPV4_IPV6 \    --regionREGION \    --subnet projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET

      Replace the following:

      • TEMPLATE_NAME: the name of the template.
      • SERVICE_PROJECT_ID: the ID of the serviceproject.
      • REGION: the region that contains the shared subnet.
      • HOST_PROJECT_ID: the ID of theShared VPC host project.
      • SUBNET: the name of the shared subnet.

    • Create a IPv6-only instance templatethat uses a subnet in a custom mode Shared VPC network:

      gcloud compute instance-templates createTEMPLATE_NAME \    --projectSERVICE_PROJECT_ID \    --stack-type IPV6_ONLY \    --regionREGION \    --subnet projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET

      Replace the following:

      • TEMPLATE_NAME: the name of the template.
      • SERVICE_PROJECT_ID: the ID of the serviceproject.
      • REGION: the region that contains the shared subnet.
      • HOST_PROJECT_ID: the ID of theShared VPC host project.
      • SUBNET: the name of the shared subnet.

    API

    • To create an IPv4-only instance template that uses anyautomatically created subnet of an auto mode Shared VPC network,specify the VPC network:

      POST https://compute.googleapis.com/compute/v1/projects/SERVICE_PROJECT_ID/global/instanceTemplates{"properties": {  "networkInterfaces": [    {      "network": "projects/HOST_PROJECT_ID/global/networks/NETWORK"    }  ]...}

      Replace the following:

      • SERVICE_PROJECT_ID: the ID of the serviceproject.
      • HOST_PROJECT_ID: the ID of the project thatcontains the Shared VPC network.
      • NETWORK: the name of the Shared VPCnetwork.

      For more information, see theinstanceTemplates.insert method.

    • To create an IPv4-only instance template that uses a manually createdsubnet in a Shared VPC network (auto or custom mode), specify thesubnet:

      POST https://compute.googleapis.com/compute/v1/projects/SERVICE_PROJECT_ID/global/instanceTemplates{"properties": {  "networkInterfaces": [    {      "subnetwork": "projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME"    }  ]...}

      Replace the following:

      • SERVICE_PROJECT_ID: the ID of the serviceproject.
      • HOST_PROJECT_ID: the ID of the project thatcontains the Shared VPC network.
      • REGION: the region that contains the shared subnet.
      • SUBNET_NAME: the name of the shared subnet.

      For more information, see theinstanceTemplates.insert method.

    • To create a dual-stack instance template that uses a subnet in a custommode Shared VPC network, specify the subnet and the stack type:

      POST https://compute.googleapis.com/compute/v1/projects/SERVICE_PROJECT_ID/global/instanceTemplates{"properties": {  "networkInterfaces": [    {      "subnetwork": "projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME",      "stackType": "IPV4_IPV6"    }  ]...}

      Replace the following:

      • SERVICE_PROJECT_ID: the ID of the serviceproject.
      • HOST_PROJECT_ID: the ID of the project thatcontains the Shared VPC network.
      • REGION: the region that contains the shared subnet.
      • SUBNET_NAME: the name of the shared subnet.

      For more information, see theinstanceTemplates.insert method.

    • To create an IPv6-only instance templatethat uses a subnet in a custom mode Shared VPC network, specifythe subnet and the stack type:

      POST https://compute.googleapis.com/compute/v1/projects/SERVICE_PROJECT_ID/global/instanceTemplates{"properties": {  "networkInterfaces": [    {      "subnetwork": "projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME",      "stackType": "IPV6_ONLY"    }  ]...}

      Replace the following:

      • SERVICE_PROJECT_ID: the ID of the serviceproject.
      • HOST_PROJECT_ID: the ID of the project thatcontains the Shared VPC network.
      • REGION: the region that contains the shared subnet.
      • SUBNET_NAME: the name of the shared subnet.

      For more information, see theinstanceTemplates.insert method.

    Terraform

    You can use a Terraform data block to specify thehost subnetinformation. Then use aTerraform resourceto create a VM instance template. The IPv4 addresses for the VMs come fromthe host project's shared subnet.

    The subnet must exist in the same region where the VM instances will becreated.

    Specify the host subnet:

    data "google_compute_subnetwork" "subnet" {  name    = "my-subnet-123"  project = var.project  region  = "us-central1"}

    Create a VM instance template in the service project:

    resource "google_compute_instance_template" "default" {  project      = var.service_project  name         = "appserver-template"  description  = "This template is used to create app server instances."  machine_type = "n1-standard-1"  disk {    source_image = "debian-cloud/debian-9"  }  network_interface {    subnetwork = data.google_compute_subnetwork.subnet.self_link  }}

    To learn how to apply or remove a Terraform configuration, seeBasic Terraform commands.

    Create a managed instance group

    Note: Connecting to a Shared VPC network using interfaces other thannic0 is supported for the following configurations:

    • Instance templates: supported in the gcloud CLI and the API.
    • Managed instance groups: supported in the gcloud CLI and the API.

    Keep the following in mind when creating a managed instance group usingShared VPC:

    • Managed instance groups used with Shared VPC requiremaking the Google APIs service account a Service Project Adminbecause tasks like automatic instance creation using autoscaling are performedby that service account.

    • The standard process forcreating a managed instancegroupinvolves selecting a zone or region, depending on the group type, and aninstance template. (Network and subnet details aretied to the instancetemplate.) Eligibleinstance templates are restricted to those that reference subnets in the sameregion used by the managed instance group.

    • Service Project Admins can only create managed instance groups whose memberinstances use subnets to which they have been granted permission. Because thenetwork and subnet details are tied to the instance template, Service ProjectAdmins can only use templates that reference subnets that they are authorizedto use.

    • When Google Cloud receives a request to create a managed instancegroup, it checks to see if the IAM principal making therequest has permission to use the subnet (in the same region as the group)specified in the instance template. If the check fails, the managed instancegroup is not created, and Google Cloud returns an error:Required'compute.subnetworks.use' permission for'projects/SUBNET_NAME.

      List available subnets to determinewhich ones can be used, and contact the Shared VPC Admin if theservice account needs additional access. For more information, seeServiceAccounts as Service Project Admins.

    For more information, refer toCreating Groups of ManagedInstancesin the Compute Engine documentation.

    Create an HTTP(S) load balancer

    There are many ways to configure external Application Load Balancers within aShared VPC network. Regardless of the type of deployment, all thecomponents of the load balancer must be in the same organization and the sameShared VPC network.

    To learn more about supported Shared VPC architectures, see thefollowing:

    Create an internal passthrough Network Load Balancer

    The following example illustrates what you must consider when creating aninternal passthrough Network Load Balancer in a Shared VPC network. Service ProjectAdmins can create an internal passthrough Network Load Balancer that uses a subnet (in thehost project) to which they have access. The load balancer'sinternal forwarding rule isdefined in the service project, but itssubnet referencepoints to a subnet in a Shared VPC network of the host project.

    Before you create an internal passthrough Network Load Balancer in a Shared VPC environment, see theShared VPC architecture.

    Console

    1. Go to the Load balancing page in the Google Cloud console.
      Go to the Load balancing page

    2. Create your internal TCP/UDP load balancer, making the followingadjustment: In theConfigure frontend services section, select theShared VPC subnet you need from theNetworks shared by otherprojects section of theSubnet menu.

    3. Finish creating the load balancer.

    gcloud

    When you create the internal forwarding rule, specify a subnet in the hostproject with the--subnet flag:

    gcloud compute forwarding-rules createFR_NAME \    --projectSERVICE_PROJECT_ID \    --load-balancing-scheme internal \    --regionREGION \    --ip-protocolIP_PROTOCOL \    --ports PORT,PORT,... \    --backend-serviceBACKEND_SERVICE_NAME \    --subnet projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET \    --addressINTERNAL_IP

    Replace the following:

    • FR_NAME: the name of the forwarding rule.
    • SERVICE_PROJECT_ID: the ID of the service project.
    • REGION: the region that contains the shared subnet.
    • IP_PROTOCOL: eitherTCP orUDP, matching the protocol of the load balancer's backend service.
    • PORT: the numeric port or list of ports for the load balancer.
    • BACKEND_SERVICE_NAME: the name of the backend service (created already as part of the general procedure forcreating an internal passthrough Network Load Balancer).
    • HOST_PROJECT_ID: the ID of the Shared VPC host project.
    • SUBNET: the name of the shared subnet.
    • INTERNAL_IP: an internal IP address in the shared subnet (if unspecified, an available one will be selected).

    For more options, see thegcloud compute forwarding-rules create command.

    API

    Create the internal forwarding rule and specify a subnet in the hostproject.

    POST https://compute.googleapis.com/compute/v1/projects/SERVICE_PROJECT_ID/regions/REGION/forwardingRules{  "name": "FR_NAME",  "IPAddress": "IP_ADDRESS",  "IPProtocol": "IP_PROTOCOL",  "ports": [ "PORT", ... ],  "loadBalancingScheme": "INTERNAL",  "subnetwork": "https://www.googleapis.com/compute/v1/projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET",  "network": "https://www.googleapis.com/compute/v1/projects/HOST_PROJECT_ID/global/networks/NETWORK_NAME",  "backendService": "https://www.googleapis.com/compute/v1/projects/SERVICE_PROJECT_ID/regions/us-west1/backendServices/BE_NAME",  "networkTier": "PREMIUM"}

    Replace the following:

    • SERVICE_PROJECT_ID: the ID of the service project.
    • REGION: the region that contains the shared subnet.
    • FR_NAME: a name for the forwarding rule.
    • IP_ADDRESS: an internal IP address in the sharedsubnet.
    • IP_PROTOCOL: eitherTCP orUDP, matching theprotocol of the load balancer's backend service.
    • PORT: the numeric port or list of ports for the loadbalancer.
    • HOST_PROJECT_ID: the ID of the Shared VPChost project.
    • SUBNET: the name of the shared subnet.
    • NETWORK_NAME: the name of the network.
    • BE_NAME: the name of the backend service (createdalready as part of the general procedure forcreating an internal passthrough Network Load Balancer).

    For more information, see theforwardingRules.insert method.

    Terraform

    You can use a Terraform data block to specify thehost subnet andhost network. Then use aTerraform resource to create the forwarding rule.

    Specify the host network:

    data "google_compute_network" "network" {  name    = "my-network-123"  project = var.project}

    Specify the host subnet:

    data "google_compute_subnetwork" "subnet" {  name    = "my-subnet-123"  project = var.project  region  = "us-central1"}

    In the service project, create a forwarding rule in the host project'snetwork and subnet:

    resource "google_compute_forwarding_rule" "default" {  project               = var.service_project  name                  = "l4-ilb-forwarding-rule"  backend_service       = google_compute_region_backend_service.default.id  region                = "europe-west1"  ip_protocol           = "TCP"  load_balancing_scheme = "INTERNAL"  all_ports             = true  allow_global_access   = true  network               = data.google_compute_network.network.self_link  subnetwork            = data.google_compute_subnetwork.subnet.self_link}

    To learn how to apply or remove a Terraform configuration, seeBasic Terraform commands.

    What's next

    Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

    Last updated 2025-12-17 UTC.