Skip to content

Kubernetes Updated 2026-05-27

Kubernetes troubleshooting

Where to look when something goes wrong on a Stack Harbor PaaS Kubernetes cluster — installation logs, the health check, event streams, and pod logs.

The Stack Harbor PaaS Kubernetes Cluster package is a stack of cooperating components — kubelet, kube-proxy, CNI, ingress controller, dashboard, metrics server, optional Prometheus, optional Jaeger — each of which can fail independently. This page is the entry point to the diagnostic surface: where the platform writes errors, how to read them, and how to escalate when a problem is past self-service.

Three levels of investigation:

  • Installation — the cluster never came up cleanly.
  • Events — the cluster is up but something is misbehaving.
  • Pod logs — a specific workload is misbehaving.

Installation troubleshooting

Cluster installation is automated and includes built-in error handling. The platform catches most recoverable failures and surfaces the root cause directly in the dashboard.

When installation fails:

  1. Read the error surfaced by the installer dialog. Most common causes — a registry credential, a missing license, a resource quota that’s been exhausted — are named directly.
  2. If the root cause isn’t obvious, use the Send Report widget in the installer. The report bundles installation logs, error messages, and platform-level debug information; it goes to Stack Harbor support with enough context to investigate without a back-and-forth.

After a successful install, a dedicated health-check utility runs and validates that the cluster’s components are all Running. Check the result at /var/log/k8s-health-check.log on the master node. The script verifies:

  • The Weave CNI plugin.
  • The ingress controller.
  • The metrics server.
  • The Kubernetes Dashboard.
  • The node problem detector.
  • The monitoring stack (Prometheus / Grafana, if installed).
  • The Remote API access.
  • The NFS storage tier (if enabled).
  • The sample application (if you chose a clean cluster with the example).

If the health checker flags a component as not Running, the post-install pop-up surfaces a warning. The warning isn’t always a real failure — a deployment may simply still be progressing. Run kubectl get pods --all-namespaces to check the actual state. If everything is Running, the cluster is healthy. If something is CrashLoopBackOff, ImagePullBackOff, or stuck Pending, that’s the lead.

Events: cluster-wide state changes

Once the cluster is up, the next layer of diagnostics is the event stream — Kubernetes’ record of what the controllers and the scheduler are doing.

Two surfaces:

  • Kubernetes Dashboard — the Events view, optionally filtered by namespace.

  • kubectl get events — the same data on the command line:

    kubectl get events -n {namespace}

    Add --sort-by='.lastTimestamp' for chronological order, or --watch to follow in real time.

Events surface the reasons behind scheduling decisions, image pull failures, readiness-probe failures, and resource pressure. They’re the right next stop after a pod state lookup.

Pod logs: container-level output

For a misbehaving workload, drop one level deeper to the container’s stdout/stderr.

Two surfaces:

  • Kubernetes Dashboard — open the pod page and click Logs in the top right.

  • kubectl logs:

    kubectl logs {pod-name} -n {namespace}
kubectl logs -f {pod-name} -n {namespace}    # follow
kubectl logs --previous {pod-name} -n {namespace}    # previous container, if crashed
kubectl logs {pod-name} -c {container-name}    # one container in a multi-container pod

Back-off restarting failed container events on a pod almost always have their root cause in the previous container’s log — kubectl logs --previous is the right command in that case.

When to escalate

Self-service runs out when:

  • The cluster’s kube-system pods are unhealthy and a pod-log dive doesn’t reveal a fixable cause.
  • The Remote API isn’t reachable and you’ve ruled out network problems on your side.
  • A node has gone NotReady and reboots / drains don’t recover it.
  • The health check repeatedly flags a component that’s actually running fine, suggesting the check itself is misconfigured.

For those cases, open a ticket with Stack Harbor support. Include:

  • The cluster’s environment name.
  • The Kubernetes version.
  • The output of kubectl get nodes, kubectl get pods --all-namespaces, and the relevant section of /var/log/k8s-health-check.log.
  • Any platform logs from /var/log on the master node that look related.

See also