# k8s-for-docker-desktop: Pulling Kubernetes Images for Docker Desktop in China

> k8s-for-docker-desktop provides shell scripts that pull the container images required by Docker Desktop's built-in Kubernetes feature from Alibaba Cloud's image registry, bypassing the Google Container Registry that is inaccessible in mainland China. The scripts also include configuration for the Kubernetes dashboard, Ingress, Helm, and Istio.

**denverdino/k8s-for-docker-desktop** — 为Docker Desktop for Mac/Windows开启Kubernetes和Istio。

- Repository: https://github.com/denverdino/k8s-for-docker-desktop
- Stars: 5,037 · Forks: 1,110
- Language: PowerShell
- License: not declared
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/denverdino-k8s-for-docker-desktop

## Why Docker Desktop's Kubernetes Fails in China

Docker Desktop for Mac and Windows includes a built-in Kubernetes option. When you enable it, Docker Desktop tries to pull the required component images from Google Container Registry (gcr.io). That registry is blocked in mainland China. The images fail to download, and Kubernetes stays in a perpetual 'starting' state. k8s-for-docker-desktop solves this by providing scripts that pull the same images from Alibaba Cloud's mirror registry, re-tag them with the gcr.io addresses that Docker Desktop expects, and make the images available locally. Docker Desktop then finds them in the local cache and the Kubernetes cluster starts normally. The README notes that the current master branch contains Kubernetes v1.34.3; other branches carry other versions. If a needed version is not yet available, you can modify the images.properties file to specify the required image versions. The README also explains how to identify the correct image tags: run kubeadm config images list --kubernetes-version v1.30.2 (adjusting the version number) and cross-reference with the available tags on Docker Hub for docker/desktop-kubernetes, docker/desktop-vpnkit-controller, and docker/desktop-storage-provisioner. The README warns that Docker Desktop requires accepting the Docker subscription service agreement. For teams unwilling to accept those terms, the README explicitly recommends Minikube as an alternative for local Kubernetes development. Minikube does not depend on Docker Desktop's built-in Kubernetes feature and manages its own image downloads through a different mechanism. The approach in this repository is specific to Docker Desktop's integrated Kubernetes: it does not apply to Kind, k3s, or other local Kubernetes tools.

## Running the Image Pull Scripts

On macOS, run the included shell script from the repository root:

```bash
./load_images.sh
```

On Windows, open a PowerShell terminal and run:

```powershell
.\load_images.ps1
```

If Windows blocks the script due to execution policy, open an administrator PowerShell and run:

```powershell
Set-ExecutionPolicy RemoteSigned
```

After the script completes and Kubernetes is enabled in Docker Desktop, the Kubernetes cluster should start. If it stays in the starting state, the README links to two Docker issue tracker comments describing a known fix: on macOS, delete ~/Library/Group Containers/group.com.docker/pki; on Windows, delete the pki directories under ProgramData\DockerDesktop and the user's AppData\Local\Docker folder.

## Configuring the Kubernetes Context and Verifying the Cluster

After Kubernetes starts, switch the kubectl context to docker-desktop:

```shell
kubectl config use-context docker-desktop
```

Verify the cluster is running:

```shell
kubectl cluster-info
kubectl get nodes
```

The README also shows how to enter a specific container inside a pod that has multiple containers, using the --container flag:

```
kubectl --namespace=kube-system exec -it kube-dns-1336009800-15b1h --container nginx -- sh
```

This technique is unrelated to the image mirror problem but is included as a practical tip for working with the cluster once it is running. The README notes that the context was named docker-for-desktop in older versions of Docker Desktop; the current name is docker-desktop.

## Deploying the Kubernetes Dashboard and Configuring Access

The README documents deploying the standard Kubernetes dashboard by applying either a remote URL or the included kubernetes-dashboard.yaml file. After deployment, checking pod status:

```shell
kubectl get pod -n kubernetes-dashboard
```

Accessing the dashboard requires starting the API proxy with kubectl proxy and opening the dashboard URL at localhost:8001. Authentication uses a token generated from the kube-system default service account. On macOS:

```shell
TOKEN=$(kubectl -n kube-system describe secret default| awk '$1=="token:"{ print $2}')
kubectl config set-credentials docker-desktop --token="${TOKEN}"
echo $TOKEN
```

Paste the printed token into the dashboard login page under the Token option. Alternatively, the login page accepts the Kubeconfig file directly: on Mac that is at $HOME/.kube/config, on Windows at %UserProfile%\.kube\config. The README also shows authorizing the kube-system default service account using the included kube-system-default.yaml file before generating the token. This authorization step must be done before the token generation command; without it, the generated token will have insufficient permissions to view most of the dashboard. The kubectl proxy command must remain running for as long as you are using the dashboard; it is not a background service.

