Kubernetes deployment pipeline
Build, push, rolling update, and rollback on failed probes.
Every team that runs Kubernetes has this pipeline, but few have it drawn — so when a deploy wedges at 2 a.m., the on-call engineer reconstructs it from CI logs instead of reading it off a diagram. This template fixes that. It follows a change from merge to main through image build, registry push, and manifest update, into the rolling update where the real decision happens: readiness probes pass and traffic shifts to new pods while old ones scale down, or probes fail and the deployment rolls back to the previous revision and pages on-call.
The probe gate is the heart of the diagram. Everything before it is plumbing; everything after it is the difference between a routine deploy and an incident.
When to use this template
- CI/CD documentation — give every engineer the same mental model of what happens between "merged" and "live", including the automated rollback path.
- Incident response — during a bad deploy, the diagram tells on-call exactly which stage failed and what the system should have done about it.
- Platform onboarding — new team members learn the deploy lifecycle, the role of readiness probes, and why rollbacks are automatic, all in one view.
How to adapt it
Match the nodes to your actual toolchain, then add your safeguards:
- Insert test and image-scan stages between build and push so quality gates appear in the same picture as deployment gates.
- Add a staging environment with smoke tests before the production apply, or replace the rolling update with your canary or blue-green strategy.
- Extend the rollback branch with automated diagnostics — capture pod logs and events before alerting, so on-call starts with context.
Visual edits regenerate clean Mermaid code, so the adapted pipeline pastes straight into your platform docs or repository README.
Mermaid code
Copy it anywhere Mermaid is supported — GitHub, Notion, or your docs.
flowchart LR
A[Merge to main] --> B[Build container image]
B --> C[Push to registry]
C --> D[Update manifest tag]
D --> E[Apply to cluster]
E --> F[Rolling update starts]
F --> G{Readiness probes pass?}
G -->|Yes| H[Shift traffic to new pods]
H --> I[Scale down old pods]
G -->|No| J[Rollback to previous revision]
J --> K[Alert on-call]
Frequently asked questions
- What are the stages of a Kubernetes deployment pipeline?
- Merge to main triggers an image build, the image is pushed to a registry, the manifest's image tag is updated, the change is applied to the cluster, and a rolling update replaces pods gradually. The critical gate is the readiness probe: pass and traffic shifts to new pods, fail and the deployment rolls back to the previous revision.
- How does a rolling update decide whether to proceed or roll back?
- Kubernetes only routes traffic to pods whose readiness probes pass, and a deployment whose new pods never become ready stalls against its progress deadline. This diagram makes that gate explicit as a decision node — healthy pods get traffic and old pods scale down; unhealthy ones trigger a rollback to the previous ReplicaSet and an on-call alert.
- Does this pipeline work with GitOps tools like Argo CD or Flux?
- Yes, with one change: instead of the CI job applying manifests directly, it commits the updated tag to a config repo and the GitOps controller applies it by reconciliation. The build, push, rolling update, probe gate, and rollback stages are identical — just insert a "GitOps controller syncs" node between the manifest update and the cluster.
- What should I add to this template for production-grade deployments?
- Common additions: image scanning and tests between build and push, a staging deployment with smoke tests before production, canary or blue-green steps instead of a plain rolling update, and post-deploy metric checks that can also trigger the rollback path. Add them visually and the editor regenerates clean Mermaid code for your CI docs.