Working with hubs and spokes

This page describes how to list, create, describe, delete, and update Network Connectivity Center hubs and spokes.

For an introduction to Network Connectivity Center, see the Network Connectivity Center overview.

For a tutorial that describes how to set up data transfer between two sites, see Connecting two branch offices using Cloud VPN spokes.

Before you begin

To make it easier to configure Network Connectivity Center, set up the following items in Google Cloud:

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
  2. In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.

  4. Install and initialize the Cloud SDK.
  1. If you are using gcloud commands, set your project ID with the following command. The gcloud command-line instructions on this page assume that you have set your project ID.
          gcloud config set project PROJECT_ID
        
  1. You can also view a project ID that has already been set:
          gcloud config list --format='text(core.project)'
        

Enabling the Network Connectivity API

Before you can perform any tasks using Network Connectivity Center, you must enable the Network Connectivity API. Use the following steps. Alternatively, you can use the Cloud Console API Library, as described in Enabling APIs.

Console

To enable the Network Connectivity API:

  1. In the Cloud Console, go to the Network Connectivity Center page.

    Go to Network Connectivity Center

  2. Click Enable.

API considerations

Using locations versus region in API commands

The Network Connectivity API uses the locations field for indicating Google Cloud regions or zones. The Compute Engine API uses regions or zones to represent these resources.

Specifying hubs or spoke resources with names or URIs

When entering commands, you can specify the following Network Connectivity Center resources by their name or by their full URI:

  • A hub
  • A resource attached to a spoke

This practice applies to the gcloud command-line tool and to the Network Connectivity API.

For example, you can refer to an HA VPN tunnel attached to a spoke as TUNNEL_NAME or as projects/PROJECT_NAME/regions/REGION/vpnTunnels/TUNNEL_NAME.

The following example describes how you would specify adding two HA VPN tunnels to a spoke by using their URIs.

--vpn-tunnel="https://www.googleapis.com/compute/projects/PROJECT_ID/regions/REGION/vpnTunnels/TUNNEL_NAME","https://www.googleapis.com/compute/projects/PROJECT_ID/regions/REGION/vpnTunnels/TUNNEL_NAME"

Working with hubs

This section describes how to list, create, describe, and delete Network Connectivity Center hubs. You can also update a hub's labels and description.

Listing hubs

Network Connectivity Center permits only one hub per project. To list a project's hub, use the following guidance.

Console

  1. In the Cloud Console, go to the Network Connectivity Center page.

    Go to Network Connectivity Center

  2. In the project pull-down menu, select a project.

gcloud

To list the hub associated with the project, enter the following command:

  gcloud alpha network-connectivity hubs list

API

To list the hub associated with the project, use the networkconnectivity.hubs.list method.

  GET https://networkconnectivity.googleapis.com/v1alpha1/projects/PROJECT_ID/locations/global/hubs

Replace PROJECT_ID with the project ID of the project that contains the hubs to list.

Creating a hub

For each project, you can create one hub. When you create a hub, you can optionally add a description and labels to it.

Console

  1. In the Cloud Console, go to the Network Connectivity Center page.

    Go to Network Connectivity Center

  2. In the project pull-down menu, select a project.

  3. Enter a Hub name.

  4. Enter an optional Description.

  5. Verify the Project ID. If the project ID is incorrect, select a different project by using the pull-down menu at the top of the screen.

  6. Click Continue.

  7. Do one of the following:

    • Fill in the form to create a spoke. For steps, see Creating a spoke.
    • If you don't want to create a spoke, click Cancel on the New spoke form.
  8. Click Done.

gcloud

To create a hub, enter the following command.

For more information about labels, see Requirements for labels.

  gcloud alpha network-connectivity hubs create NAME \
    --description=DESCRIPTION \
    --labels=KEY=VALUE

Replace the following values:

  • NAME: the name of the new hub
  • DESCRIPTION: optional text that describes the hub
  • KEY: the key in the key:value pair for optional label text
  • VALUE: the value in the key:value pair for optional label text

API

To create a hub, use the networkconnectivity.hubs.create method.

For more information about labels, see Requirements for labels.

  POST https://networkconnectivity.googleapis.com/v1alpha1/projects/PROJECT_ID/locations/global/hubs
  {
    "name":"NAME",
    "description":"DESCRIPTION",
    "labels": {
      "KEY": "VALUE"
    }
  }

Replace the following values:

  • PROJECT_ID: the project ID of the project that contains the new hub
  • NAME: the name of the new hub
  • DESCRIPTION: optional text that describes the hub
  • KEY: the key in the key:value pair for optional label text
  • VALUE: the value in the key:value pair for optional label text

