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 Ziti 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. Skipped automatically if fewer than 4 CPU cores are available.
  5. Deploy the Ziti controller — installs cert-manager, trust-manager, and the Ziti controller to the ziti namespace. For bring-your-own-cluster deployments, the installer pauses here for DNS setup.
  6. Deploy a Ziti 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 Ziti database snapshots — installs a scheduled job that captures regular snapshots of the Ziti database to a separate PVC.
  8. Configure support tool access over Ziti (optional) — creates Ziti services, policies, and identities for Grafana, Kibana, and Elasticsearch, and deploys a Ziti host identity to make the support tools accessible over the Ziti 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.

Setting up the installer​

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

Setup 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

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

Example:

export CTRL_ADDR=ziti-clients.example.com
nf-quickstart  -y

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​

# Download the tarball
curl -fSL -u "$USERNAME:$PASS" -OJ https://netfoundry.jfrog.io/artifactory/nfpax-private-tgz-stable/deb/amd64/On-Prem-Offline-0.4.2.tar.gz

# Extract on the destination machine
mkdir -p netfoundry
tar -zxf ./On-Prem-Offline-0.4.2.tar.gz -C ./netfoundry
cd ./netfoundry

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.