x509 certificate signed by unknown authority
This error occurs when a client (like kubectl or container runtime) rejects a TLS connection because the server's certificate was signed by an untrusted Certificate Authority.
Usually happens because:
- ☑ Missing cluster root CA certificate in client's trusted root certs store
- ☑ Missing or mismatching caBundle parameters inside admission webhooks specs
- ☑ Containerd runtime lacks certificates mapping to trust private registries
🔍 Quick Checklist:
What is x509 certificate signed by unknown authority?
An 'x509: certificate signed by unknown authority' error is raised during TLS handshakes when a client cannot verify the identity of a target server. This happens because the root Certificate Authority (CA) certificate that signed the server's certificate is not present in the client's local trusted certificate store. In Kubernetes v1.36 clusters, this occurs when kubectl connects to an API server using self-signed certificates, when the Kubelet communicates with custom registries, or when workloads make TLS calls to webhook servers.
Common Causes
- Self-signed API server certificates: The cluster uses a custom CA (standard in tool setups like kubeadm or minikube) and the client machine lacks the root CA file.
- Registry cert trust missing: Container runtimes (containerd) fail to pull images from private registries utilizing private TLS certs.
- Validating/Mutating webhook TLS mismatch: The API server rejects admission webhooks because the webhook server's certificate CA is not configured in the webhook's 'caBundle'.
| Cause | Frequency |
|---|---|
| Missing Root CA cert in developer client machine trusted root store | ⭐⭐⭐⭐⭐ |
| Missing or wrong caBundle in validating/mutating webhook configurations | ⭐⭐⭐⭐ |
| Container runtime (containerd) lacks private registry CA certificates | ⭐⭐⭐ |
Common Mistakes
- Using `--insecure-skip-tls-verify` inside production CI/CD pipelines to bypass x509 exceptions, which disables transport layer encryption checks, exposing workloads to man-in-the-middle exploits.
- Injecting raw PEM certificates text strings inside YAML attributes where base64-encoded strings are strictly required.
How to Fix
Kubernetes Operations & Verification
Inject the base64-encoded CA certificate inside validating webhook structures to verify webhook TLS certs in Kubernetes v1.36.
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
name: validator-hook
webhooks:
- name: validate.example.com
# Inject base64 string of root CA cert here
caBundle: "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCg==..."
clientConfig:
service:
name: validator-service
namespace: kube-system
path: "/validate"
admissionReviewVersions: ["v1"]
sideEffects: NonePlatform Specific Fixes
Distribute and update trusted CA certificates stores on Debian/Ubuntu client nodes.
# 1. Copy CA cert to system anchor directory
sudo cp cluster-ca.crt /usr/local/share/ca-certificates/cluster-ca.crt
# 2. Re-index trusted certificates database
sudo update-ca-certificatesBest Practices
- Adopt automated certificate managers (like cert-manager) to manage and rotate trusted TLS certificates profiles.
- Verify container runtime configurations are synchronized with cluster custom CAs.
Frequently Asked Questions (FAQ)
Q: What does 'x509: certificate signed by unknown authority' mean?
This means a secure TLS connection failed because the client doesn't trust the CA that signed the server's certificate. You need to add the server's root CA certificate to your client's trusted certificate store.
Q: How do I fix this error for kubectl?
Ensure your kubeconfig file has the 'certificate-authority-data' field populated with the base64-encoded root CA of the cluster. Alternatively, you can bypass validation temporarily using 'kubectl --insecure-skip-tls-verify', though this is highly discouraged for production.
Q: How do I configure this for admission webhooks?
Admission webhooks must specify a 'caBundle' field in their configuration YAML containing the base64-encoded CA certificate that signed the webhook server's TLS certificate. If missing or incorrect, the API server rejects calls with this x509 error.
Q: How do I make containerd trust my private registry CA?
Under containerd v2.0+ (standard in v1.36), place your registry CA file under '/etc/containerd/certs.d/<registry-domain>/ca.crt' on all cluster nodes, then restart the containerd service.