Quick Start

This guide walks you through creating an AttunePolicy, reviewing its recommendations, and promoting to Canary mode, all in about five minutes.

Interactive demo

Want to see the full flow on a real cluster first? Run the automated demo script that provisions a k3d cluster, deploys a sample workload, and shows recommendations appearing in real time:

./hack/demo.sh

The script cleans up automatically on exit. Use --no-cleanup to keep the cluster for exploration.

Prerequisites

• Kubernetes 1.32+ — 1.32 requires the InPlacePodVerticalScaling feature gate; 1.33–1.34 beta enabled by default; 1.35+ GA.
• A metrics source — Prometheus (default), Datadog, or CloudWatch Container Insights. This guide uses Prometheus; see Datadog Setup or CloudWatch Setup for alternatives. At most one metrics provider may be set; AttuneDefaults inherit a provider only when the policy set none.
• Attune installed — see Installation for Helm and raw manifest options. Default Helm install needs cert-manager (or --set webhooks.enabled=false).
• Cluster preflight — kubectl attune doctor checks Kubernetes 1.32+ and pods/resize before you wait on recommendations.
• Prometheus reachability — the chart NetworkPolicy allows Prometheus egress on port 9090 by default. If your Service listens on port 80 (common with prometheus-server.monitoring:80), set --set networkPolicy.prometheusPort=80 at install time or you will get no data.

What else can Attune do?

This quick start gets you to recommendations. When you are ready to go further:

Area	Start here
Multi-cluster fleet reports and dashboards	Multi-cluster
GitOps ConfigMap export and optional PR automation	GitOps integration
Application SLO checks after resize (latency, errors)	SLO guardrails
Memory limit decrease safety (usage floor on 1.34+)	Resize API and troubleshooting OOM
Language runtime defaults (Java, Python, Go, Node)	Runtime profiles
Cold-start CPU headroom	Startup boost. excludeFromHistory: true drops CPU samples from attune.io/startup-boost-at when that stamp is set, otherwise from creation, until that start plus duration plus the rate window; omitted keeps today's percentile.
Memory after OOMKilled	An optional memory OOM bump can raise the request after OOMKilled and is off until set.
Usage surge	Optional cpu.surge or memory.surge shortens the history window while recent usage is hot, and stays off until the block is set.
Node pressure skips and reclaimed capacity	Bin packing and node capacity

1. Create an AttunePolicy in Recommend mode

Start in Recommend mode so that no pods are modified. The operator will collect metrics and write recommendations to the resource status.

All fields have production-ready defaults: P95 CPU, P99 memory, 20% CPU overhead, and 30% memory overhead. Omitted minimums floor at 1m CPU and 4Mi memory. Omitted maximums are not capped. A minimal policy is:

apiVersion: attune.io/v1alpha1
kind: AttunePolicy
metadata:
  name: my-app
  namespace: default
spec:
  targetRef:
    kind: Deployment
    name: my-app
  cpu: {}
  memory: {}
  metricsSource:
    prometheus:
      address: http://prometheus-server.monitoring:80
  updateStrategy:
    type: Recommend
  # Optional: faster first look (~1h instead of ~4h at default queryStep: 5m)
  # minimumDataPoints: 12

To give one container its own CPU ceiling, add containerPolicies. An omitted list keeps the shared cpu and memory blocks. Known sidecars such as istio-proxy stay excluded until excludeKnownSidecars is false.

containerPolicies:
  - containerName: sidecar
    cpu:
      maxAllowed: "200m"

Skip the Prometheus address on every policy

Create a cluster-scoped AttuneDefaults resource with the Prometheus address and it will apply to all policies. If only one namespace should inherit that address, use a namespaced AttuneNamespaceDefaults instead. The repo includes examples/05-cluster-defaults.yaml for a cluster-wide setup and examples/11-namespace-defaults.yaml for a namespace-only setup. That address has no token. When Prometheus requires one, use the four cases in Choose how Attune authenticates.

