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 and verify the following:

  • Ubuntu 22.x or Ubuntu 24.x host machine
  • User account with sudo permissions
  • For existing Kubernetes clusters: 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 automates deployment by:

  1. Verifying prerequisites and cluster connectivity
  2. Installing NetFoundry Support stack to the support namespace
  3. Deploying OpenZiti ziti-controller to the ziti namespace
  4. Optionally installing a Ziti edge router with edge listener (requires an advertise address that is reachable by the Ziti network clients)
  5. Optionally configuring Ziti network resources for support tool access (Ziti services and policies for Grafana, Kibana, and RabbitMQ)
  6. Optionally installing Ziti edge tunnel as a host identity to access the support resources in the support namespace

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.md](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. zLAN features are not currently supported.

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.