Running Connectivity Tests

Learn how to run Connectivity Tests by following the steps on this page.

To edit or delete one or more tests, see Updating or deleting Connectivity Tests.

To learn about Connectivity Tests, see the overview.

Before you begin

Set up the following items in Google Cloud before you use Connectivity Tests:

  1. In the Google Cloud Console, go to the project selector page.

    Go to the project selector page

  2. Select or create a Google Cloud project.
  3. Make sure that billing is enabled for your Cloud project.
  4. Enable the Network Management API.

The procedures in this document include the following:

  • Example API calls that use the Network Management API. For more information, see the API documentation.

  • Sample code that uses the API Python client.

Using the API Python client

The example code in this document assumes that you have constructed a resource named api to interact with the Network Management API. To construct a resource, use the build function.

See the following example:

 from googleapiclient.discovery import build

 api = build('networkmanagement', 'v1')

For more information, see the following:

Using the API Explorer

You can test Network Management API commands by using the API Explorer. In the Network Management API reference document, use the Try this API column to explore API fields and run a test.

Using the gcloud SDK

The gcloud command-line tool is part of the Cloud SDK. To install the latest version of the gcloud command-line tool, see the Cloud SDK documentation.

For a list of all commands, see the gcloudcommand reference.

Obtaining test permissions

For information about permissions that you need to run and view tests, see Access control for Connectivity Tests.

Checking a running test operation

To check the status of a test operation while the operation runs, see Checking a running test operation.

Some examples of test operations are create and rerun.

Running Connectivity Tests

When you run a Connectivity Test, you provide test inputs as a 5-tuple without the source port.

The following sections show you how to run a test for source and destination endpoints described in Common use cases.

From the Google Cloud Console, you can run Connectivity Tests by using either of the following:

  • The Connectivity Tests page, which is available from the Networking > Network Intelligence Center menu.

  • The Network interface details page for a network interface of a Compute Engine virtual machine (VM) instance. If you use this page, you must use the current network interface as either the Source or Destination of the test. This page only lists tests relevant to the current network interface.

Each test that you create runs immediately after you create it and is stored in the Connectivity Tests resource. A test exists until you delete it.

When you use an IP address for the source or destination endpoint, you might need to specify additional fields.

Best practices

  • When you test an endpoint (a VM or IP address) located in a Shared VPC service project, it's more convenient to run the test from the service project. This is because you can select the VM or IP address from the drop-down box in the Cloud Console.

    However, you still must specify the host project before specifying the Virtual Private Cloud (VPC) network, because the network is in the host project. For details, see Testing IP addresses in a Shared VPC network.

  • When running a test between your VPC network and your peer or on-premises network, it can help to run another Connectivity Test by using the on-premises IP address as the source, and a VM instance or IP address in your VPC network as the destination.

    This type of test verifies that Google Cloud is advertising routes as expected to your on-premises network. However, Connectivity Tests doesn't verify that your on-premises network has received and implemented those routes.

  • It takes between 20 and 120 seconds for Connectivity Tests to receive a configuration update and incorporate it into analysis. If you run a test immediately after making a configuration change, you might not see the results that you expect. Make sure that you wait long enough between making the configuration change and running your tests.

    This delay does not apply to dynamic verification. Therefore, you might see a temporary mismatch between the results shown by dynamic verification and configuration analysis. For example, if you add a firewall rule, it might be reachable for dynamic verification. However, you might have to wait for some time before the firewall rule is reachable for configuration analysis.

Testing to or from a VM with multiple network interfaces

This section describes how to test to or from a VM's non-primary network interface.

Console

If you specify a VM instance with multiple network interfaces as the source or destination of a test, Connectivity Tests prompts you to select a network interface from a drop-down menu.

Alternatively, you can run a test from the Network interface details page for a network interface of a Compute Engine VM instance. If you use this page, you must use the current network interface as either the Source or Destination of the test.

gcloud and API

You must specify the network interface to use for the test in one of the following ways:

  • IP address and network URI
  • IP address and VM URI
  • Network URI and VM URI

Providing only the URI for a VM with multiple interfaces selects only the VM's primary interface.

Listing all tests for a project

Console

  1. In the Cloud Console, go to the Connectivity Tests page.

    Go to the Connectivity Tests page

  2. At the top of the page, select a project from the drop-down project menu.
  3. The Connectivity Tests page refreshes and shows you the tests for that project.

gcloud

To list all tests owned by a project, enter the following gcloud command. This command shows tests in the currently selected project.

  gcloud network-management connectivity-tests list

To list tests in a specific project, specify the PROJECT_ID.

  gcloud network-management connectivity-tests list --project=PROJECT_ID

API

To list all existing tests owned by a project, use the networkmanagement.connectivitytests.list method.

GET https://networkmanagement.googleapis.com/v1/{parent=projects/PROJECT_ID/locations/global}/connectivityTests
  • Replace PROJECT_ID with the project ID of the project that contains the tests that you want to list.

Python

The following example code lists all existing tests owned by a project. For more information, see list in the API Python client reference documentation.

project_id = "PROJECT_ID"
parent = 'projects/%s/locations/global' % project_id
request = api.projects().locations().global_().connectivityTests().list(parent=parent)
print(json.dumps(request.execute(), indent=4))

