> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/harness-platform/use-harness-platform/references/network-and-security/cloud-private-connectivity/configure.md).

# Configure Cloud Private Connectivity

Configure routes and domains, deploy a customer appliance, activate workloads, and verify private access

{% hint style="info" %}
**Note**

Cloud Private Connectivity requires enablement by Harness.
{% endhint %}

Harness provisions the account network before customer configuration begins. Customers do not create the Tailscale network. Use this procedure to verify readiness, optionally narrow the default policy, obtain an appliance credential, deploy an appliance, and activate the required workloads.

***

## Before you begin

Before you configure cloud private connectivity, ensure you have the following:

* **Harness account**: Provide the account identifier and Harness environment to Harness Support. Harness enables the Beta feature, provisions the account with the default policy, and confirms that the control plane is `READY`.
* **Account Admin PAT**: Use a Harness personal API key for an Account Admin identity. You would require **Account Edit** permission at account scope. Go to [Create a PAT](https://developer.harness.io/harness-platform/use-harness-platform/automation/api/add-and-manage-api-keys) to generate the key.
* **Workflow permissions**: Obtain the permissions required to edit Default Settings, connectors, pipelines, and any referenced Harness secrets at their intended scopes.
* **Hosted image**: Select one of the [supported hosted images](https://developer.harness.io/harness-platform/use-harness-platform/references/network-and-security/cloud-private-connectivity.md#supported-hosted-build-images).
* **Private destinations**: Record the required CIDRs, domains, private DNS resolvers, and application ports.
* **Appliance infrastructure**: Prepare a Kubernetes cluster with Linux workers that support privileged containers, or a fresh Ubuntu 24.04 VM. The appliance must reach the private services, DNS, and the [required outbound endpoints](https://developer.harness.io/harness-platform/use-harness-platform/references/network-and-security/cloud-private-connectivity.md#network-connectivity-requirements).
* **Local tools**: Use Bash, `curl`, and `jq` on a protected administrator workstation. Use an approved secret manager to deliver the appliance credential.

***

## Verify and configure the account

{% stepper %}
{% step %}

### Prepare customer API authentication

Run this once in Bash and keep the same session open for the API requests:

```bash
set -euo pipefail
set +x
umask 077
HARNESS_BASE_URL='https://<your-harness-host>'
ACCOUNT_ID='<your-account-id>'
PC_WORK_DIR="$(mktemp -d)"
echo "$PC_WORK_DIR"
```

The last line shows your private working directory. In your local editor, create `auth.conf` in that directory with the following content. Replace the placeholder with your Account Admin PAT and keep the file private:

{% code title="auth.conf" %}

```
header = "x-api-key: <your-account-admin-PAT>"
```

{% endcode %}

The requests read this file so you do not need to paste the API key into every command. `--fail-with-body` reports API errors while keeping the error response available.

Use the Harness URL for the account without a trailing slash. Do not add organization, project, provider, or Tailscale identifiers to these account-scoped requests.
{% endstep %}

{% step %}

### Verify Harness provisioning

**GET `/ng/api/private-connectivity`**

Read the account configuration:

{% code overflow="wrap" %}

```bash
curl --config "$PC_WORK_DIR/auth.conf" --fail-with-body \
  "$HARNESS_BASE_URL/ng/api/private-connectivity?accountIdentifier=$ACCOUNT_ID" | jq
```

{% endcode %}

Before the first change, expect `READY`, `advertiseRoutes` equal to `["*"]`, and empty or omitted domains and DNS. `NOT_PROVISIONED` means Harness setup is incomplete. `PROVISIONING`, `UPDATING`, or an error state requires Harness to finish or reconcile the managed operation. Do not try to create a replacement network.
{% endstep %}

{% step %}

### Keep or narrow the default policy

**PUT `/ng/api/private-connectivity/config`**

You can keep the default `["*"]` route boundary. Configure `domains` if you use an App Connector. To restrict destinations or configure DNS, use a partial update.

Save this example as `config.json` in your current directory and replace the destinations with your values. It permits one subnet, adds two App Connector domains, and configures a private resolver:

{% code title="config.json" %}

```json
{
  "advertiseRoutes": ["10.77.0.0/24"],
  "domains": [
    "git.internal.example.com",
    "*.artifacts.internal.example.com"
  ],
  "dns": {
    "splitDnsDomains": {
      "internal.example.com": ["10.77.0.53"]
    }
  }
}
```

{% endcode %}

Send the update. Go to [Request examples](https://developer.harness.io/harness-platform/use-harness-platform/references/network-and-security/cloud-private-connectivity/reference.md#request-examples) to review subnet-only and App Connector configurations.

{% code overflow="wrap" %}

```bash
curl --config "$PC_WORK_DIR/auth.conf" --fail-with-body \
  --request PUT \
  --header 'Content-Type: application/json' \
  --data @config.json \
  "$HARNESS_BASE_URL/ng/api/private-connectivity/config?accountIdentifier=$ACCOUNT_ID" | jq
```

{% endcode %}

A successful update returns HTTP `200` and `READY`. Omitted top-level fields remain unchanged. A supplied array replaces that entire array, and a supplied `dns` object replaces the complete split-DNS map. Every domain's possible resolved IPs and every split-DNS resolver must fit inside `advertiseRoutes`.
{% endstep %}

{% step %}

### Obtain an appliance credential

**POST `/ng/api/private-connectivity/credential`**

Create a credential only when a new appliance group needs to enroll. Save the response privately; it contains a reusable 90-day Tailscale auth key. This request has no body:

{% code overflow="wrap" %}

```bash
curl --config "$PC_WORK_DIR/auth.conf" --fail-with-body \
  --request POST \
  --output "$PC_WORK_DIR/credential.json" \
  "$HARNESS_BASE_URL/ng/api/private-connectivity/credential?accountIdentifier=$ACCOUNT_ID"
```

{% endcode %}

Extract the key into the file used by the deployment guides:

{% code overflow="wrap" %}

```bash
jq -ej '.data.authKey // empty' \
  "$PC_WORK_DIR/credential.json" > "$PC_WORK_DIR/appliance.authkey"
```

{% endcode %}

The file contains the raw key without a trailing newline. The earlier `umask` keeps it private. Record `.data.expiresAt` from the saved response for renewal. Go to [Response examples](https://developer.harness.io/harness-platform/use-harness-platform/references/network-and-security/cloud-private-connectivity/reference.md#response-examples) to review the response fields.

Harness returns the raw key once and does not persist it. The same valid key can enroll intended subnet-router, App Connector, or combined replicas until it expires. Already-enrolled appliances with retained state continue working after enrollment-key expiry.

Transfer `appliance.authkey` through your approved secret manager. Do not place it in Git, tickets, chat, screenshots, cloud-init metadata, or shell history.
{% endstep %}

{% step %}

### Deploy the appliance

Go to [Deploy appliances on Kubernetes](https://developer.harness.io/harness-platform/use-harness-platform/references/network-and-security/cloud-private-connectivity/kubernetes.md) to use the recommended path, or go to [Deploy an appliance on an Ubuntu VM](https://developer.harness.io/harness-platform/use-harness-platform/references/network-and-security/cloud-private-connectivity/virtual-machine.md) to deploy the appliance when Kubernetes is unavailable.

Choose one role per appliance group:

* A subnet router advertises actual CIDRs that it can reach.
* An App Connector discovers configured domains using the appliance's own DNS.
* A combined appliance performs both functions.

After the appliance is healthy, return to [Enable and verify Harness Cloud access](#enable-and-verify-harness-cloud-access). For a new installation, keep both customer activation controls off until the appliance is ready. For a Secure Connect migration, retain existing connector opt-ins. Affected connector work must stay paused until the Tailscale path is verified.
{% endstep %}
{% endstepper %}

***

## Enable and verify Harness Cloud access

{% stepper %}
{% step %}

### Enable the required controls

**Platform connector**

Ask Harness to confirm the Harness-managed cloud delegate is ready if you need a Platform connector. In the connector, select **Connect through Harness Platform**, select **Enable Private Connectivity**, save, and run **Test Connection**. For Git, use the supported HTTP form. For Vault, use the supported JWT/Platform form.

![Git connector with Connect through Harness Platform selected and Enable Private Connectivity enabled](https://173309742-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3F2TpHXhur2QtQnORSM9%2Fuploads%2Fgit-blob-aa7aa9d3d104c26ed9dad11c676138167172b411%2Fconnector-private-connectivity.png?alt=media)

**Harness Cloud**

This setup has been shown to work with hosted Cloud build. It also works with other modules that run on Harness Cloud, such as Infrastructure as Code Management (IaCM). The steps below use a hosted Cloud build to verify the path.

**Enable Cloud Private Connectivity** defaults to **False**, including for accounts using Secure Connect. It is separate from the connector opt-in. For an existing Secure Connect account, retain the connector opt-in before cutover.

In **Account Settings > Default Settings > Continuous Integration**, configure the value inherited by organizations and projects. Keep **Allow Overrides** selected if lower scopes should choose their own value. This example keeps the account default at **False**:

![Account Default Settings showing Enable Cloud Private Connectivity set to False with Allow Overrides selected](https://173309742-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3F2TpHXhur2QtQnORSM9%2Fuploads%2Fgit-blob-66baec8b12db914d1405cad799df2caa78dc12dd%2Faccount-cloud-private-connectivity.png?alt=media)

In **Project Settings > Default Settings > Continuous Integration**, select **True** for **Enable Cloud Private Connectivity** if parent settings permit the override, then **Save**. This example enables the project while the account default remains **False**:

![Project Default Settings showing Enable Cloud Private Connectivity set to True](https://173309742-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3F2TpHXhur2QtQnORSM9%2Fuploads%2Fgit-blob-50a298ef3e11e1abd898f8473061010a7731fbac%2Fproject-cloud-private-connectivity.png?alt=media)

Confirm the project's effective value is **True**. The setting affects new Harness Cloud VMs; it does not create the account network or deploy appliances.

Configure a [Harness Cloud stage](https://developer.harness.io/docs/continuous-integration/use-ci/set-up-build-infrastructure/use-harness-cloud-build-infrastructure#use-harness-cloud) with a [supported hosted image](https://developer.harness.io/harness-platform/use-harness-platform/references/network-and-security/cloud-private-connectivity.md#supported-hosted-build-images). To check connectivity before configuring a Git connector, turn off **Clone Codebase** and add a **Run** step without a container image, using the shell for that image.
{% endstep %}

{% step %}

### Verify the private and public paths

Use a private HTTPS health endpoint with a non-secret response. Replace the example hostname with your service hostname and use its existing authentication and certificate trust.

Choose the shell for your hosted image. These examples check private access and public HTTPS:

{% tabs %}
{% tab title="Ubuntu 24 AMD64 / ARM64" %}

```sh
set -eu
getent hosts service.internal.example.com
curl --fail --noproxy '*' --max-time 30 \
  https://service.internal.example.com/health
curl --fail --max-time 30 \
  https://example.com/ --output /dev/null
```

{% endtab %}

{% tab title="Windows Server 2025 AMD64" %}
{% code overflow="wrap" %}

```powershell
$ErrorActionPreference = 'Stop'
Resolve-DnsName -Name service.internal.example.com -DnsOnly -ErrorAction Stop
curl.exe --fail --noproxy '*' --max-time 30 `
  https://service.internal.example.com/health
if ($LASTEXITCODE -ne 0) { throw 'Private HTTPS request failed' }
curl.exe --fail --max-time 30 `
  https://example.com/ --output NUL
if ($LASTEXITCODE -ne 0) { throw 'Public HTTPS request failed' }
```

{% endcode %}
{% endtab %}

{% tab title="macOS Sequoia / Tahoe ARM64" %}

```sh
set -eu
dscacheutil -q host -a name service.internal.example.com
curl --fail --noproxy '*' --max-time 30 \
  https://service.internal.example.com/health
curl --fail --max-time 30 \
  https://example.com/ --output /dev/null
```

{% endtab %}
{% endtabs %}

Confirm that the private request returns your service's expected response. If your application runs in a container, repeat the check there. The private request bypasses HTTP proxies; retain any corporate proxy settings required for other destinations.

For an App Connector, request the configured domain name rather than its IP. The first request can time out while the route is learned. Retry briefly, then use [Troubleshooting](https://developer.harness.io/harness-platform/use-harness-platform/references/network-and-security/cloud-private-connectivity/reference.md#troubleshooting) if access still fails.
{% endstep %}
{% endstepper %}

***

## Maintain the configuration

Use [PUT /config](https://developer.harness.io/harness-platform/use-harness-platform/references/network-and-security/cloud-private-connectivity/reference.md#customer-api-operations) to update routes, domains, or split DNS. Wait for GET to report `READY`, then verify the affected destination. Add routes to Harness before advertising them. Stop use of a route before removing it.

Go to [renew an appliance key](https://developer.harness.io/harness-platform/use-harness-platform/references/network-and-security/cloud-private-connectivity/reference.md#renew-an-appliance-key) to determine when you need another credential. Earlier keys remain valid until expiry or revocation; configuration updates do not rotate them. Every replica must keep its own device state.

Disabling **Enable Cloud Private Connectivity** stops enrollment of new Harness Cloud VMs without deleting your private connectivity tenant or changing connector opt-in. Contact Harness for offboarding before deleting the account.

After secure credential delivery, remove the local raw credential response, authentication file, and key file. Keep only sanitized configuration and identifiers for support.

***

## Next steps

* [API reference and troubleshooting](https://developer.harness.io/harness-platform/use-harness-platform/references/network-and-security/cloud-private-connectivity/reference.md): Add routes, manage appliance keys, or diagnose a failed connection.
* [Cloud Private Connectivity overview](https://developer.harness.io/harness-platform/use-harness-platform/references/network-and-security/cloud-private-connectivity.md): Review ownership and policy boundaries with your security team.
