{
    "slug": "rolling_deployment",
    "term": "Rolling Deployment",
    "category": "devops",
    "difficulty": "intermediate",
    "short": "Gradually replacing old application instances with new ones, a few at a time, so the service remains available throughout the upgrade.",
    "long": "A rolling deployment updates servers sequentially — draining a server of active connections, deploying the new version, verifying health, then moving to the next. At any point during the rollout, both old and new versions serve traffic simultaneously. This means: database migrations must be backward compatible with both versions, API contracts must not have breaking changes, and feature flags may be needed to gate new behaviour. Rolling deployments are simpler than blue/green (no duplicate infrastructure) but slower to roll back — you must roll forward through the remaining servers or trigger a reverse rolling update. Kubernetes performs rolling updates natively via Deployment resources.",
    "aliases": [
        "rolling update",
        "rolling deploy",
        "gradual rollout"
    ],
    "tags": [
        "devops",
        "deployment",
        "zero-downtime"
    ],
    "misconception": "Rolling deployments are always safer than blue-green. Rolling updates expose users to mixed versions simultaneously — if old and new code are incompatible (e.g. different DB schema expectations), some requests will fail during the rollout window. Blue-green avoids this by cutting over atomically.",
    "why_it_matters": "Rolling deployments update servers one by one rather than all at once — at any point, some servers run the old version and some the new, providing gradual rollout without a full traffic cutover.",
    "common_mistakes": [
        "Database migrations that break the old code version — both versions run simultaneously during a rolling deploy.",
        "Not handling mixed-version traffic in the application — old and new API contracts must coexist during rollout.",
        "Rolling too fast — updating all servers before monitoring shows the new version is healthy.",
        "No rollback plan — if the new version has issues, rolling back means going through the same process in reverse."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "blue_green_deployment",
        "canary_release",
        "database_migrations",
        "health_check"
    ],
    "prerequisites": [
        "zero_downtime_deploy",
        "kubernetes_basics",
        "canary_deployment"
    ],
    "refs": [
        "https://kubernetes.io/docs/tutorials/kubernetes-basics/update/update-intro/"
    ],
    "bad_code": "# Rolling deploy with breaking DB migration — causes errors:\n# Step 1: Run migration that renames column 'user_name' to 'username'\n# Step 2: Start deploying new code that uses 'username'\n# Step 3: Old code still running on 50% of servers uses 'user_name' — errors!\n# Fix: expand-contract — add 'username', dual-write, then remove 'user_name'",
    "good_code": "# Kubernetes — rolling update (default strategy)\napiVersion: apps/v1\nkind: Deployment\nspec:\n  replicas: 4\n  strategy:\n    type: RollingUpdate\n    rollingUpdate:\n      maxUnavailable: 1   # at most 1 pod down at a time\n      maxSurge: 1         # at most 1 extra pod above replica count\n  template:\n    spec:\n      containers:\n      - name: app\n        image: myapp:v2.5.0  # change this to trigger rolling update\n        readinessProbe:\n          httpGet: { path: /health, port: 9000 }\n          # pod only receives traffic once /health returns 200\n\n# kubectl rollout status deployment/myapp\n# kubectl rollout undo deployment/myapp   ← instant rollback",
    "quick_fix": "Configure Kubernetes rolling updates with maxUnavailable: 0 and maxSurge: 1 — this brings up one new PHP pod before terminating an old one, ensuring zero downtime",
    "severity": "medium",
    "effort": "medium",
    "created": "2026-03-15",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/rolling_deployment",
        "html_url": "https://codeclaritylab.com/glossary/rolling_deployment",
        "json_url": "https://codeclaritylab.com/glossary/rolling_deployment.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[Rolling Deployment](https://codeclaritylab.com/glossary/rolling_deployment) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/rolling_deployment"
            }
        }
    }
}