Describing a hub

Use the following guidance to retrieve details about a project's hub. If you want additional information about the spokes attached to the hub, see Describing a spoke.

Console

  1. In the Cloud Console, go to the Network Connectivity Center page.

    Go to Network Connectivity Center

  2. In the project pull-down menu, select a project to view information about that project's hub.

  3. To view details about the hub's spokes, click the Spokes tab.

gcloud

To get detailed information about an existing hub, enter the following command:

gcloud alpha network-connectivity hubs describe NAME

Replace NAME with the name of the hub.

API

To get detailed information about an existing hub, use the networkconnectivity.hubs.get method.

  GET https://networkconnectivity.googleapis.com/v1alpha1/projects/PROJECT_ID/locations/global/hubs/NAME

Replace the following values:

  • PROJECT_ID: the project ID of the project that contains the hubs to describe
  • NAME: the name of the hub to describe

Output from this command shows the following information:

  • The time the hub was created
  • Any labels applied to the hub
  • The hub's name
  • The URI of each spoke attached to the hub
  • The hub's unique identifier
  • The time the hub was last updated
 createTime: '2020-11-05T21:29:09.168879193Z'
    labels:
     hubs: hub-us-west2
     name: projects/my-project/locations/global/hubs/my-hub
     spokes:
     - https://networkconnectivity.googleapis.com/v1alpha1/projects/419575220454/locations/us-west2/spokes/spoke1
    uniqueId: 8ca1fd2d-979e-4925-bd23-a5f739b3f4ae
  updateTime: '2020-11-05T21:29:09.305702283Z'
 

Updating a hub with labels or a new description

After a hub has been created, you can update it by adding or changing either of the following:

  • Labels applied to the hub
  • The hub's description

You can also set a label or description when you create a hub, as described in Creating a hub.

For more information about labels, see Requirements for labels.

gcloud

To update a hub's description or add labels to a hub, enter the following command:

  gcloud alpha network-connectivity hubs update NAME \
    --description=DESCRIPTION \
    --labels=KEY=VALUE

Replace the following values:

  • NAME: the name of the hub
  • DESCRIPTION: an optional new description for the hub
  • KEY: the key in the key:value pair for optional label text
  • VALUE: the value in the key:value pair for optional label text

API

To update a hub's description or add labels to a hub, use the networkconnectivity.hubs.patch method.

  PATCH https://networkconnectivity.googleapis.com/v1alpha1/projects/PROJECT_ID/locations/global/hubs/NAME
  {
    "description": "DESCRIPTION",
    "labels": {
      "KEY": "VALUE"
    }
  }

Replace the following values:

  • PROJECT_ID: the project ID of the project that contains the hub to add a label to
  • NAME: the name of the hub
  • DESCRIPTION: an optional new description for the hub
  • KEY: the key in the key:value pair for optional label text
  • VALUE: the value in the key:value pair for optional label text

Deleting a hub

Before you can delete a hub, you must delete its spokes, as described in Deleting a spoke.

Console

  1. In the Cloud Console, go to the Network Connectivity Center page.

    Go to Network Connectivity Center

  2. In the project pull-down menu, select a project.

  3. Click Delete hub.

  4. In the confirmation dialog, do one of the following:

    • Click Cancel if you don't want to delete the hub.
    • Click Delete to delete the hub.

gcloud

To delete a hub, enter the following command:

  gcloud alpha network-connectivity hubs delete NAME

Replace NAME with the name of the hub.

API

To delete a hub, use the networkconnectivity.hubs.delete method.

  DELETE https://networkconnectivity.googleapis.com/v1alpha1/projects/PROJECT_ID/locations/global/hubs/NAME

Replace the following values:

  • PROJECT_ID: the project ID of the project that contains the hub to delete
  • NAME: the name of the hub to delete

Working with spokes

This section describes how to list, create, describe, and delete Network Connectivity Center spokes. You can also update a hub's labels and description.

For guidelines to consider when creating a spoke, see Creating a spoke.

Listing spokes

This set of commands lists spokes in the specified region. To list spokes for a specific hub or view spokes in the Cloud Console, see Describing a hub.

gcloud

To list existing spokes, enter the following command:

gcloud alpha network-connectivity spokes list \
--region=REGION

Replace REGION with the region where the spoke is located.

API

To list existing spokes, use the networkconnectivity.spokes.list method.

  GET https://networkconnectivity.googleapis.com/v1alpha1/projects/PROJECT_ID/locations/REGION/spokes

Replace the following values:

  • PROJECT_ID: the project ID of the project that contains the spokes to list
  • REGION: the region where the spoke is located; for example, us-west1

