Private Service Connect

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")

```
provider "google" {
  project = "my-gcp-project"
  region  = "us-central1"
}

variable "region" {
  type    = string
  default = "us-central1"
}

variable "subnetwork" {
  type = string
  default = "https://www.googleapis.com/compute/v1/projects/my-gcp-project/regions/us-central1/subnetworks/default"
}

variable "network" {
  type = string
  default = "https://www.googleapis.com/compute/v1/projects/my-gcp-project/global/networks/default"
}

resource "google_compute_address" "psc_endpoint_ip" {
  address      = "10.128.0.2"
  address_type = "INTERNAL"
  name         = "your-ip-address"
  purpose      = "GCE_ENDPOINT"
  region       = var.region
  subnetwork   = var.subnetwork
}

resource "google_compute_forwarding_rule" "clickhouse_cloud_psc" {
  ip_address            = google_compute_address.psc_endpoint_ip.self_link
  name                  = "ch-cloud-${var.region}"
  network               = var.network
  region                = var.region
  load_balancing_scheme = ""
  # service attachment
  target = "https://www.googleapis.com/compute/v1/$TARGET" # See below in notes
}

output "psc_connection_id" {
  value       = google_compute_forwarding_rule.clickhouse_cloud_psc.psc_connection_id
  description = "Add GCP PSC Connection ID to allow list on instance level."
}
```

Note

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

## Set private DNS name for endpoint[​](#set-private-dns-name-for-endpoint "Direct link to Set private DNS name for endpoint")

Note

There are various ways to configure DNS. Please set up DNS according to your specific use case.

You need to point the "DNS name", taken from [Obtain GCP service attachment for Private Service Connect](#obtain-gcp-service-attachment-and-dns-name-for-private-service-connect) step, to the GCP Private Service Connect endpoint IP address. This ensures that services/components within your VPC/Network can resolve it properly.

References

Connecting to the PSC endpoint IP address directly is not sufficient. ClickHouse Cloud routes connections based on the DNS name (via SNI in the TLS handshake), so you must configure DNS to resolve the private DNS hostname (`privateDnsHostname`) to the endpoint IP address. Without this, ClickHouse Cloud cannot identify which service the connection is intended for and the connection will fail.

## Add Endpoint ID to ClickHouse Cloud organization[​](#add-endpoint-id-to-clickhouse-cloud-organization "Direct link to Add Endpoint ID to ClickHouse Cloud organization")

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

To add an endpoint to your organization, proceed to the [Add "Endpoint ID" to ClickHouse service allow list](#add-endpoint-id-to-services-allow-list) step. Adding the `PSC Connection ID` using the ClickHouse Cloud console to the service allow list automatically adds it to the organization.

To remove an endpoint, open **Organization details -> Private Endpoints** and click the delete button to remove the endpoint.

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

Set these environment variables before running any commands:

Replace `ENDPOINT_ID` below with the value from **Endpoint ID** from the [Adding a Private Service Connection](#adding-a-private-service-connection) step.

To add an endpoint, run:

```
cat <<EOF | tee pl_config_org.json
{
  "privateEndpoints": {
    "add": [
      {
        "cloudProvider": "gcp",
        "id": "${ENDPOINT_ID:?}",
        "description": "A GCP private endpoint",
        "region": "${REGION:?}"
      }
    ]
  }
}
EOF
```

To remove an endpoint, run:

```
cat <<EOF | tee pl_config_org.json
{
  "privateEndpoints": {
    "remove": [
      {
        "cloudProvider": "gcp",
        "id": "${ENDPOINT_ID:?}",
        "region": "${REGION:?}"
      }
    ]
  }
}
EOF
```

Add/remove a Private Endpoint for an organization:

```
curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" -X PATCH -H "Content-Type: application/json" "https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}" -d @pl_config_org.json
```

## Add "Endpoint ID" to ClickHouse service allow list[​](#add-endpoint-id-to-services-allow-list "Direct link to Add \"Endpoint ID\" to ClickHouse service allow list")

You need to add an Endpoint ID to the allow-list for each instance that should be available using Private Service Connect.

### Option 1: ClickHouse Cloud console[​](#option-1-clickhouse-cloud-console-2 "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 navigate to **Settings**. Enter the `Endpoint ID` retrieved from the [Adding a Private Service Connection](#adding-a-private-service-connection) step. Click **Create endpoint**.

Note

If you want to allow access from an existing Private Service Connect connection, use the existing endpoint drop-down menu.

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

Set these environment variables before running any commands:

Replace **ENDPOINT\_ID** below with the value from **Endpoint ID** from the [Adding a Private Service Connection](#adding-a-private-service-connection) step.

Execute it for each service that should be available using Private Service Connect.

To add:

```
cat <<EOF | tee pl_config.json
{
  "privateEndpointIds": {
    "add": [
      "${ENDPOINT_ID}"
    ]
  }
}
EOF
```

To remove:

```
cat <<EOF | tee pl_config.json
{
  "privateEndpointIds": {
    "remove": [
      "${ENDPOINT_ID}"
    ]
  }
}
EOF
```

```
curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" -X PATCH -H "Content-Type: application/json" "https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services/${INSTANCE_ID:?}" -d @pl_config.json | jq
```

## Accessing instance using Private Service Connect[​](#accessing-instance-using-private-service-connect "Direct link to Accessing instance using Private Service Connect")

Each service with Private Service Connect enabled has a public and private endpoint. To connect using Private Service Connect, you need to use the private endpoint, which is the `privateDnsHostname` from the [Obtain GCP service attachment for Private Service Connect](#obtain-gcp-service-attachment-and-dns-name-for-private-service-connect) step.

### Getting private DNS hostname[​](#getting-private-dns-hostname "Direct link to Getting private DNS hostname")

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

In the ClickHouse Cloud console, navigate to **Settings**. Click on the **Set up private endpoint** button. In the opened flyout, copy the **DNS Name**.

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

```
curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" "https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services/${INSTANCE_ID:?}/privateEndpointConfig" | jq  .result
```

```
{
  ...
  "privateDnsHostname": "xxxxxxx.<region code>.p.gcp.clickhouse.cloud"
}
```

In this example, connection to the `xxxxxxx.yy-xxxxN.p.gcp.clickhouse.cloud` hostname will be routed to Private Service Connect. Meanwhile, `xxxxxxx.yy-xxxxN.gcp.clickhouse.cloud` will be routed over the internet.

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

### Test DNS setup[​](#test-dns-setup "Direct link to Test DNS setup")

DNS\_NAME - Use `privateDnsHostname` from [Obtain GCP service attachment for Private Service Connect](#obtain-gcp-service-attachment-and-dns-name-for-private-service-connect) step

```
nslookup $DNS_NAME
```