Jikkou Tutorials

• 1: Jikkou Getting Started
• 2: Preview Changes and Detect Drift
• 3: Generate Topics with Templates

1 - Jikkou Getting Started

This document will guide you through setting up Jikkou in a few minutes and managing your first resources with Jikkou.

Prerequisites

The following prerequisites are required for a successful and properly use of Jikkou.

Make sure the following is installed:

• An Apache Kafka cluster.
  • Using Docker, Docker Compose is the easiest way to use it.
• Java 25 (not required when using the binary version).

Start your local Apache Kafka Cluster

You must have access to an Apache Kafka cluster for using Jikkou. Most of the time, the latest version of Jikkou is always built for working with the most recent version of Apache Kafka.

Make sure the Docker is up and running.

Then, run the following commands:

$ git clone https://github.com/streamthoughts/jikkou
$ cd jikkou
$ ./up              # use ./down for stopping the docker-compose stack

Run Jikkou

Download the latest distribution (For Linux)

Run the following commands to install the latest version:

wget https://github.com/streamthoughts/jikkou/releases/download/v0.37.0/jikkou-0.37.0-linux-x86_64.zip && \
unzip jikkou-0.37.0-linux-x86_64.zip  && \
cp jikkou-0.37.0-linux-x86_64/bin/jikkou $HOME/.local/bin && \
source <(jikkou generate-completion) && \
jikkou --version

For more details, or for other options, see the installation guide.

Configure Jikkou for your local Apache Kafka cluster

Set configuration context for localhost

jikkou config set-context localhost \
--provider kafka \
--config-props client.bootstrap.servers=localhost:9092

Show the complete configuration.

jikkou config view --name localhost

Finally, let’s check if your cluster is accessible:

jikkou health get kafka

(output)

If OK, you should get an output similar to :

---
apiVersion: "core.jikkou.io/v1"
kind: "ApiHealthResult"
name: "kafka"
status:
  name: "UP"
details:
  resource: "urn:kafka:cluster:id:xtzWWN4bTjitpL3kfd9s5g"
  brokers:
    - id: "101"
      host: "localhost"
      port: 9092

Create your first topics

First, create a resource YAML file describing the topics you want to create on your cluster:

file: kafka-topics.yaml

apiVersion: "kafka.jikkou.io/v1beta2"
kind: "KafkaTopicList"
items:
  - metadata:
      name: 'my-first-topic'
    spec:
      partitions: 5
      replicationFactor: 1
      configs:
        cleanup.policy: 'compact'

  - metadata:
      name: 'my-second-topic'
    spec:
      partitions: 4
      replicationFactor: 1
      configs:
        cleanup.policy: 'delete'

Then, run the following Jikkou command to trigger the topic creation on the cluster:

jikkou create -f ./kafka-topics.yaml

(output)

TASK [CREATE] Create topic 'my-second-topic' (partitions=4, replicas=-1, configs=[cleanup.policy=delete]) - CHANGED
{
  "end" : "2025-08-26T00:00:00.000000Z",
  "status" : "CHANGED",
  "description" : "Create topic 'my-second-topic' (partitions=4, replicas=-1, configs=[cleanup.policy=delete])",
  "change" : {
    "apiVersion" : "kafka.jikkou.io/v1beta2",
    "kind" : "KafkaTopicChange",
    "metadata" : {
      "name" : "my-second-topic",
      "labels" : { },
      "annotations" : {
        "jikkou.io/items-count" : 2
      }
    },
    "spec" : {
      "changes" : [ {
        "name" : "partitions",
        "op" : "CREATE",
        "after" : 4
      }, {
        "name" : "replicas",
        "op" : "CREATE",
        "after" : -1
      }, {
        "name" : "config.cleanup.policy",
        "op" : "CREATE",
        "after" : "delete"
      } ],
      "op" : "CREATE",
      "data" : { }
    }
  },
  "changed" : true,
  "failed" : false
}
  
