Flink Playgrounds gives you three runnable Flink labs in compose files

A set of labs rather than a framework

The repository states its purpose plainly: it provides playgrounds to quickly and easily explore Apache Flink's features.

That word playgrounds is doing the work here. This is not a library, not an example collection of isolated snippets, and not a starter project. Each subfolder is a complete docker-compose environment that brings up a working cluster with an example job in it, and the point of each one is that you can break it and watch what happens.

The structure is described in the documentation. The playgrounds are based on docker-compose environments. Each subfolder of the repository contains the docker-compose setup of a playground, except for the ./docker folder which contains code and configuration to build custom Docker images for the playgrounds.

So the layout has two halves. The playground folders are the environments themselves, and the docker folder is a shared build directory for the images they use. That is the arrangement that lets several playgrounds share a Flink image, a Kafka image and the rest without each one carrying its own copy of the build files.

The repository is Java, Apache-2.0 licensed, with the default branch master and the last push on 2026-09-28. There are no GitHub releases, which is consistent with a repository that is versioned by tracking the main Flink branch rather than by cutting its own tags.

The top-level entries are short and confirm the structure: .github/, .gitignore, LICENSE, README.md, docker/, howto-update-playgrounds.md, and then the three playground folders.

The homepage is the Flink site itself, and the repository sits under the Apache Software Foundation as part of the Flink project.

The operations playground is about failure and change

The Flink Operations Playground lives in the operations-playground folder, and it is the one that most distinguishes this repository from a set of tutorials.

It lets you explore and play with Flink's features to manage and operate stream processing jobs. The specific things you can witness are how Flink recovers a job from a failure, how you upgrade and rescale a job, and how you query job metrics.

Those three are the whole vocabulary of operating a streaming job, and each one is a scenario where the behaviour is hard to reason about from documentation alone.

A failure is the clearest example. When a job fails, the interesting question is not whether it restarts but what happens to the state, whether the offsets are checkpointed correctly, and whether duplicates appear in the output. That is something you can read about and then still get wrong, and being able to kill a task inside a running local cluster and watch the recovery is the fastest way to build the right intuition.

Upgrade and rescale are similar. A streaming job that has been running for hours has state, and changing the parallelism or replacing the job image is an operation with real failure modes. Doing it in a throwaway local cluster first is the sensible way to learn the shape of it.

The metrics question is the third, and it is what links the playground to the observability tooling you would use in production.

The playground consists of a Flink cluster, a Kafka cluster and an example Flink job, so the three pieces you would actually have are all there. Kafka is not incidental, because a stream processing job with no source has nothing to recover from.

The presentation is in the Flink documentation under the Try Flink section, in the Flink Operations Playground page.

Two walkthroughs, one per API

The other two playgrounds are walkthroughs, and they split by API rather than by topic.

The Table Walkthrough lives in the table-walkthrough folder and shows how to use the Table API to build an analytics pipeline. The pipeline reads streaming data from Kafka and writes results to MySQL, and there is a real-time dashboard in Grafana alongside it.

The choice of MySQL and Grafana is what makes this a walkthrough rather than a demo. A SQL table in a relational database is a destination with semantics you already know, and a dashboard is the point at which you see whether the pipeline is doing what you meant. The Flink side is the part being taught, and everything around it is deliberately familiar.

The PyFlink Walkthrough lives in the pyflink-walkthrough folder and provides a complete example that uses the Python API, guiding you through the steps needed to run and manage PyFlink jobs. Its pipeline reads data from Kafka, performs aggregations, and writes results to Elasticsearch, which are visualized with Kibana.

That is the same shape as the Table one with different technologies, and that is the point of having both. The Table API and the Python API are two ways to express the same kind of pipeline over the same engine, and running both lets you compare how the same job looks in each. The Elasticsearch and Kibana combination also has a particular character, since it is a document store rather than a relational one, so the aggregation step in the middle is doing real work rather than a direct write.

