Skip to main content

Step 2: Install NetFoundry Self-Hosted

NetFoundry Self-Hosted provides a guided installation process via the nf-quickstart script to deploy your network across various Kubernetes environments, supporting both interactive and automated configurations.

Before you begin​

Ensure you've completed Step 1: Plan your deployment. Prerequisites differ depending on your installation path:

K3s quickstart (installer manages the cluster)​

  • Ubuntu 22.x or Ubuntu 24.x host machine
  • User account with sudo permissions
  • DNS entry for the VM that resolves to a persistent IP address

The installer handles K3s setup, storage configuration, and all Kubernetes prerequisites automatically.

Bring your own Kubernetes cluster​

  • Ubuntu 22.x or Ubuntu 24.x host machine (or access to a machine with kubectl configured)
  • Kubernetes context loaded into your shell session
  • Default storage class configured on the cluster
  • DNS entries configured for controller and edge router addresses

The installer verifies cluster access by running kubectl cluster-info.

What the installer does​

The quickstart script walks you through deployment step by step. Each step is checkpointed, so if the installer is interrupted you can re-run it and it will resume where it left off.

  1. Verify and install prerequisites: Checks for ziti, helm, kubectl, nslookup, and zip, installing any that are missing.
  2. Set up K3s (if selected): Installs K3s, configures KUBECONFIG, and sets up a default storage class with OpenEBS.
  3. Verify cluster connectivity: Confirms kubectl and helm can communicate with the cluster and that a default storage class exists.
  4. Install the support stack: Deploys Elasticsearch, Logstash, Kibana, Grafana, RabbitMQ, and Beats agents to the support namespace. It's skipped automatically if fewer than 4 CPU cores are available.
  5. Deploy the OpenZiti controller: Installs cert-manager, trust-manager, and the controller to the ziti namespace. For bring-your-own-cluster deployments, the installer pauses here for DNS setup.
  6. Deploy an OpenZiti edge router: Installs an initial edge router with an edge listener. For bring-your-own-cluster deployments, the installer pauses again for router DNS setup.
  7. Set up OpenZiti database snapshots: Installs a scheduled job that captures regular snapshots of the database to a separate PVC.
  8. Configure support tool access over OpenZiti (optional): Creates services, policies, and identities for Grafana, Kibana, and Elasticsearch, and deploys a host identity to make the support tools accessible over the OpenZiti network without exposing external ports.
  9. Install zLAN features (optional, requires -z flag): Deploys NetFoundry zLAN components from the private container registry.
  10. Set up CLI helpers: Installs the nf-* shortcut commands and generates installation notes.

Set up the installer​

The NetFoundry self-hosted installer is available through a private package repository, and is available in AMD64 and ARM64. See Plan your deployment for system requirements. Credentials for this repository can be obtained by contacting the NetFoundry Sales team.

Set up the package repository and installer the self-hosted installation tools:

curl -fsSL https://get.netfoundry.io/linux-install.bash | sudo bash -s -- --private --username $USERNAME --password $PASS netfoundry-self-hosted

Once installed, the installation tools will prompt to begin the installation wizard:

NetFoundry installation tools have been installed successfully!

Run nf-quickstart to begin the setup wizard!

To run in non-interactive mode, run:
 export CTRL_ADDR=<ziti controller advertise address>
 nf-quickstart -y

For additional documentation, see https://netfoundry.io/docs/onprem/intro
Container registry credentials required

As of version 1.0.0, NetFoundry private container registry credentials are required for installation. The installer will prompt for these credentials during setup. For non-interactive installs, set REGISTRY_USERNAME and REGISTRY_PASSWORD environment variables before running the quickstart. Credentials can be obtained from the NetFoundry Console or by contacting your NetFoundry representative.

Run the installer​

Interactive mode​

Run the installer and follow the prompts:

nf-quickstart

The installer will prompt you for:

  • Controller advertise address
  • Edge router advertise address (if installing the default router)
  • Whether to install optional components (support tools, edge tunnel)

If you don't have an existing Kubernetes cluster, the installer can set up K3s for you when prompted.

