The Flink Kubernetes Operator manages streaming jobs as custom resources

Flink jobs become a custom resource rather than a set of manifests

Apache Flink runs on Kubernetes in a few shapes, and the operator exists to put a controller in the middle of them. The README describes it plainly: a Kubernetes operator for Apache Flink, implemented in Java, that lets users manage Flink applications and their lifecycle through native k8s tooling like kubectl.

What that means in practice is that a Flink job stops being a pile of Deployment and Service manifests you edit by hand. It becomes a custom resource whose state the operator watches, so the operational verbs the README lists, deploy and monitor, upgrade, suspend and delete, happen by editing that resource rather than by re-rendering Helm values. The feature list also includes full logging and metrics integration, and calls out flexible deployments with native integration with Kubernetes tooling.

The audience is a platform or streaming team that has more than one Flink workload and wants the lifecycle handled by a reconciler. It is a poor fit for a single job on a cluster where a hand written manifest is still accurate, since the operator adds a controller, a webhook and custom resource definitions to a system that did not have them before.

Application, Session and Job deployments share one API

The operator supports the three Flink deployment modes, and the examples directory makes the mapping visible through its file names. There is a basic.yaml for the straightforward case, separate files for a session deployment and a job in basic-session-deployment-and-job.yaml and basic-session-deployment-only.yaml and basic-session-job-only.yaml, and a basic-reactive.yaml for the reactive variant. A basic-checkpoint-ha.yaml shows a deployment configured for checkpointing and high availability.

The current API version is v1beta1, and the project status is stated as Production Ready. Those two facts sit in some tension with each other, and it is worth reading both carefully. A production ready status is a statement about the operator's behaviour, while a v1beta1 API is a statement about the contract you write manifests against. The API version is the one that changes under you: when the API graduates, the resource spec you wrote may need edits.

The repository also publishes documentation on the upgrade process and on backward compatibility guarantees, and the README links both. That is the documentation to read before an operator upgrade rather than after one, since the compatibility notes are what tell you whether your existing manifests keep working.

The autoscaler is a separate subsystem with its own deployment modes

A Flink Job Autoscaler is listed as a feature, and the repository layout shows it is a substantial part of the project rather than a side note. There are three modules for it: flink-autoscaler, flink-autoscaler-standalone, and flink-autoscaler-plugin-jdbc, the last named for its use of a database for its state.

The examples directory backs up the claim of integration with the platform rather than against it. There is an autoscaling directory, and there is a separate hpa directory, which points to the autoscaler being able to coexist with the Horizontal Pod Autoscaler rather than fight it. A canary.yaml example suggests progressive rollout patterns are supported too.

The point for an adopter is that scaling a streaming job is not the same problem as scaling a stateless service, because the job has state and its parallelism determines how that state is sharded. The autoscaler has to reason about the job rather than about pod counts, which is why it gets its own modules instead of being folded into the operator core. The README does not document the autoscaler's scaling policy configuration in the text itself, so the configuration keys have to come from the documentation site.

The operator image is a multi module Maven build on Java 17

The Dockerfile in the repository root shows exactly how the official image is produced, and the build arguments are the first thing to read if you plan to build it yourself. The Java version is a build argument defaulting to 17, the base image is the Temurin flavoured Maven image, and the HTTP client used by the Kubernetes client library is selected by an argument that defaults to okhttp. Tests are skipped by default in the image build.

ARG JAVA_VERSION=17
FROM maven:3.8.8-eclipse-temurin-${JAVA_VERSION} AS build
ARG SKIP_TESTS=true
ARG HTTP_CLIENT=okhttp

The build step is a single Maven invocation over five modules, and it is worth noting which ones are in the list: the standalone jar, the operator API, the operator itself, the autoscaler and the webhook.

RUN --mount=type=cache,target=/root/.m2 mvn -ntp clean install -pl flink-kubernetes-standalone,flink-kubernetes-operator-api,flink-kubernetes-operator,flink-autoscaler,flink-kubernetes-webhook -DskipTests=$SKIP_TESTS -Dfabric8.httpclient.impl="$HTTP_CLIENT"

The fabric8.httpclient.impl property is how the underlying HTTP implementation is selected, and the module list is the clearest statement of the architecture: the operator, its API types, the webhook that validates and mutates resources, the standalone jar, and the autoscaler are separate artifacts that ship together in one image.

The webhook, the helm chart and the example tree

Three directories show how the project expects to be deployed and tested. The helm directory holds a chart, which is how most operators get installed, since the CRDs and the controller deployment have to exist before any FlinkDeployment resource can be created. The e2e-tests directory holds end to end tests, which is where the operator's behaviour is actually pinned down rather than described.

The examples directory is unusually broad, and it doubles as documentation. Beyond the deployment mode samples there are advanced-ingress.yaml and basic-ingress.yaml for exposing a job, custom-logging.yaml for the logging integration, pod-template.yaml for customising the pods the operator creates, and a snapshot directory. There are language and integration examples too: flink-python-example, flink-sql-runner-example, flink-beam-example and a kubernetes-client-examples directory. A kustomize directory is present alongside the helm chart, so the project supports both a templated and a plain overlay style of deployment.

Installation guidance is not in the README, which points to the quick start guide on the documentation site for setup instructions. The images themselves are published under the apache/flink-kubernetes-operator name on Docker Hub, and the README notes that the latest stable version can be obtained from the Flink downloads page as well.

No GitHub releases means the image tag is your version record

This repository has no GitHub releases, and that is a practical detail rather than a cosmetic one. There is no tagged changelog to diff, and no release page to point a platform team at when they ask which version is running in production. The version sources named in the README are the Flink downloads page and the Docker Hub tags for the operator image, so pinning is done against an image tag.

The Apache Software License 2 applies to the code, and the repository also carries a NOTICE file and a licenses directory, with a license collection script in the tools directory that runs as part of the image build. The repository follows the ASF layout with a .asf.yaml file, and the README directs code contributions through the Apache Flink contribution pages, with bugs tracked in the ASF Jira under the FLINK project. The project is not archived, and the last push was on 2026-10-06.

One more constraint is worth naming for operators of the operator itself. A custom resource based system needs the CRDs installed, and the controller needs permissions to watch and mutate them, so installing the operator is a cluster level change with an RBAC footprint, not a per namespace action. The README does not spell out the required permissions, so those belong in the documentation and in your own review of the helm chart.

Editorial conclusion

Adopt the operator when you run several Flink workloads on Kubernetes and want one declarative resource to own upgrades, suspension and scaling instead of a set of Helm values and manual restarts. Skip it for a single long running job on a cluster where the extra CRD and controller add more moving parts than they remove. Verify first which operator image tag you are pinning, because the repository publishes no GitHub releases, and read the v1beta1 compatibility notes before you plan an API migration.

Frequently asked questions

Official sources

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