Step 1: Plan your deployment

Before installing NetFoundry Self-Hosted, review the hardware, software, and network requirements to ensure a successful deployment.

Choose your deployment type

NetFoundry Self-Hosted supports different deployment scenarios based on your environment and use case:

Deployment type	Best for	Requirements
Production cluster	Production workloads	Existing Kubernetes cluster with specific resource requirements
K3s quickstart	Virtual appliance, single-node deployments	Single Ubuntu VM, quickstart script handles setup
Offline installation	Air-gapped environments	Pre-downloaded installation tarball, K3s only

Production deployments

Production deployments require an existing Kubernetes cluster with proper resource allocation and storage configuration.

Minimum cluster requirements

Full installation (Ziti components + support stack)

• 4 CPU cores minimum (8 recommended)
• 16 GB memory minimum
• Dedicated or compute-optimized nodes (AWS c5.* series recommended)
• IP provisioning, storage, and LoadBalancer provisioning configured
• Default storage class configured (CSI-enabled storage recommended)

Small-footprint installation (Ziti components only):

• Single-node cluster (K3s or MicroK8s)
• 4 CPU cores
• 8 GB memory
• Default storage class configured

Cluster compatibility

NetFoundry Self-Hosted can't be installed on clusters with cert-manager already installed. A dedicated Kubernetes cluster is recommended.

Storage configuration

CSI-enabled storage provides volume resizing, snapshots, and automated backups. Storage drivers depend on your Kubernetes provider.

For EKS clusters, initialize the ebs.csi.aws.com driver:

./installers/setup_eks_storage.sh

For other Kubernetes providers, see the Kubernetes CSI drivers list.

Network and access requirements

A functioning network requires clients to establish connections to two key components:

Controller client advertise address

• Used by clients to establish API sessions and discover available services.
• Used to establish the fastest path through the mesh and create complete circuits.
• Must be reachable by all Ziti clients.
• Must be a DNS name—IP addresses aren't supported, and the installer rejects CTRL_ADDR set to an IPv4 or IPv6 address.

Edge router advertise address

• Clients must connect to at least one edge router to pass traffic.
• Edge router can run separately from the controller.
• NetFoundry Self-Hosted installs an initial router by default for convenience.

DNS mapping example

The quickstart script creates load-balanced Kubernetes services that require DNS mapping:

kubectl get services -n ziti

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

If your desired controller address is ziti-clients.example.com, create a DNS entry mapping:

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

DNS configuration

DNS setup depends on your environment. You must configure DNS manually using your DNS registry before the installer can proceed with edge router installation.

Single-node deployments (K3s quickstart)

The quickstart installer simplifies deployment by setting up a single-node K3s cluster on a single VM. This is suitable for production use as a virtual appliance as well as for development, testing, and demos.

Hardware requirements

• 4 CPU cores minimum
• 16 GB RAM minimum
• 50 GB storage minimum
• VM equivalent: AWS t3.xlarge or similar

Software requirements

• Ubuntu 22.04 or 24.04
• User account with sudo permissions
• The installer will verify and prompt to install required packages.

Network requirements

• A persistent DNS entry for the VM (survives reboots)
• These ports must be accessible to Ziti clients and routers:
  • Ziti Client Access to Control Plane: Default 1280 (must be > 1024 for K3s)
  • Ziti Router Edge/Link Listeners: Default 3022 (must be > 1024 for K3s)

note

Port restrictions K3s quickstart installations require ports higher than 1024. To use ports below 1024, see the FAQ documentation for additional configuration steps.

Offline/air-gapped deployments

Offline installations use a pre-packaged tarball containing all necessary packages and container images.

Current limitations:

• Single-node K3s installations only (full K8s support coming soon).
• Requires JFROG service account credentials from NetFoundry Console.
• Container registry credentials aren't needed at install time — every private image is pre-loaded from the tarball.

Requirements:

• Same as K3s quickstart (4 CPU, 16 GB RAM, 50 GB storage)
• Ubuntu 22.04 or 24.04
• NetFoundry Console access to download offline tarball

NetFoundry credentials

Installing requires two separate sets of credentials from NetFoundry. Have both on hand before you start.

Credential	Used for	How it's supplied
Package repository credentials	Downloading the netfoundry-self-hosted installer package	Passed to the linux-install.bash setup script
Container registry credentials	Pulling NetFoundry private images from quay.io — Ziti Console Enterprise and the Ziti metrics processor	REGISTRY_USERNAME / REGISTRY_PASSWORD, or entered at the installer prompt

Container registry credentials are required for a standard install

As of version 1.0.0, REGISTRY_USERNAME and REGISTRY_PASSWORD are required for any installation that includes the support stack, which is the default. The installer exits with an error during preflight if they're missing, before making any changes to your cluster.

They're only optional when you install with the support stack disabled (-s), or when you use the offline tarball, where private images are pre-loaded into the container runtime.

Both sets of credentials come from the NetFoundry Console or your NetFoundry representative.

Corporate proxy environments

Installing behind a corporate proxy requires additional configuration steps. Review the proxy setup documentation before running the installer.

Pre-installation checklist

Before proceeding to installation, verify you have:

• Appropriate hardware resources for your deployment type
• Supported operating system (Ubuntu 22.04 or 24.04)
• User account with sudo permissions
• Persistent DNS entry configured (if applicable)
• Required ports accessible to Ziti clients and routers
• Kubernetes cluster with default storage class (production deployments)
• DNS registry access to map controller and router addresses
• NetFoundry package repository credentials (to install the netfoundry-self-hosted package)
• NetFoundry container registry credentials (REGISTRY_USERNAME / REGISTRY_PASSWORD) — required for a standard install; see NetFoundry credentials