Pulumi Kubernetes Operator: Rolling out changes

The Stack object supports safe rollouts with prerequisites and preview mode.

Stage rollouts across environments

To roll a change through deployment stages, use spec.prerequisites. A Stack with a prerequisite waits for the referenced stack to reach a successful state before it runs. This enforces stage order declaratively, without manual sequencing.

In the following example, dev tracks the main branch and deploys every merge, while test and prod pin an immutable commit so they change only when that commit is promoted through a reviewed pull request.

apiVersion: pulumi.com/v1
kind: Stack
metadata:
  name: app-dev
spec:
  # ...stack configuration...
  branch: main            # dev tracks main and deploys every merge
---
apiVersion: pulumi.com/v1
kind: Stack
metadata:
  name: app-test
spec:
  # ...stack configuration...
  commit: 03658b5514f08970f350618a6e6fdf1bd75f45d0   # the candidate commit
  prerequisites:
  - name: app-dev
    requirement:
      succeededWithinDuration: "1h"
---
apiVersion: pulumi.com/v1
kind: Stack
metadata:
  name: app-prod
spec:
  # ...stack configuration...
  commit: 03658b5514f08970f350618a6e6fdf1bd75f45d0   # promoted only after test is green
  prerequisites:
  - name: app-test
    requirement:
      succeededWithinDuration: "1h"

The optional requirement.succeededWithinDuration sets a freshness window on the prerequisite: with "1h", its last successful run must have completed within the last hour. If it’s older, the operator re-syncs the prerequisite and waits for it to succeed again before the dependent stack proceeds.

Advancing the pinned commit on app-test and app-prod in a reviewed pull request then rolls the change out in order: test deploys first, and prod follows only once test is green.

To preview a change before promoting it, use preview mode; the preview-demo example shows one setup.

Verify application health

The operator gates on whether a deployment succeeded, not on whether the deployed application is healthy. To check that traffic and error rates look normal after a rollout, combine it with a progressive-delivery tool such as Argo Rollouts or Flagger.

Learn more

• Defining stacks — configure a Stack’s Git source, including spec.commit and spec.branch.
• Stack operations — drift detection, state refresh, prerequisites, external triggers, and preview mode.
• Argo CD with Pulumi Kubernetes Operator — a trunk-based GitOps workflow, preview environments, and sync waves.