Deploying OpenZiti

Introduction

OpenZiti is an open-source zero-trust networking platform that creates secure overlay networks without exposing services to the public internet. Unlike traditional VPNs that grant broad network access, OpenZiti provides application-specific connectivity with strong identity verification, eliminating the attack surface of open ports and publicly accessible services.

Built on the principle of “zero trust” where no connection is trusted by default, OpenZiti requires every connection to be authenticated and authorized before allowing access. This approach provides security benefits beyond traditional perimeter-based security models, protecting against lateral movement and minimizing the impact of compromised credentials.

Key highlights of OpenZiti:

Zero Trust Architecture: Every connection requires authentication and authorization
No Open Ports: Services are invisible to the public internet
Application-Level Access: Grant access to specific applications, not entire networks
Strong Identity: Certificates and identity verification for all participants
Embedded SDKs: Integrate zero-trust directly into applications
Cross-Platform: Clients available for Windows, macOS, Linux, iOS, and Android
End-to-End Encryption: All traffic encrypted between endpoints
Programmable Policies: Define access rules declaratively
Self-Hosted Control: Complete ownership of your network infrastructure
Open Source: Fully transparent codebase under Apache 2.0 license

This guide walks through deploying an OpenZiti controller and edge routers on Klutch.sh using Docker, establishing your zero-trust network foundation.

Why Deploy OpenZiti on Klutch.sh

Deploying OpenZiti on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically builds and deploys your OpenZiti infrastructure. Push to GitHub, and your network control plane deploys automatically.

Persistent Storage: Attach persistent volumes for certificates, identities, and database. Your network configuration survives container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for the controller API endpoints.

Reliable Availability: Your network controller runs 24/7 with consistent uptime, essential for zero-trust infrastructure.

GitHub Integration: Store configuration in Git for version-controlled infrastructure. Update by pushing changes.

Scalable Resources: Allocate resources based on network size and expected connection volume.

Custom Domains: Use professional domains for your controller and edge routers.

Prerequisites

Before deploying OpenZiti on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your OpenZiti configuration
Basic familiarity with Docker and containerization concepts
Understanding of networking and PKI concepts
Custom domain(s) for your OpenZiti infrastructure

Understanding OpenZiti Architecture

OpenZiti consists of several key components:

Controller: The central management plane that handles identity management, policy enforcement, and network coordination. This is the brain of your OpenZiti network.

Edge Routers: Network entry and exit points that handle encrypted traffic. Clients connect through edge routers to access services.

Identities: Certificates representing users, devices, or services that can participate in the network.

Services: Definitions of applications or resources that can be accessed through the network.

Policies: Rules defining which identities can access which services.

Tunnelers: Client applications that create local endpoints for accessing Ziti services.

Preparing Your Repository

Create a GitHub repository containing your Dockerfile and configuration.

Repository Structure

openziti-deploy/
├── Dockerfile
├── docker-compose.yml
├── .dockerignore
└── README.md

Creating the Dockerfile

Create a Dockerfile for the OpenZiti controller:

FROM openziti/ziti-controller:latest

# Create directories for persistent data
RUN mkdir -p /persistent/db /persistent/pki

# Environment variables
ENV ZITI_HOME=/persistent
ENV ZITI_CONTROLLER_RAWNAME=ziti-controller
ENV ZITI_EDGE_CONTROLLER_RAWNAME=ziti-edge-controller

# Expose controller ports
EXPOSE 1280
EXPOSE 6262

# Use the default entrypoint

Edge Router Dockerfile

Create a separate Dockerfile for edge routers:

FROM openziti/ziti-router:latest

# Create directories for persistent data
RUN mkdir -p /persistent

# Environment variables
ENV ZITI_HOME=/persistent

# Expose router ports
EXPOSE 3022
EXPOSE 10080

# Use the default entrypoint

Environment Variables Reference

Variable	Description
`ZITI_HOME`	Base directory for Ziti configuration and data
`ZITI_CONTROLLER_RAWNAME`	Internal name for the controller
`ZITI_EDGE_CONTROLLER_RAWNAME`	External-facing name for the controller
`ZITI_CONTROLLER_HOSTNAME`	Hostname for controller access
`ZITI_EDGE_CONTROLLER_HOSTNAME`	Hostname for edge controller access
`ZITI_EDGE_ROUTER_HOSTNAME`	Hostname for edge router access
`ZITI_CTRL_ADVERTISED_ADDRESS`	Advertised address for the controller
`ZITI_EDGE_ADVERTISED_ADDRESS`	Advertised address for edge connections

Deploying OpenZiti on Klutch.sh

Follow these steps to deploy your OpenZiti infrastructure:

Plan Your Network Architecture

Before deploying, plan your OpenZiti network:

Controller hostname (e.g., controller.ziti.example.com)
Edge router hostname(s) (e.g., router1.ziti.example.com)
DNS records for all components

Configure DNS Records

Create DNS records pointing to your Klutch.sh deployments for:

Controller API endpoint
Edge router connection points

Push Your Repository to GitHub

Initialize and push your repository:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial OpenZiti controller configuration"
git remote add origin https://github.com/yourusername/openziti-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project named “openziti” or “zero-trust”.

