Set up a network

Vertex AI Workbench managed notebooks isdeprecated. On April 14, 2025, support for managed notebooks ended and the ability to create managed notebooks instances was removed. Existing instances will continue to function until March 30, 2026, but patches, updates, and upgrades won't be available. To continue using Vertex AI Workbench, we recommend that youmigrate your managed notebooks instances to Vertex AI Workbench instances.

This page describes networking options for Vertex AI Workbenchmanaged notebooks instances and shows you how toset up a network.

This guide is recommended for networking administratorswho are already familiar with Google Cloud networking concepts.

Overview

This guide describes how to configure each of the following network options:

• Google-managed network
• VPC network in the same project as your managed notebooks instance
• Shared VPC network

By default, your managed notebooks instance usesa Google-managed network. If you want to,you can instead specify a Virtual Private Cloud network located within yourproject or a Shared VPC network that you have access to.If you specify a VPC or Shared VPC network,the network requires aprivate servicesaccess connection.

Supported feature comparison

The following table describes which common features are supported for eachnetworking option.

When you create a managed notebooks instancewith the default Google-managed network,the instance is deployed in atenant projectand uses a default VPC and subnet.

To download additional resources such as Python or Conda packages,a managed notebooks instance using thedefault Google-managed network requires an external IP address.

Connect your instance to a VPC network in the same project

To connect a managed notebooks instanceto a VPC network in the same projectas your managed notebooks instance,complete the following steps.

This option requires you to configureprivate services access.

Before you begin

1. Select orcreate a Google Cloudproject where yourmanaged notebooks instance will be.

   Go to project selector

2. Verify that billing is enabled for your Google Cloud project.

3. Enable the Compute Engine, Notebooks, and Service Networking APIs.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

   Enable the APIs

4. Install thegcloud CLI to run thegcloudcommand-line examples in this guide.

Set up private services access for your VPC

When you set up private services access,you establish a private connection between your networkand a network owned by Google or a third party service (service producers).In this case, your managed notebooks instanceis a service producer. Toset upprivate services access, youreserve an IP rangefor the service producer, and thencreatea peering connectionwith your managed notebooks instance.

Configure your project ID

To configure your project ID, use the following command.

gcloudconfigsetprojectPROJECT_ID

Enable the APIs

Create or select a VPC

1. Create or select an existing VPC in asupportedmanaged notebooks regionto use with your managed notebooks instance.

   If you already have a VPCwith private services access configured,and you want to use that VPC to peer withyour managed notebooks instance,skip toCreate a managed notebooks instance.

   If you need to create a new VPC,run the following gcloud CLI commands:

   gcloudcomputenetworkscreateVPC_NAME\--project=PROJECT_ID--subnet-mode=auto\--mtu=1460--bgp-routing-mode=regionalgcloudcomputefirewall-rulescreateVPC_NAME-allow-icmp\--project=PROJECT_ID\--network=projects/PROJECT_ID/global/networks/VPC_NAME\--description=Allows\ICMP\connections\from\any\source\to\any\instance\on\the\network.\--direction=INGRESS--priority=65534--source-ranges=0.0.0.0/0\--action=ALLOW--rules=icmpgcloudcomputefirewall-rulescreateVPC_NAME-allow-internal\--project=PROJECT_ID\--network=projects/PROJECT_ID/global/networks/VPC_NAME\--description=Allows\connections\from\any\source\in\the\network\IP\range\to\any\instance\on\the\network\using\all\protocols.\--direction=INGRESS--priority=65534--source-ranges=10.128.0.0/9\--action=ALLOW--rules=allgcloudcomputefirewall-rulescreateVPC_NAME-allow-rdp\--project=PROJECT_ID\--network=projects/PROJECT_ID/global/networks/VPC_NAME\--description=Allows\RDP\connections\from\any\source\to\any\instance\on\the\network\using\port\3389.\--direction=INGRESS--priority=65534--source-ranges=0.0.0.0/0\--action=ALLOW--rules=tcp:3389gcloudcomputefirewall-rulescreateVPC_NAME-allow-ssh\--project=PROJECT_ID\--network=projects/PROJECT_ID/global/networks/VPC_NAME\--description=Allows\TCP\connections\from\any\source\to\any\instance\on\the\network\using\port\22.\--direction=INGRESS--priority=65534--source-ranges=0.0.0.0/0\--action=ALLOW--rules=tcp:22

   ReplaceVPC_NAME with a name foryour VPC.

