Troubleshooting
kubectl
Section titled “kubectl”exec: executable kubectl-oidc_login not found
Section titled “exec: executable kubectl-oidc_login not found”Install kubelogin: kubectl krew install oidc-login or brew install int128/kubelogin/kubelogin.
The browser signs you in as the wrong GitHub account, or keeps failing
Section titled “The browser signs you in as the wrong GitHub account, or keeps failing”Delete kubelogin’s cache and try again: rm -rf ~/.kube/cache/oidc-login.
… is forbidden: User "github:you" cannot …
Section titled “… is forbidden: User "github:you" cannot …”Check who you are (kubectl auth whoami) and that you own this control plane. Owners can’t
create namespaces or cluster-wide RBAC; see what you may do.
x509: certificate signed by unknown authority
Section titled “x509: certificate signed by unknown authority”You’re using a kubeconfig from a different (or deleted and re-created) control plane. Download it again from the site.
The site
Section titled “The site”A button does nothing, or “Your session expired”
Section titled “A button does nothing, or “Your session expired””Sessions last a day. The site signs you in again and brings you back to the same page.
Controllers
Section titled “Controllers”CrashLoopBackOff with no matches for kind … or failed to wait for … caches to sync
Section titled “CrashLoopBackOff with no matches for kind … or failed to wait for … caches to sync”Your operator watches a type that isn’t installed. Install all of its CRDs (many operators ship several), and it starts on its own.
ImagePullBackOff
Section titled “ImagePullBackOff”Check the image name and tag. For a private image, add registry credentials under Edit → Private image.
“doesn’t fit this control plane’s limits”
Section titled ““doesn’t fit this control plane’s limits””Lower its CPU or memory limit, or another controller’s. See limits.
Errors calling a webhook, or connection refused on startup about port 9443
Section titled “Errors calling a webhook, or connection refused on startup about port 9443”Set the controller’s webhook port, so it gets its certificate in
/tmp/k8s-webhook-server/serving-certs, and point your webhook configurations at
ctrl-<controller>-webhook in your namespace, without a caBundle. See Webhooks.
It crashes writing files, or permission denied
Section titled “It crashes writing files, or permission denied”Controllers run as user 65532, and their home directory (/var/run/tenant, where the
kubeconfig is) is read-only. Write to /tmp, or build the image so that user can write where
it needs to.
No metrics
Section titled “No metrics”ctrlplane scrapes :8080/metrics over HTTP. For kubebuilder v4 projects add
--metrics-bind-address=:8080 --metrics-secure=false.
The tunnel
Section titled “The tunnel”Controllers can’t reach a host in your network
Section titled “Controllers can’t reach a host in your network”- Network shows the tunnel running? If not, check the connector (
docker logs ctrlplane-connector) or the Tailscale node in your tailnet. - Can the machine running the connector reach the host itself?
- Does your client honour
HTTPS_PROXY? Database drivers, SSH and some SDKs don’t: add a forward and connect to it instead. - Tailscale: is the host’s subnet advertised by a subnet router, and do your ACLs allow the tunnel’s node to reach it?