Quickstart

This guide walks you from nothing to your first automated canary deployment in under 10 minutes.

1. Install the controller

Kubestead runs as a Kubernetes operator in your cluster. Install with:

terminal

$ kubectl apply -f https://install.kubestead.com/controller/v0.9.4/kubestead-controller.yaml
namespace/kubestead-system created
customresourcedefinition.apiextensions.k8s.io/rolloutpolicies.kubestead.io created
serviceaccount/kubestead-controller created
clusterrole.rbac.authorization.k8s.io/kubestead-controller created
deployment.apps/kubestead-controller created
+ kubestead-controller is running (1/1 ready)

Verify the controller is running:

terminal

$ kubectl get pods -n kubestead-system
NAME                                    READY   STATUS    RESTARTS   AGE
kubestead-controller-7d8b9f6c4-xq2rp    1/1     Running   0          23s

2. Write your first RolloutPolicy

Create a rolloutpolicy.yaml for your deployment:

rolloutpolicy.yaml

apiVersion: kubestead.io/v1alpha1
kind: RolloutPolicy
metadata:
  name: payments-canary
  namespace: production
spec:
  targetDeployment: payments-service
  metricSource:
    prometheus:
      url: http://prometheus.monitoring:9090
  steps:
    - trafficPercent: 10
      soakMinutes: 5
      gate:
        query: rate(http_errors_total{job="payments"}[2m])
        threshold: 0.02
    - trafficPercent: 30
      soakMinutes: 10
    - trafficPercent: 100
  onFailure:
    action: rollback
    notify:
      slack: "#deploys-alerts"

Apply it:

terminal

$ kubectl apply -f rolloutpolicy.yaml
rolloutpolicy.kubestead.io/payments-canary created

3. Connect your metrics source

Kubestead supports Prometheus, Datadog, New Relic, VictoriaMetrics, and InfluxDB as metric sources. See the metrics reference for full configuration options.

Kubestead reads from your existing metrics endpoint — no additional agents or data pipelines required. It only needs read access to query your existing metric data.

4. GitOps mode (Argo CD / Flux CD)

Commit your rolloutpolicy.yaml alongside your service manifests. Argo CD and Flux CD will sync it into the cluster automatically. The policy is version-controlled and code-reviewed before it takes effect.

5. Notifications

Configure Slack, PagerDuty, or OpsGenie in the spec.onFailure.notify block. Multiple channels can be configured simultaneously. See the notifications reference.

6. Multi-cluster (Team & Platform plans)

Connect additional clusters via the Kubestead web UI. Each cluster runs its own controller; the Kubestead cloud aggregates rollout history and notifications across all clusters.

Docs Overview RolloutPolicy Reference