## Helm and Istio Setup

The README documents installing Helm v3, noting that the Helm CDN uses Google Cloud infrastructure and may be inaccessible in China. For macOS, Homebrew works:

```shell
brew install helm
helm repo add stable http://mirror.azure.cn/kubernetes/charts/
helm repo update
```

For Windows, Chocolatey installs Helm, but it requires network access to googleapis. The repo URL points to the Azure China mirror rather than the default Helm stable repo. For Istio, the README shows downloading a specific version (1.22.1 is the example) using the official install script and running istioctl install with the demo profile. The README notes that Istio Ingress Gateway conflicts with Nginx Ingress on default ports, so the guide instructs removing Ingress before deploying Istio's gateway. The Windows Istio setup is noted as not having been strictly tested.

After installing Istio, the README shows enabling automatic sidecar injection for the default namespace:

```shell
kubectl label namespace default istio-injection=enabled
kubectl get namespace -L istio-injection
```

The label tells Istio to inject the Envoy proxy sidecar into every new pod in that namespace. The second command verifies the label is applied by listing namespaces with their istio-injection value. Checking pod status after Istio installation:

```shell
kubectl get pods -n istio-system
```

For the BookInfo sample, the README references the Istio documentation at istio.io/docs/examples/bookinfo/ and shows applying the sample with `kubectl apply -f samples/bookinfo/platform/kube/bookinfo.yaml`. The BookInfo manifests are not included in this repository; they come from the Istio installation directory downloaded by the curl command.

## Testing the Ingress Configuration with Sample Applications

The repository includes sample Kubernetes manifests in the sample/ directory for testing Nginx Ingress once it is deployed. The README shows deploying two small test services and an Ingress rule:

```shell
kubectl create -f sample/apple.yaml
kubectl create -f sample/banana.yaml
kubectl create -f sample/ingress.yaml
```

Once deployed, the README shows testing with curl:

```bash
$ curl -kL http://localhost/apple
apple
$ curl -kL http://localhost/banana
banana
```

These samples verify that the Ingress controller is routing requests correctly. Cleaning up after the test removes all three resources. These sample files are the only application code included in the repository; the repository's purpose is infrastructure configuration, not application development.

The repository has no formal software license file. The last push was on 2026-05-19. The README explicitly requires reading the Docker subscription service agreement before use, and suggests Minikube as an alternative if the Docker terms are not acceptable. Memory allocation is a practical prerequisite: the README recommends assigning at least 4 GB of memory to the Kubernetes cluster in Docker Desktop's resource settings before enabling Kubernetes. The macOS log stream command documented in the README provides real-time Docker Desktop diagnostics by filtering system log entries for Docker-related processes, which is more reliable for diagnosing startup failures than watching the Docker Desktop status icon. On Windows, the equivalent log files are in C:\ProgramData\DockerDesktop and C:\Users\yourUserName\AppData\Local\Docker.

## Conclusion

k8s-for-docker-desktop suits developers in mainland China who need to enable Kubernetes in Docker Desktop and cannot reach Google Container Registry directly. It is not a Kubernetes distribution or a general Kubernetes installation guide: it specifically addresses the image-pull problem for Docker Desktop's built-in K8s feature. Engineers outside China or using a VPN that reaches Google's registries have no need for it. Before running the scripts, read and accept the Docker subscription service agreement, which the README explicitly references; if you do not accept it, the README suggests using Minikube or another open-source alternative instead. The current master branch packages Kubernetes v1.34.3.

## FAQ

### Why does Docker Desktop Kubernetes fail to start in China?

Docker Desktop pulls Kubernetes component images from Google Container Registry (gcr.io), which is inaccessible in mainland China. k8s-for-docker-desktop provides scripts that pull the same images from Alibaba Cloud's mirror and re-tag them so Docker Desktop finds them locally.

### Which Kubernetes version does k8s-for-docker-desktop support?

The current master branch contains Kubernetes v1.34.3. Other branches carry other versions. The images.properties file can be edited to specify a different version; the README notes you can run kubeadm config images list --kubernetes-version to identify the required image tags for any supported version.

### Does K8s work with Docker Desktop?

Docker Desktop for Mac and Windows includes a built-in Kubernetes option. When enabled, it runs a local single-node Kubernetes cluster. k8s-for-docker-desktop specifically addresses the image-pull problem that prevents this from working in mainland China.

## Sources

- [denverdino/k8s-for-docker-desktop on GitHub](https://github.com/denverdino/k8s-for-docker-desktop)
- [Issues](https://github.com/denverdino/k8s-for-docker-desktop/issues)
- [README](https://github.com/denverdino/k8s-for-docker-desktop/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/denverdino-k8s-for-docker-desktop