kubectl create secret docker-registry: Pull Secrets

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.