Deploy the Controller

Create a new app for the controller:

Connect your GitHub account
Select the controller repository
Configure traffic for ports 1280 and 6262
Set environment variables for hostnames

Set Environment Variables

Configure your controller:

Variable	Value
`ZITI_HOME`	`/persistent`
`ZITI_CONTROLLER_HOSTNAME`	`controller.yourdomain.com`
`ZITI_EDGE_CONTROLLER_HOSTNAME`	`controller.yourdomain.com`

Attach Persistent Volumes

Add persistent storage:

Mount Path	Recommended Size	Purpose
`/persistent/db`	5 GB	Controller database
`/persistent/pki`	1 GB	Certificates and keys

Initialize the Controller

After deployment, initialize the controller:

Access the container console
Run the initialization script to create the PKI and initial configuration
Create the admin identity
Note the admin credentials securely

Deploy Edge Routers

Deploy additional apps for edge routers:

Create new apps using the edge router Dockerfile
Configure appropriate ports (3022, 10080)
Set environment variables with router-specific hostnames
Enroll routers with the controller

Verify Deployment

Test your OpenZiti installation:

Install the Ziti CLI locally
Login to the controller
Verify edge routers are online
Create a test identity and service

Managing Your OpenZiti Network

Creating Identities

Create identities for users and services:

# Create an identity
ziti edge create identity user myuser -o myuser.jwt

# Enroll the identity (on client device)
ziti edge enroll myuser.jwt

Defining Services

Create services for applications:

# Create a service for a web application
ziti edge create service mywebapp \
  --configs myconfig \
  --role-attributes myapp-services

Creating Policies

Define access policies:

# Create a service policy
ziti edge create service-policy mywebapp-access Dial \
  --identity-roles '#myapp-users' \
  --service-roles '#myapp-services'

# Create a bind policy for hosting
ziti edge create service-policy mywebapp-bind Bind \
  --identity-roles '@myserver' \
  --service-roles '#myapp-services'

Edge Router Policies

Control router access:

# Allow identities to use edge routers
ziti edge create edge-router-policy default-routers \
  --identity-roles '#all' \
  --edge-router-roles '#public'

Client Configuration

Installing Tunnelers

Install Ziti tunnelers on client devices:

Desktop: Ziti Desktop Edge for Windows/macOS/Linux
Mobile: Ziti Mobile Edge for iOS/Android
Server: ziti-edge-tunnel for headless systems

Connecting to Services

After enrollment, clients can access services:

Launch the Ziti tunneler
Load your identity file
Connect to the network
Access services using their Ziti addresses

SDK Integration

Embed zero-trust directly in applications using SDKs:

Go SDK
C SDK
Python SDK
Node.js SDK
.NET SDK

Use Cases

Secure Application Access

Replace VPNs with application-specific access:

Employees access internal apps without VPN
Services are invisible to the internet
Fine-grained access control per application

IoT Security

Secure IoT device communication:

Devices connect outbound only
No inbound ports required
Device-specific access policies

Multi-Cloud Networking

Connect services across cloud providers:

Secure private connectivity
No public IPs required
Consistent access policies

Third-Party Access

Secure access for contractors and partners:

Time-limited access
Application-specific permissions
Full audit trail

Security Best Practices

Certificate Management

Rotate certificates regularly
Use strong key sizes (4096-bit RSA or ECDSA)
Secure the controller PKI
Implement certificate revocation

Identity Hygiene

Create specific identities for each purpose
Use role-based access policies
Regularly audit identity permissions
Remove unused identities promptly

Network Monitoring

Enable audit logging
Monitor connection patterns
Alert on unusual activity
Regular security reviews

Troubleshooting Common Issues

Controller Not Accessible

Symptoms: Cannot connect to controller API.

Solutions:

Verify DNS records resolve correctly
Check that ports 1280 and 6262 are accessible
Verify the controller is running
Check TLS certificate configuration

Router Enrollment Failing

Symptoms: Edge routers cannot enroll with controller.

Solutions:

Verify controller is accessible from router
Check enrollment JWT is valid and not expired
Verify network connectivity
Review router and controller logs

Identities Cannot Connect

Symptoms: Enrolled identities fail to establish sessions.

Solutions:

Verify edge router policies allow the identity
Check service policies grant access
Ensure edge routers are online
Review client tunneler logs

Service Not Reachable

Symptoms: Cannot access a defined service.

Solutions:

Verify service configuration
Check bind and dial policies
Ensure hosting identity is connected
Review service terminator configuration

Additional Resources

Conclusion

Deploying OpenZiti on Klutch.sh provides a foundation for zero-trust networking that eliminates the security risks of exposed services. With application-level access control and strong identity verification, OpenZiti offers a modern approach to secure connectivity.

The combination of persistent storage for certificates and database, reliable uptime, and scalable resources makes Klutch.sh well-suited for hosting OpenZiti infrastructure. Whether securing internal applications, IoT devices, or multi-cloud deployments, your self-hosted OpenZiti network provides the security and control that traditional VPNs cannot match.

Start with a controller and single edge router, then expand your network as needs grow. With OpenZiti, you can progressively adopt zero-trust principles while maintaining full control over your network infrastructure.