Skip to main content

ROLL OUT A NEW IMAGE TO A KUBERNETES DEPLOYMENT

This guide shows you how to move a Kubernetes deployment to a new container image, confirm that the rollout finished, and return to the previous image if it fails. The examples use the storefront deployment in the shop namespace on the prod-cluster context.

Prerequisites

  • A kubeconfig with a prod-cluster context that can read and update deployments in the shop namespace
  • A Swamp repository

Pull the extension

swamp extension pull @swamp/kubernetes

You will see output like:

INF extension·pull: Pulling "@swamp/kubernetes"@"2026.10.13.1"
INF extension·pull: Identity verified: "@swamp/kubernetes"@"2026.10.13.1"
INF extension·pull: Pulled "@swamp/kubernetes"@"2026.10.13.1"
INF extension·pull: Extracted 50 files:

Use a deployment behavior for the namespace

The steps below use a behavior named shop-deployments of type @swamp/kubernetes/deployment. If you do not have one, create it as described in Create and Run a Behavior, with these global arguments:

globalArguments:
  namespace: shop
  context: prod-cluster

To target a different namespace for a single run, pass the method's namespace input instead of changing the behavior.

Record the current image

swamp behavior run shop-deployments get --input deploymentName=storefront

This fetches the storefront deployment's full spec and writes it as a deployment resource. Note down the container image tag in it, because you need that tag if you roll back.

Update the image

swamp behavior run shop-deployments update \
    --input deploymentName=storefront \
    --input image=registry.example.com/storefront:1.4.2

This reads the deployment, replaces it with the new container image, and writes the updated deployment resource.

Check the rollout status

swamp behavior run shop-deployments getRolloutStatus --input deploymentName=storefront

This reads the deployment's Available, Progressing and ReplicaFailure conditions and writes them with the deployment resource. If Progressing is still true and Available is false, run the command again after a short wait.

Confirm the new revision

swamp behavior run shop-deployments getReplicaSets --input deploymentName=storefront

This lists the ReplicaSets the deployment owns and writes a replicaSet resource for each, with replica counts and revision number. When the rollout has finished, the newest revision holds the ready replicas.

Roll back if the rollout fails

If getRolloutStatus reports a ReplicaFailure condition, set the image back to the tag you noted earlier:

swamp behavior run shop-deployments update \
    --input deploymentName=storefront \
    --input image=registry.example.com/storefront:1.4.1

This replaces the deployment with the previous container image and writes the updated deployment resource. Then run getRolloutStatus again to confirm that the old revision is available.

The Kubernetes extensions reference lists every deployment method and its inputs.