diff --git a/content/manuals/dhi/how-to/_index.md b/content/manuals/dhi/how-to/_index.md index ee04a6de5bc..a4be1ea1666 100644 --- a/content/manuals/dhi/how-to/_index.md +++ b/content/manuals/dhi/how-to/_index.md @@ -2,6 +2,8 @@ title: How-tos description: Step-by-step guidance for working with Docker Hardened Images, from discovery to debugging. weight: 20 +aliases: + - /dhi/how-to/manage/ params: grid_discover: - title: Search and evaluate Docker Hardened Images @@ -45,10 +47,6 @@ params: description: Learn how to use Extended Lifecycle Support with Docker Hardened Images. icon: update link: /dhi/how-to/els/ - - title: Manage Docker Hardened Images and charts - description: Learn how to manage your mirrored and customized Docker Hardened Images in your organization. - icon: reorder - link: /dhi/how-to/manage/ grid_verify: - title: Verify a Docker Hardened Image or chart description: Use Docker Scout or cosign to verify signed attestations like SBOMs, provenance, and vulnerability data for Docker Hardened Images and charts. diff --git a/content/manuals/dhi/how-to/customize.md b/content/manuals/dhi/how-to/customize.md index 82aa14b154b..e8cf2facb49 100644 --- a/content/manuals/dhi/how-to/customize.md +++ b/content/manuals/dhi/how-to/customize.md @@ -14,7 +14,6 @@ Hub web interface. For images, this lets you select a base image, add packages, add OCI artifacts (such as custom certificates or additional tools), and configure settings. For charts, this lets you customize the image references. - Your customizations stay secure automatically. When the base Docker Hardened Image or chart receives a security patch or your OCI artifacts are updated, Docker automatically rebuilds your customizations in the background. This @@ -32,35 +31,8 @@ mirrored DHI repository can create a customized image. You can create customizations using either the DHI CLI or the Docker Hub web interface. -### Customize using the DHI CLI - -The DHI CLI provides a command-line interface for managing Docker Hardened Image -customizations. For installation instructions and usage details, see [Use -the DHI CLI](./cli.md#customize-dhi-images). - -#### Monitor customization builds - -List builds for a customization: - -```console -$ docker dhi customization build list --org my-org my-org/dhi-golang "golang with git" -``` - -Get details of a specific build: - -```console -$ docker dhi customization build get --org my-org my-org/dhi-golang "golang with git" -``` - -View build logs: - -```console -$ docker dhi customization build logs --org my-org my-org/dhi-golang "golang with git" -``` - -### Customize using the Docker Hub web interface - -To customize a Docker Hardened Image using the web interface, follow these steps: +{{< tabs >}} +{{< tab name="Docker Hub" >}} 1. Sign in to [Docker Hub](https://hub.docker.com). 1. Select **My Hub**. @@ -158,6 +130,86 @@ To customize a Docker Hardened Image using the web interface, follow these steps to build. Once built, it will appear in the **Tags** tab of the repository, and your team members can pull it like any other image. +{{< /tab >}} +{{< tab name="CLI" >}} + +Authenticate with `docker login` using your Docker credentials or a [personal +access token (PAT)](../../security/access-tokens.md) with **Read & Write** +permissions. [Organization access tokens +(OATs)](../../enterprise/security/access-tokens.md) are not supported. + +Use the [`docker dhi customization`](/reference/cli/docker/dhi/customization/) command: + +```console +# Prepare a customization scaffold +$ docker dhi customization prepare golang 1.25 \ + --org my-org \ + --destination my-org/dhi-golang \ + --name "golang with git" \ + --output my-customization.yaml + +# Create a customization +$ docker dhi customization create my-customization.yaml --org my-org + +# List customizations +$ docker dhi customization list --org my-org + +# Filter customizations by name, repository, or source +$ docker dhi customization list --org my-org --filter git +$ docker dhi customization list --org my-org --repo dhi-golang +$ docker dhi customization list --org my-org --source golang + +# Get a customization +$ docker dhi customization get my-org/dhi-golang "golang with git" --org my-org --output my-customization.yaml + +# Update a customization +$ docker dhi customization edit my-customization.yaml --org my-org + +# Delete a customization +$ docker dhi customization delete my-org/dhi-golang "golang with git" --org my-org + +# Delete without confirmation prompt +$ docker dhi customization delete my-org/dhi-golang "golang with git" --org my-org --yes +``` + +{{< /tab >}} +{{< /tabs >}} + +### Monitor customization builds + +{{< tabs >}} +{{< tab name="Docker Hub" >}} + +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select **My Hub**. +3. In the namespace drop-down, select your organization. +4. Select **Hardened Images** > **Manage**. +5. Select the **Customizations** tab. + +{{< /tab >}} +{{< tab name="CLI" >}} + +List builds for a customization: + +```console +$ docker dhi customization build list my-org/dhi-golang "golang with git" --org my-org +``` + +Get details of a specific build: + +```console +$ docker dhi customization build get my-org/dhi-golang "golang with git" --org my-org +``` + +View build logs: + +```console +$ docker dhi customization build logs my-org/dhi-golang "golang with git" --org my-org +``` + +{{< /tab >}} +{{< /tabs >}} + ### Create an OCI artifact image for image customization An OCI artifact image is a Docker image that contains files or directories that diff --git a/content/manuals/dhi/how-to/els.md b/content/manuals/dhi/how-to/els.md index 930920b8a98..9c3f2f73022 100644 --- a/content/manuals/dhi/how-to/els.md +++ b/content/manuals/dhi/how-to/els.md @@ -55,8 +55,3 @@ To update settings: 4. Select **Repositories** and then select the mirrored repository. 5. Select the **Settings** tab. 6. Uncheck the **Mirror end-of-life images** option. - -## Manage ELS repositories - -You can view and manage your mirrored repositories with ELS like any other -mirrored DHI repository. For more details, see [Manage images](./manage.md). \ No newline at end of file diff --git a/content/manuals/dhi/how-to/manage.md b/content/manuals/dhi/how-to/manage.md deleted file mode 100644 index 1a02cf22fa1..00000000000 --- a/content/manuals/dhi/how-to/manage.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Manage Docker Hardened Images and charts -linktitle: Manage images and charts -description: Learn how to manage your mirrored and customized Docker Hardened Images in your organization. -keywords: manage docker hardened images, custom hardened images -weight: 35 ---- - -{{< summary-bar feature_name="Docker Hardened Images" >}} - -On the **Manage** screen in Docker Hub, you can manage your mirrored Docker -Hardened Image (DHI) repositories, mirrored DHI chart repositories, and -customizations in your organization. - -Alternatively, you can use the [DHI CLI](./cli.md) to manage mirrored -repositories and customizations from the command line. - -Mirrored DHI repositories are standard Docker Hub repositories in your -organization's namespace. They behave exactly like any other Hub repository, -which means you can manage access and permissions, configure webhooks, and use -other standard Hub features. See [Docker Hub -repositories](/manuals/docker-hub/repos/_index.md) for details. The **Manage** -screen provides DHI-specific actions like customizing images and stopping -mirroring. - -## Manage mirrored Docker Hardened Image repositories - -To manage your mirrored DHI repositories: - -1. Go to the [Docker Hub](https://hub.docker.com) and sign in. -2. Select **My Hub**. -3. In the namespace drop-down, select your organization. -4. Select **Hardened Images** > **Manage**. -5. Select **Mirrored Images** -6. Select the menu icon in the far right column of the repository you want to manage. - - From here, you can: - - - **Customize**: Create a customized image based on the source repository. - - **Stop mirroring**: Stop mirroring the DHI repository. - -## Manage customized Docker Hardened Image repositories - -To manage your customized DHI repositories: - -1. Go to [Docker Hub](https://hub.docker.com) and sign in. -2. Select **My Hub**. -3. In the namespace drop-down, select your organization. -4. Select **Hardened Images** > **Manage**. -5. Select **Customizations**. - - On this page, you can view your customized DHI - repositories. - -6. Select the menu icon in the far right column of the repository you want to manage. - - From here, you can: - - - **Edit**: Edit the customized image. - - **Create new**: Create a new customized image based on the source repository. - - **Delete**: Delete the customized image. \ No newline at end of file diff --git a/content/manuals/dhi/how-to/mirror.md b/content/manuals/dhi/how-to/mirror.md index c233ab3d431..12498d6eac7 100644 --- a/content/manuals/dhi/how-to/mirror.md +++ b/content/manuals/dhi/how-to/mirror.md @@ -10,7 +10,8 @@ keywords: mirror docker image, private container registry, docker hub automation Mirroring requires a DHI Select or Enterprise subscription. Without a subscription, you can pull Docker Hardened Images directly from `dhi.io` without -mirroring. With a DHI Select or Enterprise subscription, you must mirror to get: +mirroring. With a DHI Select or Enterprise subscription, you must mirror to your +organization to get: - Compliance variants (FIPS-enabled or STIG-ready images) - Extended Lifecycle Support (ELS) variants (requires add-on) @@ -23,22 +24,17 @@ mirroring. With a DHI Select or Enterprise subscription, you must mirror to get: This topic covers two types of mirroring for Docker Hardened Image (DHI) repositories: -- [Mirror to Docker Hub](#mirror-a-dhi-repository-to-docker-hub): Mirror a DHI - repository to your organization's namespace on Docker Hub. This requires a DHI - Enterprise subscription and is used to [customize an image or - chart](./customize.md) and access compliance variants and ELS variants - (requires add-on). This must be done through the Docker Hub web interface. +- [Mirror to your organization](#mirror-a-dhi-repository-to-your-organization): + Mirror a DHI repository to your organization's namespace on Docker Hub. - [Mirror to a third-party registry](#mirror-a-dhi-repository-to-a-third-party-registry): Mirror a repository to another container registry, such as Amazon ECR, Google Artifact Registry, or a private Harbor instance. -## Mirror a DHI repository to Docker Hub +## Mirror a DHI repository to your organization -Mirroring a repository to Docker Hub requires a DHI Enterprise subscription and -enables access to compliance variants, Extended Lifecycle Support (ELS) variants -(requires add-on), and customization capabilities: +You must be an organization owner or editor to mirror repositories. - Image repositories: Mirroring lets you customize images by adding packages, OCI artifacts (such as custom certificates or additional tools), environment @@ -51,29 +47,8 @@ enables access to compliance variants, Extended Lifecycle Support (ELS) variants reference those custom locations. For more details, see [Customize a Docker Hardened Helm chart](./customize.md#customize-a-docker-hardened-helm-chart). -Only organization owners can perform mirroring. Once mirrored, the repository -becomes available in your organization's namespace, and you can customize it as -needed. - -You can mirror repositories using either the Docker Hub web interface or the DHI CLI. - -### Mirror using the DHI CLI - -The DHI CLI provides a command-line interface for managing Docker Hardened -Images, including mirroring operations. For installation instructions and usage -details, see [Use the DHI CLI](./cli.md#mirror-dhi-images). - -### Stop mirroring with the CLI - -```console -$ docker dhi mirror stop --org my-org dhi-golang -``` - -After stopping mirroring, the repository remains but will no longer receive updates. - -### Mirror using the Docker Hub web interface - -To mirror a Docker Hardened Image repository using the web interface: +{{< tabs >}} +{{< tab name="Docker Hub" >}} 1. Go to [Docker Hub](https://hub.docker.com) and sign in. 2. Select **My Hub**. @@ -88,69 +63,56 @@ To mirror a Docker Hardened Image repository using the web interface: It may take a few minutes for all the tags to finish mirroring. -After mirroring a repository, the repository appears in your organization's -repository list, prefixed by `dhi-`. It will continue to receive updated images. +{{< /tab >}} +{{< tab name="CLI" >}} -Once mirrored, the repository is a standard Docker Hub repository in your -organization's namespace. It behaves exactly like any other Hub repository, -which means you can manage access and permissions, configure webhooks, and use -other standard Hub features. See [Docker Hub -repositories](/manuals/docker-hub/repos/_index.md) for details. - -Additionally, mirrored DHI repositories let you customize images and charts. To -learn more, see [Customize a Docker Hardened Image or chart](./customize.md). +Authenticate with `docker login` using your Docker credentials or a [personal +access token (PAT)](../../security/access-tokens.md) with **Read & Write** +permissions. [Organization access tokens +(OATs)](../../enterprise/security/access-tokens.md) are not supported. -### Webhook integration for syncing and alerts +Use the [`docker dhi mirror`](/reference/cli/docker/dhi/mirror/) command: -To keep external registries or systems in sync with your mirrored Docker -Hardened Images, and to receive notifications when updates occur, you can -configure a [webhook](/docker-hub/repos/manage/webhooks/) on the mirrored -repository in Docker Hub. A webhook sends a `POST` request to a URL you define -whenever a new image tag is pushed or updated. +```console +$ docker dhi mirror start --org my-org \ + -r dhi/golang,my-org/dhi-golang \ + -r dhi/nginx,my-org/dhi-nginx \ + -r dhi/prometheus-chart,my-org/dhi-prometheus-chart +``` -For example, you might configure a webhook to call a CI/CD system at -`https://ci.example.com/hooks/dhi-sync` whenever a new tag is mirrored. The -automation triggered by this webhook can pull the updated image from Docker Hub -and push it to an internal registry such as Amazon ECR, Google Artifact -Registry, or GitHub Container Registry. +Mirror with dependencies: -Other common webhook use cases include: +```console +$ docker dhi mirror start --org my-org -r golang --dependencies +``` -- Triggering validation or vulnerability scanning workflows -- Signing or promoting images -- Sending notifications to downstream systems +List mirrored images in your organization: -#### Example webhook payload +```console +$ docker dhi mirror list --org my-org +``` -When a webhook is triggered, Docker Hub sends a JSON payload like the following: +Filter mirrored images by name or type: -```json -{ - "callback_url": "https://registry.hub.docker.com/u/exampleorg/dhi-python/hook/abc123/", - "push_data": { - "pushed_at": 1712345678, - "pusher": "trustedbuilder", - "tag": "3.13-alpine3.21" - }, - "repository": { - "name": "dhi-python", - "namespace": "exampleorg", - "repo_name": "exampleorg/dhi-python", - "repo_url": "https://hub.docker.com/r/exampleorg/dhi-python", - "is_private": true, - "status": "Active", - ... - } -} +```console +$ docker dhi mirror list --org my-org --filter python +$ docker dhi mirror list --org my-org --type image +$ docker dhi mirror list --org my-org --type helm-chart ``` +{{< /tab >}} +{{< /tabs >}} + +After mirroring, the repository appears in your organization's repository list, +prefixed by `dhi-`, and continues to receive updated images. It behaves like any +other Docker Hub repository, so you can manage access and permissions, configure +webhooks, and use other standard Hub features. See [Docker Hub +repositories](/manuals/docker-hub/repos/_index.md) for details. + ### Stop mirroring a repository -Only organization owners can stop mirroring a repository. After you stop -mirroring, the repository remains, but it will -no longer receive updates. You can still use the last images or charts that were mirrored, -but the repository will not receive new tags or updates from the original -repository. +After you stop mirroring, the repository remains, but it no longer receives +updates. You can still use the last images or charts that were mirrored. > [!NOTE] > @@ -158,7 +120,8 @@ repository. > option in the mirrored repository's **Settings** tab. For more details, see > [Disable ELS for a repository](./els.md#disable-els-for-a-repository). - To stop mirroring a repository: +{{< tabs >}} +{{< tab name="Docker Hub" >}} 1. Go to [Docker Hub](https://hub.docker.com) and sign in. 2. Select **My Hub**. @@ -168,11 +131,28 @@ repository. 6. In the far right column of the repository you want to stop mirroring, select the menu icon. 7. Select **Stop mirroring**. +{{< /tab >}} +{{< tab name="CLI" >}} + +Authenticate with `docker login` using your Docker credentials or a [personal +access token (PAT)](../../security/access-tokens.md) with **Read & Write** +permissions. [Organization access tokens +(OATs)](../../enterprise/security/access-tokens.md) are not supported. + +Use the [`docker dhi mirror`](/reference/cli/docker/dhi/mirror/) command: + +```console +$ docker dhi mirror stop --org my-org dhi-golang +``` + +{{< /tab >}} +{{< /tabs >}} + ## Mirror a DHI repository to a third-party registry -You can optionally mirror a DHI repository to another container registry, such as Amazon -ECR, Google Artifact Registry, GitHub Container Registry, or a private Harbor -instance. +After mirroring a DHI repository to your organization on Docker Hub, you can +optionally mirror it to another container registry, such as Amazon ECR, Google +Artifact Registry, GitHub Container Registry, or a private Harbor instance. You can use any standard workflow to mirror the image, such as the [Docker CLI](/reference/cli/docker/), [Docker Hub Registry @@ -189,55 +169,49 @@ OCI-aware CLI that supports mirroring images along with attached artifacts such as SBOMs, vulnerability reports, and SLSA provenance. For ongoing synchronization, you can use [`regsync`](https://regclient.org/cli/regsync/). -### Authenticate to `dhi.io` with an organization access token - -You can authenticate to `dhi.io` using an [organization access token -(OAT)](../../enterprise/security/access-tokens.md) instead of a personal access -token (PAT). OATs are owned by the organization rather than an individual user, -which makes them better suited for CI/CD pipelines and automated workflows. - -> [!NOTE] -> -> When using an OAT, use your organization name as the username, not your -> personal Docker ID. OATs are org-scoped and will return a `401 Unauthorized` -> error if presented under an individual user's username. +### Automate syncing with webhooks -To authenticate using an OAT: - -1. Sign in to [Docker Home](https://app.docker.com) and select your organization. -2. Select **Admin Console**, then **Access tokens**. -3. Select **Generate access token**. -4. Give the token a descriptive name, for example `dhi-pull-automation`. -5. Expand the **Repository** drop-down and select **Read public repositories**. -6. Select **Generate token**, then copy and save the token. You won't be able - to retrieve it after closing the screen. -7. Sign in to `dhi.io` using your organization name as the username and the OAT - as the password: - - ```console - $ oras login dhi.io -u - ``` +To keep external registries or systems in sync with your mirrored Docker +Hardened Images, and to receive notifications when updates occur, you can +configure a [webhook](/docker-hub/repos/manage/webhooks/) on the mirrored +repository in Docker Hub. A webhook sends a `POST` request to a URL you define +whenever a new image tag is pushed or updated. - Or non-interactively in a CI/CD pipeline: +For example, you might configure a webhook to call a CI/CD system at +`https://ci.example.com/hooks/dhi-sync` whenever a new tag is mirrored. The +automation triggered by this webhook can pull the updated image from Docker Hub +and push it to an internal registry such as Amazon ECR, Google Artifact +Registry, or GitHub Container Registry. - ```console - $ echo $OAT | oras login dhi.io -u "$DOCKER_ORG" --password-stdin - ``` +Other common webhook use cases include: -8. Verify access by discovering attestations on a DHI image: +- Triggering validation or vulnerability scanning workflows +- Signing or promoting images +- Sending notifications to downstream systems - ```console - $ oras discover dhi.io/node:24-dev --platform linux/amd64 - ``` +#### Example webhook payload - > [!NOTE] - > - > The `--platform` flag is required. Without it, `oras discover` resolves to - > the multi-arch image index, which returns only an index-level signature - > rather than the full set of per-platform attestations. +When a webhook is triggered, Docker Hub sends a JSON payload like the following: - A successful response lists the attestations attached to the image, - including SBOMs, provenance, vulnerability reports, and changelog metadata. +```json{collapse=true} +{ + "callback_url": "https://registry.hub.docker.com/u/exampleorg/dhi-python/hook/abc123/", + "push_data": { + "pushed_at": 1712345678, + "pusher": "trustedbuilder", + "tag": "3.13-alpine3.21" + }, + "repository": { + "name": "dhi-python", + "namespace": "exampleorg", + "repo_name": "exampleorg/dhi-python", + "repo_url": "https://hub.docker.com/r/exampleorg/dhi-python", + "is_private": true, + "status": "Active", + ... + } +} +``` ### Example mirroring with `regctl` @@ -327,7 +301,7 @@ reads a YAML configuration file and can filter tags. The following example uses a `regsync.yaml` file that syncs Node 24 and Python 3.12 Debian 13 variants, excluding Alpine and Debian 12. -```yaml{title="regsync.yaml"} +```yaml{title="regsync.yaml",collapse=true} version: 1 # Optional: inline creds if not relying on prior CLI logins # creds: diff --git a/content/manuals/dhi/how-to/use.md b/content/manuals/dhi/how-to/use.md index c1b35b13b7a..bfc0a9aaeb6 100644 --- a/content/manuals/dhi/how-to/use.md +++ b/content/manuals/dhi/how-to/use.md @@ -115,7 +115,7 @@ COPY . /app CMD ["python", "/app/main.py"] ``` -To learn how to mirror repositories, see [Mirror a DHI repository to Docker Hub](./mirror.md#mirror-a-dhi-repository-to-docker-hub). +To learn how to mirror repositories, see [Mirror a DHI repository to your organization](./mirror.md#mirror-a-dhi-repository-to-your-organization). ### Pull from a mirror on a third-party registry @@ -162,6 +162,56 @@ enforcement using tools like Docker Scout. To learn how to attach attestations during the build process, see [Docker Build Attestations](/manuals/build/metadata/attestations.md). +### Discover attestations with ORAS + +You can use [ORAS](https://oras.land/) to discover and inspect the attestations +attached to Docker Hardened Images. This is particularly useful in CI/CD +pipelines for supply chain security validation and compliance checks. + +For automated workflows, authenticate using an [organization access token +(OAT)](../../enterprise/security/access-tokens.md). OATs are owned by the +organization rather than an individual user, making them better suited for CI/CD +pipelines. + +To discover attestations with ORAS: + +1. [Generate an organization access + token](../../enterprise/security/access-tokens.md) with **Read public + repositories** scope. + + The following example shows how to discover attestations on DHI community + images from `dhi.io`. If you're discovering attestations on images mirrored to + your organization, generate an OAT scoped to read from your mirrored repository + instead of **Read public repositories**. + +2. Sign in to `dhi.io` using your organization name as the username and the OAT + as the password: + + ```console + $ oras login dhi.io -u + ``` + + Or non-interactively in a CI/CD pipeline: + + ```console + $ echo $OAT | oras login dhi.io -u "$DOCKER_ORG" --password-stdin + ``` + +3. Discover attestations on a DHI image: + + ```console + $ oras discover dhi.io/node:24-dev --platform linux/amd64 + ``` + + > [!NOTE] + > + > The `--platform` flag is required. Without it, `oras discover` resolves to + > the multi-arch image index, which returns only an index-level signature + > rather than the full set of per-platform attestations. + + A successful response lists the attestations attached to the image, + including SBOMs, provenance, vulnerability reports, and changelog metadata. + ## Use a static image for compiled executables Docker Hardened Images include a `static` image repository designed specifically