To get an aggregated list of existing spokes, where the values of multiple rows are grouped together to form a single summary value, use the networkconnectivity.spokes.list method with a hyphen (-) after locations as a wildcard.

  GET https://networkconnectivity.googleapis.com/v1alpha1/projects/PROJECT_ID/locations/-/spokes

Creating a spoke

When you create a spoke, you specify the type of Google Cloud network resource that you want to attach to it.

We recommend creating spokes in the region closest to the site that the spoke connects to. For example, a site could be an on-premises data center, a branch office, or another cloud provider.

Requirements

  • You must create a spoke in the same region as the Google Cloud resource that you attach to it. For example, if you attach HA VPN tunnels to a spoke, that spoke must reside in the same region as the HA VPN gateway that contains those tunnels.
  • To attach more than one resource to a spoke by using the gcloud command-line tool or the API, separate the resource names with a comma. There must be no space before or after the comma.
  • It's not possible to add or remove HA VPN tunnels or VLAN attachments to or from an existing spoke. Instead, you must delete and re-create the spoke to include the resources that you want the spoke to contain. However, you can add a router appliance instance to a spoke that has existing router appliance instances attached to it.

Recommendations for attaching multiple resources to a spoke

  • When creating a spoke, you can add more than one resource, but all resources must be of the same type. For example, you can add multiple HA VPN tunnels, but you can't add HA VPN tunnels and VLAN attachments. For more information, see Spoke resource types.
  • When attaching HA VPN tunnels to a spoke, we recommend that all tunnels connecting to a single site be configured together as a single spoke. The reverse is also true; two tunnels connecting to two different sites should be attached to different spokes. For example, suppose you want to connect your home office in Dallas with a remote office in Tokyo. The tunnel that connects to Dallas must be part of a different spoke than the one that connects your VPC network to London.
  • When you attach HA VPN tunnels to a Network Connectivity Center spoke, you can't connect HA VPN gateways in different regions to each other in the same Google Cloud project. For more information, see Hubs, spokes, and VPC networks.
  • If you have either a Dedicated Interconnect connection or a Partner Interconnect connection configured in a redundant configuration and connected to the same site, you should configure both Interconnect connections together as a single spoke. The redundant VLAN attachments associated with these Interconnect connections must be located in the same Google Cloud region. For more information about redundant configurations, see Best practices for Cloud Interconnect.
  • Configure Interconnect connections from different regions as different spokes.
  • If you have multiple router appliance instances connected to the same site, we recommend that you attach them to the same spoke.

Assigning ASNs to spokes

To simplify your configuration, we recommend that you assign ASNs to spokes in the following way:

  • Use a single Google autonomous system number (ASN) (router.bgp.asn) on Cloud Router for all spoke resources attached to a single hub. For example, the HA VPN tunnels attached to a spoke would use that Google ASN on the Cloud Router that they use for peering. Follow the recommendations for numbering ASNs in the documentation for creating a Cloud Router.
  • Assign a unique peer ASN to each spoke attached to the same hub (router.bgpPeers.asn). Within each spoke, make sure that all peer ASNs are the same. Because if two peers advertise the same prefix with different ASNs or AS paths, only one peer's ASN and AS path is readvertised for that prefix.
  • We recommend configuring AS path loop detection on your peer routers, although this feature is almost always on by default. In some cases, it can't be disabled. For example, when the peer router is Cloud Router or possibly when using routing capabilities from other cloud providers.

    When AS path loop detection is enabled, if two spokes are configured with the same peer ASN, AS path loop detection on a peer router for one spoke drops all prefix advertisements from the other spoke.

In the following example, peer routers in the following spokes advertise the following prefixes and different ASNs:

  • Spoke A; peer router 1, ASN 65001, advertises prefixes 10.1.0.0/16 and 10.2.0.0/16
  • Spoke A: peer router 2, ASN 65002, advertises prefixes 10.1.0.0/16 and 10.3.0.0/16
  • Spoke B; peer router 3, ASN 65003, advertises prefixes 10.1.0.0/16 and 10.4.0.0/16

Cloud Router then advertises the following prefixes to a peer on Spoke C:

  • 10.1.0.0/16, but the AS path could begin with any of these ASNs: 65001 or 65002 or 65003
  • 10.2.0.0/16 with an AS path beginning with 65001
  • 10.3.0.0/16 with an AS path beginning with 65002
  • 10.4.0.0/16 with an AS path beginning with 65003

By making sure that each prefix is advertised by only a single spoke, and that all peers within a spoke have the same ASN, this ambiguity is avoided.

Validate spoke resources

