Provisioning Shared VPC

This page describes how to provision shared VPC networks for your projects. Shared VPC allows you to share VPC networks across different projects that belong to the same Cloud Organization. You provision a shared VPC host project that owns the network you want to share, and then associate service projects that will use the network.

To learn more about Shared VPC, read Shared VPC Overview.

Shared VPC limitations

  • Quota of 100 shared VPC host projects per Cloud Organization.
  • Quota of 100 service projects attached to any given shared VPC host project.
  • External load balancing is not supported across projects. This means that the frontend of a load balancer must exist in the same project as the backends, but the backend instances in service projects can be created in the shared VPC network of the host project.
  • GKE clusters in a service project associated with an shared VPC network are not supported.
  • GAE Flexible in a service project associated with an shared VPC network is not supported.
  • Deployment manager is limited to manage resources within a single project.

Permissions

To provision shared VPC, specific administrators must configure shared VPC at the respective levels:

  • An Organization admin is the ultimate administrator of the root of the hierarchy where projects live (the Cloud Organization node). An Organization admin nominates a shared VPC admin.
  • A shared VPC admin is responsible for choosing the project that will host the shared resources and the service projects in the Organization that can use the host project. The shared VPC admin also determines which users in the service project are given compute.networkUser for the shared subnets. Users need this permission to create instances or other resources in the shared subnet.
  • A Service project admin is an administrator in a service project that uses the VPC shared network.
Shared VPC provisioning steps (click to enlarge)
Shared VPC provisioning steps (click to enlarge)

Protecting a shared VPC host project against deletion

The steps in this section must be completed by the Organization policy admin. These steps only need to be done once. The Organization policy applies to existing and future shared VPC host projects.

In order to safeguard against outages from accidental project deletion, a lien is automatically placed on any project that is enabled as a shared VPC host project. A lien is basically a lock that prevents project deletion unless a project owner first removes the lien. The lien is automatically removed when the project is disabled as a host project.

However, by default, this lien can be removed by the host project owner unless an organization-level policy is created to prevent it. You should create such a policy to ensure an additional level of insurance against outage.

The following script sets an organization policy so that only Organization owners or users with the organization-level resourcemanager.lienModifier role can delete the shared VPC host project lien and project owners without these permissions cannot remove the lien..

You must have the roles/orgpolicy.policyAdmin role for your Organization.

  1. Determine your Organization ID.

    gcloud organizations list
    

  2. Enforce the compute.restrictXpnProjectLienRemoval policy for your Organization.

    gcloud alpha resource-manager org-policies enable-enforce \
        --organization [ORG_ID] compute.restrictXpnProjectLienRemoval
    

Nominating shared VPC admins for the Organization

The Organization admin nominates one or more shared VPC admins for the Organization. The shared VPC admin role is granted by the Organization admin using a binding at the organization level. You cannot bind the shared VPC admin role to a project.

Then, the shared VPC admin(s) are responsible for designating the shared VPC host project(s) on behalf of the organization. More than one shared VPC host project can exist per organization, but each service project can only be associated to a single host project.

Refer to the IAM documentation for more information.

Console

  1. Go to the IAM page in the Google Cloud Platform Console.
    Go to the IAM page
  2. From the project pull-down menu, select your Org. If you select a project instead of the Org, you will not see the correct entries in the Roles menu.
  3. Click Add.
  4. Enter the email addresses of the Members.
  5. Under Roles, select Compute Engine > Compute Shared VPC Admin.
  6. Click Add.

gcloud

  1. Find your Organization ID.

    gcloud organizations list
    

  2. Apply shared VPC admin role to a member.

    gcloud organizations add-iam-policy-binding [ORG_ID] \
        --member 'user:[EMAIL_ADDRESS]' \
        --role "roles/compute.xpnAdmin"
    

Enabling a shared VPC host project

The shared VPC admin must run this command.

The nominated shared VPC admin either creates a new shared VPC host project or selects an already created project of which they are already an owner.

