Custom Pod Annotations

Ververica Platform lets you attach custom Kubernetes annotations to the pods of platform components through the Helm values.yaml file. These annotations appear directly in each pod's metadata and are available to Kubernetes-native tooling such as log collectors, secrets injectors, and service meshes.

Supported Components

The podAnnotations field is available for the following Ververica Platform components:

Component	values.yaml key
Gateway	gateway
AppManager	appManager
Meta	meta
Autopilot	autopilot
Advisor	advisor
AppAgent	appAgent
Premise	premise
SQL Service	sqlService
Kubernetes Operator	k8sOperator

Configuration Levels

You can configure pod annotations at two levels:

• Global: annotations under global.podAnnotations apply to all platform component pods.
• Per-component: annotations under <component>.podAnnotations apply only to that component's pods, and are merged with any global annotations.

# Apply to all component pods
global:
  podAnnotations:
    team: "data-engineering"

# Apply only to AppManager pods (merged with global annotations)
appManager:
  podAnnotations:
    vault.hashicorp.com/agent-inject: "true"

Annotation Merge Behavior

Annotations from global.podAnnotations and <component>.podAnnotations are merged and written to PodSpec.metadata.annotations. podAnnotations targets the pod resource, not the Deployment or StatefulSet resource itself.

note

When a user-supplied annotation key matches a platform-hardcoded annotation key (for example, admission-webhook/eniSecurityReinforce), the platform-hardcoded value takes precedence. The user-supplied value for that key has no effect.

Example Use Cases

Fluent Bit Log Exclusion

Exclude platform component pods from Fluent Bit log collection:

global:
  podAnnotations:
    fluentbit.io/exclude: "true"

HashiCorp Vault Agent Injector

Enable the HashiCorp Vault Agent Injector to inject secrets into a component's pods:

appManager:
  podAnnotations:
    vault.hashicorp.com/agent-inject: "true"
    vault.hashicorp.com/role: "ververica-platform"
    vault.hashicorp.com/agent-inject-secret-config: "secret/data/vvp/config"

Service Mesh Sidecar Injection Control

Disable Istio sidecar injection for a specific component:

gateway:
  podAnnotations:
    sidecar.istio.io/inject: "false"

Apply Changes

After editing values.yaml, apply the changes by running:

helm upgrade --install <RELEASE_NAME> \
  oci://registry.ververica.cloud/platform-charts/ververica-platform \
  --version 3.1.1 \
  --namespace <NAMESPACE> \
  --values values.yaml

Migration from Ververica Platform 2

Ververica Platform 2.x exposed a single top-level podAnnotations field that applied to the main platform pod. This field was removed in Ververica Platform 3.0.0. Ververica Platform 3.1.1 reintroduces annotation support with a two-level model that gives independent control over each component.

Ververica Platform 2 (no longer supported):

podAnnotations:
  team: "data-engineering"

Ververica Platform 3.1.1:

# Global: applies to all components
global:
  podAnnotations:
    team: "data-engineering"

# Per-component: applies to AppManager only
appManager:
  podAnnotations:
    vault.hashicorp.com/agent-inject: "true"

Troubleshooting

Annotation Not Appearing in the Pod Specification

If an annotation does not appear in a pod's metadata after upgrade, check the following:

• Verify the YAML key path. Confirm that the annotation is nested under podAnnotations within global or a component section, not under a top-level or resource-level annotations key.

• Apply the Helm upgrade. Changes to values.yaml take effect only after you run helm upgrade. Editing the file without running the upgrade leaves the cluster unchanged.

• Check for key conflicts. If the annotation key matches a platform-hardcoded annotation key, the user-supplied value is silently ignored. Use a distinct annotation key to avoid the conflict.

Meta Pod Rollout

Meta uses a rolling-update strategy that does not automatically restart pods when annotation changes are applied. If the Meta pods do not reflect new annotations after the Helm upgrade, trigger a manual rollout:

kubectl rollout restart statefulset/<meta-statefulset-name> -n <NAMESPACE>