Replace PROJECT_ID with the project ID of the project that contains the tests that you want to list.

Testing between VM instances in a VPC network

These steps assume that both VM instances are in the same Google Cloud project.

Console

From the main Connectivity Tests page

  1. In the Cloud Console, go to the Connectivity Tests page.

    Go to the Connectivity Tests page

  2. Select Create Connectivity Test.
  3. Enter a name for the test.
  4. Select a protocol.
  5. Under Source, select a Source VM instance from the drop-down menu.
    • If the VM instance has multiple network interfaces, select a VM network interface that uniquely identifies the source location.
  6. Under Destination, select a Destination VM instance from the drop-down menu.
    • If the VM instance has multiple network interfaces, select a VM network interface to uniquely identify the destination location.
  7. Enter a destination port.
  8. Click Create.
  9. After the test finishes, the main Connectivity Tests page loads and shows a list that contains this test and other tests. Continue to Viewing test results.

From the Network interface details page

  1. In the Cloud Console, go to the VM instances page.

    Go to the VM instances page

  2. If it is not already selected, select the project that contains the instance for which you want to run a test.
  3. Click the instance that you want to use to run a test.
  4. Under Network interfaces, select the network interface that you want to use to run a test.
  5. Under Network analysis, click Connectivity Tests, and then click Create.
  6. Enter a name for the test.
  7. Select a protocol.
  8. If you want to use the current network interface as the source, select Current network interface under Source. Otherwise, select Current network interface under Destination.
  9. Under the expanded Other field, select a VM instance from the drop-down menu.
    • If the VM instance has multiple network interfaces, select a VM network interface to uniquely identify the destination location.
  10. Enter a destination port for your specified destination.
  11. Click Create.
  12. After the test finishes, the main Connectivity Tests page loads and shows a list that contains this test and other tests. Continue to Viewing test results.

gcloud

To test between VMs in the same Cloud project, enter the following command. Replace the sample values with values from your VPC network.

  gcloud network-management connectivity-tests create NAME \
  --source-instance=SOURCE_INSTANCE
  --destination-instance=DESTINATION_INSTANCE
  --protocol=PROTOCOL

Replace the following values:

  • NAME: the name of the Connectivity Test
  • SOURCE_INSTANCE: the URI for the source VM (for example, projects/myproject/zones/us-east1-b/instances/instance-1)
  • DESTINATION_INSTANCE: the URI for the destination VM (for example, projects/myproject/zones/us-east1-b/instances/instance-2)
  • PROTOCOL: a supported protocol for Connectivity Tests; the default protocol is TCP

API

The following sample test determines if the existing network configuration allows VM instance1to ping VM instance2.

Use the networkmanagement.connectivitytests.create method to create the test.

 POST https: //networkmanagement.googleapis.com/v1/projects/PROJECT_ID/locations/global/connectivityTests?testId=TEST_ID'
   {
     "source": {
     "instance": "SOURCE_INSTANCE",
   },
     "destination": {
     "instance": "DESTINATION_INSTANCE",
   },
     "protocol": "PROTOCOL",
   }'

Replace the following values:

  • PROJECT_ID: the project ID of the source VM
  • TEST_ID: the ID of the Connectivity Tests object (test) that you are running
  • SOURCE_INSTANCE: the URI for the source VM (for example, projects/myproject/zones/us-east1-b/instances/instance-1)
  • DESTINATION_INSTANCE: the URI for the destination VM (for example, projects/myproject/zones/us-east1-b/instances/instance-2)
  • PROTOCOL: a supported protocol for Connectivity Tests; the default protocol is TCP

Python

The following example code creates a test between two VM instances. For more information, see create in the API Python client reference documentation.

test_input = {
  "source": {
      "instance":
          "SOURCE_INSTANCE",
      "projectId":
          "SOURCE_INSTANCE_PROJECT_ID"
  },
  "destination": {
      "instance":
          "DESTINATION_INSTANCE",
      "projectId": "DESTINATION_INSTANCE_PROJECT_ID"
  },
  "protocol": "PROTOCOL",
}

request = api.projects().locations().global_().connectivityTests().create(
    parent="projects/PROJECT_ID/locations/global",
    testId="TEST_ID",
    body=test_input)

print(json.dumps(request.execute(), indent=4))

Replace the following values:

  • SOURCE_INSTANCE: the URI for the source VM (for example, projects/myproject/zones/us-east1-b/instances/instance-1)
  • SOURCE_INSTANCE_PROJECT_ID: the project ID of the source VM
  • DESTINATION_INSTANCE: the URI for the destination VM (for example, projects/myproject/zones/us-east1-b/instances/instance-2)
  • DESTINATION_INSTANCE_PROJECT_ID: the project ID of the destination VM
  • PROTOCOL: a supported protocol for Connectivity Tests; the default protocol is TCP
  • PROJECT_ID: the project ID of the project in which you are creating the test
  • TEST_ID: the ID of the Connectivity Tests object (test) that you are running

Testing between private IP addresses in a VPC network

This example assumes that both IP addresses are private IP addresses in the same Cloud project and in the same VPC network.

