Health Checks & Troubleshooting
Diagnose common deployment and runtime issues.
Health check
1kubectl port-forward svc/dev-sdk 8080:80802curl http://localhost:8080/health
Common issues
Image pull error (ErrImagePull / ImagePullBackOff)
Root cause: DockerHub pull secret is missing, incorrect, or not referenced. Step 1 — verify secret exists: kubectl get secret securelytix-dockerhub. Step 2 — confirm deployment uses it: kubectl get deployment dev-sdk -o jsonpath='{.spec.template.spec.imagePullSecrets}'. Step 3 — verify image is pullable: docker login -u securelytix2026 && docker pull securelytix2026/dev-sdk:1.0.4
zsh: no matches found: imagePullSecrets[0].name
Wrap the imagePullSecrets argument in double quotes: --set "imagePullSecrets[0].name=securelytix-dockerhub"
PostgreSQL connection failed / password authentication failed for user 'admin'
The bundled PostgreSQL uses user vault, not admin. Connect with: psql postgresql://vault:vault@localhost:5432/vault
Pod stuck in Pending state
Insufficient cluster resources or a PersistentVolumeClaim that cannot be bound. Run: kubectl describe pod -l app.kubernetes.io/instance=dev-sdk && kubectl get pvc
401 Unauthorized on /tokenize
API key is missing, malformed, or invalid. Verify: kubectl get secret dev-sdk-secrets -o jsonpath='{.data.api-key}' | base64 -d
429 Too Many Requests
Traffic exceeds the configured rate limit (25 req/sec default). Increase with: helm upgrade dev-sdk securelytix/dev-sdk --set config.requestLimit=200 --reuse-values
Useful diagnostic commands
| Task | Command |
|---|---|
| List SDK pods | kubectl get pods -l app.kubernetes.io/instance=dev-sdk |
| Stream logs | kubectl logs -l app.kubernetes.io/instance=dev-sdk -f |
| Last 50 log lines | kubectl logs -l app.kubernetes.io/instance=dev-sdk --tail=50 |
| Describe pod (events) | kubectl describe pod <pod-name> |
| List Helm releases | helm list |
| Show current chart values | helm get values dev-sdk |
| Port-forward SDK | kubectl port-forward svc/dev-sdk 8080:8080 |
| Port-forward database | kubectl port-forward svc/dev-sdk-postgresql 5432:5432 |
| Resource usage | kubectl top pod -l app.kubernetes.io/instance=dev-sdk |
| Pod events | kubectl get events --sort-by='.lastTimestamp' |