The management emphasis in the PyFlink description is worth noting too. It is not only about writing the job, it is about running and managing PyFlink jobs, which in a containerized environment means the same practical concerns as anywhere else: how the job is submitted, how it is restarted, how you see what it is doing.

Unlike the other two, the PyFlink walkthrough has its own README inside the folder, and the documentation points there rather than to a page in the main Flink docs.

What you get and what you have to bring

The appeal of the compose-based approach is that almost nothing has to be installed beyond Docker.

Every playground is self-contained in the sense that it brings up its own Flink cluster, its own Kafka cluster and its own example job, along with whatever storage or dashboard component it needs. For the Table Walkthrough that is MySQL and Grafana, and for the PyFlink one it is Elasticsearch and Kibana. None of that has to be present on your machine beforehand, and none of it has to be configured with credentials you then have to change.

The flip side is that you get a specific, fixed environment rather than a flexible one. The clusters are configured for the walkthrough, and the versions are whatever the compose files and the custom images specify. If you want to try a different Kafka configuration or a different Flink version, you are editing the playground rather than using it as intended.

That is why there is a howto-update-playgrounds.md at the repository root. Its presence tells you that these environments need maintenance work, since the images and the Flink version they run against both move, and the walkthroughs have to keep working as the framework changes underneath them. A repository of hands-on labs that is left alone for a year is a repository of broken labs.

The documentation links point at the Flink 1.16 release of the docs, in the form of a ci.apache.org URL under the flink-docs-release-1.16 path. That tells you which version of the documentation the walkthroughs were written against, which is worth knowing because the Table API and the PyFlink surface have both moved over time.

So the honest summary is that this is a teaching tool with a specific vintage. It teaches the operational shape of Flink well, the surrounding documentation is pinned to a particular release, and the environment is not designed to be modified.

Where this sits against the official documentation

The comparison is with reading the Flink documentation, which is extensive and free, and the case for the playgrounds is a specific one.

Documentation describes behaviour. A playground lets you observe it. For a streaming engine, the behaviours that matter most in practice are the ones that only show up when something goes wrong or something changes, and those are exactly the behaviours that are hard to convey in prose because the reader has to imagine the state, the checkpoints and the restart.

The operations playground is the clearest case for this. A user can break the cluster and see the recovery, rescale the job and watch the state redistribute, and open the metrics endpoint and see the numbers a job actually produces. Each of those is a page of documentation that reads better after you have already seen it happen.

The other comparison is with building your own environment, which is what most people would otherwise do. You would compose a Flink cluster, work out the connector setup, find a Kafka image, decide on a sink, and get the networking right. That is an afternoon that produces something exactly suited to your needs but teaches you nothing about the intended path, and it produces one environment rather than three scenarios.

What the repository is not, and it is worth being clear about, is a production deployment template. The clusters are sized for a laptop, the images are built for the walkthroughs, and the configuration is not hardened. There is no discussion of authentication, resource limits, high availability or state backend configuration here.

The scope is also deliberately the three documented scenarios. There is no playground for a streaming SQL exercise with connectors, none for a stateful processing tutorial with timers, none for a batch example. The repository is a curated set of three labs rather than a catalogue.

Given that, the case for using it is straightforward. If you are evaluating Flink, want to see a job recover, or want to compare the Table API against the Python API on the same problem, these are ready-made environments with the surrounding services already wired in. If you want to understand Flink's internals, the source and the design documentation are elsewhere.

Editorial conclusion

Adopt Flink Playgrounds if you want to learn how Flink behaves when a job fails or needs rescaling, since watching a recovery happen locally teaches more than reading the documentation. Skip it if you already run Flink in production, since these are teaching environments rather than a reference deployment, and if you want a current feature set, since the walkthrough documents are linked from the Flink 1.16 release. Verify first which playground matches the API you use, since one is Java and one is Python, that you have Docker and docker-compose available, and that you read the howto-update-playgrounds document before applying anything to an existing environment.

Frequently asked questions

Official sources

1. apache/flink-playgrounds on GitHub
2. Issues
3. License: Apache-2.0
4. Project website
5. README