If you are testing between peered VPC networks, select the source and destination networks for each peer.

Console

  1. In the Cloud Console, go to the Connectivity Tests page.

    Go to the Connectivity Tests page

  2. Select Create Connectivity Test.
  3. Enter a name for the test.
  4. Select a protocol.
  5. Under Source IP or instance, select IP address, and then enter an IP address.
    1. Select the This is an IP address used in Google Cloud checkbox.
    2. If this is an internal IP address, not accessible from the internet, select the VPC network where the address is located.
  6. Under Destination IP or instance, select IP address, and then enter an IP address.
    1. Select the This is an IP address used in Google Cloud checkbox.
    2. If this is an internal IP address, not accessible from the internet, select the VPC network where the address is located.
  7. Enter a destination port.
  8. Click Create.
  9. After the test finishes, the main Connectivity Tests page loads and shows a list that contains this test and other tests. Continue to Viewing test results.

gcloud

Enter the following command to test between two internal IP addresses in the same project and network. Replace variables for the command options with values from your VPC network.

  gcloud network-management connectivity-tests create NAME \
  --source-ip-address=SOURCE_IP_ADDRESS \
  --source-network=SOURCE_NETWORK
  --destination-ip-address=DESTINATION_IP_ADDRESS \
  --destination-network=DESTINATION_NETWORK \
  --protocol=PROTOCOL

Replace the following values:

  • NAME: the name of the Connectivity Test
  • SOURCE_IP_ADDRESS: the internal or external source IP address that you are testing from; an IPv6 address is only allowed when the test's destination is a global load balancer VIP
  • SOURCE_NETWORK: the URI for the VPC network where the source IP address is located (for example, projects/myproject/global/networks/default)
  • DESTINATION_IP_ADDRESS: the internal or external destination IP address that you are testing to; an IPv6 address is only allowed when the test's destination is a global load balancer VIP
  • DESTINATION_NETWORK: the URI for the VPC network where the destination IP address is located (for example, projects/myproject/global/networks/network-a)
  • PROTOCOL: a supported protocol for Connectivity Tests; the default protocol is TCP

If the network is unknown, or you don't have permission to access the network, you can specify the network as GCP_NETWORK, instead of providing a network URI.

  gcloud network-management connectivity-tests create NAME \
  --source-ip-address=SOURCE_IP_ADDRESS \
  --source-network-type=GCP_NETWORK \
  --destination-instance=DESTINATION_INSTANCE  \
  --protocol=PROTOCOL

Replace the following values:

  • NAME: the name of the Connectivity Test
  • SOURCE_IP_ADDRESS: the internal or external source IP address that you are testing from; an IPv6 address is only allowed when the test's destination is a global load balancer VIP
  • SOURCE_NETWORK_TYPE: the type of network where the source is located; in this case, use a value of GCP_NETWORK
  • DESTINATION_INSTANCE: the URI for the destination VM (for example, projects/myproject/zones/us-east1-b/instances/instance-2)
  • PROTOCOL: a supported protocol for Connectivity Tests; the default protocol is TCP

When you specify a private IP address from outside of Google Cloud as the source IP address, you must specify a networkType of NON_GCP_NETWORK. Replace the values in the following command with values from your VPC network.

  gcloud network-management connectivity-tests create NAME \
  --source-ip-address=SOURCE_IP_ADDRESS \
  --source-network-type=NON_GCP_NETWORK \
  --destination-ip-address= DESTINATION_IP_ADDRESS \
  --destination-network=DESTINATION_NETWORK \
  --destination-port=DESTINATION_PORT \
  --protocol=PROTOCOL

Replace the following values:

  • NAME: the name of the Connectivity Test
  • SOURCE_IP_ADDRESS: the internal or external source IP address that you are testing from; an IPv6 address is only allowed when the test's destination is a global load balancer VIP
  • SOURCE_NETWORK_TYPE: the type of network where the source is located; in this case, use a value of NON_GCP_NETWORK
  • DESTINATION_IP_ADDRESS: the internal or external destination IP address that you are testing to; an IPv6 address is only allowed when the test's destination is a global load balancer VIP
  • DESTINATION_NETWORK: a URI for the VPC network where the destination IP address is located (for example, projects/myproject/global/networks/default)
  • DESTINATION_PORT: the IP protocol port of the destination; this option is valid only for TCP or UDP protocols; the default is port 80
  • PROTOCOL: a supported protocol for Connectivity Tests; the default protocol is TCP

API

This example tests the ability to ping from the source IP address to the destination IP address.

Use the networkmanagement.connectivitytests.create method to create the test.

  POST https://reachability.googleapis.com/v1/projects/PROJECT_ID/locations/global/connectivityTests?testId=TEST_ID'
  {
    "source": {
      "ipAddress": "SOURCE_IP_ADDRESS",
      "network": "SOURCE_NETWORK"
    },
    "destination": {
      "ipAddress": "DESTINATION_IP_ADDRESS",
      "network": "DESTINATION_NETWORK",
      "port": "DESTINATION_PORT",
    },
      "protocol": "PROTOCOL".
  }'

