From e761bf7f76ac9f3647992a8942ba4bcf149c4623 Mon Sep 17 00:00:00 2001 From: Cesar Talledo Date: Mon, 5 May 2025 11:06:24 -0700 Subject: [PATCH] Expand documentation on the KubernetesImagesRepository setting. Provide our users more help on this setting. Place the info in the Kubernetes feature section, and link to it from the admin-settings description for KubernetesImagesRepository. Signed-off-by: Cesar Talledo --- .../manuals/desktop/features/kubernetes.md | 106 ++++++++++++++++-- .../configure-json-file.md | 6 +- 2 files changed, 101 insertions(+), 11 deletions(-) diff --git a/content/manuals/desktop/features/kubernetes.md b/content/manuals/desktop/features/kubernetes.md index 1a7f77313e1..6319a7955a2 100644 --- a/content/manuals/desktop/features/kubernetes.md +++ b/content/manuals/desktop/features/kubernetes.md @@ -81,14 +81,6 @@ The following table summarizes this comparison. | 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 @@ -131,6 +123,104 @@ For more information about `kubectl`, see the 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 + +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: +docker.io/docker/desktop-cloud-provider-kind: +docker.io/docker/desktop-containerd-registry-mirror: +``` + +In `kubeadm` mode it requires the following images: + +```console +docker.io/registry.k8s.io/kube-controller-manager: +docker.io/registry.k8s.io/kube-apiserver: +docker.io/registry.k8s.io/kube-scheduler: +docker.io/registry.k8s.io/kube-proxy +docker.io/registry.k8s.io/etcd: +docker.io/registry.k8s.io/pause: +docker.io/registry.k8s.io/coredns/coredns: +docker.io/docker/desktop-storage-provisioner: +docker.io/docker/desktop-vpnkit-controller: +docker.io/docker/desktop-kubernetes: +``` + +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) +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: +my-registry:5000/kind-images/desktop-cloud-provider-kind: +my-registry:5000/kind-images/desktop-containerd-registry-mirror: +``` + +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**. diff --git a/content/manuals/security/for-admins/hardened-desktop/settings-management/configure-json-file.md b/content/manuals/security/for-admins/hardened-desktop/settings-management/configure-json-file.md index 0096692d5a8..f6856d85c66 100644 --- a/content/manuals/security/for-admins/hardened-desktop/settings-management/configure-json-file.md +++ b/content/manuals/security/for-admins/hardened-desktop/settings-management/configure-json-file.md @@ -264,14 +264,14 @@ The following `admin-settings.json` code and table provides an example of the re |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. | | > [!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): > -> `/desktop-cloud-provider-kind:*` -> `/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.