Zilla Runtime Configuration

The Zilla runtime configuration defines the bindings, guards, vaults, catalogs, stores, and telemetry used by the Zilla runtime engine. The values of properties in the configuration can be literals or expression resolvers.

Key: [Plus] = requires Zilla Plus license. [Incubator] = experimental, opt-in via ZILLA_INCUBATOR_ENABLED=true.

---
name: zilla-namespace

bindings:
  ...

guards:
  ...

vaults:
  ...

catalogs:
  ...

stores:
  ...

telemetry:
  ...

Configuration (* required)

name*

string

Namespace name.

bindings

object as map of named binding properties

Each configured binding represents a step in the pipeline as data streams are decoded, translated, or encoded according to a specific protocol type.

A binding also has a kind, indicating how it should behave, such as server, proxy, or client.

As each incoming data stream arrives, the binding follows its configured routes to reach an exit binding, or rejects the stream if no routes are viable. Route matching conditions are defined in terms specific to each binding type.

routes.exit

string

Unconditional exit binding acting as a default if none of the conditional routes are viable.

Typical Pipeline Order

Bindings are chained from client-facing to server-facing, i.e. the order in which a client would encounter them as protocols flow through the pipeline.

A typical HTTP-Kafka stack looks like:

tcp server → tls server → http server → http-kafka proxy → kafka cache_client → kafka cache_server → kafka client → tls client → tcp client

Protocol Bindings

Encode or decode a single protocol.

Type	Kinds	Purpose
`tcp`	`server`, `client`	Raw TCP connections. Entry point for all network traffic.
`tls`	`server`, `client`, `proxy`	TLS encryption and decryption. `proxy` kind routes on SNI without terminating.
`http`	`server`, `client`	HTTP/1.1 and HTTP/2. `server` supports CORS and guard-enforced authorization.
`grpc`	`server`, `client`	gRPC over HTTP/2. Supports `application/grpc+proto` and `application/grpc-web+proto`.
`mqtt`	`server`, `client`	MQTT publish/subscribe. `server` produces per-topic application streams.
`sse`	`server`, `client`	Server-Sent Events. Converts HTTP streams to SSE event streams.
`ws`	`server`, `client`	WebSocket. Converts HTTP upgrade requests to full-duplex streams.
`amqp`	`server`	AMQP 1.0. Routes on link address. `[Incubator]`
`pgsql`	`server`, `client`	PostgreSQL wire protocol.

Bridge Bindings

Translate between two protocols, adapting streams from one side to the semantics of the other.

Type	Kinds	Purpose
`http-kafka`	`proxy`	Maps HTTP CRUD operations (GET, POST, PUT, DELETE) to Kafka produce and fetch.
`grpc-kafka`	`proxy`	Adapts gRPC request-response streams to Kafka topic streams.
`mqtt-kafka`	`proxy`	Adapts MQTT publish/subscribe topic streams to Kafka topic streams.
`sse-kafka`	`proxy`	Adapts SSE data streams to Kafka data streams for server push.
`kafka-grpc`	`remote_server`	Consumes Kafka topic streams and dispatches each message as a gRPC request.
`http-filesystem`	`proxy`	Maps HTTP GET path to a local filesystem path. Used with `filesystem` binding to serve static files.
`pgsql-kafka`	`proxy`	Adapts PostgreSQL request-response streams to Kafka topic streams.
`openapi-asyncapi`	`proxy`	Adapts OpenAPI operations to AsyncAPI operations.

Spec-Driven Bindings

Configured from an API specification file; internally compose multiple protocol bindings.

Type	Kinds	Purpose
`openapi`	`server`, `client`	Spec-driven HTTP binding. Composes `tcp` + `tls` + `http` from an OpenAPI spec.
`asyncapi`	`server`, `client`, `proxy`	Spec-driven Kafka/MQTT/HTTP binding. Composes bindings from an AsyncAPI spec.

Kafka Bindings

Type	Kinds	Purpose
`kafka`	`cache_client`, `cache_server`, `client`	Kafka protocol with built-in caching. `cache_client` + `cache_server` maintain a per-partition message cache; `client` encodes the Kafka request-response protocol.
`kafka-proxy`	`proxy`	Routes and fans out Kafka topic streams to Kafka topic streams. `[Plus]`

Infrastructure Bindings

Handle transport, multiplexing, routing, and utility concerns.

