Configure service connection policies

This page describes how a network administrator can configure service connection policies to automate private connectivity to a managed service.

Before you begin

Required roles

To get the permissions that you need to configure a network and create a service connection policy, ask your administrator to grant you the Compute Network Admin (roles/compute.networkAdmin) IAM role on your project.

To use service connection policies with Shared VPC, Network Connectivity Service Accounts must be granted roles on the service and host projects. These service accounts are configured automatically when a service connection policy is created, but the roles can be manually removed. If you see errors about missing permissions, a Service Account Admin might need to grant the roles again. For more information, see Configure service accounts for Shared VPC.

Create a service connection policy

A service connection policy lets you authorize the specified service class to create a Private Service Connect connection between producer and consumer VPC networks.

You can create a maximum of one policy for each service class, region, and VPC network combination. A policy dictates service connectivity automation for that specific combination. When you configure a policy, you select a subnet. The subnet is used to allocate IP addresses for the endpoints that are created through the policy. You can reuse the same subnet in multiple connection policies if the policies share the same region.

For example, if you want use service connectivity automation with two services in three different regions, create six policies. You can use a minimum of three subnets—one for each region.

After you create a service connection policy, you can only update the policy's subnets, connection limit, and service instance scope. If you need to update other fields, delete the policy and create a new one.

Console

  1. In the Google Cloud console, go to the Private Service Connect page.

    Go to Private Service Connect

  2. Click the Connection Policies tab.

  3. Click Create connection policy.

  4. Enter a Name for the connection policy.

  5. Specify the service class.

    • For Google services, do the following:
      1. For Service details, select Google services.
      2. Select the service class from the Service class menu.
    • For third-party services, do the following:
      1. For Service details, select Third-party service.
      2. For Service class, enter the service class name.

  6. In the Endpoints scope section, select a Network and Region that this policy applies to.

  7. In the Endpoints configuration section, select one or more subnets from the Subnetworks menu. The subnets are used to allocate IP addresses for endpoints.

  8. Optional: Specify a Connection limit for the policy. The limit determines how many endpoints can be created by using this connection policy. If omitted, there is no limit.

  9. By default, endpoints are created for service instances that are in the same project as the connection policy. If you've selected a supported Google service, you can configure the connection policy to let you connect to service instances that are in a different part of the Resource Manager hierarchy.

    To select different Resource Manager nodes, do the following:

    1. Select Custom service instance scope.
    2. Choose the organizations, folders, and projects that contain service instances that you want to connect to.

  10. Click Create policy.

gcloud

Use the service-connection-policies create command.

gcloud network-connectivity service-connection-policies create POLICY_NAME \
    --network=NETWORK \
    --project=PROJECT_ID \
    --region=REGION \
    --service-class=SERVICE_CLASS \
    --subnets=https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/subnetworks/SUBNETS \
    --psc-connection-limit=LIMIT \
    --description=DESCRIPTION \
    --producer-instance-location=PRODUCER_INSTANCE_LOCATION \
    --allowed-google-producers-resource-hierarchy-level=LIST_OF_NODES

Replace the following:

  • POLICY_NAME: the name of your service connection policy.
  • NETWORK: the network to apply this policy to.
  • PROJECT_ID: the project ID or number of the VPC network's project. For Shared VPC networks, service connection policies must be deployed in the host project and are not supported in service projects.
  • REGION: the region to apply this policy to. The same policy must exist for every region in which you want to automate service connectivity.
  • SERVICE_CLASS: the producer-supplied resource identifier of the service class.
  • SUBNETS: one or more regular consumer subnets that are used to allocate IP addresses for Private Service Connect endpoints. These IP addresses are automatically allocated and returned to the subnet's pool as managed service instances are created and deleted. The subnets must be in the same region as the service connection policy. You can reuse the same subnetwork in multiple connection policies if the policies share the same region. You can enter multiple subnets in a comma-separated list.
  • LIMIT: the maximum number of endpoints that can be created by using this policy. If not specified, there is no limit.
  • DESCRIPTION: an optional description of the service connection policy.
  • PRODUCER_INSTANCE_LOCATION: for supported Google managed services, specifies whether this policy automates connections to service instances that are in custom Resource Manager locations. If set to none, endpoints are created that connect to service instances that are in the same project as the service connection policy (or in the case of Shared VPC, in connected projects). The default value is none. If set to custom-resource-hierarchy-levels, you specify the custom locations by using the --allowed-google-producers-resource-hierarchy-level flag.
  • LIST_OF_NODES: for supported Google managed services, specifies a list of Resource Manager nodes (projects, folders, and organizations) that contain the service instances that you want to connect to. This field is checked only when the --producer-instance-location flag is set to custom-resource-hierarchy-levels. The list can contain any combination of projects, folders, and organizations. For an example list, see the following: 
    "projects/1111111111",