Create and configure DNS entries

Vertex AI Workbench managed notebooks instances use several domains that a Virtual Private Cloud network doesn't handle by default. To ensure that your VPC network correctly handles requests sent to those domains, use Cloud DNS to add DNS records. For more information about VPC routes, seeRoutes.

To create amanaged zone for a domain, add a DNS entry that will route the request, and execute the transaction, complete the following steps. Repeat these steps for each ofseveral domains that you need to handle requests for, starting with*.notebooks.googleapis.com.

InCloud Shell or any environment where theGoogle Cloud CLI is installed, enter the followingGoogle Cloud CLI commands.

1. To create a private managed zone for one of the domains that your VPC network needs to handle:

   gclouddnsmanaged-zonescreateZONE_NAME\--visibility=private\--networks=https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/networks/NETWORK_NAME\--dns-name=DNS_NAME\--description="Description of your managed zone"

   Replace the following:

   • ZONE_NAME: a name for the zone to create. You must use a separate zone for each domain. This zone name is used in each of the following steps.
   • PROJECT_ID: the ID of the project that hosts your VPC network
   • NETWORK_NAME: the name of the VPC network that you created earlier
   • DNS_NAME: the part of the domain name that comes after the*., with a period on the end. For example,*.notebooks.googleapis.com has aDNS_NAME ofnotebooks.googleapis.com.

2. Start a transaction.

   gclouddnsrecord-setstransactionstart--zone=ZONE_NAME

3. Add the following DNS A record. This reroutes traffic to Google's restricted IP addresses.

   gclouddnsrecord-setstransactionadd\--name=DNS_NAME.\--type=A199.36.153.4199.36.153.5199.36.153.6199.36.153.7\--zone=ZONE_NAME\--ttl=300

4. Add the following DNS CNAME record to point to the A record that you just added. This redirects all traffic matching the domain to the IP addresses listed in the previous step.

   gclouddnsrecord-setstransactionadd\--name=\*.DNS_NAME.\--type=CNAMEDNS_NAME.\--zone=ZONE_NAME\--ttl=300

5. Execute the transaction.

   gclouddnsrecord-setstransactionexecute--zone=ZONE_NAME

6. Repeat these steps for each of the following domains. For each repetition, changeZONE_NAME andDNS_NAME to the appropriate values for that domain. KeepPROJECT_ID andNETWORK_NAME the same each time. You already completed these steps for*.notebooks.googleapis.com.

   • *.notebooks.googleapis.com
   • *.notebooks.cloud.google.com
   • *.notebooks.googleusercontent.com
   • *.googleapis.com to run code that interacts with other Google APIs and services

Reserve IP ranges for your managed notebooks instance

When you reserve an IP range for service producers, the range can be used byyour managed notebooks instance and other services. If youplan to connect with other service producers using the same range,you might want to allocate a larger range to accommodate them,to avoid IP exhaustion.

Use the following command to set a reserved range usinggcloud compute addresses create.

gcloudcomputeaddressescreatePEERING_RANGE_NAME\--global\--prefix-length=16\--description="Managed notebooks range"\--network=NETWORK_NAME\--purpose=VPC_PEERING

Replace the following:

• PEERING_RANGE_NAME: the name of your range
• NETWORK_NAME: the name of your network

Aprefix-length value of16 means that a CIDR blockwith a subnet mask of/16 will bereserved for use by Google Cloud servicessuch as Vertex AI Workbench managed notebooks.

To avoid an invalid service networking configuration, use a subnet mask of/24 or lower.

Use the following command to verify the addresses.

gcloudcomputeaddresseslist

Establish a peering connection

Establish a peering connection between yourVPC host project and Google's Service Networking, usinggcloud services vpc-peerings connect.

gcloudservicesvpc-peeringsconnect\--service=servicenetworking.googleapis.com\--network=NETWORK_NAME\--ranges=PEERING_RANGE_NAME\--project=PROJECT_ID

gcloudservicesvpc-peeringslist--network=NETWORK_NAME

