Skip to main content

asyncapi server

asyncapi server

The asyncapi server binding creates composite of tcp, tls, and mqtt or http or sse bindings with server kind and adapts MQTT/HTTP/SSE streams to AsyncAPI streams.

mqtt_asyncapi_server:
  type: asyncapi
  kind: server
  options:
    specs:
      my-mqtt-api-spec:
        servers:
          - mqtt://localhost:1883
        catalog:
          my_catalog:
            subject: mqtt-streetlights
            version: latest
  exit: south_kafka_proxy

Configuration (* required)

vault

string

Vault name.

options

object

The server specific options.

specs:
  http_api:
    servers:
      - http://localhost:8080
    catalog:
      my_catalog:
        subject: petstore
        version: latest

options.specs

object as map of named object properties

The specs specific options.

specs.catalog

object as map of named object properties

To map defined catalog for schema retrieval based on catalog specific parameters.

catalog.subject*

string

Subject name used when storing the catalog artifact.

catalog.version

string | Default: latest

Specific iteration or version of a registered schema in the defined catalog.

specs.servers*

array of string

Deployment-target URLs for the spec, independent of the servers declared in the spec document itself. At least one is required.

specs:
  mqtt_api:
    servers:
      - mqtt://broker.internal:1883

specs.security

object as map of named string properties

Maps AsyncAPI securitySchemes names declared in the spec document to guards defined elsewhere in the configuration. Used to automatically derive guarded: on the routes generated for the composite, and to synthesize the matching credential-extraction pattern for whichever protocol binding is generated (http, mqtt, or kafka), from each scheme's own declared type — no separate authorization configuration is needed:

  • An http/bearer or httpApiKey scheme synthesizes HTTP Authorization header, query parameter, or cookie extraction, matching the scheme's declared location.
  • A generic apiKey scheme with in: user or in: password synthesizes the MQTT CONNECT username/password extraction — declare one scheme per property, both mapped to the same guard, to supply both.
  • A plain, scramSha256, or scramSha512 scheme synthesizes Kafka SASL credentials using the matching mechanism.
specs:
  mqtt_api:
    security:
      bearerAuth: my_jwt_guard

specs.store

string

The name of a configured store used to coordinate MQTT session ownership for the generated mqtt server. When omitted, a default store is generated for the server; reference an external or cluster-wide store to share session ownership across Zilla instances.

specs:
  mqtt_api:
    store: mqtt_sessions

specs.overlay

object as map of named object properties

Applies an OpenAPI Overlay Specification document, stored as a catalog artifact, to the base spec document before it is used. A single overlay may be configured per spec.

specs:
  mqtt_api:
    catalog:
      my_catalog:
        subject: smartylighting
        version: latest
    overlay:
      my_catalog:
        subject: smartylighting-overlay
        version: latest

overlay.subject*

string

Subject name used when storing the overlay artifact.

overlay.version

string | Default: latest

Overlay artifact version to use.

For the mqtt-kafka mapping, the Kafka topic role of each mqtt-kafka channel (sessions, messages, retained) is declared directly in the AsyncAPI spec document via that channel's x-zilla-mqtt-kafka binding, rather than as a zilla.yaml option:

channels:
  mqttSessions:
    address: mqtt-sessions
    x-zilla-mqtt-kafka:
      role: sessions

For each https/mqtts server, a tls binding is generated automatically, with keys, trust, signers, and SNI resolved from vault and ALPN computed automatically — no separate TLS options are configured on this binding.

routes

array of object

Conditional asyncapi specific routes.

routes:
  - when:
      - spec: my-mqtt-api-spec
        operation: sendEvents
    exit: asyncapi_client
    with:
      spec: my-kafka-api-spec
      operation: toSensorData
  - when:
      - spec: my-mqtt-api-spec
        operation: receiveEvents
    exit: asyncapi_client
    with:
      spec: my-kafka-api-spec
      operation: onSensorData

routes[].guarded

object as map of named array of string

List of roles required by each named guard to authorize this route.

routes:
  - guarded:
      my_guard:
        - read:items

routes[].when

array of object

List of conditions to match this route when adapting asyncapi streams. Read more: When a route matches

when[].spec

string

AsyncAPI spec label that matches the resolved specification for the request.

when[].operation

string

AsyncAPI operationId to match, either exactly or as a glob pattern, e.g. send*.

when[].tag

string

Matches when the resolved operation declares this tag.

when[].servers

array of object

Matches when the resolved server for the request is one of these servers.

servers[].name

string

Server name to match, as declared in the spec document.

servers[].url

string

Server url to match.

routes[].with

object

Defines the target AsyncAPI spec and operation to proxy this route into. Available for kind: proxy only, where it is required on every route.

with:
  spec: my-kafka-api-spec
  operation: toSensorData

with.spec*

string

AsyncAPI spec label that the route exits with to the next binding.

with.operation

string

AsyncAPI operationId that the route exits with to the next binding, either exactly or as a glob pattern. When omitted, falls back to the operation matched on the when side.

exit

string

Default exit binding when no conditional routes are viable.

exit: echo_server

routes[].exit

string

Next binding when following this route.

routes:
  - when:
    ...
    exit: asyncapi_client

telemetry

object

Defines the desired telemetry for the binding.

telemetry.metrics

array

Telemetry metrics to track

telemetry:
  metrics:
    - stream.*

telemetry.attributes

object as map of named string properties

Telemetry attributes to add to the binding metrics.

Gateway Version