Introduction

Kubernetes on Docker Desktop pulls images from Google Container Registry the same way it pulls from any private registry: the cluster needs credentials, and your workload needs to reference those credentials through an image pull secret or a service account. The key is not Docker Desktop itself; the key is giving the local Kubernetes cluster permission to authenticate against gcr.io or the regional GCR host you are using.

What You Need

For a private GCR image, you generally need:

• the full image path, such as gcr.io/my-project/my-app:1.0
• credentials that can read the image
• a Kubernetes Secret of type docker-registry or a Docker config JSON secret

If the image is public, no secret is required, but many GCR-backed workflows use private images.

Create the Pull Secret

A common approach is to use a Google service account key. Kubernetes then stores that credential as a Docker registry secret.

1kubectl create secret docker-registry gcr-json-key \
2  --docker-server=https://gcr.io \
3  --docker-username=_json_key \
4  --docker-password="$(cat key.json)" \
5  --docker-email=[email protected]

If you use a regional host such as us.gcr.io, use that as the server value instead.

The _json_key username is the convention used when authenticating to GCR with the raw service-account JSON key.

Reference the Secret in a Pod

Once the secret exists, reference it through imagePullSecrets:

1apiVersion: v1
2kind: Pod
3metadata:
4  name: gcr-demo
5spec:
6  containers:
7    - name: app
8      image: gcr.io/my-project/my-app:1.0
9  imagePullSecrets:
10    - name: gcr-json-key

For most real applications, you would put the same setting in a Deployment instead of a single Pod.

Using a Service Account

If several workloads in the same namespace need the same pull secret, attach it to a service account instead of repeating it in every manifest.

1apiVersion: v1
2kind: ServiceAccount
3metadata:
4  name: app-sa
5imagePullSecrets:
6  - name: gcr-json-key

Then use that service account in the workload:

1apiVersion: apps/v1
2kind: Deployment
3metadata:
4  name: app
5spec:
6  replicas: 1
7  selector:
8    matchLabels:
9      app: app
10  template:
11    metadata:
12      labels:
13        app: app
14    spec:
15      serviceAccountName: app-sa
16      containers:
17        - name: app
18          image: gcr.io/my-project/my-app:1.0

This keeps the registry configuration centralized within the namespace.

Why Docker Desktop Can Be Confusing

Docker Desktop already knows how to pull images for local docker run workflows if you logged in with Docker or gcloud. That does not automatically mean the embedded Kubernetes cluster can use the same credentials in the way your Pod expects. Kubernetes still needs a registry secret or another supported credential path inside the cluster model.

That is why "it pulls with Docker but not with Kubernetes" is such a common local-development complaint.

Common Pitfalls

The most common mistake is creating the secret in the wrong namespace. Image pull secrets are namespaced, so the Pod can only use secrets from its own namespace.

Another issue is mismatching the registry host. A secret created for gcr.io may not help if the image actually comes from us.gcr.io or another regional endpoint.

A third pitfall is assuming the local Docker daemon login is enough for Kubernetes. Docker Desktop can hide that difference until the first Pod fails with ImagePullBackOff.

Finally, keep the service-account key scoped minimally. The key only needs permission to read the registry images required by the workload.

Summary

• Kubernetes on Docker Desktop pulls from private GCR through normal Kubernetes registry credentials.
• Create a Docker registry secret using a Google service account key or another valid credential source.
• Reference that secret with imagePullSecrets or attach it to a service account.
• Make sure the registry host and namespace match the actual workload configuration.
• If Docker can pull but Kubernetes cannot, the missing piece is usually cluster-side credentials, not the image itself.