> 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/virtual-machine.md).

# Deploy an appliance on an Ubuntu VM

Deploy a Cloud Private Connectivity subnet router, App Connector, or combined appliance on Ubuntu 24.04

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

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

Kubernetes is the recommended deployment. Use this procedure when a Kubernetes cluster is unavailable. Each Ubuntu 24.04 VM becomes one persistent subnet router, App Connector, or combined appliance.

***

## Before you begin

Before you deploy a private connectivity appliance on an Ubuntu VM, ensure you have the following:

* A fresh Ubuntu 24.04 AMD64 VM that can reach the private services and any private DNS resolver.
* Root or passwordless `sudo` access.
* Outbound access listed in [Network connectivity requirements](https://developer.harness.io/harness-platform/3.0/harness-platform-resources/references/network-and-security/cloud-private-connectivity.md#network-connectivity-requirements).
* A valid mode-`0600` `appliance.authkey` obtained from [Configure Cloud Private Connectivity](https://developer.harness.io/harness-platform/3.0/harness-platform-resources/references/network-and-security/cloud-private-connectivity/configure.md#obtain-an-appliance-credential).
* The actual CIDRs for a subnet router and configured domains for an App Connector.

The VM needs no public inbound port. Keep its normal management path separate from the Tailscale data path.

***

## Install and enroll the appliance

{% stepper %}
{% step %}

### Install Tailscale

Run on the VM:

{% code overflow="wrap" %}

```bash
set -euo pipefail
. /etc/os-release
test "$ID" = ubuntu
test "$VERSION_CODENAME" = noble
sudo install -d -m 0755 /usr/share/keyrings
curl -fsSL \
  https://pkgs.tailscale.com/stable/ubuntu/noble.noarmor.gpg \
  | sudo tee /usr/share/keyrings/tailscale-archive-keyring.gpg >/dev/null
curl -fsSL \
  https://pkgs.tailscale.com/stable/ubuntu/noble.tailscale-keyring.list \
  | sudo tee /etc/apt/sources.list.d/tailscale.list >/dev/null
sudo apt-get update
apt-cache madison tailscale
```

{% endcode %}

Install the exact version approved by Harness and your network owner:

```bash
TAILSCALE_PACKAGE_VERSION='<approved-version>'
sudo apt-get install "tailscale=$TAILSCALE_PACKAGE_VERSION"
sudo apt-mark hold tailscale
sudo systemctl enable --now tailscaled
tailscale version
```

Keep the selected package version pinned until you are ready to upgrade it.
{% endstep %}

{% step %}

### Enable IP forwarding

Subnet routing and App Connector routing require forwarding:

{% code overflow="wrap" %}

```bash
printf '%s\n' \
  'net.ipv4.ip_forward = 1' \
  'net.ipv6.conf.all.forwarding = 1' \
  | sudo tee /etc/sysctl.d/99-harness-private-connectivity.conf >/dev/null
sudo sysctl --system
sysctl net.ipv4.ip_forward net.ipv6.conf.all.forwarding
```

{% endcode %}

If IPv6 is intentionally disabled throughout the customer network, omit the IPv6 setting and confirm that no configured application requires an IPv6 destination.
{% endstep %}

{% step %}

### Stage the enrollment key

Transfer `appliance.authkey` through the approved secret manager, then run:

{% code overflow="wrap" %}

```bash
set -euo pipefail
set +x
sudo install -m 0600 /path/from/secret-manager/appliance.authkey \
  /run/harness-pc.authkey
```

{% endcode %}

The next step reads the key from that file. Do not put the key itself in a command argument.
{% endstep %}

{% step %}

### Enroll one appliance role

Choose exactly one tab. Replace every example CIDR and hostname.

{% tabs %}
{% tab title="Subnet Router" %}
{% code overflow="wrap" %}

```bash
sudo tailscale up --auth-key=file:/run/harness-pc.authkey \
  --accept-dns=false --accept-routes=false \
  --advertise-routes=10.77.0.0/24 \
  --hostname="harness-subnet-$(hostname -s)"
```

{% endcode %}

Use comma-separated CIDRs for multiple ranges. Every advertised CIDR must be fully contained in the Harness `advertiseRoutes` configuration.
{% endtab %}

{% tab title="App Connector" %}
{% code overflow="wrap" %}

```bash
sudo tailscale up --auth-key=file:/run/harness-pc.authkey \
  --accept-dns=false --accept-routes=false \
  --advertise-connector \
  --hostname="harness-app-connector-$(hostname -s)"
```

{% endcode %}

The VM's own resolver must resolve every domain configured in Harness. Do not add static routes unless this VM is intended to be combined.
{% endtab %}

{% tab title="Combined" %}
{% code overflow="wrap" %}

```bash
sudo tailscale up --auth-key=file:/run/harness-pc.authkey \
  --accept-dns=false --accept-routes=false \
  --advertise-connector --advertise-routes=10.77.0.0/24 \
  --hostname="harness-combined-$(hostname -s)"
```

{% endcode %}

Use comma-separated CIDRs for multiple static ranges. Confirm that the same VM can reach both the subnets and configured application domains.
{% endtab %}
{% endtabs %}

Finish the enrollment:

```bash
sudo tailscale set --auto-update=false
sudo rm -f /run/harness-pc.authkey
sudo tailscale status
sudo tailscale netcheck
```

Keep `--accept-dns=false` and `--accept-routes=false`. Do not add customer-selected tags. Exit nodes are unsupported: never add `--advertise-exit-node` or advertise `0.0.0.0/0`, `::/0`, or `*`.
{% endstep %}

{% step %}

### Verify appliance connectivity

For a subnet router, verify private reachability and the selected local route. Use the service hostname while connecting to its private IP:

```bash
ip route get 10.77.0.10
curl --fail --noproxy '*' --max-time 30 \
  --resolve service.internal.example.com:443:10.77.0.10 \
  https://service.internal.example.com/health
```

For an App Connector, verify that the VM resolves the exact configured name through its normal resolver:

```bash
getent ahosts app.internal.example.com
curl --fail --noproxy '*' --max-time 30 \
  https://app.internal.example.com/health
```

Replace the example IP and hostname with your service values. For request failures, see [Troubleshooting](https://developer.harness.io/harness-platform/3.0/harness-platform-resources/references/network-and-security/cloud-private-connectivity/reference.md#troubleshooting).

Tailscale stores the device identity under `/var/lib/tailscale`. Retain that directory across restarts and maintenance.

Next, [verify access from a Harness Cloud VM](https://developer.harness.io/harness-platform/3.0/harness-platform-resources/references/network-and-security/cloud-private-connectivity/configure.md#enable-and-verify-harness-cloud-access), using a configured domain for App Connector traffic.
{% endstep %}
{% endstepper %}

***

## Replace or retire a VM

Bring the replacement online and verify it from a fresh Harness Cloud VM before withdrawing the old appliance. On the old VM, run:

{% code overflow="wrap" %}

```bash
sudo tailscale set --advertise-connector=false --advertise-routes=
sudo tailscale down
```

{% endcode %}

Verify that the new appliance carries the intended route. Preserve the old state until the change is accepted. A broader route on another appliance is not equivalent failover for a more-specific route.

To upgrade Tailscale, confirm the target version with Harness Support, then unhold, install that version, and hold it again:

```bash
sudo apt-mark unhold tailscale
sudo apt-get install "tailscale=<approved-version>"
sudo apt-mark hold tailscale
```

***

## Next steps

* [Enable and verify Harness Cloud access](https://developer.harness.io/harness-platform/3.0/harness-platform-resources/references/network-and-security/cloud-private-connectivity/configure.md#enable-and-verify-harness-cloud-access): Enable private access from a Harness Cloud VM.
* [API and troubleshooting reference](https://developer.harness.io/harness-platform/3.0/harness-platform-resources/references/network-and-security/cloud-private-connectivity/reference.md): Credential renewal and diagnostics.