Type	Kinds	Purpose
`filesystem`	`server`	Serves files from the local filesystem. Used with `http-filesystem` proxy.
`proxy`	`server`, `client`	HAProxy PROXY v2 protocol. Preserves client IP through proxy hops.
`socks`	`server`, `client`, `remote_server`, `remote_client`	SOCKS5 tunneling and remote port forwarding.
`smux`	`server`, `client`	Stream multiplexing. Combines multiple application streams over a single connection.
`fan`	`server`	Fan-in from multiple inbound streams and fan-out to all streams in the group.
`echo`	`server`	Echoes received data back to the sender. Useful for testing.
`schema-registry`	`proxy`	Forwards Schema Registry API requests to an internal registry, namespacing subjects by cluster ID.
`risingwave`	`proxy`	Adapts RisingWave streaming SQL request-response streams. `[Incubator]`
`mcp`	`server`, `client`, `proxy`	Model Context Protocol for AI tooling. Routes MCP client connections to upstream MCP servers.

guards

object as map of named guard properties

Each configured guard represents a security checkpoint for one or more bindings based on a specific implementation type.

Guards can be used by specific protocol bindings to enforce authorization requirements.

Associated roles can be enforced during routing by only following routes guarded by specific role requirements when authorized. This implicitly supports falling through to lower privilege routes when guarded higher privilege routes are not authorized.

Type	Purpose
`jwt`	Validates JWT bearer tokens against JWKS. Extracts roles for route authorization.
`api-keys`	Validates API keys against a static list or a store. `[Plus]`
`azure-ad`	Validates Azure Active Directory OAuth2 tokens. `[Plus]`
`aws-cognito`	Validates AWS Cognito OAuth2 access tokens. `[Plus]`
`aws-lambda`	Delegates authorization to an AWS Lambda function. `[Plus]`
`oauth`	Acquires OAuth 2.0 access tokens via client-credentials, jwt-bearer, token-exchange, or authorization-code grants. `[Plus]`
`inline`	Pass-through guard; approves all requests using a static or split identity/credentials value.

vaults

object as map of named vault properties

Each configured vault represents a container for digital keys and certificates based on a specific implementation type.

Vaults can be used by specific protocol bindings, such as tls, to negotiate shared encryption keys.

Type	Purpose
`filesystem`	Loads certificates and keys from local files (PEM, PKCS12, JKS).
`aws-acm`	Loads certificates from AWS Certificate Manager. `[Plus]`
`aws-secrets`	Loads secrets from AWS Secrets Manager. `[Plus]`

catalogs

object as map of named catalog properties

Each configured catalog represents a catalog of schemas of various formats based on a specific implementation type.

Catalogs can be used by specific protocol bindings to enforce validation.

Type	Purpose
`inline`	Schemas defined directly in `zilla.yaml`. No external dependency.
`filesystem`	Schemas loaded from local files.
`schema-registry`	Generic Schema Registry API endpoint.
`confluent-schema-registry`	Confluent Schema Registry. `[Plus]`
`apicurio-registry`	Apicurio Registry.
`karapace-schema-registry`	Karapace Schema Registry.
`aws-glue`	AWS Glue Schema Registry. `[Plus]`

stores

object as map of named store properties

Each configured store provides persistent session and state storage for guards and bindings that need to track state across requests (for example, API key revocation lists or MQTT session state).

Type	Purpose
`memory`	In-process in-memory store. Resets on restart.
`redis`	Redis-backed store. Persistent and shared across instances. `[Plus]`
`hazelcast`	Hazelcast-backed distributed store. `[Plus]`

telemetry

object of telemetry properties

telemetry:
  attributes:
    service.namespace: example
  exporters:
    ...
  metrics:
    ...

attributes

object | Default: zilla namespace name

Default attributes to optionally include when exporting metrics.

exporters

object as map of named exporter properties

Exporters ship collected metrics to an external system.

Type	Purpose
`stdout`	Prints metrics to standard output. Useful for local debugging.
`prometheus`	Exposes a Prometheus-compatible `/metrics` scrape endpoint.
`otlp`	Exports metrics and traces via OpenTelemetry Protocol (OTLP/gRPC or OTLP/HTTP).
`aws-cloudwatch`	Exports metrics to AWS CloudWatch. `[Plus]`
`syslog`	Exports log events to a Syslog endpoint. `[Plus]`

metrics

array of string of named metrics

Array of named metrics to collect at runtime.

Group	Reference	Measures
`stream.*`	`stream`	Opens, closes, bytes read/written per stream.
`http.*`	`http`	Request count, response status codes, active connections.
`grpc.*`	`grpc`	RPC count, status codes, message rates.