kafka-docker-playground and reproducible Kafka and Confluent examples

A shell driven harness for Kafka and Confluent examples

The problem this solves is reproducibility. Testing a Kafka connector, a security configuration or a support case usually means assembling a cluster by hand, and the person who fixed it last week may not remember every step. This project wraps that work in Docker so that an example runs the same way for everyone.

The primary language of the repository is Shell, and the top level directories show the breadth of what it wraps: `connect/` for connectors, `ccloud/` for Confluent Cloud, `environment/` for secured setups, `cfk-analysis/`, `flink/`, `ksqldb/`, `multi-data-center/`, `schema-registry/`, `rest-proxy/`, `reproduction-models/`, `troubleshooting/`, `cloudformation/`, `academy/` and `tools/`. That directory list is a better description of the project than any single feature bullet.

The README states the aim twice, in the tagline and in the ideology section: fully automated Docker based examples, so that you can build examples or reproduction models without hand wiring. The homepage at kafka-docker-playground.io is where the documentation lives, and the README sends you there for the how it works section.

The licence is MIT, with the terms in the LICENSE file at the repository root, and the last push was on 2026-10-20.

The catalogue of connectors and environments

The feature list is best read as an inventory of what you can run without writing any infrastructure yourself.

For connectors, the README counts 170+ onprem or self-managed connector examples and 100+ fully-managed connector examples, each linked to a page in the content gallery. On top of that there are 10+ secured environments covering SASL, RBAC and SSL, plus examples for Confluent Cloud and for Confluent commercial features such as Tiered Storage, Control Center and audit logs. Multi data center work has its own section covering Cluster Linking, Replicator and MirrorMaker 2.

Two entries in that list matter more than the counts. One says you can run examples with any Confluent Platform or connector version, which matters because a connector that behaves differently between releases is exactly the kind of problem people need to reproduce. The other is the option to run any onprem connector example using Confluent For Kubernetes through a single command line switch, `--environment cfk`, with the README describing it as completely transparent.

Multi data center and Cluster Linking material is included, which suggests the project is used for more than single cluster tinkering.

Reports carry the diagnostic output

The part of the project that goes beyond running an example is the report gallery. The README says real reports, generated from the samples shipped in the repository, can be browsed in the reports gallery, and the screenshots it shows are a thread dump report, a connector benchmark report and an Oracle XStream report.

The list of report types is specific: thread dumps, GC logs, flight recordings, connector benchmarks, SMT tests, Oracle XStream and CFK diagnostics. Those are the artifacts you would otherwise attach by hand to a support ticket or a pull request, which is the practical value. A reproduction that ends in a shareable report is a very different thing from a reproduction that ends in a screenshot of a terminal.

The same idea runs through the troubleshooting and gc-analysis directories in the repository, and through the Oracle XStream analysis the README mentions again in its Claude Code section, where the project is described as usable for analyzing Oracle XStream reports.

Benchmarking a connector with the Java Flight Recorder

The benchmark feature goes further than timing a run. The README describes benchmarking a connector for throughput, for version comparison, and for where the time inside the tasks goes, and it names the Java Flight Recorder as the tool used for that last part.

That is the interesting detail. Comparing two connector versions is a normal thing to want, and the version flexibility described elsewhere in the README makes that comparison possible in the same environment. Showing where the time goes inside the tasks is a different level of question, and the Flight Recorder is the standard way to answer it in a JVM workload.

The README presents this as a reusable piece of the playground, in the reusables section, which is the same mechanism it offers for building your own examples. The repository also has an `academy/` directory and a `docs/` directory, so the project carries teaching material alongside the tooling.

Podman, remote hosts and CI

Three practical details broaden the reach of the project beyond a local Docker Desktop.

Podman is supported through its Docker compatible API, so examples can run with Podman instead of Docker on a machine where Docker is not the container runtime. The README treats this as a first class option with its own documentation page.

Remote work is handled by a CLI command, `playground ec2`, which the README describes as a way to work remotely with VS Code. That is a different model from running everything on your own laptop: the environment lives on a remote host and the editor attaches to it.

Automated testing runs on GitHub Actions. The README points at a section describing how CI works, and the repository has a `.github/` directory at the top level, alongside a `.claude/` directory and a CLAUDE.md file, which suggests the project also carries instructions for working with it from an AI coding assistant, including skills to add examples, to review pull requests and to change the CLI.

The ideology: basic examples that anyone can rebuild

The README is unusually candid about the quality of the individual examples. It says most of the examples in the playground are very basic. What it claims instead is that they let you test components in an automated way, with any versions, and, most importantly, let you build your own reproduction models.

That framing explains the structure. The reusables section is the mechanism for building new material from existing pieces, so a reproduction model is assembled rather than written from zero. The `reproduction-models/` directory at the repository root holds the models that come with the project, and the troubleshooting and gc-analysis directories sit alongside them.

The version flexibility is the other half of the claim. If an example always ran against one pinned Kafka release, reproducing a bug that only appears on a specific release would be impossible, so being able to specify versions is a functional requirement rather than a convenience.

The repository publishes no GitHub releases, so the state of the project is read from the commits rather than from a version history.

Where the playground is the wrong tool

The first limit is the container requirement. Every example runs inside Docker, or inside Podman through its compatible API, or on a remote host reached with `playground ec2`. On a machine where you cannot run containers, there is no fallback, and the project does not offer a non container mode.

The second limit is scope. This is a laboratory for Kafka and Confluent components, not a deployment tool and not a managed service. The README covers commercial features as examples to run, including Control Center and audit logs, which is the opposite of running those features in production for you.

The third limit is the size of the surface you are adopting. The repository is mostly Shell, but it pulls in a Confluent Platform, connectors, secured environments with SASL, RBAC and SSL, and optional extras such as Flink, ksqlDB and the Schema Registry. A connector example that also stands up a secured cluster is a substantial download and a slow first run, and the README does not publish timings for a cold start.

Finally, there is no published release cadence. With no GitHub releases, the version you run is whatever the repository gives you, and the only stated version handle is the one you pass when you want to pin a Confluent Platform or connector version.

Editorial conclusion

kafka-docker-playground fits a Kafka engineer who needs a repeatable environment for a connector, a security scenario or a support case, and who wants a report to attach rather than a paragraph of notes. It does not fit someone looking for a managed Kafka, or a workflow where Docker on the machine is not an option. Before using it, read the How to Use section it links to, since the README deliberately keeps the run instructions on the documentation site.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. vdesabou/kafka-docker-playground on GitHub