Custom Resource Reference

This page is the complete reference for the VvpDeployment Custom Resource. For task-oriented guides on creating, updating, and deleting deployments, see Manage Deployments.

CR Structure

A VvpDeployment CR has the following top-level structure:

apiVersion: ververica.platform/v1
kind: VvpDeployment
metadata:
  name: my-deployment           # Kubernetes resource name
  namespace: my-namespace       # Kubernetes namespace (must be in watchedNamespaces)
  labels:
    ververica.platform/owner: my-operator  # Must match the operator's instanceId
  annotations:
    apikeySecretName: my-vvp-apikey        # Secret containing the Ververica Platform API token
spec:
  syncingMode: PATCH            # PATCH or PUT
  deployment:                   # Ververica Platform deployment definition
    metadata: { ... }           # Deployment identity (name, Ververica Platform namespace, etc.)
    spec: { ... }               # Deployment configuration (state, template, etc.)
  initFields: { ... }           # Optional: creation-time overrides (PATCH mode only)
  savepointNonce: 1             # Optional: change to trigger a savepoint
  restartNonce: 1               # Optional: change to trigger a job restart
status:                         # Managed by the operator — do not set manually
  conditions: [ ... ]
  deploymentId: "..."

The ververica.platform/owner label is required. The webhook rejects CRs where this label is missing or does not match the operator's instanceId.

Operator-Specific Spec Fields

The spec.deployment body mirrors the Ververica Platform deployment structure. All standard Ververica Platform deployment fields (state, deploymentTargetName, template, resources, flinkConfiguration, and so on) are supported. This section documents only the fields the operator introduces that do not exist in Ververica Platform's deployment model.

spec.syncingMode

Controls how the operator projects spec changes to Ververica Platform. Required.

Value	Behavior
`PATCH`	Sends only the fields present in the CR. Ververica Platform preserves its defaults for omitted fields (for example, Flink restart strategy and state TTL).
`PUT`	Sends the full deployment definition. Omitted fields are reset. Requires additional mandatory fields — see Field Constraints. Use PUT when you need full declarative control over the deployment configuration.

You can switch between modes at any time by updating the CR. The new mode takes effect on the next spec change.

spec.initFields

Optional. Used with syncingMode: PATCH during creation only. Ignored for PUT.

Provides fields that are merged into the deployment body during creation only. After the initial creation, initFields are never included in any subsequent update, regardless of syncing mode. This is useful for setting initial values (for example, resources or logging configuration) that you want Ververica Platform to manage after creation.

The structure is the same as spec.deployment.

spec.savepointNonce and spec.restartNonce

Nonce fields for triggering one-shot operations. Change the value to any different non-null number to trigger the operation.

Field	Triggers
`savepointNonce`	Creates a savepoint for the running Flink job
`restartNonce`	Restarts the running Flink job

The operator uses equality comparison — any value change (including decrements) triggers the operation. Any non-null value (including 0) triggers the operation on a fresh CR. Set to null to disable.

If the job is not in RUNNING state when the operator processes a nonce, the operation is blocked and the NonceAligned condition reflects the failure. Apply a new nonce value after the job returns to RUNNING to retry.

Field Constraints

Immutable After Creation

The following fields are set when the CR is first created and must not be changed on subsequent updates:

spec.deployment.metadata.name
spec.deployment.metadata.namespace
spec.deployment.spec.deploymentTargetName

Required Fields (All Modes)

The following fields are required regardless of syncing mode:

spec.syncingMode
spec.deployment.metadata.name
spec.deployment.metadata.namespace
spec.deployment.spec.deploymentTargetName
spec.deployment.spec.template.spec.artifact (with kind and the kind-specific fields)
spec.deployment.spec.template.spec.engineVersionName

Supported artifact kinds: JAR, SQLSCRIPT, PYTHON.

Additional Required Fields (PUT Mode)

The following fields are additionally required when syncingMode is PUT. In PATCH mode, Ververica Platform provides defaults for these fields automatically.

spec.deployment.spec.maxSavepointCreationAttempts
spec.deployment.spec.maxJobCreationAttempts
spec.deployment.spec.template.metadata (can be empty — metadata: {} — but must be present)
spec.deployment.spec.template.spec.logging (must include loggingProfile, log4jLoggers, and logReservePolicy)
spec.deployment.spec.template.spec.numberOfTaskManagers or parallelism (at least one must be specified)

Status Fields