Non-interactive mode​

For automated deployments, set the controller address and accept all defaults:

export CTRL_ADDR=<controller-advertise-address>
nf-quickstart -y

You can also pass an environment file with the -f flag to configure all variables in one place:

nf-quickstart -y -f env-quickstart.sh

A template file (env-quickstart.example) is included in the installation directory with all available variables and descriptions. Copy it and customize for your environment:

cp env-quickstart.example env-quickstart.sh
# Edit env-quickstart.sh with your values
nf-quickstart -y -f env-quickstart.sh

Offline installation​

For air-gapped environments, use the offline installation tarball. Currently the offline installer only supports single-node K3s installations.

Prerequisites​

JFROG service account credentials from the NetFoundry Console at https://<orgname>.cloudziti.io

Download and extract​

On a machine with internet access, download the tarball using your JFROG credentials:

export USERNAME=<account-username>
export PASSWORD=<account-password>
curl -fSL -u "$USERNAME:$PASS" -OJ https://netfoundry.jfrog.io/artifactory/nfpax-private-tgz-stable/deb/amd64/netfoundry-self-hosted-offline-<version>.tar.gz

Transfer the tarball to the air-gapped host and extract it to the standard install path:

sudo mkdir -p /opt/netfoundry/self-hosted
sudo chown ubuntu:ubuntu /opt/netfoundry/self-hosted
tar -zxf ./netfoundry-self-hosted-offline-<version>.tar.gz -C /opt/netfoundry/self-hosted
cd /opt/netfoundry/self-hosted

Run the installer​

Interactive mode:

./quickstart-offline.sh

Non-interactive mode:

export CTRL_ADDR=<controller-advertise-address>
./quickstart-offline.sh -y
note

Offline installation currently supports single-node K3s installations only.

Enable optional features​

NetFoundry zLAN​

Enable zLAN features during initial installation or add them later:

nf-quickstart -z

The installer will prompt for NetFoundry's private container registry credentials. For non-interactive mode, set environment variables:

export REGISTRY_USERNAME=<your-username>
export REGISTRY_PASSWORD=<your-password>
nf-quickstart -z
note

Service account credentials can be obtained by downloading the QUAY service credentials from the NetFoundry Console. Credentials are stored in Kubernetes as netfoundry-pull-secret.

Advanced deployment scenarios​

Corporate proxy environments​

Installing behind a corporate proxy requires additional setup. Review the proxy setup documentation before running nf-quickstart.

EKS storage configuration​

For installations on existing Amazon EKS clusters, initialize the ebs.csi.aws.com driver:

./installers/setup_eks_storage.sh

DNS configuration during installation​

After the installer creates Kubernetes services, configure DNS mappings before proceeding:

  1. Check the service endpoint:

    kubectl get services -n ziti

    NAME                       TYPE           EXTERNAL-IP
    ziti-controller-client     LoadBalancer   a6190904c366c4c69882d46069e44e28-12345678.us-east-1.elb.amazonaws.com

  2. Create DNS entry mapping your advertise address to the external endpoint:

    ziti-clients.example.com → a6190904c366c4c69882d46069e44e28-12345678.us-east-1.elb.amazonaws.com

  3. Resume the installer once DNS is configured.

tip

DNS changes can take several minutes to propagate. Use nslookup or dig to verify before proceeding.

Troubleshooting​

Storage class not found​

Configure a default storage class before running the installer. See Storage configuration.

DNS resolution fails​

Verify DNS entries are correctly configured and propagated:

nslookup ziti-clients.example.com

Port conflicts on K3s​

K3s quickstart requires ports above 1024. Use the default ports (1280 for controller, 3022 for router) or see the FAQ for configuration below port 1024.

Reference​

Environment variables​

These environment variables can be set before running nf-quickstart to control installer behavior. In non-interactive mode (-y), variables marked as required must be set. In interactive mode, the installer prompts for these values and the environment variables are ignored.