Console

  1. If you have not done so already, enable the Compute Engine API for the project.
  2. Select the project you want to make a host project from the project picker.
  3. Go to the Shared VPC page in the Google Cloud Platform Console.
    Go to the Shared VPC page
  4. Click Set up XPN.
  5. On the next page, click Save & continue under Enable host project.
  6. Under Select subnets, do one of the following:
    1. Click Share all subnets (project-level permissions) if you want to give designated users permissions for all subnets in the project, even ones created in the future.
    2. Click Individual subnets (subnet-level permissions) to if you want to give designated users permissions to subnets on a case-by-case basis. Then, select Subnets to share.
  7. Click Continue.
  8. On the next screen, select the Project names of the service projects you want to share the hosts subnets with. Note that adding a service project give that project access to all subnets in the host project, but it does not give the project's users access.
  9. Under Select users by role, select which user roles in the service projects will be given the compute.networkUser permission for the shared subnets. Only users with the compute.networkUser permission can create resources in the shared subnets.
  10. Click Save.

gcloud

  1. Enable a project as the shared VPC host project that will share VPC networking resources. The Compute Engine API must be enabled for the project.

    gcloud compute shared-vpc enable [HOST_PROJECT_ID]
    

  2. Confirm that the project is enabled.

    gcloud compute shared-vpc organizations list-host-projects [ORG_ID]
    

When a project is enabled as a host project, this project is automatically marked as being important and not easily deleted. GCP automatically creates a "lien," or lock, on projects designated as shared VPC host projects. This prevents the project from being deleted while it is still a host project. However, the host project owner can still delete the lien and delete the project.

If a project is disabled as a host project, then GCP removes the lien automatically. The lien protects against deleting the host project while it is a host project.

We strongly recommend that the Organization admin sets up an Org policy such that removing the lien requires Org admin permissions.

Creating shared VPC networks and associating service projects

The shared VPC Admin can either create new VPC networking resources in the host project or share VPC networking resources that already exist. VPC networking resources include the VPC networks/subnets to be shared and the associated routes, firewall rules, and VPNs. You can create VPC networking resources via existing VPC networking operations.

Console

If you completed all of the steps in the Console instructions for Enabling a shared VPC host project, then this step is done already. Use this procedure if you want to link other service projects.

  1. Go to the Shared VPC network page in the Google Cloud Platform Console.
    Go to the Shared VPC network page
  2. Click the Attached projects tab.
  3. Under the Attached projects tab, click the Attach projects button.
  4. Under Project name, check the checkboxes next to the projects you wish to add as service projects. Note that adding a service project give that project access to all subnets in the host project, but it does not give the project's users access.
  5. Under VPC network permissions, select which user roles in the service projects will be given the compute.networkUser permission for the shared subnets. Only users with the compute.networkUser permission can create resources in the shared subnets.
  6. Under VPC network sharing mode, do one of the following:
    1. Click Share all subnets (project-level permissions) if you want to give designated users of the service project permissions for all subnets in the project, even ones created in the future.
    2. Click Individual subnets (subnet-level permissions) to if you want to give designated users of the service project permissions to subnets on a case-by-case basis. Then, select the subnets under VPC networks to share.
  7. Click Save.

gcloud

  1. Make project [SERVICE_PROJECT_ID] a service project of host project [HOST_PROJECT_ID]. Note that the Compute Engine API must be enabled for the projects.

    gcloud compute shared-vpc associated-projects add [SERVICE_PROJECT_ID] \
        --host-project [HOST_PROJECT_ID]
    

  2. Confirm that the service project has been associated with the host project.

    gcloud compute shared-vpc get-host-project [SERVICE_PROJECT_ID]]
    

  3. (Optional) View the service projects associated with the host project.

    gcloud compute shared-vpc list-associated-resources [HOST_PROJECT_ID]
    

Use IAM to give specific accounts permission to create instances and other resources in the shared VPC networks.

Applying the compute.networkUser role at host project level

This command provide users of the service project with permission to use all the existing and future subnets in a host project. This is done by providing all the required users/principals with the NetworkUser role at the host project level.

Console

If you completed all of the steps in the Console instructions for Enabling a shared VPC host project or Creating shared VPC networks and associating service projects, then this step is done already for the Compute Instance Admins, Compute Network Admins, Owners, and Editors Service project roles.

gcloud

