Private Service Connect

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/cloud/guides/security/02_connectivity/private_networking/03_gcp-private-service-connect.md)

Scale plan feature

GCP PSC is available in the Scale and Enterprise plans. To upgrade, visit the plans page in the cloud console.

Private Service Connect (PSC) is a Google Cloud networking feature that allows consumers to access managed services privately inside their virtual private cloud (VPC) network. Similarly, it allows managed service producers to host these services in their own separate VPC networks and offer a private connection to their consumers.

Service producers publish their applications to consumers by creating Private Service Connect services. Service consumers access those Private Service Connect services directly through one of these Private Service Connect types.

References

By default, a ClickHouse service isn't available over a Private Service connection even if the PSC connection is approved and established; you need to explicitly add the PSC ID to the allow list on an instance level by completing the [step](#add-endpoint-id-to-services-allow-list) below.

**Important considerations for using Private Service Connect Global Access**:

1. Regions utilizing Global Access must belong to the same VPC.
2. Global Access must be explicitly enabled at the PSC level (refer to the screenshot below).
3. Ensure that your firewall settings don't block access to PSC from other regions.
4. Be aware that you may incur GCP inter-region data transfer charges.

Cross-region connectivity isn't supported. The producer and consumer regions must be the same. However, you can connect from other regions within your VPC by enabling [Global Access](https://cloud.google.com/vpc/docs/about-accessing-vpc-hosted-services-endpoints#global-access) at the Private Service Connect (PSC) level.

**Complete the following steps to enable GCP PSC**:

1. Obtain GCP service attachment for Private Service Connect.
2. Create a service endpoint.
3. Add "Endpoint ID" to ClickHouse Cloud service.
4. Add "Endpoint ID" to ClickHouse service allow list.

## Attention[​](#attention "Direct link to Attention")

ClickHouse attempts to group your services to reuse the same published [PSC endpoint](https://cloud.google.com/vpc/docs/private-service-connect) within the GCP region. However, this grouping isn't guaranteed, especially if you spread your services across multiple ClickHouse organizations.
If you already have PSC configured for other services in your ClickHouse organization, you can often skip most of the steps because of that grouping and proceed directly to the final step: [Add "Endpoint ID" to ClickHouse service allow list](#add-endpoint-id-to-services-allow-list).

Find Terraform examples [here](https://github.com/ClickHouse/terraform-provider-clickhouse/tree/main/examples/).

## Before you get started[​](#before-you-get-started "Direct link to Before you get started")

Note

Code examples are provided below to show how to set up Private Service Connect within a ClickHouse Cloud service. In our examples below, we will use:

- GCP region: `us-central1`
- GCP project (customer GCP project): `my-gcp-project`
- GCP private IP address in customer GCP project: `10.128.0.2`
- GCP VPC in customer GCP project: `default`

You'll need to retrieve information about your ClickHouse Cloud service. You can do this either via the ClickHouse Cloud console or the ClickHouse API. If you're going to use the ClickHouse API, please set the following environment variables before proceeding:

```
REGION=<Your region code using the GCP format, for example: us-central1>
PROVIDER=gcp
KEY_ID=<Your ClickHouse key ID>
KEY_SECRET=<Your ClickHouse key secret>
ORG_ID=<Your ClickHouse organization ID>
SERVICE_NAME=<Your ClickHouse service name>
```

You can [create a new ClickHouse Cloud API key](/docs/cloud/manage/openapi) or use an existing one.

Get your ClickHouse `INSTANCE_ID` by filtering by region, provider and service name:

```
INSTANCE_ID=$(curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" \
"https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services" | \
jq ".result[] | select (.region==\"${REGION:?}\" and .provider==\"${PROVIDER:?}\" and .name==\"${SERVICE_NAME:?}\") | .id " -r)
```

Note

- You can retrieve your Organization ID from the ClickHouse console (Organization -> Organization Details).
- You can [create a new key](/docs/cloud/manage/openapi) or use an existing one.

## Obtain GCP service attachment and DNS name for Private Service Connect[​](#obtain-gcp-service-attachment-and-dns-name-for-private-service-connect "Direct link to Obtain GCP service attachment and DNS name for Private Service Connect")

### Option 1: ClickHouse Cloud console[​](#option-1-clickhouse-cloud-console "Direct link to Option 1: ClickHouse Cloud console")

In the ClickHouse Cloud console, open the service that you would like to connect via Private Service Connect, then open the **Settings** menu. Click on the **Set up private endpoint** button. Make a note of the **Service name** (`endpointServiceId`) and **DNS name** (`privateDnsHostname`). You'll use them in the next steps.

### Option 2: API[​](#option-2-api "Direct link to Option 2: API")

Note

You need at least one instance deployed in the region to perform this step.

Obtain GCP service attachment and DNS name for Private Service Connect:

```
curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" "https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services/${INSTANCE_ID:?}/privateEndpointConfig" | jq  .result
{
  "endpointServiceId": "projects/.../regions/us-central1/serviceAttachments/production-us-central1-clickhouse-cloud",
  "privateDnsHostname": "xxxxxxxxxx.us-central1.p.gcp.clickhouse.cloud"
}
```

Make a note of the `endpointServiceId` and `privateDnsHostname`. You'll use them in the next steps.

## Create service endpoint[​](#create-service-endpoint "Direct link to Create service endpoint")

References

This section covers ClickHouse-specific details for configuring ClickHouse via GCP PSC (Private Service Connect). GCP-specific steps are provided as a reference to guide you on where to look, but they may change over time without notice from the GCP cloud provider. Please consider GCP configuration based on your specific use case.

Please note that ClickHouse isn't responsible for configuring the required GCP PSC endpoints or DNS records.

For any issues related to GCP configuration tasks, contact GCP Support directly.

In this section, you'll create a service endpoint.

### Adding a private service connection[​](#adding-a-private-service-connection "Direct link to Adding a private service connection")

First, you'll create a Private Service Connection.

#### Option 1: Using Google Cloud console[​](#option-1-using-google-cloud-console "Direct link to Option 1: Using Google Cloud console")

In the Google Cloud console, navigate to **Network services -> Private Service Connect**.

Open the Private Service Connect creation dialog by clicking on the **Connect Endpoint** button.

- **Target**: use **Published service**
- **Target service**: use `endpointServiceId`API or `Service name`console from [Obtain GCP service attachment for Private Service Connect](#obtain-gcp-service-attachment-and-dns-name-for-private-service-connect) step.
- **Endpoint name**: set a name for the PSC **Endpoint name**.
- **Network/Subnetwork/IP address**: Choose the network you want to use for the connection. You will need to create an IP address or use an existing one for the Private Service Connect endpoint. In our example, we pre-created an address with the name **your-ip-address** and assigned IP address `10.128.0.2`.
- To make the endpoint available from any region, you can enable the **Enable global access** checkbox.

To create the PSC Endpoint, use the **ADD ENDPOINT** button.

The **Status** column will change from **Pending** to **Accepted** once the connection is approved.

Copy ***PSC Connection ID***; you'll use it as ***Endpoint ID*** in the next steps.

#### Option 2: Using Terraform[​](#option-2-using-terraform "Direct link to Option 2: Using Terraform")