Set up a network

This page describes networking options for Vertex AI Workbench managed notebooks instances and shows you how to set up a network.

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

Overview

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

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

Supported feature comparison

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

Feature Google-managed network VPC network in your instance's project Shared VPC network
External IP Supported Supported Supported
Internal IP Supported Supported Supported
Private Google Access Not supported Supported Supported
VPC Supported Supported Supported
VPC Network Peering (requires Service Networking) Not supported Supported Supported

Use the default Google-managed network

The default network is Google-managed and requires no additional setup to configure.

When you create a managed notebooks instance with the default Google-managed network, the instance is deployed in a tenant project and uses a default VPC and subnet.

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

Connect your instance to a VPC network in the same project

To connect a managed notebooks instance to a VPC network in the same project as your managed notebooks instance, complete the following steps.

This option requires you to configure private services access.

Before you begin

  1. Select or create a Google Cloud project where your managed notebooks instance will be.

    Go to project selector

  2. Make sure that billing is enabled for your Google Cloud project.

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

    Enable the APIs

  4. Install the gcloud CLI to run the gcloud command-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 network and a network owned by Google or a third party service (service producers). In this case, your managed notebooks instance is a service producer. To set up private services access, you reserve an IP range for the service producer, and then create a peering connection with your managed notebooks instance.

Configure your project ID

To configure your project ID, use the following command.

gcloud config set project PROJECT_ID
 Replace PROJECT_ID with the project ID of the Google Cloud project where your managed notebooks instance will be. You'll create the instance later.

Enable the APIs

Make sure you have enabled the required APIs.

Create or select a VPC

  1. Create or select an existing VPC in a supported managed notebooks region to use with your managed notebooks instance.

    If you already have a VPC with private services access configured, and you want to use that VPC to peer with your managed notebooks instance, skip to Create a managed notebooks instance.

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

    gcloud compute networks create VPC_NAME \
    --project=PROJECT_ID --subnet-mode=auto \
    --mtu=1460 --bgp-routing-mode=regional

gcloud compute firewall-rules create VPC_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=icmp

gcloud compute firewall-rules create VPC_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=all

gcloud compute firewall-rules create VPC_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:3389

gcloud compute firewall-rules create VPC_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

    Replace VPC_NAME with a name for your 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, see Routes.

To create a managed 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 of several domains that you need to handle requests for, starting with *.notebooks.googleapis.com.

In Cloud Shell or any environment where the Google Cloud CLI is installed, enter the following Google Cloud CLI commands.

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

        gcloud dns managed-zones create ZONE_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 a DNS_NAME of notebooks.googleapis.com.

  2. Start a transaction. 

        gcloud dns record-sets transaction start --zone=ZONE_NAME

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

        gcloud dns record-sets transaction add \
        --name=DNS_NAME. \
        --type=A 199.36.153.4 199.36.153.5 199.36.153.6 199.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. 

        gcloud dns record-sets transaction add \
        --name=\*.DNS_NAME. \
        --type=CNAME DNS_NAME. \
        --zone=ZONE_NAME \
        --ttl=300

  5. Execute the transaction. 

        gcloud dns record-sets transaction execute --zone=ZONE_NAME

  6. Repeat these steps for each of the following domains. For each repetition, change ZONE_NAME and DNS_NAME to the appropriate values for that domain. Keep PROJECT_ID and NETWORK_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 by your managed notebooks instance and other services. If you plan 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 using gcloud compute addresses create.

gcloud compute addresses create PEERING_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

A prefix-length value of 16 means that a CIDR block with a subnet mask of /16 will be reserved for use by Google Cloud services such 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.

gcloud compute addresses list

Establish a peering connection

Establish a peering connection between your VPC host project and Google's Service Networking, using gcloud services vpc-peerings connect.

gcloud services vpc-peerings connect \
    --service=servicenetworking.googleapis.com \
    --network=NETWORK_NAME \
    --ranges=PEERING_RANGE_NAME \
    --project=PROJECT_ID

To list the peerings, use the following command.

gcloud services vpc-peerings list --network=NETWORK_NAME

Create a managed notebooks instance

Before using any of the request data, make the following replacements:

  • USER_ACCOUNT: The user account in the form of an email address.
  • MACHINE_TYPE: The machine type, for example n1-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

Save the request body in a file named request.json, and execute the following command: 

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"

PowerShell

Save the request body in a file named request.json, and execute the following command: 

$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 connected to the VPC network, complete these steps.

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

    Go to VPC network peering

  2. On the VPC network peering page, find your connection.

Export custom routes

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

To export custom routes, you update the peering connection in your VPC. Exporting custom routes sends all eligible static and dynamic routes that are in 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 lets managed notebooks instances send traffic back to 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.

gcloud services vpc-peerings list \
    --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.

gcloud compute networks peerings update PEERING_NAME \
    --network=NETWORK_NAME \
    --export-custom-routes \
    --project=PROJECT_ID

