# Pod Spec Whitelist and Remapping

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:

```yaml
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:

```yaml
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

```yaml
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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cedana.ai/cedana-kubernetes/podspec-whitelist-remapping.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.