Replace the following values:

  • PROJECT_ID: the project ID of the source VM
  • TEST_ID: the ID of the Connectivity Tests object (test) that you are running
  • SOURCE_IP_ADDRESS: the internal or external source IP address that you are testing from; an IPv6 address is only allowed when the test's destination is a global load balancer VIP
  • SOURCE_NETWORK: the URI for the VPC network where the source IP address is located (for example, projects/myproject/global/networks/default)
  • DESTINATION_IP_ADDRESS: the internal or external destination IP address that you are testing to; an IPv6 address is only allowed when the test's destination is a global load balancer VIP
  • DESTINATION_NETWORK: a URI for the VPC network where the destination IP address is located (for example, projects/myproject/global/networks/network-a)
  • DESTINATION_PORT: the IP protocol port of the destination; this option is valid only for TCP or UDP protocols; the default is port 80
  • PROTOCOL: a supported protocol for Connectivity Tests; the default protocol is TCP

If the VPC network is unknown, or you don't have permission to access the network, you can specify the network as GCP_NETWORK, instead of providing a network URI.

  POST https://reachability.googleapis.com/v1/projects/PROJECT_ID/locations/global/connectivityTests?connectivityTestId=TEST_ID'
  {
    "source": {
      "ipAddress": "SOURCE_IP_ADDRESS",
      "networkType": "GCP_NETWORK"
    },
    "destination": {
      "instance": "projects/myproject/zones/us-east1-b/instances/instance-2 ",
    },
    "protocol": "PROTOCOL"
  }'

Replace the following values:

  • PROJECT_ID: the project ID of the source VM
  • TEST_ID: the ID of the Connectivity Tests object (test) that you are running
  • SOURCE_IP_ADDRESS: the internal or external source IP address that you are testing from; an IPv6 address is only allowed when the test's destination is a global load balancer VIP
  • SOURCE_NETWORK_TYPE: the type of network where the source is located; in this case, use a value of GCP_NETWORK
  • DESTINATION_INSTANCE: the URI for the destination VM (for example, projects/myproject/zones/us-east1-b/instances/instance-2)
  • PROTOCOL: a supported protocol for Connectivity Tests; the default protocol is TCP

When you specify a private IP address from outside of Google Cloud as the source IP address, you must specify a networkType of NON_GCP_NETWORK. Replace the values in the following command with values for your Google Cloud network.

  POST https://reachability.googleapis.com/v1/projects/PROJECT_ID/locations/global/connectivityTests?testId=TEST_ID'
  {
    "source": {
      "ipAddress": "SOURCE_IP_ADDRESS",
      "networkType": "NON_GCP_NETWORK",

    },
    "destination": {
      "ipAddress": "DESTINATION_IP_ADDRESS",
      "network": "DESTINATION_NETWORK",
      "port": "DESTINATION_PORT",
    },
    "protocol": "PROTOCOL",
  }'

Python

The following example code creates a test between two IP addresses. For more information, see create in the API Python client reference documentation.

test_input = {
  "source": {
      "ipAddress": "SOURCE_IP_ADDRESS",
      "projectId": "SOURCE_IP_PROJECT_ID"
  },
  "destination": {
      "ipAddress": "DESTINATION_IP_ADDRESS",
      "port": "DESTINATION_PORT",
      "projectId": "DESTINATION_IP_PROJECT_ID"
  },
  "protocol": "PROTOCOL",
}

request = api.projects().locations().global_().connectivityTests().create(
    parent="projects/PROJECT_ID/locations/global",
    testId="TEST_ID",
    body=test_input)

print(json.dumps(request.execute(), indent=4))

Replace the following values:

  • SOURCE_IP_ADDRESS: the internal or external source IP address that you are testing from; an IPv6 address is only allowed when the test's destination is a global load balancer VIP
  • SOURCE_IP_PROJECT_ID: the project ID for the source IP address
  • DESTINATION_IP_ADDRESS: the internal or external destination IP address that you are testing to; an IPv6 address is only allowed when the test's destination is a global load balancer VIP
  • DESTINATION_PORT: the IP protocol port of the destination; this option is valid only for TCP or UDP protocols; the default is port 80
  • DESTINATION_IP_PROJECT_ID: the project ID for the destination IP address
  • PROTOCOL: a supported protocol for Connectivity Tests; the default protocol is TCP
  • PROJECT_ID: the project ID of the project in which you are creating the test
  • TEST_ID: the ID of the Connectivity Tests object (test) that you are running

If the VPC network is unknown, or you don't have permission to access the network, you can specify the network as GCP_NETWORK, instead of providing a network URI. See the following example code:

test_input = {
    "source": {
        "ipAddress": "SOURCE_IP_ADDRESS",
        "networkType": "GCP_NETWORK"
    },
    "destination": {
        "ipAddress": "DESTINATION_IP_ADDRESS",
        "port": "DESTINATION_PORT",
        "projectId": "DESTINATION_IP_PROJECT_ID"
    },
    "protocol": "PROTOCOL",
}

request = api.projects().locations().global_().connectivityTests().create(
  parent="projects/PROJECT_ID/locations/global",
  testId="TEST_ID",
  body=test_input)

print(json.dumps(request.execute(), indent=4))