apiVersion: attune.io/v1alpha1
kind: AttuneDefaults
metadata:
  name: cluster-defaults
spec:
  metricsSource:
    prometheus:
      address: http://prometheus-server.monitoring:80

With this set, your policies only need targetRef.

Requests only vs requests and limits

By default, Attune adjusts requests only (controlledValues: RequestsOnly). If your containers have CPU/memory limits set, the recommendation may be capped at the limit value. Set controlledValues: RequestsAndLimits on the policy if you want Attune to scale both. See Configuration Reference for details.

Full configuration reference

All defaults can be overridden per-policy. See Configuration Reference for the complete list of fields including cpu.percentile, memory.overhead, updateStrategy.cooldown, bounds, and more.

kubectl apply -f attunepolicy.yaml

2. Check status

kubectl get attunepolicy my-app -o wide

Right after applying, the policy will be collecting data:

NAME     TYPE        WORKLOADS   RECS   RESIZED   READY   AGE   CPU SAVED   MEM SAVED
my-app   Recommend   1           0      0         False   5m

Note: READY=False here means the policy is still in the InsufficientData phase. Check .status.conditions to see the reason and progress message.

minimumDataPoints counts Prometheus range-query samples, not hours. With the default queryStep: 5m, minimumDataPoints: 48 needs about 4 hours of data before recommendations can appear. Lower it for faster evaluation, or raise it for more confidence.

Quick evaluation

For a faster first look (~1 hour instead of ~4 hours), set minimumDataPoints: 12 in your policy:

spec:
  metricsSource:
    prometheus:
      address: http://prometheus-server.monitoring:80
    minimumDataPoints: 12    # ~1 hour at the default queryStep: 5m

After validating that recommendations look reasonable, remove minimumDataPoints to use the default (48) for production accuracy.

Most defaultable fields are applied by the controller at reconcile time so that AttuneDefaults and AttuneNamespaceDefaults can override them. That means omitted fields may still look empty in kubectl get attunepolicy -o yaml even though the policy is already following the built-in and inherited runtime behavior unless you override those fields. Use kubectl attune explain -n <namespace> <policy> to inspect the effective values for the key controller-applied defaults.

After enough data has accumulated:

NAME     TYPE        WORKLOADS   RECS   RESIZED   READY   AGE   CPU SAVED   MEM SAVED
my-app   Recommend   1           1      0         True    7d    200m        256Mi

3. Review recommendations

kubectl get attunepolicy my-app -o jsonpath='{.status.recommendations}' | jq .

The output shows per-container current and recommended values along with the confidence score and data-point count. See Recommend Mode for details on interpreting these fields.

4. Upgrade to Canary mode

Once you are happy with the recommendations, switch the policy to Canary mode. This resizes a percentage of pods first, observes them, and only proceeds if they remain healthy.

spec:
  cpu:
    maxChangePercent: 50
  memory:
    maxChangePercent: 30
  updateStrategy:
    type: Canary
    canary:
      percentage: 10
      observationPeriod: 30m  # suggested first window; omit for 5m
    cooldown: 2h               # suggested first gap; omit for 1h
    autoRevert: true           # default

kubectl apply -f attunepolicy.yaml

5. Verify the resize

kubectl get attunepolicy my-app

The RESIZED column increments as pods are resized in place. If a safety violation occurs (OOMKill, excessive restarts, pod NotReady, or SLO guardrail breach), the operator auto-reverts the affected pods.

Tip

Watch resize events in real time with kubectl get events --field-selector reason=Resized -w.

Next steps

• Follow the First 30 Days guide for a day-by-day walkthrough from first install to production Auto mode.
• Read Concepts to understand modes, estimators, and safety.
• Set up Prometheus integration with ServiceMonitor, Grafana dashboard, and PrometheusRule alerts.
• Explore the Canary Rollout guide for production best practices.
• For high-replica fleets, read Scaling (default PromQL podAggregation: Max and large-fleet operator flags).