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

Make sure that the managed service that you want to deploy supports service connection policies. Making services available for deployment by using service connection policies is available in a limited Preview. For more information about services that support service connection policies, see Supported services.
You must know the name of the service class for the managed service instance that you want to deploy connectivity for.
Read about Private Service Connect endpoints.
You need a Virtual Private Cloud (VPC) network and a subnet.
You must enable the Compute Engine API in your project.
You must enable the Network Connectivity API in your project.
You must enable the Service Consumer Management API in the consumer project that Private Service Connect endpoints are deployed in. This API lets Google Cloud create the Network Connectivity Service Account that deploys Private Service Connect endpoints.

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 and connection limit. If you need to update other fields, delete the policy and create a new one.

Permissions required for this task

To perform this task, you must have been granted the following permissions or one of the following IAM roles.

Permissions

networkconnectivity.serviceConnectionPolicies.create

Roles

Compute Network Admin (roles/compute.networkAdmin)

Console

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

Go to Private Service Connect
Click the Connection Policies tab.
Click Create connection policy.
Enter a Name for the connection policy.
Specify the service class.
- For Google services, do the following:
  1. For Source service class, select Google services.
  2. Select the service class from the Service class menu.
- For third-party services, do the following:
  1. For Source service class, select 3rd party services.
  2. For Service class, enter the service class name.
In the Target endpoints scope section, select a Network and Region that this policy applies to.
In the Policy section, select one or more subnets from the Subnetworks menu. The subnets are used to allocate IP addresses for endpoints.
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.
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

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.

For example, the following command creates a service connection policy for the gcp-database-service service class that allocates IP addresses from the managed-services subnet. A maximum of 10 Private Service Connect endpoints can be created by using this policy. The endpoints must be created in projects that are in the same organization as the managed service instance.

gcloud network-connectivity service-connection-policies create gcp-database-cxn-policy \
    --network=default \
    --project=my-project \
    --region=us-central1 \
    --service-class=gcp-database-service \
    --subnets=managed-service-subnet \
    --psc-connection-limit=10

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.

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"
    ]
  },
  "serviceClass": "SERVICE_CLASS"
}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/serviceConnectionPolicies?serviceConnectionPolicyId=POLICY_NAME"

PowerShell (Windows)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/serviceConnectionPolicies?serviceConnectionPolicyId=POLICY_NAME" | Select-Object -Expand Content

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

Permissions required for this task

To perform this task, you must have been granted the following permissions or one of the following IAM roles.

Permissions

networkconnectivity.serviceConnectionPolicies.list

Roles

Compute Network Admin (roles/compute.networkAdmin)

Console

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

Go to Private Service Connect
Click the Connection Policies tab.
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:

curl (Linux, macOS, or Cloud Shell)

Execute the following command:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/serviceConnectionPolicies"

PowerShell (Windows)

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/serviceConnectionPolicies" | Select-Object -Expand Content

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

Permissions required for this task

To perform this task, you must have been granted the following permissions or one of the following IAM roles.

Permissions

networkconnectivity.serviceConnectionPolicies.get

Roles

Compute Network Admin (roles/compute.networkAdmin)

Console

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

Go to Private Service Connect
Click the Connection Policies tab.
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:

curl (Linux, macOS, or Cloud Shell)

Execute the following command:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/serviceConnectionPolicies/POLICY_NAME"

PowerShell (Windows)

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/serviceConnectionPolicies/POLICY_NAME" | Select-Object -Expand Content

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 and connection limit 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 do not 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.

Permissions required for this task

To perform this task, you must have been granted the following permissions or one of the following IAM roles.

Permissions

networkconnectivity.serviceConnectionPolicies.update

Roles

Compute Network Admin (roles/compute.networkAdmin)

Console

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

Go to Private Service Connect
Click the Connection Policies tab.
Click the service connection policy that you want to edit.
Click Edit.
To update the policy's subnetworks, do the following:
1. Click Subnetworks, and then select the subnetworks that you want to associate with this policy.
2. Click OK.
To update the policy's connection limit, enter a new value in the Connection limit field.
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:

curl (Linux, macOS, or Cloud Shell)

Save the request body in a file named request.json, and execute the following command:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/serviceConnectionPolicies/POLICY_NAME"

PowerShell (Windows)

Save the request body in a file named request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/serviceConnectionPolicies/POLICY_NAME" | Select-Object -Expand Content

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

Permissions required for this task

To perform this task, you must have been granted the following permissions or one of the following IAM roles.

Permissions

networkconnectivity.serviceConnectionPolicies.delete

Roles

Compute Network Admin (roles/compute.networkAdmin)

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

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

Go to Private Service Connect
Click the Connection Policies tab.
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:

curl (Linux, macOS, or Cloud Shell)

Execute the following command:

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/serviceConnectionPolicies/POLICY_NAME"

PowerShell (Windows)

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/serviceConnectionPolicies/POLICY_NAME" | Select-Object -Expand Content

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

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.
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

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

Deploy a managed service instance by using service connection policies