Skip to content
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

cx: update docs for RAM limits #22365

Merged
merged 1 commit into from
Apr 7, 2025
Merged

cx: update docs for RAM limits #22365

Show file tree
Hide file tree
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
51 changes: 38 additions & 13 deletions content/manuals/security/for-admins/hardened-desktop/registry-access-management.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,16 @@

{{< summary-bar feature_name="Registry access management" >}}

With Registry Access Management (RAM), administrators can ensure that their developers using Docker Desktop only access allowed registries. This is done through the Registry Access Management dashboard in Docker Hub or the Docker Admin Console.
With Registry Access Management (RAM), administrators can ensure that their
developers using Docker Desktop only access allowed registries. This is done
through the Registry Access Management dashboard in Docker Hub or the
Docker Admin Console.

Registry Access Management supports both cloud and on-prem registries. This feature operates at the DNS level and therefore is compatible with all registries. You can add any hostname or domain name you’d like to include in the list of allowed registries. However, if the registry redirects to other domains such as `s3.amazon.com`, then you must add those domains to the list.
Registry Access Management supports both cloud and on-prem registries. This
feature operates at the DNS level and therefore is compatible with all
egistries. You can add any hostname or domain name you’d like to include in the
list of allowed registries. However, if the registry redirects to other domains
such as `s3.amazon.com`, then you must add those domains to the list.

Example registries administrators can allow include:

Expand All @@ -29,7 +36,7 @@

## Prerequisites

You need to [enforce sign-in](../enforce-sign-in/_index.md). For Registry Access
You must [enforce sign-in](../enforce-sign-in/_index.md). For Registry Access
Management to take effect, Docker Desktop users must authenticate to your
organization. Enforcing sign-in ensures that your Docker Desktop developers
always authenticate to your organization, even though they can authenticate
Expand All @@ -53,21 +60,39 @@

## Verify the restrictions

The new Registry Access Management policy takes effect after the developer successfully authenticates to Docker Desktop using their organization credentials. If a developer attempts to pull an image from a disallowed registry via the Docker CLI, they receive an error message that the organization has disallowed this registry.
The new Registry Access Management policy takes effect after the developer
successfully authenticates to Docker Desktop using their organization
credentials. If a developer attempts to pull an image from a disallowed
registry via the Docker CLI, they receive an error message that the organization
has disallowed this registry.

## Caveats

There are certain limitations when using Registry Access Management:

- Windows image pulls and image builds are not restricted by default. For Registry Access Management to take effect on Windows Container mode, you must allow the Windows Docker daemon to use Docker Desktop's internal proxy by selecting the [Use proxy for Windows Docker daemon](/manuals/desktop/settings-and-maintenance/settings.md#proxies) setting.
- Builds such as `docker buildx` using a Kubernetes driver are not restricted
- Builds such as `docker buildx` using a custom docker-container driver are not restricted
- Blocking is DNS-based; you must use a registry's access control mechanisms to distinguish between “push” and “pull”
- WSL 2 requires at least a 5.4 series Linux kernel (this does not apply to earlier Linux kernel series)
- Under the WSL 2 network, traffic from all Linux distributions is restricted (this will be resolved in the updated 5.15 series Linux kernel)
- Images pulled by Docker Desktop when Docker Debug or Kubernetes is enabled, are not restricted by default even if Docker Hub is blocked by RAM.

Also, Registry Access Management operates on the level of hosts, not IP addresses. Developers can bypass this restriction within their domain resolution, for example by running Docker against a local proxy or modifying their operating system's `sts` file. Blocking these forms of manipulation is outside the remit of Docker Desktop.
- You can add up to 100 registries/domains.
- Windows image pulls and image builds are not restricted by default. For
Registry Access Management to take effect on Windows Container mode, you must
allow the Windows Docker daemon to use Docker Desktop's internal proxy by

Check warning on line 76 in content/manuals/security/for-admins/hardened-desktop/registry-access-management.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Docker.RecommendedWords] Consider using 'let' instead of 'allow'

