Pod Spec Whitelist and Remapping

Extending the saved Kubernetes pod spec with annotations

When Cedana checkpoints a pod, the controller stores a reduced version of the pod spec for later restore. By default, it keeps the core fields the controller already depends on. If your workload needs extra fields preserved, or if you need to map a legacy field name into the modern pod spec, you can opt in with pod annotations.

Annotations

Use these annotations on metadata.annotations:

• cedana.ai/pod-spec-whitelist

• cedana.ai/pod-spec-remap

Default behavior

The saved pod spec always includes these fields without any annotation:

• volumes

• nodeSelector

• containers

• initContainers

• restartPolicy

• dnsPolicy

• serviceAccountName

• priorityClassName

• priority

This default set is intentionally small so Cedana only preserves the fields it already needs for restore.

Whitelist annotation

The whitelist annotation is a comma-separated list of pod spec field names.

Example:

metadata:
  annotations:
    cedana.ai/pod-spec-whitelist: "schedulerName,tolerations"

Each listed field is copied from the live pod spec into the saved pod spec if the controller supports it.

Supported whitelist fields:

• affinity

• automountServiceAccountToken

• dnsConfig

• enableServiceLinks

• hostAliases

• imagePullSecrets

• schedulerName

• tolerations

• topologySpreadConstraints

Behavior:

• Unknown or unsupported field names are ignored and logged as warnings.

• Empty entries are skipped.

• Duplicate entries are harmless.

Remap annotation

The remap annotation is a JSON object that maps a source field to a destination field.

Example:

metadata:
  annotations:
    cedana.ai/pod-spec-remap: '{"serviceAccount":"serviceAccountName"}'

This is useful when a pod spec uses a deprecated or alternate field name that should be written into the modern field before the checkpointed spec is published.

Supported remaps:

• serviceAccount to serviceAccountName

Behavior:

• The annotation must be valid JSON.

• Both the source field and destination field must be supported by the controller.

• The source value must be non-empty.

• A remap does not overwrite a destination field that was already populated by the default saved spec.

• Invalid remaps are ignored and logged as warnings.

Merge order

Cedana applies the saved spec updates in this order:

1. Copy the default fields into the saved spec.

2. Apply whitelist entries.

3. Apply remaps.

This means annotations only add fields to the saved spec. They do not remove the default fields, and remaps stay conservative so they do not overwrite a non-empty destination field.

Example pod

apiVersion: v1
kind: Pod
metadata:
  name: cedana-podspec-meta-sample
  annotations:
    cedana.ai/pod-spec-whitelist: "schedulerName,tolerations"
    cedana.ai/pod-spec-remap: '{"serviceAccount":"serviceAccountName"}'
spec:
  serviceAccount: legacy-runner
  schedulerName: default-scheduler
  restartPolicy: Never
  tolerations:
    - key: dedicated
      operator: Equal
      value: checkpoint
      effect: NoSchedule
  containers:
    - name: app
      image: busybox:1.36
      command: ["sh", "-c", "sleep 3600"]

For this pod, the saved spec keeps the default fields and also preserves:

• schedulerName

• tolerations

• serviceAccountName copied from serviceAccount

Operational notes

• If you are debugging a missing field, check the Cedana controller logs for warnings about unknown whitelist fields or invalid remaps.

• This feature is designed for the controller path that captures pod specs during checkpointing, so it applies to workloads restored through Cedana Kubernetes.