gcloud projects add-iam-policy-binding [HOST_PROJECT_ID] \
--member "group:email_group1@gmail.com" \
--role "roles/compute.networkUser"

If there are service accounts in the service projects that require NetworkUser permission in the host project, for example, service accounts to create instances in a Managed Instance Group associated to a shared VPC network, you will need to repeat the command above for the service account.

For more information about how Managed Instance Group with service accounts work with shared VPC, please refer to Managed Instance Groups with service accounts in shared VPC.

Applying the compute.networkUser role at subnet level

Provide users with permission to use specific subnets in a host project. This is done by providing all the required users/principals with NetworkUser role for specific subnets.

Console

If you completed all of the steps in the Console instructions for Enabling a shared VPC host project or Creating shared VPC networks and associating service projects, then this step is done already the Compute Instance Admins, Compute Network Admins, Owners, and Editors Service project roles.

gcloud

  1. Get the current JSON permissions file:

    gcloud beta compute networks subnets get-iam-policy [SUBNET_NAME] \
        --project [HOST_PROJECT_ID] \
        --format json
    

  2. Save it to a file called my-subnet-policy.json.

  3. Add the following binding:

    {
      "bindings": [
      {
         "members": [
               "group:email_group1@gmail.com"
            ],
            "role": "roles/compute.networkUser"
      }
      ],
      "etag": "[ETAG_STRING]"
    }
    

  4. Use the updated file to set the new policy.

    gcloud beta compute networks subnets set-iam-policy [SUBNET_NAME] my-subnet-policy.json \
        --project [HOST_PROJECT_ID]
    

Similarly, if there are service accounts in the service projects that require NetworkUser permission in specific subnets in the host project, you add the service account using the above steps.

For more information about how Managed Instance Group with service accounts Managed Instance Groups with service accounts in shared VPC.

The recommendation is to provide NetworkUser role for a group, not for individual users, so that if a new user is added in the group, that user will automatically have the NetworkUser role. Similarly, if you want ANY user in your domain to be able to use shared VPC networks and automatically grant such permission to any new user within the domain, you can use member "Domain".

Discovering subnets that can be used

These steps should be completed by a service project admin. Service project admins can be project owners, editors, or users that have been granted the compute.instanceAdmin role.

Console

Go to the Shared VPC page in the Google Cloud Platform Console.
Go to the Shared VPC page

gcloud

gcloud alpha compute networks subnets list-usable --filter PROJECT~[HOST_PROJECT_ID]

Creating resources

Creating an instance in a shared subnet

These steps should be completed by a service project admin. Service project admins can be project owners, editors, or users that have been granted the compute.instanceAdmin role. Such users must also have the compute.networkUserrole for the shared subnet.

Console

  1. Go to the VM instances page in the Google Cloud Platform Console.
    Go to the VM instances page
  2. Click Create.
  3. Specify a Name for the instance.
  4. Click Management, disk, networking, SSH keys.
  5. Click Networking.
  6. Click the Networks shared with me radio button.
  7. Select the Shared subnet where you want to create the instance.
  8. Specify any other necessary parameters for the instance.
  9. Click Create.

gcloud

gcloud compute instances create vm1 \
    --project [SERVICE_PROJECT_ID] \
    --subnet projects/[HOST_PROJECT_ID]/regions/[REGION]/subnetworks/[SUBNET] \
    --zone [ZONE]

Creating an instance template in the shared VPC network

These steps should be completed by a service project admin. Service project admins can be project owners, editors, or users that have been granted the compute.instanceAdmin role. Such users must also have the compute.networkUserrole for the shared subnet.

Console

  1. Go to the Instance templates page in the Google Cloud Platform Console.
    Go to the Instance templates page
  2. Click Create instance template.
  3. Specify a Name for the instance template.
  4. Click Management, disk, networking, SSH keys.
  5. Click Networking.
  6. Click the Networks shared with me radio button.
  7. Select the Shared subnet where you want to create the instance template.
  8. Specify any other necessary parameters for the instance template.
  9. Click Create.

gcloud

gcloud compute instance-templates create [NAME] \
    --project [SERVICE_PROJECT_ID] \
    --network projects/[HOST_PROJECT_ID]/global/networks/[NETWORK]

