| name | ci-cd-gitops-kubernetes |
| description | Apply Kubernetes deployment and GitOps patterns when configuring container orchestration, deployment strategies (rolling, blue-green, canary), ArgoCD/Flux manifests, or Kubernetes secrets management. Supplement to ci-cd-principles. |
| user-invocable | false |
CI/CD — GitOps and Kubernetes Deployment
Agent scope: This is a supplement to ci-cd-principles.md (Level 2).
Apply only when the project targets Kubernetes or a Kubernetes-based managed platform.
Do not apply rolling/canary/blue-green patterns to Docker Compose or serverless deployments.
Choosing a Deployment Strategy
| Strategy | When to use | Trade-off |
|---|
| Rolling | Default for most services; SLO requirements | Simple, but mixes versions briefly |
| Blue-Green | Zero-downtime with instant rollback | Doubles infrastructure cost during switch |
| Canary | Risk-reducing incremental rollout; A/B variants | Requires traffic splitting capability |
Rolling Deployment (Default)
Kubernetes native. Suitable for most stateless services.
strategy:
type: RollingUpdate
rollingUpdate:
maxSurge: 25%
maxUnavailable: 0%
Rules:
- Set
maxUnavailable: 0 for production services with SLO requirements
- Set
minReadySeconds to let pods stabilize before proceeding
- Configure
terminationGracePeriodSeconds to finish in-flight requests before shutdown
Blue-Green Deployment
When: Zero-downtime deployments where rollback must be instant and clean.
┌──────────────┐ ┌──────────────┐
│ Blue (v1) │ │ Green (v2) │
│ [LIVE 100%] │────→│ [STANDBY] │
└──────────────┘ └──────────────┘
↕ Switch load balancer
┌──────────────┐ ┌──────────────┐
│ Blue (v1) │ │ Green (v2) │
│ [STANDBY] │ │ [LIVE 100%] │
└──────────────┘ └──────────────┘
Rules:
- Both environments must be identical in infrastructure
- Run smoke tests against green before switching traffic
- Keep blue alive for at least 30 minutes post-switch (fast rollback window)
- Database migrations must be backward-compatible (blue still runs against the same DB)
Canary Deployment
When: Risk-reducing incremental rollout; A/B testing deployment variants.
Traffic split during rollout:
5% → canary (v2)
95% → stable (v1)
↓ metrics look good
25% → canary
75% → stable
↓ bake time passes
100% → canary (now stable)
Rules:
- Define success metrics before starting rollout (error rate, latency SLO)
- Set automatic rollback threshold: if canary error rate > 2× baseline → auto-rollback
- Minimum bake time per traffic increment: 15–30 minutes
- Feature flags complement canary routing for functional (not just traffic) testing
GitOps Pattern
For Kubernetes environments, use declarative GitOps instead of imperative kubectl apply.
Pattern:
Application Repo (code) → CI builds image → updates tag in Config Repo
Config Repo (K8s manifests) → ArgoCD/Flux syncs to cluster automatically
Rules:
- Git is the single source of truth for cluster state
- All changes to production go through PRs on the config repo — no direct
kubectl in prod
- ArgoCD/Flux continuously reconciles — any manual drift is auto-corrected
- Secrets reference external secret stores — never plaintext in git
Example ArgoCD Application
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: myapp-production
spec:
source:
repoURL: https://github.com/org/config-repo
path: environments/production/myapp
targetRevision: HEAD
destination:
server: https://kubernetes.default.svc
namespace: production
syncPolicy:
automated:
prune: true
selfHeal: true
Secrets Management in Kubernetes
Never store plaintext secrets in git — even in private repositories.
| Tool | Pattern |
|---|
| External Secrets Operator | Syncs secrets from AWS Secrets Manager, GCP Secret Manager, Vault into K8s Secrets |
| Sealed Secrets | Encrypts secrets with a cluster-held key; safe to commit encrypted form |
| Vault Agent Injector | Sidecars inject secrets directly into pods at runtime |
Choose based on your cloud provider or existing tooling. Document the choice in your
technical architecture document.
Kubernetes CI/CD Checklist
Related Principles
- CI/CD Principles @.claude/skills/ci-cd-principles/SKILL.md (core pipeline — read first)
- Security Principles @.claude/rules/security-principles.md (secrets management)
- Monitoring and Alerting Principles @.claude/skills/monitoring-and-alerting-principles/SKILL.md (canary success metrics)
- Feature Flags @.claude/skills/feature-flags-principles/SKILL.md (canary + feature flag interaction)