Skip to content

dhi: update mirroring example #22879

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+29 −33
Open

dhi: update mirroring example #22879

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 29 additions & 33 deletions content/manuals/dhi/how-to/mirror.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -129,50 +129,46 @@
registry, such as Amazon ECR, Google Artifact Registry, GitHub Container
Registry, or a private Harbor instance.

You can use any standard workflow, including:
You can use any standard workflow to mirror the image, such as the
[Docker CLI](/reference/cli/docker/_index.md), [Docker Hub Registry
API](/reference/api/registry/latest/), third-party registry tools, or CI/CD

Check warning on line 134 in content/manuals/dhi/how-to/mirror.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Docker.Acronyms] 'CD' has no definition.

Raw Output:
{"message": "[Docker.Acronyms] 'CD' has no definition.", "location": {"path": "content/manuals/dhi/how-to/mirror.md", "range": {"start": {"line": 134, "column": 74}}}, "severity": "WARNING"}
automation.

- [The Docker CLI](/reference/cli/docker/_index.md)
- [The Docker Hub Registry API](/reference/api/registry/latest/)
- Third-party registry tools or CI/CD automation
However, to preserve the full security context, including signatures and
attestations, you must also copy its associated OCI artifacts. Docker
Hardened Images store the image layers on Docker Hub (`docker.io`) and the
signed attestations in a separate registry (`registry.scout.docker.com`).

The following example shows how to use the Docker CLI to pull a mirrored DHI and
push it to another registry:
To copy both, you can use [regctl](https://regclient.org/cli/regctl/), an

Check failure on line 142 in content/manuals/dhi/how-to/mirror.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'regctl'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'regctl'?", "location": {"path": "content/manuals/dhi/how-to/mirror.md", "range": {"start": {"line": 142, "column": 28}}}, "severity": "ERROR"}
OCI-aware CLI that supports mirroring images along with attached artifacts such
as SBOMs, vulnerability reports, and SLSA provenance.

```console
# Authenticate to Docker Hub (if not already signed in)
$ docker login

# Pull the image from your organization's namespace on Docker Hub
$ docker pull <your-namespace>/dhi-<image>:<tag>

# Tag the image for your destination registry
$ docker tag <your-namespace>/dhi-<image>:<tag> registry.example.com/my-project/<image>:<tag>
The following example uses `regctl` to mirror a DHI and then its attestations to a
private registry:

# Push the image to the destination registry
# You will need to authenticate to the third-party registry before pushing
$ docker push registry.example.com/my-project/<image>:<tag>
```console
$ regctl \
--host "reg=docker.io,user=$DOCKER_USERNAME,pass=$DOCKER_PASSWORD_OR_PAT" \
--host "reg=registry.example.com" \
image copy \
docker.io/docs/dhi-python@sha256:25c9... \
my-registry.example.com/mirror/dhi-python@sha256:25c9...

$ regctl \
--host "reg=registry.scout.docker.com,user=$DOCKER_USERNAME,pass=$DOCKER_PASSWORD_OR_PAT" \
--host "reg=registry.example.com" \
image copy --referrers \
registry.scout.docker.com/docs/dhi-python@sha256:25c9... \
my-registry.example.com/mirror/dhi-python@sha256:25c9...
```

This mirrors both the image and its associated attestations to a private OCI-compatible registry.

> [!IMPORTANT]
>
> To continue receiving image updates and preserve access to Docker Hardened
> Images, ensure that any copies pushed to other registries remain private.

### Include attestations when mirroring images

Docker Hardened Images are signed and include associated attestations that
provide metadata such as build provenance and vulnerability scan results. These
attestations are stored as OCI artifacts and are not included by default when
using the Docker CLI to mirror images.

To preserve the full security context when copying DHIs to another registry, you
must explicitly include the attestations. One tool is `regctl`, which supports
copying both images and their associated artifacts.

For more details on how to use `regctl` to copy images and their associated
artifacts, see the [regclient
documentation](https://regclient.org/cli/regctl/image/copy/).

## What's next

After mirroring an image repository, you can you can start [using the
Expand Down