VariableRequiredDefaultDescription
CTRL_ADDRYes (non-interactive)—DNS address advertised by the controller for client connections. Must be a DNS name, not an IP address.
CLIENT_PORTNo1280Ziti controller client API port.
TRUST_DOMAINNoValue of CTRL_ADDRTrust domain for the controller cluster identity. This is an arbitrary string that becomes part of the SPIFFE ID and must be the same for all controllers in a cluster.
RTR_ADDRNoValue of CTRL_ADDRDNS address advertised by the edge router. On single-node installs, defaults to the controller address.
RTR_EDGE_PORTNo3022Edge router listener port.
USE_K3SNo0Set to 0 to skip K3s installation (bring-your-own-cluster). When unset in non-interactive mode, K3s installation is skipped by default.
KUBECONFIGNo/etc/rancher/k3s/k3s.yamlPath to the kubeconfig file. Automatically set for K3s installations.
REGISTRY_USERNAMEYes (with -z)—Username for the NetFoundry private container registry. Required for zLAN and Console Enterprise features.
REGISTRY_PASSWORDYes (with -z)—Password for the NetFoundry private container registry. Required for zLAN and Console Enterprise features.
CONSOLE_DISABLEDNo—Set to true to skip ZAC and Ziti Console Enterprise installation.
EXTERNAL_ELASTICSEARCHNo—Set to true to use an external Elasticsearch cluster instead of deploying one.
EXTERNAL_ES_URLYes (with external ES)—URL of the external Elasticsearch cluster (e.g., https://es.example.com:9200).
EXTERNAL_ES_USERNAMEYes (with external ES)—Username for the external Elasticsearch cluster.
EXTERNAL_ES_PASSWORDYes (with external ES)—Password for the external Elasticsearch cluster.
EXTERNAL_ES_CA_FILENo—Path to a CA certificate file for the external Elasticsearch cluster.

Generated files​

The installer produces the following files in the installation directory that can be customized for advanced configurations:

FileDescription
controller-values.ymlHelm values for the Ziti controller chart. Contains the advertised address, port, cluster configuration, and logging settings.
controller-vars.shShell variables (CTRL_ADDR, CLIENT_PORT, TRUST_DOMAIN) persisted for use by upgrade and utility scripts.
router-values.ymlHelm values for the Ziti router chart. Contains the advertised address, edge listener port, and controller connection settings.
support-values.ymlHelm values for the support stack chart. Contains Elasticsearch, Logstash, Kibana, and Grafana configuration.
INSTALL-NOTES.txtPost-installation notes including access URLs and useful commands. Credentials are not stored in this file — use nf-install-notes to retrieve them live from Kubernetes secrets.
.checkpoints/Progress tracking directory. Each completed step writes a checkpoint file so re-runs skip finished steps.

Helper commands​

The installer sets up the following nf-* shortcut commands, available after opening a new shell or running source /etc/profile.d/nf_help_menu.sh. For DEB package installs, these are also available as system-wide commands via /usr/local/bin.

CommandDescription
nf-helpShow the help menu with all available commands.
nf-quickstartRun the NetFoundry quickstart installer. Re-running resumes from the last checkpoint.
nf-upgradeUpgrade one or more installed Helm charts. Supports component flags (--controller, --router, --support, --console, --ziti-host, --k3s) and non-interactive mode (-y).
nf-statusShow Kubernetes deployment status for all NetFoundry components.
nf-install-notesDisplay installation notes and live-fetch credentials from Kubernetes secrets.
nf-loginLog into the Ziti controller CLI using the admin secret stored in Kubernetes.
nf-controller-logsLive tail of the Ziti controller logs.
nf-router-logsLive tail of the Ziti router logs.
nf-create-snapshotTake a snapshot of the Ziti database and store it on a local PVC.
nf-restore-snapshotRestore a Ziti controller database from a snapshot backup.
nf-support-bundleCollect system diagnostics and logs into a zip file for NetFoundry support.
nf-clusterManage HA controller cluster — check status, add/remove controllers, migrate to cluster mode.
nf-uninstallUninstall all NetFoundry resources from Kubernetes.
nfChange to the NetFoundry installation directory (/opt/netfoundry/self-hosted).