Deprovision Shared VPC

This page describes how to deprovision an existing Shared VPC configuration,disconnecting all service projects from a Shared VPC host project.Deprovisioning is a one-way process. Make sure that you are familiar with theShared VPC andProvision Shared VPC pages first.

Note: Shared VPC is also referred to as "XPN" in the API and command-lineinterface.Caution: Deleting a Shared VPC host project without following the processesdescribed here will cause an outage for instances in all service projectsattached to the host project. The directions for provisioning a Shared VPCexplain how tocreate an organization-level policy to limit IAM principals who canremove the lien that prevents deletion of hostprojects. If you have that policy inplace, then you limit the risk of deleting a host project without properlydeprovisioning it.

Service Project Admin tasks

In each service project attached to the Shared VPC host project, aServiceProject Admin must remove all dependencieson the host project. Dependencies might include instances, instance groups,instance templates, backend services, and forwarding rules.

Determine affected resources

To identify resources that depend on the Shared VPC host project, aService Project Admin canlist its sharedsubnets. When theservice project is detached from the host project, these subnets will no longerbe available to it; thus, any resources that depend on them will be affected.

Delete resources

Once a Service Project Admin has identified the resources that will be affectedby the deprovisioning process, those resources will need to be deleted:

Caution: If a service project should eventually be shut down (deleted),itmust first be detached from the host project.Donot simply delete it. For details about why detaching must be donefirst, refer tothe delete service projectssection.

Load Balancer Admin tasks

Note: This section only covers tasks that relate tointernal Application Load Balancers and regional external Application Load Balancers.

Internal Application Load Balancers and regional external Application Load Balancers allow you to configurethe load balancer so that a URL map in one host or service project can referencebackend services (and backends) located across multiple projects inShared VPC environments.

Before you can delete a service project, you must make sure that any suchcross-project references to backend services in your service project have beenremoved. Load Balancer Admins will need to modify their URL maps to removereferences to backend services in your service project.

Shared VPC Admin tasks

All tasks in this section must be performed by aShared VPCAdmin.

Detach service projects

Repeat these steps for each service project you need to detach from theShared VPC host project.

Caution: Detaching a service project can only be done after the Service ProjectAdmins have deleted all service project resources that depend on the host project.Before performing these steps, make sure that Service Project Admins have completedService Project Admin tasks.

Console

To view the Shared VPC page in the Google Cloud console, you must havethe Shared VPC Admin role.

  1. Go to theShared VPC page in the Google Cloud console.
    Go to Shared VPC
  2. Log in as a Shared VPC Admin.
  3. Select the host project you are removing service projects from.
  4. Click theAttached projects tab.
  5. Select the service project that you want to detach.
  6. Click theDetach Projects button.
  7. Review the information in the dialog.
  8. ClickDetach.

gcloud

  1. If you have not already, authenticate togcloud as a Shared VPC Admin.ReplaceSHARED_VPC_ADMIN with the name of the Shared VPCAdmin:

    gcloud auth loginSHARED_VPC_ADMIN

  2. Detach the service project from the host project. ReplaceSERVICE_PROJECT_ID with the project ID for the service projectandHOST_PROJECT_ID with the project ID for the host project.

    gcloud compute shared-vpc associated-projects removeSERVICE_PROJECT_ID    --host-projectHOST_PROJECT_ID

  3. Confirm that the service project has been detached using one of thesecommands:

    gcloud compute shared-vpc get-host-projectSERVICE_PROJECT_ID
    gcloud compute shared-vpc list-associated-resourcesHOST_PROJECT_ID

  4. If you only needed to detach service projects, log out ofgcloud toprotect your Shared VPC Admin account credentials. Otherwise, skip thisstep and proceed withdisable the hostproject.

    gcloud auth revokeSHARED_VPC_ADMIN

API

  1. Detach the service project.

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

    Replace the placeholders with valid values:

    • HOST_PROJECT_ID is the ID of the host project.
    • SERVICE_PROJECT_ID is the ID of the service project todetach.

    For more information, refer to theprojects.disableXpnResourcemethod.

  2. Confirm that the service project has been detached.

    • Check that the service project isn't attached to any host project.

      GET https://compute.googleapis.com/compute/v1/projects/SERVICE_PROJECT_ID/getXpnHost

      ReplaceSERVICE_PROJECT_ID with the ID of the serviceproject.

      For more information, refer to theprojects.getXpnHostmethod.

    • List the service projects attached the Shared VPC host project toconfirm that the project is no longer listed.

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

      ReplaceHOST_PROJECT_ID with the ID of the host project.

      For more information, refer to theprojects.getXpnResourcesmethod.

Disable host project

Disabling Shared VPC for the host project is only possible after all serviceprojects have beendetached. When disabled, the lienthat prevents it from being easily deleted is removed automatically.

Console

To view the Shared VPC page in the Google Cloud console, you must havethe Shared VPC Admin role.

  1. Go to theShared VPC page in the Google Cloud console.
    Go to Shared VPC
  2. Log in as a Shared VPC Admin.
  3. Select the Host Project you want to disable.
  4. Click theDisable Shared VPC button.
  5. In the dialog, read the description carefully.
  6. Enter the project ID of the host project forHost project ID.
  7. ClickDisable.