This command creates a template for instances within a specific shared subnet only.

gcloud compute instance-templates create [NAME] \
    --project [SERVICE_PROJECT_ID] \
    --subnet projects/[HOST_PROJECT_ID]/regions/us-central1/subnetworks/[SUBNET]

Creating an Internal load balancer forwarding rule

Creates a forwarding rule associated to a shared VPC network subnet for one subnet only. When you create the Internal load balancing forwarding rule, you must specify the shared subnet as a fully or partially qualified URL.

This command is only part of setting up an Internal load balancer. The rest of the instructions are the same the normal case for setting up an Internal load balancer.

Console

  1. Go to the Load balancers page in the Google Cloud Platform Console.
    Go to the Load balancers page
  2. Follow the instructions for creating an Internal load balancer.
  3. When you get to Configure frontend services, select the subnet you want from the Networks shared by other projects section of the Subnet pull-down menu.
  4. Finish the rest of the procedure.

gcloud

gcloud compute forwarding-rules create [NAME] \
    --project [SERVICE_PROJECT_ID] \
    --load-balancing-scheme internal \
    --region \
    --ports PORT,[PORT,…] \
    --backend-service [BACKEND_SERVICE_NAME] \
    --subnet projects/[HOST_PROJECT_ID]/regions/[REGION]/subnetworks/[SUBNET] \
    [--address] \
    [--protocol]

Managed instance groups with service accounts in shared VPC

Managed instance groups use service accounts to perform actions like instance creation. See Managed Instance Groups and IAM for details.

The shared VPC Admin must grant the service account [SERVICE_PROJECT_NUMBER]@cloudservices.gserviceaccount.com the compute.networkUser role for the shared VPC host project or for specific shared subnets. This is done by setting an IAM policy at the shared VPC project level that binds the service account with the with compute.networkUser role.

Console

  1. Go to the Settings page in the Google Cloud Platform Console.
    Go to the Settings page
  2. Change the project to be the shared VPC service account.
  3. Copy the Project number of the service project to the system clipboard. This value is represented as [SERVICE_PROJECT_NUMBER] in the rest of this procedure.
  4. Change the project to the shared VPC host project.
  5. Go to the IAM page in the Google Cloud Platform Console.
    Go to the IAM page
  6. Click Add.
  7. Enter [SERVICE_PROJECT_NUMBER]@cloudservices.gserviceaccount.com into the Members field.
  8. Select Compute Engine > Compute Network User from the Roles pull-down menu.
  9. Click Add.

gcloud

  1. Get the host project number. This value is represented as [SERVICE_PROJECT_NUMBER] in the rest of this procedure.

    gcloud projects describe [SERVICE_PROJECT_ID]
    

  2. Grant the service account the compute.networkUser role.

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

More generally, any service accounts that are used in operations that require network use will need to be given compute.networkUser role in the host project. Any and all of the IAM roles can be given to the service account.

Console

  1. Go to the Settings page in the Google Cloud Platform Console.
    Go to the Settings page
  2. Change the project to be the service account.
  3. Copy the Project number of the service project to the system clipboard. This value is represented as [SERVICE_PROJECT_NUMBER] in the rest of this procedure.
  4. Change the project to the shared VPC host project.
  5. Go to the IAM page in the Google Cloud Platform Console.
    Go to the IAM page
  6. Click Add.
  7. Enter [USER_ID]@[SERVICE_PROJECT_ID].iam.gserviceaccount.com into the Members field.
  8. Select Compute Engine > Compute Network User from the Roles pull-down menu.
  9. Click Add.

gcloud

  1. Get the host project number. This value is represented as [SERVICE_PROJECT_NUMBER] in the rest of this procedure.

    gcloud projects describe [SERVICE_PROJECT_ID]
    

  2. Grant the service account the compute.networkUser role.

    gcloud projects add-iam-policy-binding [HOST_PROJECT_ID] \
        --member "user:[USER_ID]@[SERVICE_PROJECT_ID].iam.gserviceaccount.com" \
        --role "roles/compute.networkUser"
    

For information on how to apply IAM policies to service accounts, see granting roles to service accounts.

What's next

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Compute Engine Documentation