Replace PEERING_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.

gcloud compute networks peerings list --network NETWORK_NAME

Verify that the state of the peering connection that you just created is ACTIVE. Learn more about active peering connections.

Connect your instance to a Shared VPC network

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

This option requires you to configure private services access.

Before you begin

  1. Select or create a Google Cloud project where your managed notebooks instance will be.

    Go to project selector

  2. Make sure that billing is enabled for your Google Cloud project.

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

    Enable the APIs

  4. When you use Shared VPC, you run your managed notebooks instance in a separate Google Cloud project than your VPC host project. Repeat the previous steps to enable the Compute Engine, Notebooks, and Service Networking APIs in your VPC host project. Learn more about how to provision Shared VPC.

  5. Install the gcloud CLI to run the gcloud command-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 network and a network owned by Google or a third party service (service producers). In this case, your managed notebooks instance is a service producer. To set up private services access, you reserve an IP range for the service producer, and then create a peering connection with your managed notebooks instance.

Configure your project ID

To configure your project ID, use the following command.

gcloud config set project PROJECT_ID
 Replace PROJECT_ID with the project ID of your VPC host project. If you haven't created the VPC yet, use the project ID where it will be after it is created.

Enable the APIs

Make sure you have enabled the required APIs in both your VPC host project and the Google Cloud project where your managed notebooks instance will be.

Create or select a VPC

  1. Create or select an existing VPC in a supported managed notebooks region to use with your managed notebooks instance.

    If you already have a VPC with private services access configured, and you want to use that VPC to peer with your managed notebooks instance, skip to Create a managed notebooks instance.

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

    gcloud compute networks create VPC_NAME \
    --project=PROJECT_ID --subnet-mode=auto \
    --mtu=1460 --bgp-routing-mode=regional

gcloud compute firewall-rules create VPC_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=icmp

gcloud compute firewall-rules create VPC_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=all

gcloud compute firewall-rules create VPC_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:3389

gcloud compute firewall-rules create VPC_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

    Replace VPC_NAME with a name for your 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, see Routes.

To create a managed 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 of several domains that you need to handle requests for, starting with *.notebooks.googleapis.com.

In Cloud Shell or any environment where the Google Cloud CLI is installed, enter the following Google Cloud CLI commands.

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

        gcloud dns managed-zones create ZONE_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 a DNS_NAME of notebooks.googleapis.com.

  2. Start a transaction. 

        gcloud dns record-sets transaction start --zone=ZONE_NAME

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

        gcloud dns record-sets transaction add \
        --name=DNS_NAME. \
        --type=A 199.36.153.4 199.36.153.5 199.36.153.6 199.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. 

        gcloud dns record-sets transaction add \
        --name=\*.DNS_NAME. \
        --type=CNAME DNS_NAME. \
        --zone=ZONE_NAME \
        --ttl=300

  5. Execute the transaction. 

        gcloud dns record-sets transaction execute --zone=ZONE_NAME

  6. Repeat these steps for each of the following domains. For each repetition, change ZONE_NAME and DNS_NAME to the appropriate values for that domain. Keep PROJECT_ID and NETWORK_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 by your managed notebooks instance and other services. If you plan 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 using gcloud compute addresses create.

gcloud compute addresses create PEERING_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

A prefix-length value of 16 means that a CIDR block with a subnet mask of /16 will be reserved for use by Google Cloud services such 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.

gcloud compute addresses list

Establish a peering connection

Establish a peering connection between your VPC host project and Google's Service Networking, using gcloud services vpc-peerings connect.

gcloud services vpc-peerings connect \
    --service=servicenetworking.googleapis.com \
    --network=NETWORK_NAME \
    --ranges=PEERING_RANGE_NAME \
    --project=PROJECT_ID

To list the peerings, use the following command.

gcloud services vpc-peerings list --network=NETWORK_NAME

Create a managed notebooks instance

Before using any of the request data, make the following replacements:

  • USER_ACCOUNT: The user account in the form of an email address.
  • MACHINE_TYPE: The machine type, for example n1-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

Save the request body in a file named request.json, and execute the following command: 

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"

PowerShell

Save the request body in a file named request.json, and execute the following command: 

$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 connected to the Shared VPC network, complete these steps.

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

    Go to VPC network peering

  2. On the VPC network peering page, find your connection.

Export custom routes

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

To export custom routes, you update the peering connection in your VPC. Exporting custom routes sends all eligible static and dynamic routes that are in 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 lets managed notebooks instances send traffic back to 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.

gcloud services vpc-peerings list \
    --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.

gcloud compute networks peerings update PEERING_NAME \
    --network=NETWORK_NAME \
    --export-custom-routes \
    --project=PROJECT_ID

Replace PEERING_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.

gcloud compute networks peerings list --network NETWORK_NAME

Verify that the state of the peering connection that you just created is ACTIVE. Learn more about active peering connections.

What's next