Zilla Platform Deployment on Kubernetes

This guide describes how to deploy the Zilla Platform on a self-managed Kubernetes cluster.

It applies to on-premises Kubernetes environments as well as local development using Docker Desktop.

The deployment uses the umbrella Helm chart, which installs all core platform components (Console, Management, and Control) into a single Kubernetes namespace.

Prerequisites

Kubernetes cluster (v1.25+)
kubectl
helm (v3 or later)
jq (used during platform initialization)
Ingress controller installed (e.g., NGINX Ingress Controller)
DNS configured for platform hostnames

Install Tools (macOS)

brew install kubectl helm jq

Select the Kubernetes Context

Ensure kubectl is pointing to the correct cluster.

kubectl config get-contexts
kubectl config use-context docker-desktop

Verify Cluster Access

Verify Kubernetes is running and accessible:

kubectl cluster-info
kubectl get nodes

Prepare the Cluster

Install Ingress Controller

This guide uses the NGINX Ingress Controller.

For on-prem deployments, you may replace this with another ingress solution if required.

If an ingress controller is not already installed in your cluster, install the NGINX Ingress Controller:

kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.8.2/deploy/static/provider/cloud/deploy.yaml

Wait for the controller to become ready:

kubectl wait --namespace ingress-nginx \
  --for=condition=ready pod \
  --selector=app.kubernetes.io/component=controller \
  --timeout=120s

Prepare Configuration

Generate JWT Keys

Zilla Platform uses JWTs for internal authentication.

openssl genrsa -out jwt.key 2048
openssl rsa -in jwt.key -pubout -out jwt.pub

Create `values.yaml`

Create a minimal values file for self-managed Kubernetes deployments.

global:
  licenseKey: <LICENSE_KEY>
  domain: <DOMAIN>

Deploy the Platform

export ZILLA_PLATFORM_LICENSE_KEY="<LICENSE_KEY>"

Create Namespace and Secrets

kubectl create namespace zilla-platform

kubectl create secret generic zilla-platform-jwt \
  -n zilla-platform \
  --from-file=publicKey=jwt.pub \
  --from-file=privateKey=jwt.key

Install the Umbrella Chart

helm install zilla-platform oci://ghcr.io/aklivity/charts/zilla-platform-umbrella \
  -n zilla-platform \
  -f values.yaml \
  --set global.licenseKey="${ZILLA_PLATFORM_LICENSE_KEY}" \
  --set kubernetes.distribution=docker-desktop \
  --set jwt.issuer="http://zilla-platform-control:8081" \
  --wait --timeout 15m

Verify Deployment

kubectl get pods -n zilla-platform
kubectl get ingress -n zilla-platform

All pods should be in the Running state before continuing.

Configure DNS

Zilla Platform exposes the following hostnames derived from the configured domain:

console.<DOMAIN>
management.<DOMAIN>
control.<DOMAIN>
platform.<DOMAIN>

For on-premises clusters, configure DNS records to point to your ingress endpoint, such as an external load balancer IP or a MetalLB assigned IP.

For local deployment, add /etc/hosts entries

echo "127.0.0.1 console.localhost management.localhost control.localhost platform.localhost" | sudo tee -a /etc/hosts

Access the Console

Open your browser and navigate to Zilla Platform Console.

Get started with one-time administrator registration and access the Zilla Platform.

Create an Environment & Deploy Gateway

After completing your admin onboarding, the next step is to create an Environment and attach your Gateway & Kafka Cluster.

Follow the guide here to create an Environment and generate Bootstrap token required to attach Gateway with Platform.

Info

Creating an environment generates the ZILLA_PLATFORM_BOOTSTRAP_TOKEN, which is later used to launch and attach the Zilla Platform Gateway.

Deploy the Gateway

Deploy the Zilla Platform Gateway by following the guide:

Deploy a Zilla Gateway on Kubernetes

Consume an API Product

To validate access to deployed API Products, follow the steps in the Consume an API Product guide.

Security

For production deployments, additional security configuration is recommended.

Zilla Platform includes Istio mTLS by default for internal service communication.

Production setups should also consider network policies, external databases, authenticated Kafka access, and secure handling of bootstrap tokens.

Check out this guide for detailed steps.

Uninstall

helm uninstall zilla-platform -n zilla-platform
kubectl delete namespace zilla-platform

Clean up /etc/hosts (optional)

sudo sed -i '' '/console.localhost/d; /management.localhost/d; /control.localhost/d; /platform.localhost/d' /etc/hosts

Resources

Troubleshooting Guide: Common issues and debugging steps.