Status fields are managed exclusively by the operator. Do not set them manually. Ververica Platform's internal state is authoritative — status fields provide observability into the operator's view of that state.

Field	Description
`deploymentId`	The Ververica Platform deployment UUID, assigned when the CR is first reconciled.
`observedGeneration`	Mirrors `metadata.generation` at the end of each reconcile cycle. Used internally to detect spec changes.
`syncEnabled`	Whether the operator is actively projecting spec changes to Ververica Platform. Should always be `true` under normal operation.
`observedSpecState`	The desired state from the CR spec (`RUNNING`, `CANCELLED`, `SUSPENDED`).
`actualState`	The actual deployment state as reported by Ververica Platform (`RUNNING`, `CANCELLED`, `SUSPENDED`, `TRANSITIONING`, `FAILED`, `FINISHED`).
`vvpNamespace`	The Ververica Platform namespace used for API calls (from `spec.deployment.metadata.namespace`).
`instanceId`	The operator instance ID managing this CR.
`lastProcessedSavepointNonce`	The last `savepointNonce` value successfully submitted.
`lastProcessedTriggerNonce`	The last `restartNonce` value successfully submitted.
`conditions`	Kubernetes-standard conditions reflecting the CR's health. See Conditions.

Conditions

Conditions follow the standard Kubernetes condition convention (type, status, reason, message, lastTransitionTime).

Condition Summary

Condition	Description
`Healthy`	Aggregate condition. `True` when all other conditions are in their healthy state. Check this first for overall CR health.
`Consistent`	Whether the CR-to-Ververica Platform mapping is intact — the operator can reach the corresponding Ververica Platform deployment.
`SpecAligned`	Whether the last spec projection to Ververica Platform succeeded.
`NonceAligned`	Whether the operator has processed the latest savepoint and restart nonce values.
`ParallelismAligned`	Whether the CR's parallelism matches Ververica Platform's current parallelism. Primarily relevant when Autopilot is active.
`DeletionBlocked`	Whether CR deletion is blocked because the deployment is still active. Healthy when `False` or absent.

Healthy

The aggregate condition, computed from all other conditions on every reconcile cycle.

Status	Reason	Meaning
`True`	`AllConditionsMet`	All sub-conditions are healthy. No action needed.
`False`	(propagated)	A single sub-condition failed. The `Healthy` condition inherits that sub-condition's reason (for example, `SavepointBlocked`). Check the `message` field for details.
`False`	`SubConditionsFailing`	Multiple sub-conditions are failing. The `message` field lists all failures.

Consistent

Reflects whether the operator's internal mapping between the CR and the Ververica Platform deployment is intact.

Status	Reason	Meaning	Action
`True`	`RecordIntact`	The CR is correctly linked to a Ververica Platform deployment.	None.
`False`	`AppManagerRecordNotFound`	The Ververica Platform deployment record is missing. Since operator-managed deployments are protected from direct UI and API deletion, this typically indicates a database-level modification.	Manual intervention required. Delete and recreate the CR, or investigate the AppManager database.
`False`	`DBRecordMissing`	The operator's internal mapping record is missing but the Ververica Platform deployment still exists.	Manual intervention required. Contact your platform administrator.
`False`	`ResourceDeleted`	Both the internal mapping and the Ververica Platform deployment are gone. The CR is orphaned.	Delete the CR with `kubectl delete vvpdeployment <name> --force` and recreate it if needed.
`False`	`AppManagerCreateFailed`	The initial deployment creation in Ververica Platform failed.	Check the `message` field for the error from Ververica Platform. Common causes: invalid artifact URI, unsupported engine version, or deployment target misconfiguration.

SpecAligned

Reflects whether the CR's spec was successfully projected to Ververica Platform.

Status	Reason	Meaning
`True`	`ConfigUpdated`	The CR spec was projected to Ververica Platform successfully.
`True`	`SpecUnchanged`	No spec changes since the last projection.
`False`	`StateProjectionSuppressedAutopilot`	State drift detected but re-projection suppressed — an Autopilot scaling operation is in progress. Transient; resolves automatically when scaling completes. See Autopilot Integration.
`False`	`SyncDisabled`	Sync is disabled. The operator recorded the change but is not projecting it. This is not expected under normal operation — contact your platform administrator.

NonceAligned

Reflects whether the operator has processed the latest savepoint and restart nonce values.