Before you attach one of the preceding resources to a spoke, the resource must be configured correctly.

For information about configuring the resources that are required to create a spoke, see the following documentation:

For information about verifying spoke resources, see the following documentation:

Create a spoke

Use the following guidance to create a new spoke. When you create a spoke, you can also optionally add a description and labels to it.

To add a Router appliance spoke, use the gcloud tool or the API.

Console

Open the Add spokes page and select a network

  1. Go to the Network Connectivity Center page.

    Go to Network Connectivity Center

  2. In the project pull-down menu, select a project.

  3. Click the Spokes tab.

  4. Click Add spokes.

  5. In the Network drop-down list, select a network. All of your hub's spokes must reside in the same VPC network.

Enter basic details about the spoke

  1. In the New spoke form, enter a Spoke name.
  2. Optionally, enter a Description of the spoke.
  3. Continue to one of the following sets of steps to attach resources to the spoke. Each spoke can use only one type of resource. For more information, see Spoke resource types.

Create a VPN tunnel spoke (Option 1)

  1. If you want to attach HA VPN tunnels to this spoke, set the Spoke type drop-down list to VPN tunnels.
  2. Select the Region for the spoke.
  3. Choose a tunnel:
    1. Click Add tunnel.
    2. From the VPN tunnels drop-down menu, select an existing tunnel.
  4. To add more tunnels to this spoke, repeat the preceding step. When you are finished, click Done and continue to Save your spoke.

Create a VLAN attachment spoke (Option 2)

  1. If you want to attach VLAN attachments to this spoke, set the Spoke type drop-down list to VLAN attachments.
  2. Select the Region for the spoke.
  3. Choose an attachment:
    1. Click Add attachment.
    2. From the VLAN attachments drop-down menu, select an existing attachment.
  4. To add more attachments to this spoke, repeat the preceding step. When you are finished, click Done and continue to Save your spoke.

Save your spoke

  1. If you want to add more spokes, click Add spoke and begin the process again, starting with entering a Spoke name.
  2. When you are finished adding spokes, click Create.

    The Network Connectivity Center page updates to show details about spokes that you created.

gcloud

To create a spoke that contains an HA VPN tunnel, enter the following command:

  gcloud alpha network-connectivity spokes create NAME \
    --hub=HUB_NAME \
    --description=DESCRIPTION \
    --vpn-tunnel=TUNNEL_NAME \
    --region=REGION
    --labels=KEY=VALUE

To create a spoke that contains a VLAN attachment, enter the following command:

  gcloud alpha network-connectivity spokes create NAME \
    --hub=HUB_NAME" \
    --description=DESCRIPTION \
    --interconnect-attachment=VLAN_ATTACHMENT_NAME \
    --region=REGION
    --labels=KEY=VALUE

To create a spoke that contains a router appliance instance, enter the following command:

  gcloud alpha network-connectivity spokes create NAME \
    --hub=HUB_NAME \
    --description=DESCRIPTION \
    --router-appliance=ROUTER_APPLIANCE_DETAILS \
    --region=REGION \
    --labels=KEY=VALUE
 

Replace the following values:

  • NAME: the name of the spoke
  • HUB_NAME: the name of the hub, in URI format, that you are attaching the spoke to; for example:
    projects/PROJECT_ID/locations/global/hubs/us-west-to-uk
  • DESCRIPTION: optional text that describes the spoke; for example, us-vpn-spoke
  • Spoke types
    • TUNNEL_NAME: the name of the HA VPN tunnel to add to the spoke
    • VLAN_ATTACHMENT_NAME: the name of the VLAN attachment to add to the spoke
    • ROUTER_APPLIANCE_DETAILS: the URI and IP address of the router appliance instance to add to the spoke—for example,
      instance="https://www.googleapis.com/compute/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME",ip="INTERNAL_IP_ADDRESS"
      
  • REGION: the Google Cloud region where the spoke is located; for example, us-west1
  • KEY: the key in the key:value pair for the label text
  • VALUE: the value in the key:value pair for the label text

API

To create a spoke, use the networkconnectivity.spokes.create method.