gcloud

  1. If you have not already, authenticate togcloud as a Shared VPC Admin.ReplaceSHARED_VPC_ADMIN with the name of the Shared VPCAdmin:

    gcloud auth loginSHARED_VPC_ADMIN

  2. Disable Shared VPC for the host project. ReplaceHOST_PROJECT_ID with the ID of the host project.

    gcloud compute shared-vpc disableHOST_PROJECT_ID

  3. Confirm that the project is no longer 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 disable a host project, you can log out ofgcloud to protect your Shared VPC Admin account credentials.Otherwise, skip this step and continue withdeleteprojects.

    gcloud auth revokeSHARED_VPC_ADMIN

API

  1. Disable Shared VPC for the project.

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

    ReplaceHOST_PROJECT_ID with the ID of the host project.

    For more information, refer to theprojects.disableXpnHostmethod.

  2. List your host projects to confirm that the project isn't listed.

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

    ReplaceHOST_PROJECT_ID with the ID of the host project.

    For more information, refer to theprojects.listXpnHostsmethod.

Delete projects

This section discusses deleting projects that are no longer used; for example,you may have service projects that need to be deleted after they have beendetached from a host project, or you may no longer need the host projectafter it has been disabled.

Delete host project

You may choose to keep it as a normal project orshut itdown.Shutting down a project deletes it.

An IAM principal can delete the host project if the principal has theresourcemanager.projectDeleterrole for yourorganization or if the principal is the owner of the host project.Shared VPC Admins may be able to delete host projects if they have thecorrect role or ownership.

Important: If you have not firstdetached all service projects from the hostproject anddisabled SharedVPC, a lien will prevent the host project from beingdeleted. If you need to forcibly delete a host project,refer to thissection..

Delete service project

You may choose toshut down each serviceprojectif you no longer need them. Before doing so, make sure thatthe service projecthas been detached from the host project.

An IAM principal can delete a service project if the principal has theresourcemanager.projectDeleterrole for yourorganization or if the principal is the owner of the service project. ServiceProject Admins may be able to delete service projects if they have the correctrole or ownership.

Caution: If you shut down a service project without first detaching it from thehost project, you will be unable to destroy its attachment (and the host projectcannot be disabled). This happens because Google Cloud considers the service projectattachment valid for the duration of the service project's recoverable period(30 days). If this happens, you must firstrestore the deleted serviceproject or wait for itsrecoverable period to expire,detach it from the hostproject, then shut down the service project again.For more information, refer tothispage.

Forcibly delete a host project

While Shared VPC is active for a host project, a lien is placed on the projectto prevent it from being accidentally deleted. Because this lien can be removedby a project owner, theguidelines for provisioning a SharedVPC include steps to define anorganizational policy that limits which IAM principals have the ability toremove a project lien.

Normally, a host project should be deletedafter the following tasks have beencompleted in this order:

  • All service projects have beendetached from thehost project, and
  • Shared VPC has beendisabled.

When Shared VPC has been disabled, the lien that protects the host project isautomatically removed.

This section details how to forcibly shut down a host project. You should onlyconsider this option under these circumstances:

  • You cannot follow the normal steps of detaching service projects and disablingShared VPC.
  • There are additional liens protecting the host project beyond the one that isadded automatically.

If you forcibly shut down a host project and you have resources in serviceprojects that use the Shared VPC network, the following events occur:

  • All Shared VPC networks, their subnets, routes, firewall rules, and allnetworking resources in the host project are deleted.
  • Resources, such as running instances in the service projects attached to thehost project, are stopped.
  • Internal TCP/UDP load balancers are disabled if their forwarding rules dependon the Shared VPC network.
Note: The host project can berestored within 30 days ofbeing shut down. If restored, resources in service projects attached to it canbe restarted.

gcloud

  1. Authenticate togcloud as an IAM principal who can remove a projectlien. If you havean organizational policy that limits which principalscan remove liens, you mustauthenticate as an IAM principal with theresourcemanager.lienModifierrole for your organization. If you do not have such a policy in place,the project owner for the host project can remove the lien.

    ReplaceACCOUNT with the name of the appropriate IAMprincipal:

    gcloud auth loginACCOUNT

  2. List the liens associated with the host project. ReplaceHOST_PROJECT_ID with the ID of the host project.

    gcloud alpha resource-manager liens list \--projectHOST_PROJECT_ID

  3. Remove each lien by name, one at a time, until no more liens are present.ReplaceLIEN_NAME with the name of the lien to remove.

    gcloud alpha resource-manager liens deleteLIEN_NAME \--projectHOST_PROJECT_ID

  4. Confirm that all liens have been removed.

    gcloud alpha resource-manager liens list \--projectHOST_PROJECT_ID

  5. After removing the lien, you can log out ofgcloud to protect thecredentials of the IAM principal which has permission to remove liens.

    gcloud auth revokeACCOUNT

  6. The host project can now beshutdown.

API

  1. List the liens that are associated with the host project.

    GET https://cloudresourcemanager.googleapis.com/v1/liens?parent=projects:HOST_PROJECT_ID

    ReplaceHOST_PROJECT_ID with the ID of the host project.

    For more information, refer to theliens.listmethod.

  2. Remove each lien by name until no more liens are present.

    DELETE https://cloudresourcemanager.googleapis.com/v1/liens/LIEN_NAME

    ReplaceLIEN_NAME with the name of the lien to delete.

    For more information, refer to theliens.deletemethod.

  3. List the liens again to confirm that they have been removed.

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 2026-02-19 UTC.