Common Issues

Solutions to frequently encountered problems.

# Pod stuck in Pending

Symptom: kubectl get pods shows a pod in Pending state.

Causes and fixes:

  • Insufficient resources: the node doesn’t have enough CPU or memory. Check: kubectl describe pod <name> → look for Insufficient cpu or Insufficient memory events. Fix: reduce resource requests, or contact TrueFullstaq to scale the cluster.

  • PVC not bound: a PersistentVolumeClaim is waiting for a volume. Check: kubectl get pvc -n <namespace>. Fix: verify the storageClass in your PVC matches an available class (kubectl get sc).

  • Image pull error: the container image cannot be pulled. See Image pull errors below.

# Image pull errors

Symptom: Pod shows ImagePullBackOff or ErrImagePull.

Causes and fixes:

  • Wrong image name or tag: verify the image exists in Harbor.
  • Missing pull secret: ensure the namespace has an image pull secret configured. Check: kubectl get secrets -n <namespace> for a secret of type kubernetes.io/dockerconfigjson.
  • Harbor unreachable: check the service cluster status with your TrueFullstaq engineer.

# Pod CrashLoopBackOff

Symptom: Pod restarts repeatedly; kubectl get pods shows CrashLoopBackOff.

Diagnosis:

# View logs from the last (crashed) run
kubectl logs <pod-name> -n <namespace> --previous

# Check events
kubectl describe pod <pod-name> -n <namespace>

Common causes: missing environment variable, failed health check, application startup error.

# ArgoCD shows OutOfSync

Symptom: Application is OutOfSync in the ArgoCD UI even after a sync.

Causes and fixes:

  • Resource exists outside Git: a resource was created manually with kubectl apply. Fix: either add it to Git, or delete it and let ArgoCD recreate it.
  • Sync hook failure: a PreSync or PostSync hook job failed. Fix: check the hook job logs in the ArgoCD UI under the application’s resource tree.
  • Comparison error: a field is being modified by a controller (e.g. status). Fix: add an ignore difference annotation or contact TrueFullstaq.

# Secret not syncing from OpenBao

Symptom: ExternalSecret shows SecretSyncedError or the Kubernetes Secret is missing.

Diagnosis:

kubectl describe externalsecret <name> -n <namespace>

Causes and fixes:

  • Wrong path: verify the key in the ExternalSecret matches the path in OpenBao.
  • OpenBao sealed: OpenBao requires manual unseal after a restart. Contact TrueFullstaq.
  • Missing permissions: the ESO service account may not have read access to that path.

# Cannot connect to the cluster

Symptom: kubectl commands fail with Unable to connect to the server or error: You must be logged in to the server (Unauthorized).

Cluster access uses SSO/OIDC: your kubeconfig signs you in through TrueFullstaq Identity on demand (there are no static or Teleport credentials to renew).

Fix:

  1. Clear any stale SSO token and let the next command trigger a fresh login:

    kubectl oidc-login clean
kubectl get nodes        # opens your browser to sign in via SSO

  2. If it still fails, your kubeconfig may be outdated, so re-download it from the dashboard (https://dash.<CUSTOMER_ID>.truefullstaq.cloud) and select it again.

  3. error: ... (Unauthorized) after a successful browser login means you’re authenticated but lack RBAC for that action; see Access Control.

See Using kubectl for the full setup, including installing the kubectl oidc-login (kubelogin) plugin.