kubectl create secret docker-registry: Pull Secrets

By Daniel Zoghalchali·Latchkey

kubectl create secret docker-registry produces a kubernetes.io/dockerconfigjson Secret that pods reference via imagePullSecrets.

Private images need a pull secret. This subcommand assembles the dockerconfigjson from registry credentials without hand-editing JSON.

What it does

kubectl create secret docker-registry takes a registry host, username, and password (or token) and writes a Secret of type kubernetes.io/dockerconfigjson. Pods or service accounts reference it through imagePullSecrets so the kubelet can authenticate to the registry.

Common usage

Terminal

kubectl create secret docker-registry regcred \
  --docker-server=ghcr.io \
  --docker-username="$GH_USER" \
  --docker-password="$GH_TOKEN"
# generate YAML to commit instead of applying live
kubectl create secret docker-registry regcred \
  --docker-server=ghcr.io --docker-username=u --docker-password=p \
  --dry-run=client -o yaml > regcred.yaml

Options

Flag	What it does
--docker-server	Registry host (e.g. ghcr.io, registry.gitlab.com)
--docker-username	Registry username
--docker-password	Registry password or access token
--docker-email	Optional email field (rarely required now)
--from-file=.dockerconfigjson	Build from an existing docker config file
--dry-run=client -o yaml	Emit the Secret YAML without contacting the API

In CI

Use --dry-run=client -o yaml plus a downstream kubectl apply -f - so the secret is idempotent across reruns (plain create fails the second time with AlreadyExists). Then attach it: reference the secret under imagePullSecrets in the pod spec or patch it onto the default service account.

Common errors in CI

"Error from server (AlreadyExists): secrets \"regcred\" already exists" means the secret exists from a prior run; use apply with dry-run YAML, or delete first. If pods still hit "ErrImagePull ... no basic auth credentials", the secret host did not match the image registry exactly (for example docker.io vs index.docker.io), or the pod never listed it in imagePullSecrets.

Using this in CI

A runner has no kubeconfig, no cached context, and no interactive auth. Every kubectl invocation in CI needs the context supplied explicitly, and most confusing CI failures here are the command running against the wrong cluster or no cluster at all.

Terminal

# never rely on the ambient context on a runner
kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" get pods

# confirm what you are actually connected to before mutating anything
kubectl config current-context
kubectl cluster-info

# fail fast instead of hanging on an unreachable API server
kubectl --request-timeout=30s get nodes

Frequently asked questions

kubectl create secret docker-registry: Pull Secrets?

Private images need a pull secret. This subcommand assembles the dockerconfigjson from registry credentials without hand-editing JSON.

What it does?

kubectl create secret docker-registry takes a registry host, username, and password (or token) and writes a Secret of type kubernetes.io/dockerconfigjson. Pods or service accounts reference it through imagePullSecrets so the kubelet can authenticate to the registry.

In CI?

Use --dry-run=client -o yaml plus a downstream kubectl apply -f - so the secret is idempotent across reruns (plain create fails the second time with AlreadyExists). Then attach it: reference the secret under imagePullSecrets in the pod spec or patch it onto the default service account.

Common errors in CI?

"Error from server (AlreadyExists): secrets \"regcred\" already exists" means the secret exists from a prior run; use apply with dry-run YAML, or delete first. If pods still hit "ErrImagePull ...