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:

1apiVersion: ververica.platform/v1
2kind: VvpDeployment
3metadata:
4  name: my-deployment           # Kubernetes resource name
5  namespace: my-namespace       # Kubernetes namespace (must be in watchedNamespaces)
6  labels:
7    ververica.platform/owner: my-operator  # Must match the operator's instanceId
8  annotations:
9    apikeySecretName: my-vvp-apikey        # Secret containing the Ververica Platform API token
10spec:
11  syncingMode: PATCH            # PATCH or PUT
12  deployment:                   # Ververica Platform deployment definition
13    metadata: { ... }           # Deployment identity (name, Ververica Platform namespace, etc.)
14    spec: { ... }               # Deployment configuration (state, template, etc.)
15  initFields: { ... }           # Optional: creation-time overrides (PATCH mode only)
16  savepointNonce: 1             # Optional: change to trigger a savepoint
17  restartNonce: 1               # Optional: change to trigger a job restart
18status:                         # Managed by the operator — do not set manually
19  conditions: [ ... ]
20  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.

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.

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.

Conditions

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

Condition Summary

Healthy

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

Consistent

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

SpecAligned

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

NonceAligned

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

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.

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.

Printer Columns

kubectl get vvpdeployments displays the following columns by default:

1NAME              ACTUAL      INSTANCE-ID   DESIRED     SYNC   VVP-NAMESPACE   HEALTHY   AGE
2my-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).

1apiVersion: ververica.platform/v1
2kind: VvpDeployment
3metadata:
4  name: my-deployment
5  namespace: my-deploy-namespace
6  labels:
7    ververica.platform/owner: my-operator
8  annotations:
9    apikeySecretName: my-vvp-apikey
10spec:
11  syncingMode: PATCH
12  deployment:
13    metadata:
14      name: my-deployment
15      namespace: default
16    spec:
17      state: CANCELLED
18      deploymentTargetName: default
19      template:
20        spec:
21          artifact:
22            kind: JAR
23            jarUri: "s3://my-bucket/artifacts/MyJob.jar"
24          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.

1apiVersion: ververica.platform/v1
2kind: VvpDeployment
3metadata:
4  name: my-deployment
5  namespace: my-deploy-namespace
6  labels:
7    ververica.platform/owner: my-operator
8  annotations:
9    apikeySecretName: my-vvp-apikey
10spec:
11  syncingMode: PUT
12  deployment:
13    metadata:
14      name: my-deployment
15      namespace: default
16    spec:
17      state: CANCELLED
18      deploymentTargetName: default
19      maxJobCreationAttempts: 3
20      maxSavepointCreationAttempts: 3
21      template:
22        metadata: {}
23        spec:
24          artifact:
25            kind: JAR
26            jarUri: "s3://my-bucket/artifacts/MyJob.jar"
27          numberOfTaskManagers: 1
28          engineVersionName: "vera-4.1-flink-1.20"
29          logging:
30            loggingProfile: "default"
31            log4jLoggers:
32              "": "INFO"
33            logReservePolicy:
34              openHistory: true
35              expirationDays: 7