Skip to content


Latest release License python-checks e2e-checks image-build

ImageSwap Mutating Admission Controller for Kubernetes

The ImageSwap webhook enables you to define one or more mappings to automatically swap image definitions within Kubernetes Pods with a different registry. This is useful to easily transition from external to internal image registries, work around rate limiting issues, or to maintain consistency with manifests in environments that are airgapped and unable to access commonly used image registries (DockerHub, Quay, GCR, etc.)

An existing image:


can be swapped to:


Find version/environment specific notices and information here



You can use the following command to install ImageSwap from this repo with sane defaults

NOTE: The quickstart installation is not meant for production use. Please read through the Cautions sections, and as always, use your best judgement when configuring ImageSwap for production scenarios.

$ kubectl apply -f

This will do the following

  • Create the imageswap-system namespace
  • Create cluster and namespace scoped roles/rolebindings
  • Deploy the ImageSwap workload and related configs

Once this is complete you can do the following to test

Create and label a test namespace

$ kubectl create ns test1
$ kubectl label ns test1

Deploy some test workloads

# These examples assume you're in the root directory of this repo
# Example with without expected prefix

$ kubectl apply -f ./testing/deployments/test-deploy01.yaml -n test1

# Example with expected prefix

$ kubectl apply -f ./testing/deployments/test-deploy02.yaml -n test1