Traceable Platform - Single Node Installation¶

This guide provides step-by-step instructions for installing the Traceable Platform on a single node, covering both internet-connected and airgap environments.

Overview¶

Single node installation is suitable for:

Development and testing environments
Small-scale deployments
Proof of concept setups

For production deployments with high availability requirements, see Multi-Node Installation.

Prerequisites¶

Before proceeding, ensure you have:

Completed the Platform Checklist
Met all VM Requirements
Configured System Settings
Registry credentials (for internet-connected installations)
Downloaded airgap bundle (for airgap installations)

Installation Methods¶

Choose the appropriate installation method based on your environment:

Method	Use Case
Internet Access	VM with direct internet access
Bundled Airgap	Offline VM without internet
Existing Airgap K8s	Pre-existing offline Kubernetes cluster

Internet Access Installation¶

For VMs with direct internet connectivity.

Step 1: Export Environment Variables¶

Set the required environment variables:

export CLUSTERMGR_VERSION=<version>
export REPO_USER=<your-registry-username>
export REPO_PWD=<your-registry-password>
export RKE2_VERSION=v1.35.3+rke2r3

Parameters:

CLUSTERMGR_VERSION: Version of ClusterMgr to download (e.g., 2.5.0)
REPO_USER: Your Traceable registry username
REPO_PWD: Your Traceable registry password/token

Step 2: Download ClusterMgr¶

Download and extract the ClusterMgr binary:

curl -L https://downloads.traceable.ai/platform/installer/clustermgr/linux-amd64/traceable-clustermgr-${CLUSTERMGR_VERSION}-linux-amd64.tgz | tar -zxv
cd traceable-clustermgr-${CLUSTERMGR_VERSION}

Step 3: Run Installation¶

Execute the installation command:

sudo ./clustermgr install --dns <DNS_NAME> \
    --registry-host="pkg.harness.io/ieq3j_9otlwbpfz-uryoda/docker-external" \
    --registry-prefix="" \
    --registry-user $REPO_USER --registry-password $REPO_PWD

Parameters:

--dns: The DNS name for accessing the platform (must be externally accessible)
--registry-host: Traceable container registry host
--registry-prefix: Registry path prefix (empty for default)
--registry-user: Registry authentication username
--registry-password: Registry authentication password

Step 3.1: Dry Run Mode (Optional)¶

To validate the installation without making changes, use dry-run mode:

sudo ./clustermgr install --dns <DNS_NAME> \
    --registry-host="pkg.harness.io/ieq3j_9otlwbpfz-uryoda/docker-external" \
    --registry-prefix="" \
    --registry-user $REPO_USER --registry-password $REPO_PWD \
    --dry-run

Expected Pre-flight Check Output:

[PASS] Number of CPUs: This server has at least 4 CPU cores
[PASS] Amount of Memory: The system has at least 8G of memory
[PASS] Ephemeral Disk Usage /var/lib/kubelet: The disk containing directory /var/lib/kubelet has at least 30Gi of total space, has at least 10Gi of disk space available, and is less than 60% full
[PASS] Kubernetes API TCP Port Status: Port 6443 is open
[PASS] ETCD Client API TCP Port Status: Port 2379 is open
[PASS] ETCD Server API TCP Port Status: Port 2380 is open
[PASS] ETCD Health Server TCP Port Status: Port 2381 is available
[PASS] Kubelet Health Server TCP Port Status: Port 10248 is available
[PASS] Kubelet API TCP Port Status: Port 10250 is open
[PASS] Kube Controller Manager Health Server TCP Port Status: Port 10257 is available
[PASS] Kube Scheduler Health Server TCP Port Status: Port 10259 is available
[PASS] Filesystem Performance: Write latency is ok (p99 target < 10ms, actual: 2.987837ms)
[PASS] NTP Status: System clock is synchronized
[PASS] NTP Status: Timezone is set to UTC
[PASS] Host OS Info: containerd addon supports ubuntu 20.04
[PASS] Weave Network Policy Controller Metrics Server TCP Port Status: Port 6781 is available
[PASS] Weave Net Metrics Server TCP Port Status: Port 6782 is available
[PASS] Weave Net Control TCP Port Status: Port 6783 is open
⚙  Host preflights success

Bundled Airgap Installation¶

For offline VMs without internet access.

Step 1: Download Airgap Package¶

On a machine with internet access, download the latest airgap package:

traceable-platform-airgap-<version>.tgz

NOTE: Reach out to Traceable support to provide you the download link

Step 2: Transfer to Target VM¶

Transfer the airgap package to the target VM using secure methods (SCP, SFTP, or physical media).

