Getting started¶

This short tutorial introduces some of the main features of kdef.

Tutorial setup¶

Clone the kdef repository and change directory to docs/tutorial.

git clone git@github.com:peter-evans/kdef.git
cd kdef/docs/tutorial

Execute the following to spin up a two-broker Kafka cluster using Docker compose.

ZOOKEEPER_PORT=12181 \
BROKER1_PORT=19092 \
BROKER2_PORT=19093 \
docker-compose up -d

At the end of the tutorial use the following to bring the cluster down.

ZOOKEEPER_PORT=12181 \
BROKER1_PORT=19092 \
BROKER2_PORT=19093 \
docker-compose down --volumes

Your current working directory should now be docs/tutorial. In this directory is a config.yml configuration file. This is the configuration kdef will use to connect to the Kafka cluster spun up in the previous step.

Applying definitions¶

The cluster we spun up in the previous section has no resources. Let's apply some definitions.

from files¶

Execute the following to perform a dry-run apply of all definitions under the "definitions" directory.
```
kdef apply "definitions/**/*.yml" --dry-run
```
Remove the --dry-run flag and apply the definitions.
```
kdef apply "definitions/**/*.yml"
```
Execute the command in step 2 a second time. You should now see that there are "no changes to apply."
Edit definitions/topic/tutorial_topic1.yml and make the following changes.
- retention.ms: "43200000"
- partitions: 6
Execute steps 1 and 2 again to dry-run and then apply the topic definition update.

from stdin¶

Execute the following to perform a dry-run apply of a definition passed via stdin.

cat <<EOF | kdef apply - --dry-run
apiVersion: v1
kind: topic
metadata:
  name: tutorial_topic2
spec:
  configs:
    retention.ms: "86400000"
  partitions: 3
  replicationFactor: 2
EOF

Remove the --dry-run flag and apply the definition.

cat <<EOF | kdef apply -
apiVersion: v1
kind: topic
metadata:
  name: tutorial_topic2
spec:
  configs:
    retention.ms: "86400000"
  partitions: 3
  replicationFactor: 2
EOF

Execute the command in step 2 a second time. You should now see that there are "no changes to apply."

Execute the following to perform a dry-run apply and update the topic created in step 2. This time we'll supply the definition as JSON.

cat <<EOF | kdef apply - --format json --dry-run
{
  "apiVersion": "v1",
  "kind": "topic",
  "metadata": {
    "name": "tutorial_topic2"
  },
  "spec": {
    "configs": {
      "retention.ms": "43200000"
    },
    "partitions": 6,
    "replicationFactor": 2
  }
}
EOF

Remove the --dry-run flag and apply the definition update.

cat <<EOF | kdef apply - --format json
{
  "apiVersion": "v1",
  "kind": "topic",
  "metadata": {
    "name": "tutorial_topic2"
  },
  "spec": {
    "configs": {
      "retention.ms": "43200000"
    },
    "partitions": 6,
    "replicationFactor": 2
  }
}
EOF

Exporting definitions¶

Let's export definitions for the resources we created in the previous section.

to files¶

Execute the following to export topic definitions to files in the directory "exported".
```
kdef export topic --output-dir exported
```
Let's additionally export partition assignments for the topics and overwrite the files created in step 1.
```
kdef export topic --output-dir exported --overwrite --assignments broker
```

to stdout¶

Execute the following to export topic definitions to stdout. --quiet suppresses log messages so we just see the definitions output.
```
kdef export topic --quiet
```

Alternatively, we can export as JSON.

kdef export topic --quiet --format json