TASK [CREATE] Create topic 'my-first-topic' (partitions=5, replicas=-1, configs=[cleanup.policy=compact]) - CHANGED
{
  "end" : "2025-08-26T00:00:00.000000Z",
  "status" : "CHANGED",
  "description" : "Create topic 'my-first-topic' (partitions=5, replicas=-1, configs=[cleanup.policy=compact])",
  "change" : {
    "apiVersion" : "kafka.jikkou.io/v1beta2",
    "kind" : "KafkaTopicChange",
    "metadata" : {
      "name" : "my-first-topic",
      "labels" : { },
      "annotations" : {
        "jikkou.io/items-count" : 2
      }
    },
    "spec" : {
      "changes" : [ {
        "name" : "partitions",
        "op" : "CREATE",
        "after" : 5
      }, {
        "name" : "replicas",
        "op" : "CREATE",
        "after" : -1
      }, {
        "name" : "config.cleanup.policy",
        "op" : "CREATE",
        "after" : "compact"
      } ],
      "op" : "CREATE",
      "data" : { }
    }
  },
  "changed" : true,
  "failed" : false
}

EXECUTION in 114ms
ok : 0, created : 2, altered : 0, deleted : 0 failed : 0

Finally, you can verify that topics are created on the cluster

jikkou get kafkatopics --default-configs

Update Kafka Topics

Edit your kafka-topics.yaml to add a retention.ms: 86400000 property to the defined topics.

Then, run the following command.

jikkou update -f ./kafka-topics.yaml

Delete Kafka Topics

To delete all topics defines in the topics.yaml, add an annotation jikkou.io/delete: true as follows:

apiVersion: "kafka.jikkou.io/v1beta2"
kind: "KafkaTopicList"
metadata:
  annotations:
    # Annotation to specify that all resources must be deleted.
    jikkou.io/delete: true
items:
  - metadata:
      name: 'my-first-topic'
    spec:
      partitions: 5
      replicationFactor: 1
      configs:
        cleanup.policy: 'compact'

  - metadata:
      name: 'my-second-topic'
    spec:
      partitions: 4
      replicationFactor: 1
      configs:
        cleanup.policy: 'delete'

Then, run the following command:

$ jikkou apply \
    --files ./kafka-topics.yaml \
    --selector "metadata.name MATCHES (my-.*-topic)" \
    --dry-run

Using the dry-run option, give you the possibility to check the changes that will be made before applying them.

Now, rerun the above command without the --dry-run option to definitively delete the topics.

Reading the Help

To learn more about the available Jikkou commands, use jikkou help or type a command followed by the -h flag:

$ jikkou help get

Next Steps

Now, you’re ready to use Jikkou!🚀

As next steps, we suggest reading the following documentation in this order:

• Learn Jikkou concepts
• Read the Developer Guide to understand how to use the Jikkou API for Java
• Look at the examples

2 - Preview Changes and Detect Drift

In this tutorial you’ll learn the mental model at the heart of Jikkou: reconciliation. You declare the desired state of your resources, and Jikkou compares it with the actual state on your cluster and computes the changes needed to make them match.

By the end you’ll know how to preview changes, apply them safely, and detect when a cluster has drifted away from your declared configuration.

Prerequisites

• You have completed the Getting Started tutorial.
• You have a running Kafka cluster and a configured Jikkou context.

Step 1 — Declare a topic

Create a resource file describing a single topic:

file: orders.yaml

apiVersion: "kafka.jikkou.io/v1beta2"
kind: "KafkaTopic"
metadata:
  name: "orders"
spec:
  partitions: 3
  replicationFactor: 1
  configs:
    cleanup.policy: "delete"
    retention.ms: 86400000

Step 2 — Preview the plan with diff

Before changing anything, ask Jikkou what it would do. The diff command produces a speculative reconciliation plan without touching the cluster:

jikkou diff -f ./orders.yaml

Because the topic doesn’t exist yet, the plan reports a CREATE operation. diff is your safety net — use it before every apply.

Step 3 — Apply the change

Now create the topic:

jikkou apply -f ./orders.yaml

Run diff again:

jikkou diff -f ./orders.yaml

This time there are no changes — the actual state already matches your desired state. This is what reconciliation looks like when everything is in sync.

Step 4 — Detect drift

“Drift” happens when the cluster changes outside of Jikkou. Let’s simulate it by editing your desired state instead: change retention.ms to 3600000 and add a new config in orders.yaml:

spec:
  partitions: 3
  replicationFactor: 1
  configs:
    cleanup.policy: "delete"
    retention.ms: 3600000          # changed
    max.message.bytes: 20971520    # added

Preview the drift:

jikkou diff -f ./orders.yaml

