Cluster Troubleshooting

Kubernetes Cluster: Troubleshooting

A Kubernetes cluster contains many interconnected components, so an installation or workload problem can originate at different stages. The platform includes automated error handling and post-installation health checks, while Kubernetes events and pod logs provide the main tools for diagnosing application-level problems.
Installation Diagnostics Use platform error messages, support reports, and the Kubernetes health-check log.
Events Tracking Review Kubernetes events through the Dashboard or kubectl.
Pod Logs Inspect container logs to identify runtime and restart problems.
On this page

Kubernetes Installation Troubleshooting

Kubernetes Cluster installation is fully automated and includes built-in error handling. Common problems are processed automatically, and the detected root cause is shown directly in the platform dashboard when possible.

1Review the installation error

If installation fails, first review the error message shown by the platform. It can identify the cause without requiring manual log analysis.

2Send a support report for complex failures

If the problem requires deeper analysis, use the Send Report action in the error widget. The generated report contains installation logs, error messages, and additional debugging information required by the support team.

Kubernetes cluster installation error with Send Report button
For complex installation failures, use Send Report to provide the support team with diagnostic information.

Post-Installation Health Check

After installation, the Kubernetes package automatically checks the health of the cluster components. Detailed results are stored on the master node in:

/var/log/k8s-health-check.log

The health-check utility verifies the following Kubernetes components:

Weave CNI PluginCluster networking.
Ingress ControllerExternal application routing.
Metrics ServerResource metrics.
Kubernetes DashboardWeb-based cluster management.
Node Problem DetectorNode-level issue detection.
Monitoring ToolsMonitoring components enabled in the cluster.
Remote APIExternal Kubernetes API access when enabled.
NFS StoragePersistent storage service when enabled.
Sample AppSample application deployed with the package.

If the health checker cannot confirm that a component is in Running state, the installation success frame displays a warning.

A health-check warning does not always mean the cluster is broken. Some deployments may still be starting when the automated verification runs.

Check the current state of all pods across all namespaces:

kubectl get pods --all-namespaces
  • If all pods are Running, the cluster is operating normally.
  • If one or more pods remain unhealthy, continue with Kubernetes events and pod-log analysis.

Track Kubernetes Events

Kubernetes events record important activity and errors for resources in a namespace. With sufficient permissions, events can be inspected from either Kubernetes Dashboard or kubectl.

Events in Kubernetes Dashboard

Open the appropriate namespace in Kubernetes Dashboard and review the Events section to see recent scheduling, scaling, container, and resource-related activity.

Kubernetes Dashboard events
Kubernetes Dashboard provides a graphical view of recent cluster events.

Events with kubectl

Use the following command to retrieve events for a specific namespace:

kubectl get events -n $namespace
kubectl get events output
Example output from kubectl showing Kubernetes events for a namespace.
Events are especially useful for identifying scheduling problems, failed image pulls, restart activity, configuration errors, and other lifecycle issues.

Review Pod Logs

After a pod is scheduled on an available node, inspect its logs to understand what is happening inside the running or failing container.

Kubernetes Dashboard Open the pod page and click the Logs button in the top-right corner.
kubectl Use standard Kubernetes pod-management and logging commands to retrieve container logs from the command line.

Pod logs can reveal application startup errors, configuration problems, unavailable dependencies, crashes, and repeated container restarts.

Example: Pod logs are a key place to investigate events such as Back-off restart failed container, where Kubernetes repeatedly attempts to restart a container that exits or crashes.

When to Contact Support

If the cluster remains unhealthy after checking pod state, events, and container logs, contact the platform support team.

  • Describe the installation or runtime problem clearly.
  • Include relevant Kubernetes events and pod states.
  • Attach Kubernetes-related log files from the master node’s /var/log directory.
  • Use Send Report when an installation-error widget provides that option.
Troubleshooting sequence: Start with the platform error message, review the Kubernetes health-check log, verify pod status, inspect events, then review pod logs. Escalate to support with the collected diagnostics if the issue remains unresolved.

What’s next?