Replace the following values:

  • SOURCE_IP_ADDRESS: the internal or external source IP address that you are testing from; an IPv6 address is only allowed when the test's destination is a global load balancer VIP
  • SOURCE_NETWORK_TYPE: the type of network where the source is located; in this case, use a value of GCP_NETWORK
  • DESTINATION_IP_ADDRESS: the IP address of the destination VM
  • DESTINATION_PORT: the IP protocol port of the destination; this option is valid only for TCP or UDP protocols; the default is port 80
  • DESTINATION_IP_PROJECT_ID: the project ID for the destination IP address
  • PROTOCOL: a supported protocol for Connectivity Tests; the default protocol is TCP
  • PROJECT_ID: the project ID of the project in which you are creating the test
  • TEST_ID: the ID of the Connectivity Tests object (test) that you are running

When you specify a private IP address from outside of Google Cloud as the source IP address, you must specify a networkType of NON_GCP_NETWORK.

Testing IP addresses in a Shared VPC network

When you have a Shared VPC network, you can create and run a test from the host project or from the service project.

The following example shows both cases and uses a destination IP address allocated in the service project. The field values in the Cloud Console are slightly different for each case. However, the command options for the gcloud command-line and for API calls are the same.

Console: from host

  1. In the Cloud Console, from the host project, go to the Connectivity Tests page.

    Go to the Connectivity Tests page

  2. Select Create Connectivity Test.
  3. Enter a name for the test.
  4. Select a protocol.
  5. Under Source IP or instance, select IP address, and then enter an IP address.
    1. Make sure that the This is an IP address used in Google Cloud checkbox is selected.
    2. Select the source instance or IP address.
  6. Under Destination IP or instance, select IP address, and then enter an IP address.
    1. Make sure that the This is an IP address used in Google Cloud checkbox is selected.
    2. Specify the Service project where the IP address is located.
    3. Select the Network in the host (current) project where the IP address is located.
  7. Enter a destination port.
  8. Click Create.
  9. After the test finishes, the main Connectivity Tests page loads and shows a list that contains this test and other tests. Continue to Viewing test results.

Console: from service

  1. In the Cloud Console, from the service project, go to the Connectivity Tests page.

    Go to the Connectivity Tests page

  2. Select Create Connectivity Test.
  3. Enter a name for the test.
  4. Select a protocol. During the beta period, only the protocols shown in the menu are available.
  5. Under Source IP or instance, select IP address, and then enter an IP address.
    1. Make sure that the This is an IP address used in Google Cloud checkbox is selected.
  6. Under Destination IP or instance, select IP address, and then enter an IP address.
    1. Make sure that the This is an IP address used in Google Cloud checkbox is selected.
    2. Specify the Service project where the IP address is located.
    3. Select the Network is in a project other than the current project checkbox.
    4. Select the Host project.
    5. Select the Network where the IP address is located.
  7. Enter a destination port.
  8. Click Create.
  9. After the test finishes, the main Connectivity Tests page loads and shows a list that contains this test and other tests. Continue to Viewing test results.

gcloud

Enter the following command to test between two private IP addresses in a host and in a service project where the destination IP address is located in the service project. Replace variables for the command options with values from your VPC network.

Because the destination IP address is in the service project, specify the service project and the network URI of the host project. In this case, default represents the default VPC network for the host-project.

  gcloud network-management connectivity-tests create NAME \
  --source-ip-address=SOURCE_IP_ADDRESS \
  --source-project=SOURCE_PROJECT \
  --destination-ip-address=DESTINATION_IP_ADDRESS \
  --destination-network=DESTINATION_NETWORK  \
  --destination-project=DESTINATION_PROJECT \
  --destination-port=DESTINATION_PORT \
  --protocol=PROTOCOL

Replace the following values:

  • NAME: the name of the Connectivity Test
  • SOURCE_IP_ADDRESS: the internal or external source IP address that you are testing from; an IPv6 address is only allowed when the test's destination is a global load balancer VIP
  • SOURCE_PROJECT: the project ID of the source endpoint
  • DESTINATION_IP_ADDRESS: the internal or external destination IP address that you are testing to in the service project; an IPv6 address is only allowed when the test's destination is a global load balancer VIP
  • DESTINATION_NETWORK: a URI for the VPC network for the host project (for example, projects/host-project/global/networks/default)
  • DESTINATION_PROJECT: the project ID of the destination endpoint (for example, a project called service-project that represents the service project used for this Shared VPC network)
  • DESTINATION_PORT: the IP protocol port of the destination; this option is valid only for TCP or UDP protocols; the default is port 80
  • PROTOCOL: a supported protocol for Connectivity Tests; the default protocol is TCP

API

Use the networkmanagement.connectivitytests.create method to create the test.

  POST https: //networkmanagement.googleapis.com/v1/projects/PROJECT_ID/locations/global/connectivityTests?testId=TEST_ID'
    {
      "source": {
        "ipAddress": "SOURCE_IP_ADDRESS",
        "projectId": "SOURCE_PROJECT",
      },
      "destination": {
        "ipAddress": "DESTINATION_IP_ADDRESS",
        "projectId": "DESTINATION_PROJECT",
        "network": "DESTINATION_NETWORK",
        "port": "DESTINATION_PORT",
      },
      "protocol": "PROTOCOL",
    }'