• USER_ACCOUNT: The user account in the form of an email address.
• MACHINE_TYPE: Themachine type, for examplen1-standard-1.
• PROJECT_ID: The project ID of your managed notebooks instance.
• NETWORK_NAME: The VPC network name.
• LOCATION: The region of your VPC network.
• NOTEBOOK_NAME: The name of your managed notebooks instance.
• SUBNET_NAME: The subnet name for your VPC network.
• PEERING_RANGE_NAME: Optional. The name of the peering range if you want to specify one.

HTTP method and URL:

POST https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/runtimes?runtimeId=NOTEBOOK_NAME

Request JSON body:

{  "access_config": {    "access_type": "SINGLE_USER",    "runtime_owner": "USER_ACCOUNT"  },  "virtual_machine": {    "virtual_machine_config": {      "machine_type": "MACHINE_TYPE",      "network": "projects/PROJECT_ID/global/networks/NETWORK_NAME",      "subnet":  "projects/PROJECT_ID/regions/LOCATION/subnetworks/SUBNET_NAME",      "internal_ip_only": true,      "reserved_ip_range": "PEERING_RANGE_NAME" # Optional    }  }}

To send your request, choose one of these options:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/runtimes?runtimeId=NOTEBOOK_NAME"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/runtimes?runtimeId=NOTEBOOK_NAME" | Select-Object -Expand Content

Verify connectivity

To verify that your managed notebooks instance is connectedto the VPC network,complete these steps.

1. In the Google Cloud console,go to theVPC network peering page.

   Go to VPC network peering

2. On theVPC network peering page, find your connection.

Export custom routes

If you use custom routes, you need to export them so thatVertex AI Workbench managed notebooks can import them.

To export custom routes, youupdatethe peering connectionin your VPC. Exporting custom routes sends alleligiblestatic and dynamic routes that arein your VPC network, such as routes to your on-premises network,to service producers' networks (in this case, managed notebooks).This establishes the necessary connections and letsmanaged notebooks instances send traffic backto your on-premises network.

To list the name of the peering connection to update,use the following command.If you have multiple peering connections, omit the--format flag.

gcloudservicesvpc-peeringslist\--network=NETWORK_NAME\--service=servicenetworking.googleapis.com\--project=PROJECT_ID\--format"value(peering)"

To update the peering connection to export custom routes,use the following command.

gcloudcomputenetworkspeeringsupdatePEERING_NAME\--network=NETWORK_NAME\--export-custom-routes\--project=PROJECT_ID

ReplacePEERING_NAME with the name of your peering connection.

Check the state of your peering connections

To check whether your peering connections are active,you can list them using the following command.

gcloudcomputenetworkspeeringslist--networkNETWORK_NAME

Verify that the state of the peering connection thatyou just created isACTIVE.Learn more aboutactivepeering connections.

Connect your instance to a Shared VPC network

To connect a managed notebooks instanceto a Shared VPC network that you have access to,complete the following steps.

This option requires you to configureprivate services access.

Before you begin

1. Select orcreate a Google Cloudproject where yourmanaged notebooks instance will be.

   Go to project selector

2. Verify that billing is enabled for your Google Cloud project.

3. Enable the Compute Engine, Notebooks, and Service Networking APIs.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

   Enable the APIs

4. When you useShared VPC, you runyour managed notebooks instance ina separate Google Cloud project thanyour VPC host project.Repeat the previous steps to enable the Compute Engine, Notebooks,and Service Networking APIsin your VPC host project.Learn more about how toprovision Shared VPC.

5. Install thegcloud CLI to run thegcloudcommand-line examples in this guide.

Set up private services access for your VPC

When you set up private services access,you establish a private connection between your networkand a network owned by Google or a third party service (service producers).In this case, your managed notebooks instanceis a service producer. Toset upprivate services access, youreserve an IP rangefor the service producer, and thencreatea peering connectionwith your managed notebooks instance.

Configure your project ID

To configure your project ID, use the following command.

gcloudconfigsetprojectPROJECT_ID

Enable the APIs

Create or select a VPC

1. Create or select an existing VPC in asupportedmanaged notebooks regionto use with your managed notebooks instance.

   If you already have a VPCwith private services access configured,and you want to use that VPC to peer withyour managed notebooks instance,skip toCreate a managed notebooks instance.

   If you need to create a new VPC,run the following gcloud CLI commands:

   gcloudcomputenetworkscreateVPC_NAME\--project=PROJECT_ID--subnet-mode=auto\--mtu=1460--bgp-routing-mode=regionalgcloudcomputefirewall-rulescreateVPC_NAME-allow-icmp\--project=PROJECT_ID\--network=projects/PROJECT_ID/global/networks/VPC_NAME\--description=Allows\ICMP\connections\from\any\source\to\any\instance\on\the\network.\--direction=INGRESS--priority=65534--source-ranges=0.0.0.0/0\--action=ALLOW--rules=icmpgcloudcomputefirewall-rulescreateVPC_NAME-allow-internal\--project=PROJECT_ID\--network=projects/PROJECT_ID/global/networks/VPC_NAME\--description=Allows\connections\from\any\source\in\the\network\IP\range\to\any\instance\on\the\network\using\all\protocols.\--direction=INGRESS--priority=65534--source-ranges=10.128.0.0/9\--action=ALLOW--rules=allgcloudcomputefirewall-rulescreateVPC_NAME-allow-rdp\--project=PROJECT_ID\--network=projects/PROJECT_ID/global/networks/VPC_NAME\--description=Allows\RDP\connections\from\any\source\to\any\instance\on\the\network\using\port\3389.\--direction=INGRESS--priority=65534--source-ranges=0.0.0.0/0\--action=ALLOW--rules=tcp:3389gcloudcomputefirewall-rulescreateVPC_NAME-allow-ssh\--project=PROJECT_ID\--network=projects/PROJECT_ID/global/networks/VPC_NAME\--description=Allows\TCP\connections\from\any\source\to\any\instance\on\the\network\using\port\22.\--direction=INGRESS--priority=65534--source-ranges=0.0.0.0/0\--action=ALLOW--rules=tcp:22

   ReplaceVPC_NAME with a name foryour VPC.

Create and configure DNS entries

Vertex AI Workbench managed notebooks instances use several domains that a Virtual Private Cloud network doesn't handle by default. To ensure that your VPC network correctly handles requests sent to those domains, use Cloud DNS to add DNS records. For more information about VPC routes, seeRoutes.

To create amanaged zone for a domain, add a DNS entry that will route the request, and execute the transaction, complete the following steps. Repeat these steps for each ofseveral domains that you need to handle requests for, starting with*.notebooks.googleapis.com.

InCloud Shell or any environment where theGoogle Cloud CLI is installed, enter the followingGoogle Cloud CLI commands.

1. To create a private managed zone for one of the domains that your VPC network needs to handle:

   gclouddnsmanaged-zonescreateZONE_NAME\--visibility=private\--networks=https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/networks/NETWORK_NAME\--dns-name=DNS_NAME\--description="Description of your managed zone"

   Replace the following:

   • ZONE_NAME: a name for the zone to create. You must use a separate zone for each domain. This zone name is used in each of the following steps.
   • PROJECT_ID: the ID of the project that hosts your VPC network
   • NETWORK_NAME: the name of the VPC network that you created earlier
   • DNS_NAME: the part of the domain name that comes after the*., with a period on the end. For example,*.notebooks.googleapis.com has aDNS_NAME ofnotebooks.googleapis.com.

2. Start a transaction.

   gclouddnsrecord-setstransactionstart--zone=ZONE_NAME

3. Add the following DNS A record. This reroutes traffic to Google's restricted IP addresses.

   gclouddnsrecord-setstransactionadd\--name=DNS_NAME.\--type=A199.36.153.4199.36.153.5199.36.153.6199.36.153.7\--zone=ZONE_NAME\--ttl=300

4. Add the following DNS CNAME record to point to the A record that you just added. This redirects all traffic matching the domain to the IP addresses listed in the previous step.

   gclouddnsrecord-setstransactionadd\--name=\*.DNS_NAME.\--type=CNAMEDNS_NAME.\--zone=ZONE_NAME\--ttl=300

5. Execute the transaction.

   gclouddnsrecord-setstransactionexecute--zone=ZONE_NAME

6. Repeat these steps for each of the following domains. For each repetition, changeZONE_NAME andDNS_NAME to the appropriate values for that domain. KeepPROJECT_ID andNETWORK_NAME the same each time. You already completed these steps for*.notebooks.googleapis.com.

   • *.notebooks.googleapis.com
   • *.notebooks.cloud.google.com
   • *.notebooks.googleusercontent.com
   • *.googleapis.com to run code that interacts with other Google APIs and services

Reserve IP ranges for your managed notebooks instance

When you reserve an IP range for service producers, the range can be used byyour managed notebooks instance and other services. If youplan to connect with other service producers using the same range,you might want to allocate a larger range to accommodate them,to avoid IP exhaustion.

Use the following command to set a reserved range usinggcloud compute addresses create.

gcloudcomputeaddressescreatePEERING_RANGE_NAME\--global\--prefix-length=16\--description="Managed notebooks range"\--network=NETWORK_NAME\--purpose=VPC_PEERING

Replace the following:

• PEERING_RANGE_NAME: the name of your range
• NETWORK_NAME: the name of your network

Aprefix-length value of16 means that a CIDR blockwith a subnet mask of/16 will bereserved for use by Google Cloud servicessuch as Vertex AI Workbench managed notebooks.

To avoid an invalid service networking configuration, use a subnet mask of/24 or lower.

Use the following command to verify the addresses.

gcloudcomputeaddresseslist

Establish a peering connection

Establish a peering connection between yourVPC host project and Google's Service Networking, usinggcloud services vpc-peerings connect.

gcloudservicesvpc-peeringsconnect\--service=servicenetworking.googleapis.com\--network=NETWORK_NAME\--ranges=PEERING_RANGE_NAME\--project=PROJECT_ID

gcloudservicesvpc-peeringslist--network=NETWORK_NAME

• USER_ACCOUNT: The user account in the form of an email address.
• MACHINE_TYPE: Themachine type, for examplen1-standard-1.
• PROJECT_ID: The project ID of your managed notebooks instance.
• NETWORK_NAME: The VPC network name.
• LOCATION: The region of your VPC network.
• NOTEBOOK_NAME: The name of your managed notebooks instance.
• SUBNET_NAME: The subnet name for your VPC network.
• PEERING_RANGE_NAME: Optional. The name of the peering range if you want to specify one.

HTTP method and URL:

POST https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/runtimes?runtimeId=NOTEBOOK_NAME

Request JSON body:

{  "access_config": {    "access_type": "SINGLE_USER",    "runtime_owner": "USER_ACCOUNT"  },  "virtual_machine": {    "virtual_machine_config": {      "machine_type": "MACHINE_TYPE",      "network": "projects/PROJECT_ID/global/networks/NETWORK_NAME",      "subnet":  "projects/PROJECT_ID/regions/LOCATION/subnetworks/SUBNET_NAME",      "internal_ip_only": true,      "reserved_ip_range": "PEERING_RANGE_NAME" # Optional    }  }}

To send your request, choose one of these options:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/runtimes?runtimeId=NOTEBOOK_NAME"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/runtimes?runtimeId=NOTEBOOK_NAME" | Select-Object -Expand Content

Verify connectivity

To verify that your managed notebooks instance is connectedto the Shared VPC network,complete these steps.

1. In the Google Cloud console,go to theVPC network peering page.

   Go to VPC network peering

2. On theVPC network peering page, find your connection.

Export custom routes

If you use custom routes, you need to export them so thatVertex AI Workbench managed notebooks can import them.

To export custom routes, youupdatethe peering connectionin your VPC. Exporting custom routes sends alleligiblestatic and dynamic routes that arein your VPC network, such as routes to your on-premises network,to service producers' networks (in this case, managed notebooks).This establishes the necessary connections and letsmanaged notebooks instances send traffic backto your on-premises network.

To list the name of the peering connection to update,use the following command.If you have multiple peering connections, omit the--format flag.

gcloudservicesvpc-peeringslist\--network=NETWORK_NAME\--service=servicenetworking.googleapis.com\--project=PROJECT_ID\--format"value(peering)"

To update the peering connection to export custom routes,use the following command.

gcloudcomputenetworkspeeringsupdatePEERING_NAME\--network=NETWORK_NAME\--export-custom-routes\--project=PROJECT_ID

ReplacePEERING_NAME with the name of your peering connection.

Check the state of your peering connections

To check whether your peering connections are active,you can list them using the following command.

gcloudcomputenetworkspeeringslist--networkNETWORK_NAME

Verify that the state of the peering connection thatyou just created isACTIVE.Learn more aboutactivepeering connections.

What's next

• Learn more aboutVPC Network Peering.

• Seereference architectures andbest practicesfor VPC design.