Kubernetes Image Pull "x509: certificate signed by unknown authority"

By Daniel Zoghalchali·Latchkey

The kubelet could not verify the TLS certificate of your private registry. The registry presents a self-signed or internal-CA certificate that the nodes’ trust store does not contain.

What this error means

Pods fail to pull from a private registry with x509: certificate signed by unknown authority (or failed to verify certificate). Public-registry images pull fine; only the internal registry fails.

kubectl describe pod

Failed to pull image "registry.internal:5000/api:1.0": failed to do request:
Head "https://registry.internal:5000/v2/api/manifests/1.0": x509: certificate
signed by unknown authority

Diagnose it: read events and previous logs

Terminal

kubectl --context "$KUBE_CONTEXT" -n "$NS" get pods -o wide
kubectl -n "$NS" describe pod <pod> | sed -n "/Events/,$p"
kubectl -n "$NS" logs <pod> --previous --tail=50

Common causes

Registry CA not in the node trust store

A self-signed or private-CA registry certificate is not trusted by the container runtime on the nodes, so TLS verification fails.

Incomplete certificate chain

The registry serves a leaf cert without its intermediate CA, so the runtime cannot build a path to a trusted root.

How to fix it

Trust the registry CA on the nodes

Install the registry’s CA into the container runtime’s per-registry certs directory (containerd shown).

Terminal

# on each node (or via DaemonSet / node bootstrap)
mkdir -p /etc/containerd/certs.d/registry.internal:5000
cp ca.crt /etc/containerd/certs.d/registry.internal:5000/ca.crt

Serve the full chain

Configure the registry to present leaf + intermediate certificates.
Verify the chain with openssl s_client -connect registry.internal:5000 -showcerts.
Roll the CA out through node bootstrap so new nodes trust it automatically.

How to prevent it

Distribute the registry CA via node bootstrap so every node trusts it.
Serve the complete certificate chain from the registry.
Prefer certificates from a CA the cluster already trusts.

Frequently asked questions

What causes Kubernetes image pull "x509: certificate signed by unknown authority"?

There are 2 common causes: registry ca not in the node trust store and incomplete certificate chain. A self-signed or private-CA registry certificate is not trusted by the container runtime on the nodes, so TLS verification fails.

How do I fix Kubernetes image pull "x509: certificate signed by unknown authority"?

There are 2 fixes depending on which cause you have: trust the registry ca on the nodes and serve the full chain. Work through them in order, since the first is the most common.

What does Kubernetes image pull "x509: certificate signed by unknown authority" actually mean?

Pods fail to pull from a private registry with x509: certificate signed by unknown authority (or failed to verify certificate).

How do I stop Kubernetes image pull "x509: certificate signed by unknown authority" happening again?

Distribute the registry CA via node bootstrap so every node trusts it. The prevention section lists 3 changes that keep it from recurring.