Replace the following values:

  • PROJECT_ID: the project ID of the source VM
  • TEST_ID: the ID of the Connectivity Tests object (test) that you are running
  • SOURCE_IP_ADDRESS: the internal or external source IP address that you are testing from; an IPv6 address is only allowed when the test's destination is a global load balancer VIP
  • SOURCE_PROJECT: the project ID of the source endpoint
  • DESTINATION_IP_ADDRESS: the internal or external destination IP address that you are testing to in the service project; an IPv6 address is only allowed when the test's destination is a global load balancer VIP
  • DESTINATION_PROJECT: the project ID of the destination endpoint; (for example, a project called service-project that represents the service project used for this Shared VPC network)
  • DESTINATION_NETWORK: a URI for the VPC network for the host project (for example, projects/host-project/global/networks/default)
  • DESTINATION_PORT: the IP protocol port of the destination; this option is valid only for TCP or UDP protocols; the default is port 80
  • PROTOCOL: a supported protocol for Connectivity Tests; the default protocol is TCP

Python

The following example code creates a test between two IP addresses. For more information, see create in the API Python client reference documentation.

test_input = {
  "source": {
      "ipAddress": "SOURCE_IP_ADDRESS",
      "projectId": "SOURCE_IP_PROJECT_ID"
  },
  "destination": {
      "ipAddress": "DESTINATION_IP_ADDRESS",
      "projectId": "DESTINATION_IP_PROJECT_ID",
      "network": "DESTINATION_NETWORK",
      "port": "DESTINATION_PORT",
  },
  "protocol": "PROTOCOL",
}

request = api.projects().locations().global_().connectivityTests().create(
    parent="projects/PROJECT_ID/locations/global",
    testId="TEST_ID",
    body=test_input)

print(json.dumps(request.execute(), indent=4))

Replace the following values:

  • SOURCE_IP_ADDRESS: the internal or external source IP address that you are testing from; an IPv6 address is only allowed when the test's destination is a global load balancer VIP
  • SOURCE_IP_PROJECT_ID: the project ID of the source endpoint
  • DESTINATION_IP_ADDRESS: the internal or external destination IP address that you are testing to in the service project; an IPv6 address is only allowed when the test's destination is a global load balancer VIP
  • DESTINATION_IP_PROJECT_ID: the project ID of the destination endpoint (for example, a project called service-project that represents the service project used for this Shared VPC network)
  • DESTINATION_NETWORK: a URI for the VPC network for the host project (for example, projects/host-project/global/networks/default)
  • DESTINATION_PORT: the IP protocol port of the destination; this option is valid only for TCP or UDP protocols; the default is port 80
  • PROTOCOL: a supported protocol for Connectivity Tests; the default protocol is TCP
  • PROJECT_ID: the project ID of the project in which you are creating the test
  • TEST_ID: the ID of the Connectivity Tests object (test) that you are running

Testing from a VM to a Google-managed service (alpha)

This section describes how to test from a VM in your VPC network to a service that runs in a Google-owned VPC network. For example , you can follow the steps in this section to test connectivity to a Cloud SQL instance or a GKE master. You can also run a test using a Google-managed service endpoint as the source and an endpoint in your VPC network as the destination.

By default, Connectivity Tests attempts to run a test using the private IP address of the Google-managed service endpoint. If the endpoint does not have a private IP address, Connectivity Tests uses the public IP address. Connectivity Tests analyzes whether the packet can reach the endpoint, which includes analyzing the configuration within the Google-owned VPC network. If configuration issues are detected within your project, the analysis stops before analyzing the Google-owned network configuration.

To test from a VM to a Google-managed service, see the following instructions.

Console

From the main Connectivity Tests page

  1. In the Cloud Console, go to the Connectivity Tests page.

    Go to the Connectivity Tests page

  2. Select Create Connectivity Test.
  3. Enter a name for the test.
  4. Select a protocol.
  5. Under Source, select a Source VM instance from the drop-down menu.
    • If the VM instance has multiple network interfaces, select a VM network interface that uniquely identifies the source location.
  6. Under Destination, select a type of Google-managed service resource from the Destination endpoint drop-down menu, such as GKE master cluster.
    1. Use the additional drop-down menu to the right to select the specific endpoint. For example, if you selected GKE master cluster, select the cluster for which you want to test connectivity to the cluster master.
  7. Enter a destination port.
  8. Click Create.
  9. After the test finishes, the main Connectivity Tests page loads and shows a list that contains this test and other tests. Continue to Viewing test results.

From the Network interface details page

  1. In the Cloud Console, go to the VM instances page.

    Go to the VM instances page

  2. If it is not already selected, select the project that contains the instance for which you want to run a test.
  3. Click the instance that you want to use to run a test.
  4. Under Network interfaces, select the network interface that you want to use to run a test.
  5. Under Network analysis, click Connectivity Tests, and then click Create.
  6. Enter a name for the test.
  7. Select a protocol.
  8. Select Current network interface under Source.
  9. Under Destination , select a type of Google-managed service resource from the Destination endpoint drop-down menu, such as GKE master cluster.
    1. Use the additional drop-down menu to the right to select the specific endpoint. For example, if you selected GKE master cluster, select the cluster for which you want to test connectivity to the cluster master.
  10. Enter a destination port for your specified destination.
  11. Click Create.
  12. After the test finishes, the main Connectivity Tests page loads and shows a list that contains this test and other tests. Continue to Viewing test results.

