Quickstart

Get started with Zilla by trying some of its Kafka proxying and API gateway features.

In this guide, you will see how Zilla operates as HTTP Kafka Proxy that exposes Kafka topics via REST endpoints.

Prerequisites

• Docker Compose

Running Zilla Locally

Download and run the Zilla http.kafka.crud example using these steps.

git clone https://github.com/aklivity/zilla.git

Note

Alternatively, download zilla and unzip the compressed file.

cd zilla/examples

To start the Docker Compose stack defined in the compose.yaml file, use:

docker compose --project-directory http.kafka.crud up -d

It will start with Zilla and everything you need for this guide.

The key components this script will set:

• Configured Zilla instance
• Kafka Cluster and topics
• Kafka UI at http://localhost:8080/ui/clusters/local/all-topics for browsing topics & messages

HTTP Kafka Proxy

The Zilla HTTP Kafka Proxy lets you configure application-centric REST APIs that unlock Kafka event-driven architectures.

1. Open the live items-snapshots Kafka topic, which will have all the JSON messages you create. You can switch the filter from live to newest to see all the latest messages on the topic.
2. Refer to the exposed HTTP Endpoints.
3. Use the POST request to create an event. The new object will appear in the Kafka topic.
4. View your Kafka message key from the items-snapshots topic.
5. Triggered GET, PUT & DELETE requests to experience the application-centric REST APIs.

You can easily configure many common Restful actions with the added benefit of built-in streaming with an SSE endpoint. The zilla.yaml config has simple and clear syntax for defining each HTTP endpoint.

Create

Create a new message.

  north_http_kafka_mapping:
    type: http-kafka
    kind: proxy
    routes:
      - when:
          - method: POST
            path: /items
        exit: north_kafka_cache_client
        with:
          capability: produce
          topic: items-snapshots
          key: ${idempotencyKey}

Read:many

Fetch all messages on the topic.

  north_http_kafka_mapping:
    type: http-kafka
    kind: proxy
    routes:
      - when:
          - method: GET
            path: /items
        exit: north_kafka_cache_client
        with:
          capability: fetch
          topic: items-snapshots
          merge:
            content-type: application/json

Read:one

Fetch one message by its key.

  north_http_kafka_mapping:
    type: http-kafka
    kind: proxy
    routes:
      - when:
          - method: GET
            path: /items/{id}
        exit: north_kafka_cache_client
        with:
          capability: fetch
          topic: items-snapshots
          filters:
            - key: ${params.id}

Update

Update a message based on its key.

  north_http_kafka_mapping:
    type: http-kafka
    kind: proxy
    routes:
      - when:
          - method: PUT
            path: /items/{id}
        exit: north_kafka_cache_client
        with:
          capability: produce
          topic: items-snapshots
          key: ${params.id}

Delete

Produce a blank message for a key.

  north_rest_api_http_kafka_mapping:
    type: http-kafka
    kind: proxy
    routes:
      - when:
          - method: DELETE
            path: /items/{id}
        exit: north_kafka_cache_client
        with:
          capability: produce
          topic: items-snapshots
          key: ${params.id}

Full HTTP Proxy zilla.yaml Config

name: example
bindings:
  north_tcp_server:
    type: tcp
    kind: server
    options:
      host: 0.0.0.0
      port:
        - 7114
    routes:
      - when:
          - port: 7114
        exit: north_http_server
  north_http_server:
    type: http
    kind: server
    routes:
      - when:
          - headers:
              :scheme: http
        exit: north_http_kafka_mapping
  north_http_kafka_mapping:
    type: http-kafka
    kind: proxy
    routes:
      #region rest_create
      - when:
          - method: POST
            path: /items
        exit: north_kafka_cache_client
        with:
          capability: produce
          topic: items-snapshots
          key: ${idempotencyKey}
      #endregion rest_create
      #region rest_update
      - when:
          - method: PUT
            path: /items/{id}
        exit: north_kafka_cache_client
        with:
          capability: produce
          topic: items-snapshots
          key: ${params.id}
      #endregion rest_update
      #region rest_delete
      - when:
          - method: DELETE
            path: /items/{id}
        exit: north_kafka_cache_client
        with:
          capability: produce
          topic: items-snapshots
          key: ${params.id}
      #endregion rest_delete
      #region rest_retrieve_all
      - when:
          - method: GET
            path: /items
        exit: north_kafka_cache_client
        with:
          capability: fetch
          topic: items-snapshots
          merge:
            content-type: application/json
      #endregion rest_retrieve_all
      #region rest_retrieve_id
      - when:
          - method: GET
            path: /items/{id}
        exit: north_kafka_cache_client
        with:
          capability: fetch
          topic: items-snapshots
          filters:
            - key: ${params.id}
      #endregion rest_retrieve_id
  north_kafka_cache_client:
    type: kafka
    kind: cache_client
    exit: south_kafka_cache_server
  south_kafka_cache_server:
    type: kafka
    kind: cache_server
    options:
      bootstrap:
        - items-snapshots
    exit: south_kafka_client
  south_kafka_client:
    type: kafka
    kind: client
    options:
      servers:
        - ${{env.KAFKA_BOOTSTRAP_SERVER}}
    exit: south_tcp_client
  south_tcp_client:
    type: tcp
    kind: client
telemetry:
  exporters:
    stdout_logs_exporter:
      type: stdout

To stop the Docker Compose stack, use:

docker compose --project-directory http.kafka.crud down

Explore More

Checkout other examples

grpc.kafka.proxy

mqtt.kafka.proxy

Zilla examples