Status	Reason	Meaning	Action
`True`	`NoncesProcessed`	All nonce operations have been processed, or none were requested.	None.
`False`	`SavepointBlocked`	A savepoint was requested but the job is not `RUNNING`, or an Autopilot scaling operation is in progress.	Wait for the job to reach `RUNNING` and for any Autopilot scaling to complete, then apply a new `savepointNonce` value. The blocked nonce is consumed — you cannot re-trigger by reverting to the same value.
`False`	`RestartBlocked`	A restart was requested but the job is not `RUNNING`, or an Autopilot scaling operation is in progress.	Same as above, using `restartNonce`.

ParallelismAligned

Compares the CR's parallelism against Ververica Platform's current parallelism on every reconcile cycle. This condition auto-heals — no CR update is needed when the underlying state changes.

Status	Reason	Meaning
`True`	`Aligned`	Autopilot is not active, has not scaled yet, the CR does not specify parallelism, or the CR's parallelism matches Autopilot's runtime parallelism.
`False`	`AutopilotManaged`	Autopilot is active and its runtime parallelism differs from what the CR specifies. This is expected behavior. See Autopilot Integration.

DeletionBlocked

Set during CR deletion when the Ververica Platform deployment is still in an active state. This condition has inverted polarity — it is healthy when False or absent.

Status	Reason	Meaning	Action
`True`	`DeploymentStillActive`	The deployment is in `RUNNING` or `TRANSITIONING` state.	Set the deployment to `CANCELLED` before deleting the CR. See Delete a Deployment.
`False` / absent		Normal state. Deletion is not blocked.	None.

Printer Columns

kubectl get vvpdeployments displays the following columns by default:

NAME              ACTUAL      INSTANCE-ID   DESIRED     SYNC   VVP-NAMESPACE   HEALTHY   AGE
my-deployment     RUNNING     my-operator   RUNNING     true   default         True      5m

Run kubectl get vvpdeployments -o wide to add: CONSISTENT, SPECALIGNED, PARALLELISMALIGNED, DELETIONBLOCKED.

Complete YAML Examples

These examples assume API key authentication is configured. If you are testing without API keys, set webhook.apiKeyValidation.enabled: false in your Helm values.

Minimal PATCH Mode CR

PATCH mode requires only the structurally required fields. Ververica Platform provides defaults for everything else (logging, resources, Flink configuration, and so on).

apiVersion: ververica.platform/v1
kind: VvpDeployment
metadata:
  name: my-deployment
  namespace: my-deploy-namespace
  labels:
    ververica.platform/owner: my-operator
  annotations:
    apikeySecretName: my-vvp-apikey
spec:
  syncingMode: PATCH
  deployment:
    metadata:
      name: my-deployment
      namespace: default
    spec:
      state: CANCELLED
      deploymentTargetName: default
      template:
        spec:
          artifact:
            kind: JAR
            jarUri: "s3://my-bucket/artifacts/MyJob.jar"
          engineVersionName: "vera-4.1-flink-1.20"

Minimal PUT Mode CR

PUT mode requires additional fields that PATCH mode can omit. Missing any of these causes the webhook to reject the CR.

apiVersion: ververica.platform/v1
kind: VvpDeployment
metadata:
  name: my-deployment
  namespace: my-deploy-namespace
  labels:
    ververica.platform/owner: my-operator
  annotations:
    apikeySecretName: my-vvp-apikey
spec:
  syncingMode: PUT
  deployment:
    metadata:
      name: my-deployment
      namespace: default
    spec:
      state: CANCELLED
      deploymentTargetName: default
      maxJobCreationAttempts: 3
      maxSavepointCreationAttempts: 3
      template:
        metadata: {}
        spec:
          artifact:
            kind: JAR
            jarUri: "s3://my-bucket/artifacts/MyJob.jar"
          numberOfTaskManagers: 1
          engineVersionName: "vera-4.1-flink-1.20"
          logging:
            loggingProfile: "default"
            log4jLoggers:
              "": "INFO"
            logReservePolicy:
              openHistory: true
              expirationDays: 7

CR Structure​

Operator-Specific Spec Fields​

spec.syncingMode​

spec.initFields​

spec.savepointNonce and spec.restartNonce​

Field Constraints​

Immutable After Creation​

Required Fields (All Modes)​

Additional Required Fields (PUT Mode)​

Status Fields​

Conditions​

Condition Summary​

Healthy​

Consistent​

SpecAligned​

NonceAligned​

ParallelismAligned​

DeletionBlocked​

Printer Columns​

Complete YAML Examples​

Minimal PATCH Mode CR​

Minimal PUT Mode CR​