常見問題與故障排除
快速診斷流程
常見問題表格
| 問題症狀 | 可能原因 | 解決方式 |
|---|---|---|
| UI 無法開啟(connection refused) | port-forward 未執行或已中斷 | 重新執行 kubectl port-forward -n sentinel-system svc/sentinel 8080:80 |
| 登入失敗(帳號密碼錯誤) | 預設帳號已被修改或遺忘 | 重置 users.json(見下方步驟) |
| Policy 套用後無效 | 模式為 Monitoring(非 Protect) | 在 Tracing Policy 列表切換該 Policy 的 Mode,或以頁面頂部的 Global Protect Mode banner 全域切換為 ON |
| Behavior Discovery 無資料 | Tetragon Agent 未正常運作 | 確認 tetragon DaemonSet 狀態(見下方步驟) |
| Security Events 頁面空白 | TracingPolicy 尚未建立,或 Tetragon 事件串流中斷 | 先到「Cluster → Event Sources」確認各節點 Ingestion 為 Connected(Stream Down 時檢查 Tetragon gRPC 綁定與網路),再確認已建立 TracingPolicy |
Vulnerabilities 頁面顯示 Trivy Operator was not found in this cluster. | 尚未安裝 Trivy Operator(只套用 deploy/sentinel.yaml 不會安裝) | 依 安裝 Trivy Operator 安裝 |
Vulnerabilities 頁面顯示 Sentinel is not permitted to read vulnerability reports. | 從 v0.59 以前升級,ClusterRole 缺少 vulnerabilityreports 讀取規則 | 重新套用 deploy/sentinel.yaml |
工作負載一直停在 partial 或 Not scanned | Trivy Operator 以舊版 values 安裝,沒有共用的 Trivy server,掃描容器互搶快取鎖(cache may be in use by another process);或掃描逾時 | 以目前的 deploy/trivy-operator-values.yaml 執行 helm upgrade,再 rollout restart deployment/trivy-operator(見 安裝 Trivy Operator) |
| 剛掃描完的結果沒有出現 | 掃描報告摘要快取 5 分鐘 | 在 Vulnerabilities 頁面按 Refresh |
| Registry 掃描以權限錯誤失敗 | 從 v0.61 以前升級,缺少 sentinel-system 內的 Role sentinel-registry-scan | 重新套用 deploy/sentinel.yaml |
Registry 的 Image 掃描出現 context deadline exceeded | v0.63.2(含)以前單一 Image 掃描沿用 Trivy 預設的 5 分鐘上限 | 升級至 v0.63.3+(上限為 13 分鐘) |
quay.io 使用萬用字元 Filter(如 myorg/*)且設定帳密時出現 the registry's token service refused the credentials (HTTP 400) | v0.63.1(含)以前的已知問題 | 升級至 v0.63.2+ |
| YAML 編輯器沒有顯示 | v0.53.0 至 v0.59.4 的編輯器從公開 CDN 載入,被 Content-Security-Policy 擋下(離線叢集也無法載入) | 升級至 v0.59.5+,編輯器已內建於 Image |
| Pod 啟動失敗(CrashLoopBackOff) | ServiceAccount 無法連線叢集或 RBAC 設定錯誤 | 確認 ServiceAccount 與 ClusterRoleBinding 設定是否正確 |
重置管理員密碼
忘記管理員密碼時,依部署方式處理:
未設定永久儲存(預設 emptyDir):帳號資料跟著 Pod 走,直接重啟即會重建預設帳號:
kubectl -n sentinel-system rollout restart deployment sentinel
已掛載 PV / PVC:需刪除儲存卷上的 users.json 再重啟。K8s Sentinel 容器是精簡的單一執行檔映像且以唯讀根檔案系統執行,不一定能以 kubectl exec 進入操作;最可靠的方式是建立一個臨時 Pod 掛載同一個 PVC 來刪檔:
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
重啟完成後以預設帳號 admin / admin 登入,系統會依首次登入流程強制要求設定新密碼(見登入 K8s Sentinel)。
確認 Tetragon Agent 狀態
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
確認所有 tetragon Pod 均處於 Running 狀態,且 log 中無 ERROR 或 FATAL 訊息。若 DaemonSet Pod 數量不足(未覆蓋所有節點),請檢查節點 taints 與 tolerations 設定。
查看 K8s Sentinel 日誌
# 查看最近 100 行日誌
kubectl logs -n sentinel-system deployment/sentinel --tail=100
# 即時追蹤日誌輸出
kubectl logs -n sentinel-system deployment/sentinel -f
日誌中可查看 API 請求記錄、JWT 驗證錯誤、TracingPolicy 操作結果等資訊,有助於快速定位問題根源。
提示
排查問題時,建議先執行以下指令確認 sentinel-system namespace 中所有資源的整體狀態:
kubectl get all -n sentinel-system
確認 Deployment、ReplicaSet、Pod、Service 均處於正常狀態後,再針對個別元件深入排查。