Raw Output:
{"message": "[Docker.RecommendedWords] Consider using 'let' instead of 'allow'", "location": {"path": "content/manuals/security/for-admins/hardened-desktop/registry-access-management.md", "range": {"start": {"line": 76, "column": 1}}}, "severity": "INFO"}
selecting the [Use proxy for Windows Docker daemon](/manuals/desktop/settings-and-maintenance/settings.md#proxies)
setting.
- Builds such as `docker buildx` using a Kubernetes driver are not restricted.
- Builds such as `docker buildx` using a custom docker-container driver are not

Check failure on line 80 in content/manuals/security/for-admins/hardened-desktop/registry-access-management.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Docker.Capitalization] Please capitalize Docker.

Raw Output:
{"message": "[Docker.Capitalization] Please capitalize Docker.", "location": {"path": "content/manuals/security/for-admins/hardened-desktop/registry-access-management.md", "range": {"start": {"line": 80, "column": 48}}}, "severity": "ERROR"}
restricted.
- Blocking is DNS-based. You must use a registry's access control mechanisms to
distinguish between “push” and “pull”.
- WSL 2 requires at least a 5.4 series Linux kernel (this does not apply to
earlier Linux kernel series).
- Under the WSL 2 network, traffic from all Linux distributions is restricted.
This will be resolved in the updated 5.15 series Linux kernel.
- Images pulled by Docker Desktop when Docker Debug or Kubernetes is enabled,
are not restricted by default even if Docker Hub is blocked by RAM.

Also, Registry Access Management operates on the level of hosts, not IP
addresses. Developers can bypass this restriction within their domain
resolution, for example by running Docker against a local proxy or modifying
their operating system's `sts` file. Blocking these forms of manipulation is
outside the remit of Docker Desktop.

## More resources

Expand Down
32 changes: 26 additions & 6 deletions layouts/shortcodes/admin-registry-access.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,19 +13,39 @@

> [!NOTE]
>
> When enabled, the Docker Hub registry is set by default, however you can also restrict this registry for your developers.
> When enabled, the Docker Hub registry is set by default; however you can
> also restrict this registry for your developers.

4. Select **Add registry** and enter your registry details in the applicable fields, and then select **Create** to add the registry to your list. There is no limit on the number of registries you can add.
4. Select **Add registry** and enter your registry details in the applicable
fields, and then select **Create** to add the registry to your list. You can
add up to 100 registries/domains.
5. Verify that the registry appears in your list and select **Save changes**.

Once you add a registry, it can take up to 24 hours for the changes to be enforced on your developers’ machines.
Once you add a registry, it can take up to 24 hours for the changes to be
enforced on your developers’ machines.

If you want to apply the changes sooner, you must force a Docker signout on your developers’ machine and have the developers re-authenticate for Docker Desktop. See the [Caveats](#caveats) section below to learn more about limitations when using this feature.
If you want to apply the changes sooner, you must force a Docker signout on your
developers’ machine and have the developers re-authenticate for Docker Desktop.
See the [Caveats](#caveats) section below to learn more about limitations.

> [!IMPORTANT]
>
> Starting with Docker Desktop version 4.36, you can enforce sign-in for multiple organizations. If a developer belongs to multiple organizations with different RAM policies, only the RAM policy for the first organization listed in the `registry.json` file, `.plist` file, or registry key is enforced.
> Starting with Docker Desktop version 4.36, you can enforce sign-in for
multiple organizations. If a developer belongs to multiple organizations with
different RAM policies, only the RAM policy for the first organization listed
in the `registry.json` file, `.plist` file, or registry key is enforced.

> [!TIP]
>
> Since RAM sets policies about where content can be fetched from, the [ADD](/reference/dockerfile/#add) instruction of the Dockerfile, when the parameter of the ADD instruction is a URL, is also subject to registry restrictions. It's recommended that you add the domains of URL parameters to the list of allowed registry addresses under the Registry Access Management settings of your organization.
> Since RAM sets policies about where content can be fetched from, the
[ADD](/reference/dockerfile/#add) instruction of the Dockerfile when the
parameter of the ADD instruction is a URL is also subject to registry
restrictions.
>
> If you're using ADD to fetch an image or artifact from a trusted registry via
> URL, make sure the registry's domain is included in your organzation's
> allowed registries list.
>
> RAM is not intended to restrict access to general-purpose external URLs, for
> example, package mirrors or storage services. Attempting to add too many domains
> may cause errors or hit system limits.