gcloud

To test from a VM in your VPC network to a Google-managed service, enter the following command. Replace the variables for the command options according to the following guidance:

  gcloud beta network-management connectivity-tests create NAME \
  --source-instance=SOURCE_INSTANCE \
  DESTINATION_RESOURCE_FLAG=DESTINATION_ENDPOINT \
  --destination-port=DESTINATION_PORT \
  --protocol=PROTOCOL

Replace the following values:

  • NAME: the name of the Connectivity Test
  • SOURCE_INSTANCE: the URI for the source VM (for example, projects/myproject/zones/us-east1-b/instances/instance-1)
  • DESTINATION_RESOURCE_FLAG: the flag that specifies the type of Google-managed service resource; see the following list for available options and the gcloud beta network-management connectivity-tests create reference for more information:
    • --destination-gke-master-cluster
    • --destination-cloud-sql-instance
  • DESTINATION_ENDPOINT: the URI for the destination endpoint (for example, projects/myproject/locations/us-central1/clusters/cluster-1 for the flag --destination-gke-master-cluster)
  • DESTINATION_PORT: the IP protocol port of the destination; this option is valid only for TCP or UDP protocols; the default is port 80
  • PROTOCOL: a supported protocol for Connectivity Tests; the default protocol is TCP

API

The following example tests connectivity from a VM in your VPC network to a Google-managed service.

Use the networkmanagement.connectivitytests.create method to create the test.

 POST https: //networkmanagement.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/connectivityTests?testId=TEST_ID'
   {
     "source": {
     "instance": "SOURCE_INSTANCE",
   },
     "destination": {
     "DESTINATION_RESOURCE_FIELD": "DESTINATION_ENDPOINT",
     "port": DESTINATION_PORT
   },
     "protocol": "PROTOCOL",
   }'

Replace the following values:

  • PROJECT_ID: the project ID of the source VM
  • TEST_ID: the ID of the Connectivity Tests object (test) that you are running
  • SOURCE_INSTANCE: the URI for the source VM (for example, projects/myproject/zones/us-east1-b/instances/instance-1)
  • DESTINATION_RESOURCE_FIELD: the field that specifies the type of Google-managed service resource; see the following list for available options and the Endpoint reference for more information:
    • gkeMasterCluster
    • cloudSqlInstance
  • DESTINATION_ENDPOINT: the URI for the destination endpoint (for example, projects/myproject/locations/us-central1/clusters/cluster-1 for the field gkeMasterCluster)
  • DESTINATION_PORT: the IP protocol port of the destination; this option is valid only for TCP or UDP protocols; the default is port 80
  • PROTOCOL: a supported protocol for Connectivity Tests; the default protocol is TCP

Python

The following example code creates a test between a VM instance and a Google-managed service endpoint. For more information, see create in the API Python client reference documentation.

test_input = {
  "source": {
      "instance":
          "SOURCE_INSTANCE",
      "projectId":
          "SOURCE_INSTANCE_PROJECT_ID"
  },
  "destination": {
      "DESTINATION_RESOURCE_FIELD":
          "DESTINATION_ENDPOINT",
      "port": "DESTINATION_PORT"
  },
  "protocol": "PROTOCOL",
}

request = api.projects().locations().global_().connectivityTests().create(
    parent="projects/PROJECT_ID/locations/global",
    testId="TEST_ID",
    body=test_input)

print(json.dumps(request.execute(), indent=4))

Replace the following values:

  • SOURCE_INSTANCE: the URI for the source VM (for example, projects/myproject/zones/us-east1-b/instances/instance-1)
  • SOURCE_INSTANCE_PROJECT_ID: the project ID of the source VM
  • DESTINATION_RESOURCE_FIELD: the field that specifies the type of Google-managed service resource; see the following list for available options and the Endpoint reference for more information:
    • gkeMasterCluster
    • cloudSqlInstance
  • DESTINATION_ENDPOINT: the URI for the destination endpoint (for example, projects/myproject/locations/us-central1/clusters/cluster-1 for the field gkeMasterCluster)
  • DESTINATION_PORT: the IP protocol port of the destination; this option is valid only for TCP or UDP protocols; the default is port 80
  • PROTOCOL: a supported protocol for Connectivity Tests; the default protocol is TCP
  • PROJECT_ID: the project ID of the project in which you are creating the test
  • TEST_ID: the ID of the Connectivity Tests object (test) that you are running

Testing from a VPC network to a non-Google Cloud network

This procedure is the same as the Testing between private IP addresses in a VPC network procedure except for the following steps. See this procedure for Cloud Console, the gcloud command-line tool, API examples, and Python examples.

  1. Specify an external IP address for the destination IP.
  2. In the Cloud Console, leave the This is an IP address used in Google Cloud checkbox cleared.

Testing from a non-Google Cloud network to a VPC network

