Skip to content

Expand documentation on the KubernetesImagesRepository setting. #22589

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

Merged
merged 1 commit into from
May 8, 2025
Merged

Expand documentation on the KubernetesImagesRepository setting. #22589

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
106 changes: 98 additions & 8 deletions content/manuals/desktop/features/kubernetes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,14 +81,6 @@
| Works with containerd image store | Yes | Yes |
| Works with Docker image store | Yes | No |

### Additional settings

#### Viewing system containers

By default, Kubernetes system containers are hidden. To inspect these containers, enable **Show system containers (advanced)**.

You can now view the running Kubernetes containers with `docker ps` or in the Docker Desktop Dashboard.

## Using the kubectl command

Kubernetes integration automatically installs the Kubernetes CLI command
Expand Down Expand Up @@ -131,6 +123,104 @@

Kubernetes clusters are not automatically upgraded with Docker Desktop updates. To upgrade the cluster, you must manually select **Reset Kubernetes Cluster** in settings.

## Additional settings

### Viewing system containers

By default, Kubernetes system containers are hidden. To inspect these containers, enable **Show system containers (advanced)**.

You can now view the running Kubernetes containers with `docker ps` or in the Docker Desktop Dashboard.

### Configuring a custom image registry for Kubernetes control plane images

Check warning on line 134 in content/manuals/desktop/features/kubernetes.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Docker.HeadingLength] Try to keep headings short (< 8 words).

Raw Output:
{"message": "[Docker.HeadingLength] Try to keep headings short (\u003c 8 words).", "location": {"path": "content/manuals/desktop/features/kubernetes.md", "range": {"start": {"line": 134, "column": 5}}}, "severity": "INFO"}

Docker Desktop uses containers to run the Kubernetes control plane. By default, Docker Desktop pulls
the associated container images from Docker Hub. The images pulled depend on the [cluster provisioning mode](#cluster-provisioning-method).

For example, in `kind` mode it requires the following images:

```console
docker.io/kindest/node:<tag>
docker.io/docker/desktop-cloud-provider-kind:<tag>
docker.io/docker/desktop-containerd-registry-mirror:<tag>
```

In `kubeadm` mode it requires the following images:

```console
docker.io/registry.k8s.io/kube-controller-manager:<tag>
docker.io/registry.k8s.io/kube-apiserver:<tag>
docker.io/registry.k8s.io/kube-scheduler:<tag>
docker.io/registry.k8s.io/kube-proxy
docker.io/registry.k8s.io/etcd:<tag>
docker.io/registry.k8s.io/pause:<tag>
docker.io/registry.k8s.io/coredns/coredns:<tag>
docker.io/docker/desktop-storage-provisioner:<tag>
docker.io/docker/desktop-vpnkit-controller:<tag>
docker.io/docker/desktop-kubernetes:<tag>
```

The image tags are automatically selected by Docker Desktop based on several
factors, including the version of Kubernetes being used. The tags vary for each image.

To accommodate scenarios where access to Docker Hub is not allowed, admins can
configure Docker Desktop to pull the above listed images from a different registry (e.g., a mirror)

Check warning on line 166 in content/manuals/desktop/features/kubernetes.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Docker.RecommendedWords] Consider using 'previous' instead of 'above'

Raw Output:
{"message": "[Docker.RecommendedWords] Consider using 'previous' instead of 'above'", "location": {"path": "content/manuals/desktop/features/kubernetes.md", "range": {"start": {"line": 166, "column": 38}}}, "severity": "INFO"}
using the [KubernetesImagesRepository](../../security/for-admins/hardened-desktop/settings-management/configure-json-file.md#kubernetes) setting as follows.

An image name can be broken into `[registry[:port]/][namespace/]repository[:tag]` components.
The `KubernetesImagesRepository` setting allows users to override the `[registry[:port]/][namespace]`
portion of the image's name.

For example, if Docker Desktop Kubernetes is configured in `kind` mode and
`KubernetesImagesRepository` is set to `my-registry:5000/kind-images`, then
Docker Desktop will pull the images from:

```console
my-registry:5000/kind-images/node:<tag>
my-registry:5000/kind-images/desktop-cloud-provider-kind:<tag>
my-registry:5000/kind-images/desktop-containerd-registry-mirror:<tag>
```

These images should be cloned/mirrored from their respective images in Docker Hub. The tags must
also match what Docker Desktop expects.

The recommended approach to set this up is the following:

1) Start Docker Desktop.

