Roles and permissions

This page describes the Identity and Access Management (IAM) roles and permissions needed for running Connectivity Tests.

You can grant users or service accounts permissions or predefined roles, or you can create a custom role that uses permissions that you specify.

The IAM permissions use a prefix of networkmanagement.

To get or set IAM policies, or to test IAM permissions with the Network Management API, see Manage access policies.

Roles

This section describes how to use predefined and custom roles when granting permissions for Connectivity Tests.

For an explanation of each permission, see the permissions table.

For more information about project roles and Google Cloud resources, see the following documentation:

Predefined roles

Connectivity Tests has the following predefined roles:

  • networkmanagement.admin has permission to perform all operations on a test resource.
  • networkmanagement.viewer has permission to list or get a specific test resource.

The following table lists the predefined roles and the permissions that apply to each role.

Role Permissions

(roles/networkmanagement.admin)

Full access to Network Management resources.

Lowest-level resources where you can grant this role:

  • Project

networkmanagement.*

  • networkmanagement.connectivitytests.create
  • networkmanagement.connectivitytests.delete
  • networkmanagement.connectivitytests.get
  • networkmanagement.connectivitytests.getIamPolicy
  • networkmanagement.connectivitytests.list
  • networkmanagement.connectivitytests.rerun
  • networkmanagement.connectivitytests.setIamPolicy
  • networkmanagement.connectivitytests.update
  • networkmanagement.locations.get
  • networkmanagement.locations.list
  • networkmanagement.operations.cancel
  • networkmanagement.operations.delete
  • networkmanagement.operations.get
  • networkmanagement.operations.list
  • networkmanagement.vpcflowlogsconfigs.create
  • networkmanagement.vpcflowlogsconfigs.delete
  • networkmanagement.vpcflowlogsconfigs.get
  • networkmanagement.vpcflowlogsconfigs.list
  • networkmanagement.vpcflowlogsconfigs.update

resourcemanager.organizations.get

resourcemanager.projects.get

resourcemanager.projects.list

(roles/networkmanagement.viewer)

Read-only access to Network Management resources.

Lowest-level resources where you can grant this role:

  • Project

networkmanagement.connectivitytests.get

networkmanagement.connectivitytests.getIamPolicy

networkmanagement.connectivitytests.list

networkmanagement.locations.*

  • networkmanagement.locations.get
  • networkmanagement.locations.list

networkmanagement.operations.get

networkmanagement.operations.list

networkmanagement.vpcflowlogsconfigs.get

networkmanagement.vpcflowlogsconfigs.list

resourcemanager.organizations.get

resourcemanager.projects.get

resourcemanager.projects.list

Custom roles

You can create custom roles by selecting a list of permissions from the permissions table for Connectivity Tests.

For example, you can create a role called reachabilityUsers, and grant the list, get, and rerun permissions to this role. A user with this role can rerun existing Connectivity Tests and view updated test results based on the latest network configuration.

Project roles

You can use project roles to set permissions to Google Cloud resources. Because Connectivity Tests must have read access to the Google Cloud resource configurations in your Virtual Private Cloud (VPC) network to run a test, you must grant at least the Compute Network Viewer role (roles/compute.networkViewer) to users or service accounts running a test against those resources. You can also create a custom role or temporarily authorize permissions associated with the preceding role for a specific user.

Alternatively, you can grant a user or service account one of the following predefined roles for Google Cloud projects:

Permissions

This section describes permissions for Connectivity Tests and how to use them when testing different types of network configurations.

Connectivity Tests permissions

Connectivity Tests has the following IAM permissions.

Permission Description
networkmanagement.connectivitytests.list Lists all tests configured in the specified project.
networkmanagement.connectivitytests.get Gets the details of a specific test.
networkmanagement.connectivitytests.create Creates a new test object in the specified project with the data that you specify for the test. This permission includes permission to update, rerun, or delete tests.
networkmanagement.connectivitytests.update Updates one or more fields in an existing test.
networkmanagement.connectivitytests.delete Deletes the specified test.
networkmanagement.connectivitytests.rerun Reruns a one-time reachability verification for a specified test.

If you don't have permission to create or update a test, the corresponding buttons are inactive. These include the Create connectivity test button and, on the Connectivity test details page, the Edit button. In each case, when you hold the pointer over the inactive button, Connectivity Tests displays a message describing the permission that you need.

Permissions for running a test

You need the following roles and permissions to run a test:

  • networkmanagement.connectivitytests.create permission (or networkmanagement.connectivitytests.rerun) in a project with a Connectivity Tests resource.
  • Compute Network Viewer role (roles/compute.networkViewer) or the legacy Viewer role (roles/viewer) to all the projects included in the trace path.

Note the following additional considerations with different types of connectivity options.

VPC Network Peering, Network Connectivity Center, or Cloud VPN connectivity

If the trace path includes VPC Network Peering, Network Connectivity Center, or Cloud VPN connectivity to a network in a different project, a packet path in that network is simulated only if you have permissions to that project. Otherwise, an incomplete test result is returned (for example, a trace ending with the Forward final state).

Shared VPC projects

If a source or destination endpoint (such as a virtual machine (VM) instance) uses Shared VPC, you must have permission to access both the host and service projects.

  • If you have permission to access both the host and service projects, the trace information includes details about all the relevant resources.
  • If you don't have permission to access one of the projects, information about resources defined in this project is hidden in the trace. A permission error is displayed.
Examples
  • You have access to the VM instance project (service project) but don't have access to its network project (host project). If you run a test with this VM instance as a source (specified by the name), any steps associated with the host project (for example, applying firewalls or routes) are hidden.

  • You have access to the network project (host project) but don't have access to the VM project (service project). If you run a test with this VM instance as a source (specified by its IP address), any steps associated with the service project—for example, a step with the VM instance details—are hidden.

Private Service Connect published services

If the packet goes to the Private Service Connect published service (through a Private Service Connect endpoint or Private Service Connect backend), the part of the trace in the producer project is shown only if you have access to it. Otherwise, the trace ends with a general final state such as Packet delivered to the PSC producer project or Packet dropped inside the PSC producer project.

Google-managed services

If the packet goes to or from the Google-managed network associated with a Google-managed service (like Cloud SQL), the steps inside the Google-managed project aren't shown. A general starting step or a final step is displayed.

Public IP addresses of Google Cloud resources

If you specify a public IP address that is assigned to a resource in one of your projects as a test source or destination but don't have permissions to the project where the resource with this address is defined, this IP address is considered to be an internet IP address. Any details about the underlying resource or packet path after this resource is reached are not displayed.

Permissions for viewing test results

To view the test results, note the following:

  • To view the results of tests created or updated after October 2024, you only need the permission to view the test resource (networkmanagement.connectivitytests.get); you don't need permissions to the resources and projects included in the trace path.
  • To view the results of tests executed before October 2024, you must have the Compute Network Viewer role or the legacy Viewer role (roles/viewer) for all projects included in the trace path.

Hierarchical firewall policies

Your trace might include a hierarchical firewall policy that you don't have permission to view. However, even if you don't have permission to view the policy details, you can still see the policy rules that apply to your VPC network. For details, see IAM roles in the "Hierarchical firewall policies" overview.

What's next