"folders/2222222222",
"folders/3333333333",
"organizations/4444444444"

For example, the following command creates a service connection policy for the Google-published google-cloud-sql service class. The policy can be used to automate connectivity to service instances deployed in shared-db-service-project. Private Service Connect endpoints that are created by using this policy are allocated IP addresses from the endpoint-subnet subnet. A maximum of 10 endpoints can be created by using this policy.

gcloud network-connectivity service-connection-policies create google-cloud-sql-policy \
    --network=default \
    --project=my-project \
    --region=us-central1 \
    --service-class=google-cloud-sql \
    --subnets=endpoint-subnet \
    --psc-connection-limit=10 \
    --producer-instance-location=custom-resource-hierarchy-levels \
    --allowed-producer-instance-scope=projects/shared-db-service-project

Terraform

You can use the Terraform resource to create a service connection policy.

# Create a VPC network
resource "google_compute_network" "default" {
  name                    = "consumer-network"
  auto_create_subnetworks = false
}

# Create a subnetwork
resource "google_compute_subnetwork" "default" {
  name          = "consumer-subnet"
  ip_cidr_range = "10.0.0.0/16"
  region        = "us-central1"
  network       = google_compute_network.default.id
}

# Create a service connection policy
resource "google_network_connectivity_service_connection_policy" "default" {
  name          = "service-connection-policy"
  location      = "us-central1"
  service_class = "gcp-memorystore-redis"
  network       = google_compute_network.default.id
  psc_config {
    subnetworks = [google_compute_subnetwork.default.id]
    limit       = 2
  }
}

To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.

API

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

  • PROJECT_ID: the ID of your project.
  • REGION: the region of your service connection policy.
  • POLICY_NAME: the name of your service connection policy.
  • DESCRIPTION: an optional description of your service connection policy.
  • NETWORK: the network of your service connection policy.
  • LIMIT: the maximum number of endpoints that can be created by using this policy. If not specified, there is no limit.
  • SUBNET: one or more regular consumer subnets that are used to allocate IP addresses for Private Service Connect endpoints. These IP addresses are automatically allocated and returned to the subnet's pool as managed service instances are created and deleted. The subnets must be in the same region as the service connection policy. You can reuse the same subnetwork in multiple connection policies if the policies share the same region. You can enter multiple subnet URLs in a comma-separated list.
  • SERVICE_CLASS: the producer-supplied resource identifier of the service class.
  • PRODUCER_INSTANCE_LOCATION: PRODUCER_INSTANCE_LOCATION_UNSPECIFIED (default) or CUSTOM_RESOURCE_HIERARCHY_LEVELS.
  • LIST_OF_NODES: A list of Resource Manager nodes (projects, folders, and organizations) that contain the service instances that you want to connect to. This field is checked only when the PRODUCER_INSTANCE_LOCATION flag is set to CUSTOM_RESOURCE_HIERARCHY_LEVELS. The list can contain any combination of projects, folders, and organizations. For an example list, see the following: 
        "projects/1111111111",
    "folders/2222222222",
    "folders/3333333333",
    "organizations/4444444444"

