Migrations

As engineering teams grow and evolve over time, the software supply chain can become fragmented, with different standards adopted across teams. This makes it difficult to manage ongoing remediation work because sources, registries, and implementations differ between teams.

BIMP can help you consolidate your base image lifecycle around your approved base image providers and secured private registries.

Reasons to migrate

• Switch image providers to improve remediation SLAs.
• Reduce the size of base images and their attack surface.
• Meet compliance requirements such as FIPS.
• Migrate to a hardened image catalog.
• Migrate to a distroless image catalog.
• Control software ingestion through a private registry.

Preparation

Before creating migration policy, establish your current position and agree on the standards you want every team to follow.

1. Understand your inventory. Identify the base images, image providers, registries, tags, and digests currently used across your repositories. Note where teams use different sources for equivalent workloads.
2. Choose your approved image providers. Decide which providers and image catalogues meet your security, support, compatibility, and maintenance requirements. These providers define the destinations for your migration mappings.
3. Agree on a registry policy. Decide whether teams must mirror images into private registries or may reference approved public registries directly. Record the public and private registries your organization approves.
4. Review the proposed impact. Open Reports and use Digest inventory to understand tag-only and digest-pinned references. Use Organization base images detected to review current images, repository reach, and policy state before finalizing the migration.

Create Policy Groups

Represent each migration as a normal image mapping in a Policy Group. For detailed instructions on creating, scoping, reviewing, and publishing Policy Groups, see Policy Management.

We recommend moving repositories into the migration Policy Group in a controlled way. When the migration is complete, you can add the new image references to your baseline policies.

For each migration:

1. use the current image reference as the From image;
2. use the approved destination as the exact Target image;
3. record the reason for the migration;
4. add a second phase to your Policy Group to manage incremental updates to your new image catalog.

Examples

Migrate image provider

This example shows how you can map a Docker Official Image to the corresponding Docker Hardened Image:

• From image: docker.io/library/python:3.14
• Target image: dhi.io/python:3.14

Migrate to a private registry

This example shows how you can map a public Docker image to a private image hosted in Cloudsmith:

• From image: docker.io/library/python:3.12
• Target image: docker.cloudsmith.io/<owner>/<repository>/python:3.12

Migrate image provider and move to a private registry

This example shows how you can map a Docker Official Image on Docker Hub to a Red Hat image hosted in an approved Artifactory registry:

• From image: docker.io/library/python:3.12
• Target image: <company>.jfrog.io/<repository-key>/ubi9/python-312:latest

Migration readiness

Migrate repositories in a controlled way by moving them into the new Policy Group. Ensure teams are ready to migrate before you make the change.

1. Are the base images available in the new registry?
2. Does the CI/CD system have access to pull the new images?
3. Is test coverage sufficient to catch any issues?

Migrate to a distroless image

Image providers such as Chainguard and Minimus require additional changes to the Dockerfile that BIMP does not currently support.

See the Chainguard Dockerfile migration guide.

See the Minimus distroless migration guide.

Note: Dockerfile migrations for Chainguard and Minimus are currently on our roadmap. If you would like to become a design partner for this feature, contact us at hello@bimp.ai.

Use a multi-phase policy

Multi-phase policies are useful for migration scenarios where you want to manage the initial mappings separately from incremental updates to the future catalog.

1. Phase 1 maps existing images to a target image.
2. Phase 2 maps the original target image to subsequent updates.

Using two phases results in a remediation pull request that resolves to the most up-to-date image from the new catalog.

You can use an external mapping for Phase 2 to automate future updates as part of your image ingestion and approval pipeline.