Jikkou now reports an UPDATE operation describing exactly which config keys differ. You can narrow the output to specific operations:

jikkou diff -f ./orders.yaml --filter-change-op UPDATE

Step 5 — Apply safely with --dry-run

apply also supports --dry-run, which runs the full plan without committing it — useful in scripts and CI where you want the apply command’s exact behavior:

jikkou apply -f ./orders.yaml --dry-run   # preview, no changes
jikkou apply -f ./orders.yaml             # commit the changes

Step 6 — Understand deletion behavior

apply reconciles to the declared state. By default it will not delete topics that are missing from your files unless you opt in. To delete the topic you created, add the delete annotation:

apiVersion: "kafka.jikkou.io/v1beta2"
kind: "KafkaTopic"
metadata:
  name: "orders"
  annotations:
    jikkou.io/delete: true
spec:
  partitions: 3
  replicationFactor: 1

Preview, then apply:

jikkou diff -f ./orders.yaml          # shows a DELETE operation
jikkou apply -f ./orders.yaml --dry-run
jikkou apply -f ./orders.yaml

What you learned

• Jikkou reconciles desired state (your YAML) with actual state (the cluster).
• diff previews the plan; --dry-run runs apply without committing.
• Re-running with no changes is a no-op — that’s how you confirm there’s no drift.
• Deletion is opt-in via the jikkou.io/delete annotation.

Next steps

• Learn the Reconciliation concept in depth.
• Generate many resources at once in the Generate Topics with Templates tutorial.
• Enforce rules automatically with governance policies.

3 - Generate Topics with Templates

Declaring resources one by one gets tedious when you manage dozens of similar topics across teams or regions. In this tutorial you’ll learn Jikkou’s templating by generating a list of topics from a compact data file — a single template plus a few values produces many resources.

By the end you’ll understand the values variable, values files, and how to preview rendered output before applying it.

Prerequisites

• You have completed the Getting Started tutorial.
• You have a running Kafka cluster and a configured Jikkou context.

Step 1 — Define your values

Templating separates data from structure. Put the data in a values file:

file: values.yaml

topicPrefix: "iot-events"
partitions: 6
replicas: 1
countryCodes:
  - fr
  - be
  - de
  - es

Step 2 — Write the template

Now write a template that loops over the data. Templates use Jinja syntax, where {{ ... }} outputs a value and {% ... %} is a control statement. The values from your file are available under the top-level values variable.

file: topics.tpl

apiVersion: "kafka.jikkou.io/v1beta2"
kind: "KafkaTopicList"
items:
{% for country in values.countryCodes %}
  - metadata:
      name: "{{ values.topicPrefix }}-{{ country }}"
    spec:
      partitions: {{ values.partitions }}
      replicationFactor: {{ values.replicas }}
      configs:
        cleanup.policy: "delete"
{% endfor %}

Step 3 — Preview the rendered resources

Always render and inspect the result before touching the cluster. The validate command renders the template and prints the resulting resources:

jikkou validate --files ./topics.tpl --values-files ./values.yaml

You should see four fully-rendered topics — iot-events-fr, iot-events-be, iot-events-de, and iot-events-es — each with 6 partitions.

Step 4 — Apply the generated topics

Once you’re happy with the output, preview the plan and apply it. The same --values-files flag is accepted by diff, apply, create, and update:

jikkou diff  --files ./topics.tpl --values-files ./values.yaml   # preview
jikkou apply --files ./topics.tpl --values-files ./values.yaml   # apply

Add a country to values.yaml, re-run diff, and you’ll see Jikkou plan a single new topic — without touching the template.

Step 5 — Override values from the command line

You can pass or override individual values with --set-value (-v), which is handy in CI pipelines:

jikkou apply --files ./topics.tpl \
  --values-files ./values.yaml \
  --set-value partitions=12

You can also read values from the environment inside the template — for example {{ system.env.TOPIC_PREFIX | default('iot-events', true) }}.

What you learned

• Templating separates data (values files) from structure (the template).
• values exposes your data; {{ }} outputs values and {% %} drives loops and conditions.
• Render and inspect with validate before applying.
• --values-files and --set-value work with diff, apply, and the other reconciliation commands.

Next steps

• Read the Templates concept for two-phase rendering, ConfigMap references, and advanced features.
• Manage multiple schemas the same way using a SchemaRegistrySubjectList — see Manage Schemas.