HTTP method and URL: 

POST https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/serviceConnectionPolicies?serviceConnectionPolicyId=POLICY_NAME

Request JSON body: 

{
  "description": "DESCRIPTION",
  "network": "projects/PROJECT_ID/global/networks/NETWORK",
  "pscConfig": {
    "limit": "LIMIT",
    "subnetworks": [
      "projects/PROJECT_ID/regions/REGION/subnetworks/SUBNET"
    ]
    "producerInstanceLocation": "CUSTOM_RESOURCE_HIERARCHY_LEVELS",
    "allowedGoogleProducersResourceHierarchyLevel": [
      LIST_OF_NODES
    ]
  },
  "serviceClass": "SERVICE_CLASS"
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "name": "projects/project-id/locations/us-central1/operations/operation-1692118768698-602f91a204523-8c6a2d93-d5c20a6a",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.networkconnectivity.v1.OperationMetadata",
    "createTime": "2023-08-15T16:59:29.236110917Z",
    "target": "projects/project-id/locations/us-central1/serviceConnectionPolicies/policy-name",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

List service connection policies

Console

  1. In the Google Cloud console, go to the Private Service Connect page.

    Go to Private Service Connect

  2. Click the Connection Policies tab.

  3. The connection policies are displayed.

gcloud

Use the service-connection-policies list command.

gcloud network-connectivity service-connection-policies list \
    --region=REGION

Replace REGION with the region that you want to list service connection policies in.

API

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

  • PROJECT_ID: the ID of your project.
  • REGION: the region to list service connection policies in.

HTTP method and URL: 

GET https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/serviceConnectionPolicies

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "serviceConnectionPolicies": [
    {
      "name": "projects/project-id/locations/us-central1/serviceConnectionPolicies/policy-1",
      "createTime": "2023-08-15T15:33:54.712819865Z",
      "updateTime": "2023-08-15T15:33:54.945630882Z",
      "description": "descriptor",
      "network": "projects/project-id/global/networks/network-two",
      "serviceClass": "service-class",
      "infrastructure": "PSC",
      "pscConfig": {
        "subnetworks": [
          "projects/project-id/regions/us-west1/subnetworks/us-west1-subnet"
        ],
        "limit": "12"
      },
      "etag": "zCqDFBG1dS7B4gNdJKPR98YMUXpSrBIz0tZB_hwOIZI"
    },
    {
      "name": "projects/project-id/locations/us-central1/serviceConnectionPolicies/policy-2",
      "createTime": "2023-08-15T16:59:29.230257109Z",
      "updateTime": "2023-08-15T16:59:29.508994923Z",
      "description": "descriptor",
      "network": "projects/project-id/global/networks/custom-test",
      "serviceClass": "service-class",
      "infrastructure": "PSC",
      "pscConfig": {
        "subnetworks": [
          "projects/project-id/regions/us-central1/subnetworks/subnet-one"
        ],
        "limit": "25"
      },
      "etag": "nB603i61nRGMZpNjWoWMM6wRzsgM8QN9C9v5QFLyOa8"
    }
  ]
}

Describe a service connection policy

Console

  1. In the Google Cloud console, go to the Private Service Connect page.

    Go to Private Service Connect

  2. Click the Connection Policies tab.

  3. Click the service connection policy that you want to view.

gcloud

Use the service-connection-policies describe command.

gcloud network-connectivity service-connection-policies describe POLICY_NAME \
    --region=REGION

Replace the following:

  • POLICY_NAME: the name of the service connection policy that you want to describe.
  • REGION: the region of the service connection policy that you want to describe.

API

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

  • PROJECT_ID: the ID of your project.
  • REGION: the region of your service connection policy.
  • POLICY_NAME: the name of the service connection policy to describe.

HTTP method and URL: 