2) In Settings > Kubernetes, enable the *Show system containers* setting.

3) In Settings > Kubernetes, start Kubernetes using the desired cluster provisioning method: `kubeadm` or `kind`.

4) Wait for Kubernetes to start.

5) Use `docker ps` to view the container images used by Docker Desktop for the Kubernetes control plane.

6) Clone or mirror those images (with matching tags) to your custom registry.

7) Stop the Kubernetes cluster.

8) Configure the `KubernetesImagesRepository` setting to point to your custom registry.

9) Restart Docker Desktop.

10) Verify that the Kubernetes cluster is using the custom registry images using the `docker ps` command.

> [!NOTE]
>
> The `KubernetesImagesRepository` setting only applies to control plane images used by Docker Desktop
> to set up the Kubernetes cluster. It has no effect on other Kubernetes pods.

> [!NOTE]
>
> When using `KubernetesImagesRepository` and [Enhanced Container Isolation (ECI)](../../security/for-admins/hardened-desktop/enhanced-container-isolation/_index.md)
> is enabled, add the following images to the [ECI Docker socket mount image list](../../security/for-admins/hardened-desktop/settings-management/configure-json-file.md#enhanced-container-isolation):
>
> * [imagesRepository]/desktop-cloud-provider-kind:*
> * [imagesRepository]/desktop-containerd-registry-mirror:*
>
> These containers mount the Docker socket, so you must add the images to the ECI images list. If not,
> ECI will block the mount and Kubernetes won't start.

## Troubleshooting

- If Kubernetes fails to start, make sure Docker Desktop is running with enough allocated resources. Check **Settings** > **Resources**.
Expand Down
6 changes: 3 additions & 3 deletions ...security/for-admins/hardened-desktop/settings-management/configure-json-file.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -264,14 +264,14 @@

|Parameter|OS|Description|Version|
|:-------------------------------|---|:-------------------------------|---|
|`kubernetes`| | If `enabled` is set to true, a Kubernetes single-node cluster is started when Docker Desktop starts. If `showSystemContainers` is set to true, Kubernetes containers are displayed in the Docker Desktop Dashboard and when you run `docker ps`. `imagesRepository` lets you specify which repository Docker Desktop pulls the Kubernetes images from. For example, `"imagesRepository": "registry-1.docker.io/docker"`. | |
|`kubernetes`| | If `enabled` is set to true, a Kubernetes single-node cluster is started when Docker Desktop starts. If `showSystemContainers` is set to true, Kubernetes containers are displayed in the Docker Desktop Dashboard and when you run `docker ps`. The [imagesRepository](../../../../desktop/features/kubernetes.md#configuring-a-custom-image-registry-for-kubernetes-control-plane-images) setting lets you specify which repository Docker Desktop pulls control-plane Kubernetes images from. | |

Check failure on line 267 in content/manuals/security/for-admins/hardened-desktop/settings-management/configure-json-file.md

View workflow job for this annotation

GitHub Actions / vale 

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

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'imagesRepository'?", "location": {"path": "content/manuals/security/for-admins/hardened-desktop/settings-management/configure-json-file.md", "range": {"start": {"line": 267, "column": 265}}}, "severity": "ERROR"}

> [!NOTE]
>
> When using the `imagesRepository` setting and Enhanced Container Isolation (ECI), add the following images to the [ECI Docker socket mount image list](#enhanced-container-isolation):
>
> `<custom-image-repo>/desktop-cloud-provider-kind:*`
> `<custom-image-repo>/desktop-containerd-registry-mirror:*`
> * [imagesRepository]/desktop-cloud-provider-kind:*
> * [imagesRepository]/desktop-containerd-registry-mirror:*
>
> These containers mount the Docker socket, so you must add the images to the ECI images list. If not, ECI will block the mount and Kubernetes won't start.

Expand Down