This procedure is the same as the Testing between private IP addresses in a VPC network procedure except for the following steps. See this procedure for Cloud Console, the gcloud command-line tool, API examples, and Python examples.

  1. If the source address is not located in Google Cloud, but is not from your peer (on-premises) network, specify an external IP address.
  2. If the source address is from your peer (on-premises) network, you must select Other non-GCP network.

Viewing test results

This section describes how to view the results of a Connectivity Test.

Console

You can view a test from several different pages.

From the main Connectivity Tests page

  1. In the Cloud Console, go to the Connectivity Tests page.

    Go to the Connectivity Tests page

  2. Under the Result details column, choose a test, and then click View.
  3. The info panel for the test appears. You can view the overall result and the result cards for each Google Cloud resource in the testing path. You can click a link to the details page for some Google Cloud resources, such as VM instances or routes. If the test contains multiple traces, you can select a trace from the Trace result drop-down menu.
  4. To expand or close a results card, click the arrow at the right of the card.
  5. To interpret test results, see the Test states reference.
  6. To close the info panel, at the top right of the page, click Hide info panel.

From the Connectivity Test details page

Alternatively, from the main Cloud Console page, click the name of a test and view its results on the Connectivity Test details page.

From the Network interface details page

You can also view results from the Network interface details page for a network interface of a Compute Engine VM instance. This page only lists tests that use the current network interface as a source or destination.

To view results, you can select View under the Result details column, or click the name of the test.

gcloud

To view the results of a test, enter the following command. Use the test ID that you want to view.

  gcloud network-management connectivity-tests describe NAME

Replace NAME with the name of the Connectivity Test.

API

Use the networkmanagement.connectivitytests.get method to view the results of a test.

GET https://networkmanagement.googleapis.com/v1/{name=projects/PROJECT_ID/locations/global/connectivityTests/TEST_ID

Replace the following values:

  • PROJECT_ID: the project ID of the source VM
  • TEST_ID: the ID of the Connectivity Tests object (test) that you are running

Python

The following example code prints the results of a test. For more information, see get in the API Python client reference documentation.

project_id = "PROJECT_ID"
test_id= "TEST_ID"
request = api.projects().locations().global_().connectivityTests().get(
      name='projects/%s/locations/global/connectivityTests/%s' %
      (project_id, test_id))
print(json.dumps(request.execute(), indent=4))

Replace the following values:

  • PROJECT_ID: the project ID of the project in which the test was created
  • TEST_ID: the ID of the Connectivity Tests object (test) that you are running

Rerunning one or more tests

You might want to rerun a Connectivity Test if you make configuration changes to the Google Cloud resources in the testing path and want to see results for the latest network configuration. You can rerun one or more tests at the same time.

A Connectivity Test is based on a snapshot of the network configuration at the time of execution. Rerunning a test overwrites the previous test results. If you want to preserve older results, create a new test instead.

Console

From the main Connectivity Tests page

  1. In the Cloud Console, go to the Connectivity Tests page.

    Go to the Connectivity Tests page

  2. Select the checkbox to the left of one or more tests that you want to rerun.
  3. At the top of the page, click Rerun .

From the Connectivity Test details page

  1. From the preceding main Connectivity Tests page, click the name of a test.
  2. At the top of the Connectivity Test details page, click Rerun .

From the Network interface details page

  1. In the Cloud Console, go to the VM instances page.

    Go to the VM instances page

  2. If it is not already selected, select the project that contains the instance for which you want to rerun a test.
  3. Click the instance that you want to use to rerun a test.
  4. Under Network interfaces, select the network interface that you want to use to rerun a test.
  5. Under Network analysis, click Connectivity Tests.
  6. Select the checkbox to the left of one or more tests that you want to rerun.
  7. At the top of the list of tests, click Rerun .

gcloud

To rerun a Connectivity Test, enter the following command. Use the test ID that you want to rerun.

  gcloud network-management connectivity-tests rerun NAME

Replace NAME with the name of the Connectivity Test.

API

When the Network Management API creates a connectivityTests resource, it retains that test resource until you delete it. Because of this, you can rerun tests.

If you don't want to create persistent tests, you can use the API to create a test and delete it after viewing the test result.

Use the networkmanagement.connectivitytests.rerun method to rerun a test.

  POST https://networkmanagement.googleapis.com/v1/{name=projects/*/locations/global/connectivityTests/*}:rerun
    {
      "name": {projects/PROJECT_ID/connectivityTests/{TEST_ID}
    }

Replace the following values:

  • PROJECT_ID: the project ID of the source VM
  • TEST_ID: the ID of the Connectivity Tests object (test) that you are running

Python

The following example code reruns a test. For more information, see rerun in the API Python client reference documentation.

project_id = "PROJECT_ID"
test_id = "TEST_ID"
request = api.projects().locations().global_().connectivityTests().rerun(name='projects/%s/locations/global/connectivityTests/%s' %       (project_id, test_id))
print(json.dumps(request.execute(), indent=4))

Replace the following values:

  • PROJECT_ID: the project ID of the project in which the test was created
  • TEST_ID: the ID of the Connectivity Tests object (test) that you are running

What's next