Configure TLS

This guide explains how to configure TLS for a Zilla Gateway using a local Docker Compose.

You’ll set up the environment, generate keys & trust, and launch a TLS-enabled gateway.

Create Compose File

Create a Docker Compose file named compose.env.local.yaml with the following content:

name: quickstart-env
include:
  - oci://ghcr.io/aklivity/zilla-platform/quickstart/env
---
name: quickstart-env
services:
  gateway:
    volumes:
      - ./etc:/etc/zilla:ro

include: References the Zilla Quickstart environment published as an OCI artifact on GitHub Container Registry.
The gateway service mounts your local configuration directory (./etc) into the container.

Prepare the Directory

Create the directory structure to hold zilla.yaml & TLS files

mkdir -p etc/tls

Create Zilla Configuration

Inside the etc/ directory, create a file named zilla.yaml with the following content:

name: "gateway"
vaults:
 server:
   type: "filesystem"
   options:
     keys:
       store: "tls/server/keys"
       password: "generated"
 client:
   type: "filesystem"
   options:
     trust:
       store: "tls/client/trust"
       type: "pkcs12"
       password: "generated"

The server vault holds your gateway’s private keys and certificates.
The client vault stores trusted CA certificates for verifying inbound TLS connections.
Both are stored under the etc/tls/ directory mounted in the container.

Generate TLS Certificates

Generate the server keys & client trust using instruction here

This will create following files:

etc/
 ├── zilla.yaml
 └── tls/
      ├── server/
      │    └── keys
      └── client/
           └── trust

Start the Environment

Before starting the environment, export your license and bootstrap credentials:

export ZILLA_PLATFORM_LICENSE_KEY=<your-license-key>
export ZILLA_PLATFORM_BOOTSTRAP_TOKEN=<your-bootstrap-token>

Start the environment and wait for all services to become ready:

docker compose -f compose.env.local.yaml up --wait

You should now have a TLS enabled Zilla Platform Gateway running using the generated certificates.

Configure Client

Generate JKS

Generate the client truststore in JKS format, which is compatible with Java-based Kafka clients

export CLIENT_TRUST_PASS=generated

keytool -importkeystore \
  -srckeystore client/trust \
  -srcstoretype PKCS12 \
  -srcstorepass ${CLIENT_TRUST_PASS} \
  -destkeystore client/trust.jks \
  -deststoretype JKS \
  -deststorepass ${CLIENT_TRUST_PASS}

Create Client Properties

Create client.properties file with following content:

security.protocol=SSL
ssl.truststore.location=etc/tls/client/trust.jks
ssl.truststore.password=generated

Test Connectivity

Use the Kafka CLI to create a topic or validate connectivity through the Zilla Platform Gateway.

kafka-topics \
  --create \
  --topic test \
  --partitions 1 \
  --replication-factor 3 \
  --command-config client.properties \
  --bootstrap-server <tls-bootstrap-server-names>