Deploy an appliance on an Ubuntu VM
Deploy a Cloud Private Connectivity subnet router, App Connector, or combined appliance on Ubuntu 24.04
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
sudoaccess.Outbound access listed in Network connectivity requirements.
A valid mode-
0600appliance.authkeyobtained from Configure Cloud Private Connectivity.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
Install Tailscale
Run on the VM:
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 tailscaleInstall the exact version approved by Harness and your network owner:
TAILSCALE_PACKAGE_VERSION='<approved-version>'
sudo apt-get install "tailscale=$TAILSCALE_PACKAGE_VERSION"
sudo apt-mark hold tailscale
sudo systemctl enable --now tailscaled
tailscale versionKeep the selected package version pinned until you are ready to upgrade it.
Enable IP forwarding
Subnet routing and App Connector routing require forwarding:
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.forwardingIf IPv6 is intentionally disabled throughout the customer network, omit the IPv6 setting and confirm that no configured application requires an IPv6 destination.
Stage the enrollment key
Transfer appliance.authkey through the approved secret manager, then run:
set -euo pipefail
set +x
sudo install -m 0600 /path/from/secret-manager/appliance.authkey \
/run/harness-pc.authkeyThe next step reads the key from that file. Do not put the key itself in a command argument.
Enroll one appliance role
Choose exactly one tab. Replace every example CIDR and hostname.
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)"Use comma-separated CIDRs for multiple ranges. Every advertised CIDR must be fully contained in the Harness advertiseRoutes configuration.
sudo tailscale up --auth-key=file:/run/harness-pc.authkey \
--accept-dns=false --accept-routes=false \
--advertise-connector \
--hostname="harness-app-connector-$(hostname -s)"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.
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)"Use comma-separated CIDRs for multiple static ranges. Confirm that the same VM can reach both the subnets and configured application domains.
Finish the enrollment:
sudo tailscale set --auto-update=false
sudo rm -f /run/harness-pc.authkey
sudo tailscale status
sudo tailscale netcheckKeep --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 *.
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:
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/healthFor an App Connector, verify that the VM resolves the exact configured name through its normal resolver:
getent ahosts app.internal.example.com
curl --fail --noproxy '*' --max-time 30 \
https://app.internal.example.com/healthReplace the example IP and hostname with your service values. For request failures, see 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, using a configured domain for App Connector traffic.
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:
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:
Next steps
Enable and verify Harness Cloud access: Enable private access from a Harness Cloud VM.
API and troubleshooting reference: Credential renewal and diagnostics.
Last updated
Was this helpful?