Skip to main content
This page shows how to build a CockroachDB Docker image that includes operating system (OS) package updates released after Cockroach Labs published the image. Each CockroachDB Docker image includes the latest OS packages that were available when the release was published. Fixes that the OS vendor releases later reach the official images with the next CockroachDB patch release. To pick up a fix sooner, for example when a vulnerability scanner reports a fixable vulnerability in an OS package, build an image on top of the official image and upgrade its packages. This is the same step Cockroach Labs runs when it publishes an image. The rebuilt image contains the same CockroachDB binary as the official image; only the OS packages change. CockroachDB Docker images are available in the following variants: The -noble image is available starting in v25.4.17. Experimental images are not qualified for production use and not eligible for support or uptime SLA commitments.
Avoid upgrading packages inside running containers. Changes made to a running container are lost when the container is recreated, are not visible to scanners that inspect the image in your registry, and can leave nodes running different package versions.

​
Before you begin

  • Install Docker. To build images for more than one platform, you also need Docker Buildx.
  • Make sure the build host can reach Docker Hub and the OS vendor’s package repositories: the Red Hat UBI repositories for the default image, or the Ubuntu archive for the -noble image.
  • Have access to a container registry where you can push the rebuilt image.

​
Step 1. Create a Dockerfile

Create a directory for the build, and in it create a file named Dockerfile with the contents for the image variant you use.

​
Default (UBI) images

For the default image and the FIPS-ready image, create the following Dockerfile:
Replace {tag} with the tag of the image to update, for example v25.4.17 or v25.4.17-fips. If microdnf fails with a dependency error, the Red Hat UBI package repositories are probably partway through publishing an update, and some related packages are not available yet. Retry the build later.
In v25.4, the uses the Red Hat OpenSSL libraries installed in the image for cryptographic operations, so the upgrade installs a newer OpenSSL package when Red Hat has released one. Cockroach Labs runs the same upgrade when it publishes the FIPS-ready image. After you build the image, you can check its OpenSSL version by running docker run --rm --entrypoint rpm {image} -q openssl openssl-libs.

​
-noble images

For the -noble image, create the following Dockerfile:
Replace {version} with the CockroachDB version of the image to update, for example v25.4.17.
To make the build reproducible, reference the base image by its digest rather than only by its tag, for example FROM cockroachdb/cockroach:v25.4.17@sha256:{digest}. To look up the digest of an image, run docker buildx imagetools inspect cockroachdb/cockroach:{tag}.

​
Step 2. Build the image

To build the image for the platform of the build host, run the following command from the directory that contains the Dockerfile:
Replace {image} with the registry, repository, and tag for the rebuilt image, for example registry.example.com/cockroach:v25.4.17-20261006. Cockroach Labs recommends giving each rebuild a new tag rather than reusing a tag, so that you can tell rebuilt images apart and roll back to an earlier one. The --no-cache flag is required. Without it, Docker can reuse the package upgrade layer from an earlier build, and the image does not receive packages released since then. The --load flag makes the image available to the local Docker engine for the next steps, including when the build runs in a separate builder container. To build a multi-platform image, use docker buildx build instead. This command pushes the image to your registry directly, so skip Step 4:
Replace {platforms} with a comma-separated list of the platforms you deploy on. The default image is available for linux/amd64 and linux/arm64. The FIPS-ready image is available for linux/amd64. The -noble image is available for linux/amd64 and linux/arm64. Building for a platform other than the build host’s requires emulation or a multi-node builder. Refer to Multi-platform builds in the Docker documentation.

​
Step 3. Verify the image

To confirm that the rebuilt image starts and contains the expected CockroachDB version, run:
The output includes the following:
The Build Tag value must match the CockroachDB version of the image you updated. Then scan the rebuilt image with your vulnerability scanner to confirm that the packages were updated.

​
Step 4. Push the image

To push the rebuilt image to your registry, run:

​
Step 5. Deploy the image

Replace the official image with the rebuilt image in your deployment configuration, such as the image field of your Kubernetes manifest or your container runtime’s run command. Because the CockroachDB version does not change, no or finalization is involved. Restart one node at a time on the new image so that the cluster remains available. Refer to .

​
See also