Kubernetes Operator
A Kubernetes Operator is a Kubernetes-native application controller that extends the Kubernetes API to manage and automate the deployment, configuration, and lifecycle of complex applications. The Kubernetes documentation provides a good overview of Operators.
Ververica Platform provides a custom Kubernetes Operator that gives you a Kubernetes-native way to manage Flink deployments. Instead of managing deployments through the Web UI or the Ververica Platform API, the operator lets you define deployments as VvpDeployment Custom Resources and manage them with standard Kubernetes tooling such as kubectl and Helm. The Ververica Platform 3 Kubernetes Operator is an improved evolution of the Ververica Platform 2 operator, redesigned to align with the Ververica Platform 3 architecture. For migration guidance, see Migration from Ververica Platform 2.
Key Capabilities
- Deployment lifecycle management: Create, update, and delete Flink deployments using Custom Resources (CRs).
- Two sync modes: PATCH sends only the fields present in the CR and preserves Ververica Platform defaults for omitted fields. PUT sends the full deployment definition and resets omitted fields.
- State management: Transition deployments between
RUNNING,SUSPENDED, andCANCELLED. - Savepoint and restart triggers: Use nonce fields to trigger on-demand savepoints and job restarts without extra tooling.
- Conditions: Kubernetes-native health reporting through
Healthy,Consistent,SpecAligned,NonceAligned,ParallelismAligned, andDeletionBlockedconditions. - Events: The operator emits lifecycle and warning events to the Ververica Platform Events tab. Ververica Platform job and deployment events are also mirrored to Kubernetes Events, making them accessible through
kubectl get eventsand standard monitoring tools. - Autopilot integration: Provides observability into Autopilot's runtime scaling via the
ParallelismAlignedcondition; the operator always projects the CR's parallelism to Ververica Platform. - Webhook validation: The operator validates CRs before they reach the cluster, providing immediate feedback through
kubectl.
How It Works
Ververica Platform remains the source of truth. The operator acts as a synchronization layer that translates your Kubernetes-native intent into Ververica Platform API calls. All lifecycle management, including job scheduling, failure recovery, and autoscaling, continues to run in Ververica Platform.
The sync loop works as follows:
- You create or update a
VvpDeploymentCR in your Kubernetes cluster. - The operator detects the change and projects it to Ververica Platform through the AppManager API.
- Ververica Platform processes the change (starts a Flink job, applies configuration, triggers a savepoint, and so on).
- The operator updates the CR status with the current state from Ververica Platform.
Operator-managed deployments can only be modified through the operator. Once you create a deployment through a CR, the Ververica Platform UI and API block direct modifications. To make changes, update the CR. Deployments created through the UI or API cannot be claimed by the operator. This is a change from the Ververica Platform 2 operator, which allowed UI edits on operator-managed deployments but silently reverted them at the next reconciliation cycle.
CRDs and CRs
The Kubernetes Operator uses two resource types:
- Custom Resource Definition (CRD): A Kubernetes YAML manifest that defines the schema and behavior of the operator. The CRD ships with the Ververica Platform Helm chart.
- Custom Resource (CR): A resource instance that manages a single deployment in Ververica Platform.
You can think of the CRD as a class definition and a CR as an object that instantiates the class.
Install the CRD Independently of the Chart
By default the custom resource definition is installed and upgraded together with the Ververica Platform Helm chart. Because a custom resource definition is a cluster-scoped resource, some environments manage it under a different change-control process than namespaced workloads, or grant the installing account no permission to create it.
To exclude the custom resource definition from the Helm release, set the following value:
1ververica-platform-crd:
2 enabled: falseWith this value set, helm install and helm upgrade render no custom resource definition, and the resource must be applied separately by an account with cluster-scoped permissions. For example, extract it from the ververica-platform-crd subchart with helm template and apply it with kubectl.
Verify which behavior a set of values produces before installing:
1helm template <RELEASE_NAME> \
2 oci://registry.ververica.cloud/platform-charts/ververica-platform \
3 --version 3.1.2 \
4 --values values.yaml \
5 --include-crds | grep -c "kind: CustomResourceDefinition"The command returns 1 when the custom resource definition is part of the release and 0 when it is excluded.
If you disable this toggle without pre-installing the CRD, the Kubernetes Operator pod crash-loops on startup: its wait-for-crd init container fails with a NotFound error while waiting for the CRD to exist.
A custom resource definition that was applied outside Helm, for example with kubectl apply, is owned by a different field manager. A later Helm release that tries to manage the same resource fails with a field ownership conflict on .spec.versions. Keep the custom resource definition either Helm-managed or externally managed for the lifetime of the installation, and do not alternate between the two. This toggle only stops Helm from creating the CRD; it doesn't make Helm adopt one that already exists from another source, and ownership stays with whoever applied it first.
Uninstalling the release does not delete the custom resource definition. Remove it explicitly when decommissioning an installation, after confirming that no custom resources remain, because deleting a custom resource definition also deletes its custom resources.