Annotations - CostGraph Documentation

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:

The workload annotation.
The namespace annotation.
The built-in default.

Only via also has a cluster setting, global.autopilot.defaultVia in the operator chart. 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”.

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

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:

kubectl annotate namespace payments \
  autopilot.costgraph.ai/mode=initial \
  autopilot.costgraph.ai/profile=safe

Exclude one workload from an opted-in namespace:

kubectl annotate deployment batch-importer -n payments \
  autopilot.costgraph.ai/mode=disabled

Only reduce requests, and only at night:

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:

kubectl annotate namespace payments --overwrite \
  autopilot.costgraph.ai/paused-until=2026-11-01T00:00:00Z

​Keys

​Invalid values

​Examples

Keys

Invalid values

Examples