GET https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/serviceConnectionPolicies/POLICY_NAME

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "name": "projects/project-id/locations/us-central1/serviceConnectionPolicies/policy-name",
  "createTime": "2023-08-15T16:59:29.230257109Z",
  "updateTime": "2023-08-15T16:59:29.508994923Z",
  "description": "description",
  "network": "projects/project-id/global/networks/custom-test",
  "serviceClass": "gcp-memorystore-redis",
  "infrastructure": "PSC",
  "pscConfig": {
    "subnetworks": [
      "projects/project-id/regions/us-central1/subnetworks/subnet-one"
    ],
    "limit": "25"
  },
  "etag": "nB603i61nRGMZpNjWoWMM6wRzsgM8QN9C9v5QFLyOa8"
}

Update a service connection policy

You can update the subnets, connection limit, and service instance scope for a service connection policy.

If you remove a subnet from the service connection policy, the following applies:

  • Existing Private Service Connect endpoints are not affected.
  • New endpoints don't use the removed subnet.

If you update the connection limit of a service connection policy, the following applies:

  • Existing endpoints are not affected.
  • If the new connection limit is lower than the existing number of endpoints that are associated with the policy, service connectivity automation blocks the creation of new endpoints that use this policy.
  • If the new connection limit is higher than the existing number of endpoints that are associated with the policy, endpoints that were previously blocked by the connection limit can be created.

If you update a service connection policy and don't specify a connection limit, the updated policy has no connection limit.

If you update the service instance scope for a service connection policy, existing endpoints aren't affected. To update the scope, use the Google Cloud console or the API.

Console

  1. In the Google Cloud console, go to the Private Service Connect page.

    Go to Private Service Connect

  2. Click the Connection Policies tab.

  3. Click the service connection policy that you want to edit.

  4. Click Edit.

  5. Make the updates to the service connection policy.

  6. Click Update policy.

gcloud

Use the service-connection-policies update command.

gcloud network-connectivity service-connection-policies update POLICY_NAME \
    --region=REGION \
    --project=PROJECT_ID \
    --subnets=SUBNETS \
    --psc-connection-limit=LIMIT
  • POLICY_NAME: the name of your service connection policy.
  • REGION: the region of the service connection policy. You cannot update a policy's region.
  • PROJECT_ID: the project ID or number of the policy's project.
  • SUBNETS: one or more regular consumer subnets that are used to allocate IP addresses for Private Service Connect endpoints. These IP addresses are automatically allocated and returned to the subnet's pool as managed service instances are created and deleted. The subnets must be in the same region as the service connection policy. You can reuse the same subnetwork in multiple connection policies if the policies share the same region. You can enter multiple subnets in a comma-separated list.
  • LIMIT: the maximum number of endpoints that can be created by using this policy. If not specified, there is no limit.

API

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

  • PROJECT_ID: the ID of your project.
  • REGION: the region of your service connection policy. You cannot update a policy's region.
  • POLICY_NAME: the name of your service connection policy.
  • LIMIT: the maximum number of endpoints that can be created by using this policy. If not specified, there is no limit.
  • SUBNET: one or more regular consumer subnets that are used to allocate IP addresses for Private Service Connect endpoints. These IP addresses are automatically allocated and returned to the subnet's pool as managed service instances are created and deleted. The subnets must be in the same region as the service connection policy. You can reuse the same subnetwork in multiple connection policies if the policies share the same region. You can enter multiple subnet URLs in a comma-separated list.
  • NETWORK: the network of your service connection policy.

HTTP method and URL: 

PATCH https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/serviceConnectionPolicies/POLICY_NAME

Request JSON body: 

