Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.
CISecurityNetworking

Configure Cloud Private Connectivity

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

Note

Cloud Private Connectivity requires enablement by Harness.

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

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

  • 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

1

Prepare customer API authentication

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

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:

auth.conf
header = "x-api-key: <your-account-admin-PAT>"

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.

2

Verify Harness provisioning

GET /ng/api/private-connectivity

Read the account configuration:

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

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.

3

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:

config.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"]
    }
  }
}

Send the update. Go to Request examples to review subnet-only and App Connector configurations.

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

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.

4

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:

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"

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

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

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

5

Deploy the appliance

Go to Deploy appliances on Kubernetes to use the recommended path, or go to Deploy an appliance on an Ubuntu VM 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. 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.


Enable and verify Harness Cloud access

1

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

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

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

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 with a supported hosted image. 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.

2

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:

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 if access still fails.


Maintain the configuration

Use PUT /config 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 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

Last updated

Was this helpful?