Step 3: Extract and Install¶

On the target VM:

tar -xzf traceable-platform-airgap-<version>.tgz
cd traceable-clustermgr-<version>

Step 4: Run Installation¶

Execute the airgap installation:

sudo ./clustermgr install --dns <DNS_NAME> --airgap

Parameters:

--dns: The DNS name for accessing the platform
--airgap: Enable airgap installation mode

Existing Airgap Kubernetes Cluster¶

For deploying on a pre-existing Kubernetes cluster in an airgap environment.

Step 1: Download and Transfer Airgap Package¶

Follow the same steps as Bundled Airgap Installation to download and transfer the package.

Step 2: Run Installation¶

sudo ./clustermgr install-ti --dns <DNS_NAME> --airgap

Custom Storage Class¶

If your default storage class is named something other than "local", include the storage class parameter:

sudo ./clustermgr install-ti --dns <DNS_NAME> --airgap \
    --ti-args storageClass=<StorageClassName>

RHEL 9 Considerations¶

The kurl bundle doesn't package certain RPMs required for RHEL 9. Install these packages manually before running the ClusterMgr installation:

sudo yum install -y socat git conntrack fio

Installer Options Reference¶

Common Flags¶

Flag	Description
`--airgap`	Enable airgap install mode
`--dns <hostname>`	DNS name for the platform (defaults to `$(hostname -f)`)
`--dry-run`	Execute in dry run mode (pre-flight checks only)
`--email <email>`	Admin user email (defaults to `admin@<domain>`)
`--password <password>`	Admin password (auto-generated if not set)
`--version <version>`	Platform version to install

Note: On single-node installs the auto-generated password is saved to ./passwd.

Registry Flags¶

Flag	Description
`--registry-host <host>`	Docker registry hostname
`--registry-prefix <prefix>`	Path prefix for images
`--registry-user <user>`	Registry username
`--registry-password <password>`	Registry password

Advanced Flags¶

Flag	Description
`--disable-installer-auth`	Disable authentication for installer UI
`--skip-ti`	Skip Traceable Installer helm install
`--skip-image-load`	Skip loading images (for non-airgap)
`--mount-to <path>`	Mount `/var/**` directories to different location
`--mount-data-to <path>`	Mount only data directories to different location
`--ti-args <args>`	Additional arguments for Traceable Installer
`--ti-set <key=value>`	Helm arguments for Traceable Installer
`--ti-set-file <file>`	Helm values file for Traceable Installer
`--helm-values <file>`	Helm values override file
`--kurl-hash <hash>`	Kurl spec hash (default: `8fba4a1`)
`--kurl-options <options>`	Comma-separated kurl options

Registry Host and Prefix Examples¶

For an image with original path docker.io/ingress-nginx/controller:v1.3.1:

registry-host	registry-prefix	Result
`""`	`""`	`docker.io/ingress-nginx/controller:v1.3.1`
`example.com`	`""`	`example.com/ingress-nginx/controller:v1.3.1`
`example.com`	`path1`	`example.com/path1/controller:v1.3.1`
`example.com/namespace`	`""`	`example.com/namespace/ingress-nginx/controller:v1.3.1`
`example.com/namespace`	`path1/path2`	`example.com/namespace/path1/path2/controller:v1.3.1`

Verification¶

After installation completes:

Check Pod Status:

kubectl get pods -n traceable

All pods should be in Running state.

Access Platform UI: Navigate to https://<DNS_NAME> and login with your admin credentials.
Verify Installation: See Post-Installation Checks for comprehensive validation steps.

Troubleshooting¶

Pre-flight Check Failures¶

If pre-flight checks fail:

Review the specific failure message
Address the underlying issue (ports, disk space, memory, etc.)
Re-run with --dry-run to verify fixes
Proceed with full installation

Installation Timeout¶

If installation times out:

Check network connectivity to registry
Verify registry credentials
Check available disk space
Review logs: kubectl logs -n traceable <pod-name>

Pod Startup Issues¶

If pods fail to start:

Check pod events: kubectl describe pod -n traceable <pod-name>
Check logs: kubectl logs -n traceable <pod-name>
Verify storage class availability
Check resource availability (CPU, memory)

Next Steps¶

After successful installation:

Complete Post-Installation Checks
Configure SMTP Setup for email notifications
Configure SAML Setup for SSO authentication
Deploy Traceable Platform Agent (TPA)

Support¶

For installation assistance, contact: support@harness.io

Provide the following information:

ClusterMgr version
Target OS and version
Installation method (internet/airgap)
Pre-flight check output
Error messages and logs