When you reference a spoke type in an API call, use a resource URI instead of a name.

  POST https://networkconnectivity.googleapis.com/v1alpha1/projects/PROJECT_ID/locations/REGION/spokes
  {
    "name": NAME,
    "hub": HUB_NAME,
    "labels": {
      "KEY": "VALUE"
    }
    "linkedVpnTunnels": ["TUNNEL_NAME"],
    "linkedInterconnectAttachments": ["VLAN_ATTACHMENT_NAME"],
    "linkedRouterApplianceInstances": {
      "virtual_machine": ["ROUTER_APPLIANCE_NAME],
      "ip_address": INTERNAL_IP_ADDRESS,
      },
   }

Replace the following values:

  • PROJECT_ID: the project ID of the project that contains the spokes
  • REGION: the Google Cloud region where the spoke is located; for example, us-west1
  • NAME: the name of the spoke
  • HUB_NAME: the hub that you are attaching the spoke to.
  • KEY: the key in the key:value pair for the label text
  • VALUE: the value in the key:value pair for the label text
  • Spoke types
    • TUNNEL_NAME: the name of the HA VPN tunnel to add to the spoke
    • VLAN_ATTACHMENT_NAME: the name of the VLAN attachment to add to the spoke
    • ROUTER_APPLIANCE_NAME: the name of the router appliance instance, in URI format, to add to the spoke
    • INTERNAL_IP_ADDRESS: the internal IP address of one of the network interfaces on the router appliance VM

Describing a spoke

To get detailed information about an existing spoke, use the following guidance.

Console

  1. Go to the Network Connectivity Center page.

    Go to Network Connectivity Center

  2. In the project pull-down menu, select a project.

  3. Click the Spokes tab.

  4. In the Spoke name column, select a spoke to view the Spoke details page.

gcloud

Enter the following command:

  gcloud alpha network-connectivity spokes describe NAME \
    --region=REGION

Replace the following values:

  • NAME: the name of the spoke
  • REGION: the region where the spoke is located

API

Use the networkconnectivity.spokes.get method:

 GET https://networkconnectivity.googleapis.com/v1alpha1/projects/PROJECT_ID/locations/REGION/spokes/SPOKE

Replace the following values:

  • PROJECT_ID: the project ID of the project that contains the spoke
  • REGION: the region where the spoke is located; for example, us-west1
  • SPOKE: the name of the spoke

Updating a spoke with labels or a new description

After a spoke has been created, you can update it by adding or changing either of the following:

  • Labels applied to the spoke
  • The spoke's description

You can also set a label or description when you create a hub, as described in Creating a hub.

For more information about labels, see Requirements for labels.

gcloud

To add one or more labels to an existing spoke, enter the following command:

  gcloud alpha network-connectivity spokes update NAME \
    --description=DESCRIPTION \
    --region=REGION
    --labels=KEY=VALUE

Replace the following values:

  • NAME: the name of the spoke
  • DESCRIPTION: a new description for the spoke
  • REGION: the Google Cloud region where the spoke is located; for example, us-west1
  • KEY: the key in the key:value pair for the label text
  • VALUE: the value in the key:value pair for the label text

API

To add a label to an existing spoke, use the networkconnectivity.spokes.patch method with updateMask=labels.

 PATCH https://networkconnectivity.googleapis.com/v1alpha1/projects/PROJECT_ID/locations/REGION/spokes/SPOKE?updateMask=labels
 {
   "labels": {
     "KEY": "VALUE"
   }
 }

Replace the following values:

  • PROJECT_ID: the project ID of the project that contains the spoke
  • REGION: the region where the spoke is located; for example, us-west1
  • SPOKE: the name of the spoke
  • KEY: the key in the key:value pair for the label text
  • VALUE: the value in the key:value pair for the label text

Deleting a spoke

When you delete a spoke, you also detach the resources from that spoke. That is, deleting a spoke does not delete the resources; it only disassociates them from the spoke.

Console

  1. Go to the Network Connectivity Center page.

    Go to Network Connectivity Center

  2. In the project pull-down menu, select a project.

  3. Click the Spokes tab.

  4. View the list of Spoke names for the project.

  5. Select the checkboxes of the spokes that you want to delete.

  6. Click Delete spokes.

  7. In the confirmation dialog, do one of the following:

    • Click Cancel if you don't want to delete the spokes.
    • Click Delete to delete the spokes.

gcloud

To delete a spoke, enter the following command:

  gcloud alpha network-connectivity spokes delete NAME \
    --region=REGION

Replace the following values:

  • NAME: the name of the spoke in the following format: projects/PROJECT_ID/regions/REGION/spokes/NAME
  • REGION: the region where the spoke is located; this option is required in addition to the region listed in the full spoke name

API

To delete an existing spoke, use the networkconnectivity.spokes.delete method.

  DELETE https://networkconnectivity.googleapis.com/v1alpha1/projects/PROJECT_ID/locations/REGION/spokes/SPOKE

Replace the following values:

  • PROJECT_ID: the project ID of the project that contains the spoke to delete
  • REGION: the region where the spoke is located; for example, us-west1
  • SPOKE: the name of the spoke to delete

What's next