{
  "pscConfig": {
    "limit": "LIMIT",
    "subnetworks": [
      "projects/PROJECT_ID/regions/REGION/subnetworks/SUBNET"
    ]
  },
  "network": "projects/PROJECT_ID/global/networks/NETWORK"
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "name": "projects/project-id/locations/us-central1/operations/operation-1692118768698-602f91a204523-8c6a2d93-d5c20a6a",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.networkconnectivity.v1.OperationMetadata",
    "createTime": "2023-08-15T16:59:29.236110917Z",
    "target": "projects/project-id/locations/us-central1/serviceConnectionPolicies/policy-name",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

Delete a service connection policy

You can delete a service connection policy if you are finished using the service or want to stop automating connectivity. Deletion of the policy is blocked if active Private Service Connect connections are associated with the policy. Before deleting a service connection policy, delete all active connections by decommissioning all associated service instances.

Console

  1. In the Google Cloud console, go to the Private Service Connect page.

    Go to Private Service Connect

  2. Click the Connection Policies tab.

  3. Select the service connection policies that you want to delete, and then click Delete.

gcloud

Use the service-connection-policies delete command.

gcloud network-connectivity service-connection-policies delete POLICY_NAME \
    --region=REGION

Replace the following:

  • POLICY_NAME: the name of the service connection policy that you want to delete.
  • REGION: the region of the service connection policy that you want to delete.

API

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

  • PROJECT_ID: the ID of your project.
  • REGION: the region of your service connection policy.
  • POLICY_NAME: the name of the service connection policy to delete.

HTTP method and URL: 

DELETE https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/serviceConnectionPolicies/POLICY_NAME

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "name": "projects/project-id/locations/us-central1/operations/operation-1692128792549-602fb6f98194a-e0275435-36edc095",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.networkconnectivity.v1.OperationMetadata",
    "createTime": "2023-08-15T19:46:32.605032867Z",
    "target": "projects/project-id/locations/us-central1/serviceConnectionPolicies/policy-name",
    "verb": "delete",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

Configure service accounts for Shared VPC

Service accounts are configured automatically when you use service connection policies with Shared VPC, but the roles can be manually removed. If you see errors about missing permissions, try granting the roles again.

To grant the required roles, a Service Account Admin can do the following.

Grant roles to service account in service project

gcloud

  1. Grant the Network Connectivity Service Agent role (roles/networkconnectivity.serviceAgent) to the service project's Network Connectivity Service Account. Grant the role on the service project.

    gcloud projects add-iam-policy-binding SERVICE_PROJECT_NUMBER \
    --member=serviceAccount:service-SERVICE_PROJECT_NUMBER@gcp-sa-networkconnectivity.iam.gserviceaccount.com \
    --role=roles/networkconnectivity.serviceAgent

    Replace SERVICE_PROJECT_NUMBER with the project number of the service project.

  2. Grant the Compute Network User role (roles/compute.networkUser) to the service project's Network Connectivity Service Account. Do one of the following.

    • Grant the role on the host project.

      gcloud projects add-iam-policy-binding HOST_PROJECT_NUMBER \
    --member=serviceAccount:service-SERVICE_PROJECT_NUMBER@gcp-sa-networkconnectivity.iam.gserviceaccount.com \
    --role=roles/compute.networkUser

      Replace HOST_PROJECT_NUMBER with the project number of the host project.

    • Grant the role on each of the subnets in the host project that are associated with the service connection policy. Use the following command for each subnet.

      gcloud compute networks subnets add-iam-policy-binding SUBNET \
    --member=serviceAccount:service-SERVICE_PROJECT_NUMBER@gcp-sa-networkconnectivity.iam.gserviceaccount.com \
    --role=roles/compute.networkUser \
    --region=REGION \
    --project=HOST_PROJECT_NUMBER

      Replace the following:

      • SUBNET: the name of the subnet that's associated with your service connection policy.
      • REGION: the region of the subnet.

Grant role to service account in host project

gcloud

  1. Grant the Network Connectivity Service Agent role (roles/networkconnectivity.serviceAgent) to the host project's Network Connectivity Service Account. Grant the role on the host project.

    gcloud projects add-iam-policy-binding HOST_PROJECT_NUMBER \
    --member=serviceAccount:service-HOST_PROJECT_NUMBER@gcp-sa-networkconnectivity.iam.gserviceaccount.com \
    --role=roles/networkconnectivity.serviceAgent

    Replace HOST_PROJECT_NUMBER with the project number of the host project.

What's next