Technology · PRACTICAL GUIDE
kubectl says x509: certificate signed by unknown authority? Prove the effective trust path
Identify the active kubeconfig, cluster endpoint, CA bytes, proxy route and presented certificate chain before replacing credentials or disabling TLS verification.
A kubectl x509 error does not identify which configuration, endpoint or certificate chain actually failed. Start by proving the effective values used by the current process.
This guide separates stale or merged kubeconfig data, an unexpected proxy, a replaced API-server certificate and a hostname mismatch before any trust change.
Freeze the exact client, error and invocation context
Save the complete kubectl error, command, timestamp, kubectl client version and current shell environment. Record HOME, KUBECONFIG, explicit --kubeconfig, --context, --cluster, --server, --certificate-authority and --insecure-skip-tls-verify flags without copying credentials into tickets or chat.
Do not begin by deleting ~/.kube, replacing every CA or adding an insecure flag. The error proves that one TLS verification path failed; it does not yet prove which file, cluster endpoint, proxy or certificate chain the current process used.
Prove the effective kubeconfig and current context
Run kubectl config current-context and inspect kubectl config view --minify for the current cluster and user. When KUBECONFIG lists several files, kubectl merges them and the first file to set a map key wins. An explicit --kubeconfig selects one file without merging, so reproduce the failing command with the same flags and environment.
Use --raw only in a protected local session because it can reveal embedded certificate or credential bytes. Compare the effective output with the files you expected; a stale first file, different HOME, service account or GUI launcher can select a different context even when ~/.kube/config looks correct.
Extract the endpoint and trust anchor without changing them
From the minified effective configuration, record the cluster server URL, tls-server-name, proxy-url, certificate-authority path and whether certificate-authority-data is present. Embedded CA data overrides the CA file, and relative file references are resolved from the kubeconfig file that contains them.
Decode embedded CA data only into a permission-restricted temporary file for inspection; do not paste it into public tools. Record the CA subject, issuer, validity period and fingerprint. If a CA file is referenced, resolve its real path and hash the actual bytes so later changes are detectable.
Inspect the certificate actually presented on the same route
Resolve the effective server hostname and port, then inspect from the same network namespace, VPN, container or runner that fails. OpenSSL s_client can show the presented chain with -connect and the intended SNI name with -servername; use -verify_return_error and a verified CA file when testing trust rather than treating a successful TCP connection as proof.
Check kubeconfig proxy-url plus HTTPS_PROXY, HTTP_PROXY and NO_PROXY. A corporate proxy, local tunnel or gateway can present a different certificate chain from the API server. Compare leaf subject and SANs, issuer chain and fingerprints with the intended endpoint and trust anchor before copying any certificate.
Classify the mismatch before choosing a repair
Common branches are a stale managed-cluster kubeconfig after CA rotation, the wrong merged context, CA data that overrides a correct file, a missing intermediate, a proxy-generated certificate, or an endpoint/SNI mismatch. A certificate-expired or hostname error needs its own repair; do not collapse every TLS message into unknown authority.
Do not blindly trust the leaf certificate returned by an unexpected endpoint. A trust anchor should come from the cluster owner, managed-provider credential command or another authenticated control-plane channel. Community fixes that delete all configs or disable verification can hide the identity problem rather than solve it.
Repair one narrow trust contract
For a managed cluster, refresh credentials with the provider's documented command and compare the resulting cluster entry before replacing the original. For a self-managed cluster, install the verified issuing CA or corrected chain in the intended cluster entry, preserving the expected server hostname and using certificate-authority or embedded certificate-authority-data consistently.
If the proxy is unintended, correct proxy-url or NO_PROXY for that endpoint. If it is required, obtain its trusted CA through the organization's authenticated process instead of exporting the observed leaf. Keep insecure-skip-tls-verify false; enabling it makes HTTPS connections insecure.
Verify with the original context and preserve rollback evidence
Retest with the same explicit kubeconfig, context, network path and original command. First confirm the TLS error disappears and the observed endpoint and issuer match the intended cluster. An authentication or authorization response after that is a separate layer and can demonstrate that server trust succeeded.
Record previous and new kubeconfig hashes, cluster entry, CA fingerprint, endpoint, proxy decision, credential-refresh command and rollback file. Remove temporary decoded CA files securely, restore file permissions and keep the old trusted configuration until the new path passes the original operation.
