> ## Documentation Index
> Fetch the complete documentation index at: https://docs.costgraph.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Annotations

> Every CostGraph AutoPilot annotation, its values and its default.

CostGraph AutoPilot is configured with annotations that start with
`autopilot.costgraph.ai/`. Set them on a workload (Deployment, StatefulSet,
DaemonSet, Job, CronJob or Argo Rollout) or on its namespace.

For each key the first value found wins, in this order:

1. The workload annotation.
2. The namespace annotation.
3. The built-in default.

Only `via` also has a cluster setting, `global.autopilot.defaultVia` in the [operator chart](https://docs.costgraph.ai/costgraph/operator/configuration.md#costgraph-autopilot). It applies between the namespace annotation and the built-in default.

Settings that come from an annotation show as locked in CostGraph, marked "set in Git".

```bash theme={null}
kubectl annotate deployment api -n payments \
  autopilot.costgraph.ai/mode=auto \
  autopilot.costgraph.ai/profile=safe \
  autopilot.costgraph.ai/memory.max=2Gi
```

## Keys

| Key | Values | Default | What it does |
| - | - | - | - |
| `mode` | `auto`, `initial`, `off`, `disabled` | not set (recommendations only) | `auto` sizes new pods and resizes running pods in place. `initial` sizes new pods only. `off` applies nothing and keeps the recommendation visible. `disabled` excludes the workload. |
| `via` | `webhook`, `vpa` | `global.autopilot.defaultVia` (`webhook`) | How sizing is applied. See [Vertical Pod Autoscaler](https://docs.costgraph.ai/costgraph/autopilot/vpa.md). |
| `profile` | `tight`, `balanced`, `safe` | `balanced` | Headroom preset. `tight` targets 90% utilisation, `safe` targets 60%, `balanced` uses the CostGraph recommendation. |
| `resources` | `cpu,memory`, `cpu`, `memory` | `cpu,memory` | The resources AutoPilot controls. A resource an HPA scales on is always dropped. |
| `exclude-containers` | comma-separated container names | none | Containers that are never changed. |
| `direction` | `both`, `down`, `up` | `both` | Whether AutoPilot may only reduce requests, only raise them, or both. |
| `cpu.min`, `cpu.max` | Kubernetes quantity, for example `100m` | none | Hard CPU bounds per container. |
| `memory.min`, `memory.max` | Kubernetes quantity, for example `256Mi` | none | Hard memory bounds per container. |
| `min-change` | percent, for example `15` | `10` | Skip changes smaller than this. |
| `min-savings` | USD per month, for example `5` | `0` | Skip changes worth less than this per container. |
| `cooldown.down`, `cooldown.up` | duration, for example `24h` | `0` | Minimum time between changes in each direction. |
| `window.schedule` | cron expression, for example `0 3 * * *` | none | When reductions may be applied. Needs `window.duration`. |
| `window.duration` | duration, for example `2h` | none | How long the window stays open. Needs `window.schedule`. |
| `paused-until` | RFC 3339 time, for example `2026-11-01T00:00:00Z` | none | Freeze changes until that time, then resume automatically. |
| `placement` | `auto`, `off` | `off` | Allow moving pods onto a CostGraph-owned node pool, and steering GPU workloads to a cheaper GPU model. |
| `gpu` | `auto`, `off` | `off` | Allow reducing GPU count at pod creation. Model steering also needs `placement: auto`. |

> [!NOTE]
>
> The change window only limits reductions. Increases and out-of-memory bumps are applied at any time.

## Invalid values

A bad value affects that key only. AutoPilot ignores it, uses the next level
down (the namespace annotation, then the default), and reports the problem on the
workload in CostGraph. Everything else still applies. Unknown keys under the
prefix are reported as warnings.

For example, `cpu.max: two` is ignored and the namespace or default CPU maximum
applies, while a valid `memory.max` on the same workload still takes effect.

## Examples

Opt a namespace in at pod creation only, with a larger safety margin:

```bash theme={null}
kubectl annotate namespace payments \
  autopilot.costgraph.ai/mode=initial \
  autopilot.costgraph.ai/profile=safe
```

Exclude one workload from an opted-in namespace:

```bash theme={null}
kubectl annotate deployment batch-importer -n payments \
  autopilot.costgraph.ai/mode=disabled
```

Only reduce requests, and only at night:

```bash theme={null}
kubectl annotate deployment api -n payments \
  autopilot.costgraph.ai/mode=auto \
  autopilot.costgraph.ai/direction=down \
  autopilot.costgraph.ai/window.schedule="0 2 * * *" \
  autopilot.costgraph.ai/window.duration=3h
```

Pause a namespace for a release freeze:

```bash theme={null}
kubectl annotate namespace payments --overwrite \
  autopilot.costgraph.ai/paused-until=2026-11-01T00:00:00Z
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.