> 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/3.0/harness-platform-resources/references/network-and-security/cloud-private-connectivity/reference.md).

# Cloud Private Connectivity API and troubleshooting

Customer API requests, field limits, credentials, application configuration, and Cloud Private Connectivity troubleshooting

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

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

{% hint style="warning" %}
When contacting Harness Support, provide the sanitized account/project, execution or connector ID, timestamp, HTTP/correlation ID, platform, destination class, and expected versus actual result. Never attach raw API keys, auth keys, delegate tokens, JWTs, Vault values, machine-state files, or full process environments.
{% endhint %}

Use this reference with [Configure Cloud Private Connectivity](https://developer.harness.io/harness-platform/3.0/harness-platform-resources/references/network-and-security/cloud-private-connectivity/configure.md). Harness provisions and releases the account network and operates the Harness-managed cloud delegate. Customers use only the read, configuration-update, and appliance-credential operations documented here.

***

## Supported Platform connector operations

Select **Connect through Harness Platform** and **Enable Private Connectivity** for the following supported forms. Harness must also confirm the Harness-managed cloud delegate is ready for your account.

| Connector                              | Required form                                                               |
| -------------------------------------- | --------------------------------------------------------------------------- |
| AWS, GCP, Docker Registry, Artifactory | Platform execution with Private Connectivity enabled                        |
| Generic Git, GitHub, GitLab, Bitbucket | HTTP connection with Platform execution and Private Connectivity enabled    |
| HashiCorp Vault                        | JWT authentication with Platform execution and Private Connectivity enabled |

SSH Git does not expose this toggle. Vault Token, AppRole, Vault Agent, Kubernetes and AWS IAM authentication retain their supported customer-delegate paths. Other connector types are not supported through the Harness-managed cloud delegate merely because a Harness Cloud VM can reach their destination.

For private Git on Harness Cloud, the codebase clone also requires the **Enable Cloud Private Connectivity** setting. **Test Connection** checks the connector path only. Repository browsing and Git-status operations can use different paths; confirm support for the operations you need with Harness.

***

## Customer API operations

Use an Account Admin personal API key with **Account Edit** permission at account scope. Every request uses your Harness host, the `accountIdentifier` query parameter, and the `x-api-key` header. Do not add an organization, project, provider, tailnet, or managed-delegate identifier. Go to [Verify and configure the account](https://developer.harness.io/harness-platform/3.0/harness-platform-resources/references/network-and-security/cloud-private-connectivity/configure.md#verify-and-configure-the-account) for complete `curl` requests. JSON request and response examples are below.

Harness must first enable Cloud Private Connectivity for the account and provision its network. Customer account provisioning is not part of these APIs.

GET and POST have no request body. PUT accepts the fields to update.

| Method | Endpoint                                  | Success                        |
| ------ | ----------------------------------------- | ------------------------------ |
| GET    | `/ng/api/private-connectivity`            | `200`: account configuration   |
| PUT    | `/ng/api/private-connectivity/config`     | `200`: resulting configuration |
| POST   | `/ng/api/private-connectivity/credential` | `200`: appliance key and hints |

GET and PUT return account configuration without credentials. Securely save the credential response's `authKey`; Harness returns the raw key only once.

PUT is a **partial update**. Omitted top-level fields remain unchanged. A supplied `advertiseRoutes` or `domains` array replaces that complete array. A supplied `dns` object replaces the complete split-DNS map. Use `[]` to clear routes or domains and `{"dns":{"splitDnsDomains":{}}}` to clear split DNS. Explicit `null` and unknown fields fail validation; `{}` is a no-op.

PUT applies the configuration before returning HTTP `200` with `READY`. A provider failure returns an error; read GET before retrying. GET can show `UPDATING` while another request is applying. A concurrent customer operation can return `409`. `READY` confirms control-plane configuration, not customer-appliance or application health.

When narrowing routes, also update or clear any split-DNS resolver outside the new boundary. Otherwise, the request is rejected.

### Configuration fields

Harness initially provisions `advertiseRoutes: ["*"]`, empty domains, and no split-DNS overrides. PUT preserves every omitted field. Clearing routes requires empty domains and split DNS as well; clear all three together if they are configured. This disables customer routing without deleting the Harness-managed account network.

| Field                 | Type                                                            | Meaning and validation                                                                                                                                                                                                                                                                                  |
| --------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `advertiseRoutes`     | Optional array of one or more CIDRs, `["*"]`, or an empty array | `["*"]` permits supported IPv4/IPv6 application ranges. Explicit values must be canonical CIDRs such as `10.77.0.0/24`, not `10.77.0.7/24`. Do not mix `*` with CIDRs. Default routes and protected ranges are excluded. The boundary applies to subnet and App Connector routes. `[]` permits neither. |
| `domains`             | Optional array with at most 250 distinct normalized values      | Exact dotted names or scoped `*.` wildcards, such as `git.internal.example.com` or `*.artifacts.example.com`. Do not include a URL scheme, path, port, bare `*`, public suffix, underscore, or trailing dot. Resolved addresses must fit `advertiseRoutes`.                                             |
| `dns`                 | Optional object                                                 | Contains only `splitDnsDomains`. Supplying it replaces the complete split-DNS map.                                                                                                                                                                                                                      |
| `dns.splitDnsDomains` | Map of DNS suffixes to resolver arrays                          | Each key is a dotted suffix, not a URL or wildcard. Every resolver must be an IPv4 or IPv6 address inside a permitted subnet route and reachable through a subnet router. App Connector discovery does not itself require this map.                                                                     |

Routes, domains, and resolver arrays are trimmed, deduplicated, and sorted. Domains and suffixes are lowercased. CIDRs and resolver IPs are validated, not repaired. DNS labels have a 63-character limit and complete names have a 253-character limit. Duplicate suffixes after normalization are rejected.

Configuration determines account policy; it does not assign a role to an appliance. Customers can deploy subnet-router, App Connector, combined, or mixed appliance groups. Do not submit `routerType`, `mode`, policy JSON, tags, or credential options.

### Request examples

Save the JSON for your use case as `config.json` and send it using the [PUT request](https://developer.harness.io/harness-platform/3.0/harness-platform-resources/references/network-and-security/cloud-private-connectivity/configure.md#keep-or-narrow-the-default-policy). Replace the example values with your destinations.

**Subnet router**

```json
{
  "advertiseRoutes": ["10.77.0.0/24"]
}
```

**App Connector**

These domains are restricted to the specified address range:

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

**Combined appliance with split DNS**

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

All possible IPv4 and IPv6 answers for each configured domain must fit the route boundary. Use `/32` or `/128` for exact addresses, a containing CIDR for an approved range, or keep `["*"]` when the broad supported boundary is intended.

**Clear the configuration**

This clears routes, domains, and split DNS while retaining the account network:

```json
{
  "advertiseRoutes": [],
  "domains": [],
  "dns": {
    "splitDnsDomains": {}
  }
}
```

Sending only `{"advertiseRoutes": []}` is rejected if existing domains or split-DNS mappings remain, because omitted fields are preserved.

### What route changes do

`advertiseRoutes` is the allowed destination boundary for both subnet routers and App Connectors. Narrowing it removes access to excluded destinations, including previously approved routes. Adding an allowed range permits appliances to advertise it without re-enrolling. `*` permits supported application ranges; it does not advertise a default route from an appliance.

A server-side update does not rewrite a subnet router's local command. A device can remain enrolled and continue advertising a now-unapproved route, but Harness workloads cannot use that route. Stop using a route before narrowing policy, then align the appliance configuration.

Domains drive App Connector discovery but do not create exceptions outside the IP boundary. For example, if `artifactory.internal.example.com` resolves to `10.30.0.10`, a boundary of `10.20.0.0/16` does not permit it. Add `10.30.0.10/32` or an intended containing CIDR.

Every authorized customer appliance has the shared appliance identity and can advertise an allowed range. Appliance groups split paths, not access permissions. A broad CIDR permits that range to every enrolled workload with its activation control enabled. Keep destination firewalls and application authorization in place.

Exit nodes are unsupported. Do not use `--advertise-exit-node`, `0.0.0.0/0`, or `::/0`. Protected ranges include loopback, link-local, multicast, carrier-grade NAT and Tailscale address space (`100.64.0.0/10`), IPv4 `0.0.0.0/8` and `240.0.0.0/4`, and unspecified IPv6 addresses.

### Response examples

**GET and PUT: account configuration**

Both operations return the following response shape. PUT returns the complete resulting configuration:

```json
{
  "status": "SUCCESS",
  "data": {
    "accountIdentifier": "<account-id>",
    "status": "READY",
    "advertiseRoutes": ["10.77.0.0/24"],
    "domains": ["git.internal.example.com"],
    "dns": {
      "splitDnsDomains": {
        "internal.example.com": ["10.77.0.53"]
      }
    }
  },
  "correlationId": "<request-id>"
}
```

**POST /credential: appliance key**

The credential request returns HTTP `200` with `Cache-Control: no-store`:

```json
{
  "status": "SUCCESS",
  "data": {
    "authKey": "<returned-once-secret>",
    "expiresAt": 1790000000000,
    "installHints": ["<server-generated secret-free guidance>"]
  },
  "correlationId": "<request-id>"
}
```

`expiresAt` is epoch milliseconds. The key can enroll intended replicas until that time. Each enrolled appliance must keep its own persistent device state. Existing enrolled devices remain connected after enrollment-key expiry.

On failure, retain the HTTP status and sanitized correlation ID:

| HTTP status   | Meaning                                      |
| ------------- | -------------------------------------------- |
| `400`         | Invalid input or disabled account capability |
| `401` / `403` | Authentication or permission failure         |
| `409`         | Conflicting operation                        |
| `500`         | Service or provider failure                  |

Read current state before retrying. Do not repeatedly create credentials after an uncertain result.

### Renew an appliance key

Follow [Obtain an appliance credential](https://developer.harness.io/harness-platform/3.0/harness-platform-resources/references/network-and-security/cloud-private-connectivity/configure.md#obtain-an-appliance-credential) to generate a new key using the same POST request.

Update only the enrollment Secret for appliance groups that can create new identities. Retain existing device-state Secrets or `/var/lib/tailscale`. Remove the local response and key file after secure delivery. If the request result is uncertain, read state and contact Harness instead of repeatedly calling the credential endpoint.

***

## Troubleshooting

Diagnose in order: account state and activation, Harness-managed cloud delegate or Harness Cloud VM identity, DNS, route, destination port, then application errors.

<details>

<summary>A Harness Cloud VM reports that egress control and Private Connectivity cannot be enabled together</summary>

These networking modes cannot be combined for the same Harness Cloud VM. Ask Harness and your security owner to confirm a compatible Harness Cloud configuration before retrying. Do not change appliance routes, rotate credentials, or remove a security policy as a generic workaround. Application-level proxy settings are a separate concern.

</details>

<details>

<summary>Private Connectivity initialization fails after selecting a different hosted image</summary>

Select an image from [Supported hosted build images](https://developer.harness.io/harness-platform/3.0/harness-platform-resources/references/network-and-security/cloud-private-connectivity.md#supported-hosted-build-images). Tailscale must be preinstalled; installing it in a Run step does not repair initialization. Contact Harness Support if the required image is unavailable.

</details>

<details>

<summary>Cloud Private Connectivity reports READY but a private service is unreachable</summary>

READY describes control-plane configuration, not appliance health. Verify the appliance can reach the target, the approved route is advertised, forwarding is enabled, and the target firewall permits the application port. Compare private-IP and DNS-name access before changing credentials.

</details>

<details>

<summary>A Harness Platform connector cannot find the Harness-managed cloud delegate</summary>

Ask Harness to confirm the Harness-managed cloud delegate is ready for your account. Do not switch to an unrelated customer delegate as a workaround. A working Harness Cloud VM does not prove that connector operations are ready.

</details>

<details>

<summary>A private hostname fails but its private IP is reachable</summary>

Check the exact DNS suffix and the resolver's route. For App Connector mode, verify the appliance itself resolves the configured name and keeps that DNS configuration after reboot. Do not replace all public DNS with a private-only resolver.

</details>

<details>

<summary>The first request to an App Connector domain times out</summary>

A DNS answer can arrive before the learned route reaches the client. Verify that the appliance resolves the configured name and that every returned address fits the account's route boundary. Use bounded retries and verify a successful fresh request before starting dependent workloads. Persistent failure requires checking the appliance, DNS, and approved routes. For known destination ranges that require immediate access, use a subnet router or combined appliance advertising those approved CIDRs.

</details>

<details>

<summary>A private HTTPS request reports a certificate error</summary>

Cloud Private Connectivity does not change your service certificate or authentication requirements. Use the service hostname and configure certificate trust in the client that makes the request. Go to the existing CI guidance for [private Docker registry certificates](https://developer.harness.io/3k-docs/continuous-integration/ci-articles-faqs/continuous-integration-faqs#how-do-i-use-a-self-signed-certificate-for-a-private-docker-registry-in-the-build-and-push-to-docker) or [JFrog certificate errors](https://developer.harness.io/3k-docs/continuous-integration/ci-articles-faqs/continuous-integration-faqs#upload-artifacts-to-jfrog-step-throws-certificate-signed-by-unknown-authority) when applicable.

</details>

<details>

<summary>Small private requests work but large artifact transfers stall or slow down</summary>

Record transfer size, time, and the Tailscale direct-or-relay path. Ask the network owner to inspect MTU, TCP MSS, firewall and NAT behavior before changing host networking. A successful small ping does not establish large-transfer performance.

</details>

Tailscale can relay encrypted traffic when a direct peer connection is unavailable. Relay use can reduce throughput; it does not mean the traffic bypassed encryption. Inspect `tailscale status`, `tailscale ping`, and `tailscale netcheck` on authorized appliances. Go to [Firewall behavior](https://tailscale.com/docs/integrations/firewalls) and [TCP/MTU diagnostics](https://tailscale.com/docs/reference/troubleshooting/network-configuration/tcp-connection-two-devices) to diagnose performance.

Review overlaps between customer routes and Harness Cloud VM or container networks before rollout. A route can take precedence over another network's same addresses. App Connector domains may also redirect to other hostnames that need separate configuration. Go to [Overlapping routes](https://tailscale.com/docs/reference/troubleshooting/network-configuration/lan-traffic-overlapping-subnets) and [App Connector considerations](https://tailscale.com/docs/features/app-connectors) to review these cases. Do not add a default route or broad wildcard as a blanket fix.

***

## Next steps

* [Configure Cloud Private Connectivity](https://developer.harness.io/harness-platform/3.0/harness-platform-resources/references/network-and-security/cloud-private-connectivity/configure.md): Apply the configuration for cloud private connectivity.
