Working with hubs and spokes

This page describes how to list, create, describe, and delete Network Connectivity Center hubs and spokes. You can also add one or more labels to a hub or spoke.

For more information about hubs and spokes, see the Network Connectivity Center overview.

For a tutorial that sets up data transfer between two branch offices using Network Connectivity Center, see Connecting two branch offices using Cloud VPN spokes.

Before you begin

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

  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 before issuing commands.
          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 for Network Connectivity Center, you must enable the Network Connectivity API.

To enable the Network Connectivity API:

  1. Follow the general steps for enabling an API.
  2. Search for the Network Connectivity API and enable it.

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
  • Resources attached to a spoke

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

For example, you can refer to a 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 add one or more labels to a hub.

Listing hubs

gcloud

To list existing hubs, enter the following command:

  gcloud alpha network-connectivity hubs list

API

To list existing hubs, 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

gcloud

To create a hub, enter the following command. You can optionally add one or more labels to the hub when you create it.

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. You can optionally add labels to the hub when you create it.

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

To view information about spokes attached to a hub using the gcloud command-line tool or the Network Connectivity API, see the spokes field in the command output. If you want more information about each spoke, use the command to describe each spoke.

gcloud

To get detailed information for 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 for 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 hub name
  • A unique identifier for the hub
  • The time the hub was created and last updated
  • Any labels applied to the hub
  • The URI for spokes attached to the hub
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

To add one or more labels or a description to a new hub, see Creating a hub.

For more information about labels, see Requirements for labels.

gcloud

To add one or more labels to an existing hub or to update the hub's description field, 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 add a label to an existing hub, use the networkconnectivity.hubs.patch method.

For more information about labels, see Requirements for labels.

  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.

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 an existing 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 add one or more labels to a spoke.

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, you can use the hubs describe command.

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 at the gcloud command line or with the API, you must 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 resources attached to it.

Recommendations for attaching multiple resources to a spoke

  • When attaching HA VPN tunnels to a spoke, all tunnels connecting to a single site should be configured together as a single spoke. However, only add tunnels that will send traffic through the Network Connectivity Center hub.
  • 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, it must be configured correctly. For more information about verifying configurations, see the following documents:

Create a spoke

gcloud

To create a spoke that contains an HA VPN tunnel, enter the following command. You can optionally add one or more labels to the spoke.

For more information, see Requirements for labels.

  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

gcloud

To get detailed information for an existing spoke, 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

To get detailed information for an existing spoke, 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

Adding one or more labels to an existing spoke

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.

For more information about labels, see Requirements for 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

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

  • To get details about API and gcloud commands, see APIs and reference.
  • To find solutions for Network Connectivity Center issues, see Troubleshooting.
  • To find support resources for Network Connectivity Center, see Getting support.
  • To learn about the IAM roles and permissions needed to run Network Connectivity Center, see Access control.