Skip to main content

Troubleshooting

Quick Diagnosis Flow​

Common Issues​

SymptomPossible CauseSolution
UI not loading (connection refused)port-forward not running or interruptedRe-run kubectl port-forward -n sentinel-system svc/sentinel 8080:80
Login failed (wrong credentials)Default account has been changed or forgottenReset users.json (see steps below)
Policy has no effect after applyingMode is Monitoring (not Protect)Switch the policy Mode on the Tracing Policy list, or flip the Global Protect Mode banner at the top of that page to ON
No data in Behavior DiscoveryTetragon Agent not running normallyCheck tetragon DaemonSet status (see steps below)
Security Events page is emptyNo TracingPolicy created, or a Tetragon event stream is downCheck "Cluster → Event Sources" first: every node should show Ingestion Connected (on Stream Down, check the Tetragon gRPC bind and network), then confirm a TracingPolicy exists
The Vulnerabilities page shows Trivy Operator was not found in this cluster.Trivy Operator is not installed yet (applying only deploy/sentinel.yaml does not install it)Install it by following Installing Trivy Operator
The Vulnerabilities page shows Sentinel is not permitted to read vulnerability reports.Upgraded from v0.59 or earlier, and the ClusterRole lacks the vulnerabilityreports read ruleRe-apply deploy/sentinel.yaml
Workloads stay at partial or Not scannedTrivy Operator was installed with older values and has no shared Trivy server, so the scan containers compete for the cache lock (cache may be in use by another process); or the scan timed outRun helm upgrade with the current deploy/trivy-operator-values.yaml, then rollout restart deployment/trivy-operator (see Installing Trivy Operator)
Results of a scan that just finished do not appearThe scan report summaries are cached for 5 minutesClick Refresh on the Vulnerabilities page
Registry scans fail with a permission errorUpgraded from v0.61 or earlier, and the Role sentinel-registry-scan in sentinel-system is missingRe-apply deploy/sentinel.yaml
A registry image scan shows context deadline exceededUp to and including v0.63.2, a single image scan used Trivy's default 5-minute limitUpgrade to v0.63.3+ (the limit is 13 minutes)
On quay.io, a wildcard Filter (such as myorg/*) with credentials set shows the registry's token service refused the credentials (HTTP 400)A known issue up to and including v0.63.1Upgrade to v0.63.2+
The YAML editor does not appearFrom v0.53.0 to v0.59.4 the editor was loaded from a public CDN and blocked by the Content-Security-Policy (it could not load in air-gapped clusters either)Upgrade to v0.59.5+, where the editor is bundled in the image
Pod startup failed (CrashLoopBackOff)ServiceAccount cannot connect to cluster or RBAC misconfigurationVerify ServiceAccount and ClusterRoleBinding are configured correctly

Reset Admin Password​

If the admin password is forgotten, the fix depends on how storage is deployed:

Without persistent storage (the default emptyDir): account data lives and dies with the Pod, so a restart recreates the default account:

kubectl -n sentinel-system rollout restart deployment sentinel

With a PV / PVC mounted: delete users.json from the volume, then restart. The K8s Sentinel container is a minimal single-binary image running with a read-only root filesystem, so kubectl exec may not be available; the reliable way is a temporary Pod mounting the same PVC to remove the file:

kubectl -n sentinel-system run cleanup --rm -it --restart=Never --image=busybox \
--overrides='{"spec":{"containers":[{"name":"cleanup","image":"busybox","command":["rm","/data/users.json"],"volumeMounts":[{"name":"data","mountPath":"/data"}]}],"volumes":[{"name":"data","persistentVolumeClaim":{"claimName":"sentinel-data"}}]}}'

kubectl -n sentinel-system rollout restart deployment sentinel

After the restart, sign in with the default admin / admin; the first-login flow will force you to set a new password (see Sign In to K8s Sentinel).

Check Tetragon Agent Status​

kubectl get pods -n kube-system -l app.kubernetes.io/name=tetragon
kubectl logs -n kube-system -l app.kubernetes.io/name=tetragon --tail=50

Confirm all Tetragon Pods are in Running state and there are no ERROR or FATAL messages in the logs. If the DaemonSet Pod count is insufficient (not covering all nodes), check node taints and tolerations.

View K8s Sentinel Logs​

# View the last 100 lines of logs
kubectl logs -n sentinel-system deployment/sentinel --tail=100

# Follow logs in real time
kubectl logs -n sentinel-system deployment/sentinel -f

Logs contain API request records, JWT authentication errors, TracingPolicy operation results, and other information helpful for quickly pinpointing issues.

tip

When troubleshooting, first run the following command to check the overall status of all resources in the sentinel-system namespace:

kubectl get all -n sentinel-system

After confirming that the Deployment, ReplicaSet, Pod, and Service are all in a normal state, drill down into individual components as needed.