Troubleshooting workloads

Logs, terminal, events in the GUI and console, common errors and network problems.

When diagnosing pod and workload issues, use container logs, events (Events), and, when needed, the pod terminal. In the Shturval GUI, all of these are available on the pod page and on workload pages (Deployment, StatefulSet, and so on). Below is where to look in the GUI, how to run the same checks with kubectl, typical errors, and links to the official Kubernetes documentation.

Where to start: logs, events, terminal #

Recommended order: first look at events (reason for scheduling, image, crashes), then logs of the pod; if necessary, open a terminal to manually check inside the container.

View pod logs #

In the GUI #

1. Go to Loads → Pods (or open the workload → Pods tab) and select a pod.
2. On the pod page, open the Logs tab.
3. Select a container (if there are several of them), if necessary, enable previous log (container logs before the last restart), set a time range or search by text, and download the logs if necessary.

On the Logs tab, you can select a container, auto-update, display a timestamp and the previous log, the number of records (100 by default), time range, text search and download a log file.

In the console (kubectl) #

# Logs of the main container
kubectl logs <pod-name> -n <namespace>

# Logs of a specific container (if pod has multiple)
kubectl logs <pod-name> -n <namespace> -c <container-name>

# Stream logs in real time (like tail -f)
kubectl logs -f <pod-name> -n <namespace>

# Logs from the last hour
kubectl logs <pod-name> -n <namespace> --since=1h

# Logs of previous container (after restart — important for CrashLoopBackOff)
kubectl logs <pod-name> -n <namespace> --previous

# Last N lines
kubectl logs <pod-name> -n <namespace> --tail=100

View Events #

Events help you understand why a pod was not scheduled, cannot pull its image, keeps crashing, or never becomes Ready.

In the GUI #

• By namespace: open the namespace dashboard → Events tab. Events of all namespace objects are displayed (creation/deletion, scheduling errors, resource warnings). More details: Namespace dashboard overview - “Events” tab.
• By workload or pod: open the Deployment / StatefulSet / Pod page and go to the Events tab. Events associated with that object are shown here (including FailedScheduling, ImagePullBackOff, Killing, Unhealthy, and others).

The tab title can display the number of events. Pay attention to messages indicating errors and warnings.

In the console (kubectl) #

# Namespace events (most recent last)
kubectl get events -n <namespace> --sort-by='.lastTimestamp'

# Pod details including Events section
kubectl describe pod <pod-name> -n <namespace>

# Warnings only
kubectl get events -n <namespace> --field-selector type=Warning

Official documentation: kubectl events.

Call pod terminal #

Convenient for manually checking files, environment variables and commands inside a container.

In the GUI #

1. Open the pod page (Loads → Pods → select a pod, or from the workload page → Pods tab → pod).
2. Go to the Terminal tab. The tab is displayed only if at least one pod container has a shell (Bash is not supported in the GUI).
3. An interactive console will open inside the container.

Note: Correct operation of the terminal is guaranteed in the Google Chrome browser.

In the console (kubectl) #

# Interactive shell (often /bin/sh)
kubectl exec -it <pod-name> -n <namespace> -- /bin/sh

# If bash is available
kubectl exec -it <pod-name> -n <namespace> -- /bin/bash

# Run one command without entering the container
kubectl exec <pod-name> -n <namespace> -- ls -la /app

Common errors and what to check #

Below are typical states and errors, what to look for in the GUI (events, logs) and how to fix them. For more information, see the official guides: Troubleshooting Applications, Determine the Reason for Pod Failure.

Pending state #

Symptom: remains in the Pending status for a long time, does not change to Running.

Causes and actions:

1. Lack of resources on nodes (Insufficient CPU / Insufficient memory)
   Pod or namespace events usually have a message like 0/N nodes are available: N Insufficient cpu, N Insufficient memory.

   • In the GUI: check the Events tab on the pod or namespace dashboard page.
   • Solution: reduce requests (and if necessary limits) in the pod/Deployment manifest; or ask your administrator to add nodes/increase quotas.

2. Mismatch of node taints and tolerations
   A pod cannot be scheduled to nodes with taints unless the pod has suitable tolerations.

   • Check the events (in the GUI - Events tab; in the console - kubectl describe pod <pod>).
   • Add the appropriate tolerations to the pod spec or change the taints on the nodes (via the administrator).

3. Using hostPort
   Limits the selection of nodes. If possible, use Service instead of hostPort.

Example of checking in the console:

kubectl describe pod <pod-name> -n <namespace>
# In Events block look for FailedScheduling and reason text

CrashLoopBackOff #

Symptom: Pod keeps restarting, status is CrashLoopBackOff.

Causes (often): error in the application at startup, exceeding the memory limit (OOMKilled), incorrect environment variables or configuration, missing dependencies (DB, external service), too strict or incorrect readiness/liveness probes, volume mounting errors.

What to do:

1. Logs of the previous container - often the reason for the crash is visible there.
   • In the GUI: pod page → Logs tab → enable the option to display previous log (logs before the last restart).
   • In the console: kubectl logs <pod-name> -n <namespace> --previous
2. Events — on the pod or workload page, open the Events tab; in the console: kubectl describe pod <pod-name>. Look for messages about Killing, Unhealthy, Back-off restarting.
3. Check: image and tag, environment variables, mounting secrets/ConfigMap, availability of database and external services, probes settings (initial delay, timeouts, ports).

See also: Determine the Reason for Pod Failure (termination message, logs).

OOMKilled (Out Of Memory) #

Symptom: the container is terminated due to exceeding the memory limit (in events/status - OOMKilled).

Cause: Memory consumption is higher than resources.limits.memory value.

Solution:

1. Increase memory.limits (and optionally memory.requests) in the Deployment/Pod manifest.
2. Optimize the application (memory leaks, caches, pool sizes).
3. Check the logs and metrics before the crash (in the GUI - Logs tab, metrics block on the workload page).

Example:

resources:
  limits:
    memory: "512Mi"   # increase if needed
  requests:
    memory: "256Mi"

ImagePullBackOff / ErrImagePull #

Symptom: Pod cannot load image, status is ImagePullBackOff or ErrImagePull.

Causes: incorrect image name or tag, image in a private registry without credentials, no network access to the registry.

What to do:

1. Check the image name and tag in the manifest (in the GUI - Manifest or Pod Template tab).
2. Make sure that the image exists in the registry (accessible from cluster nodes).
3. For a private registry: set imagePullSecrets in the pod (secrets are created in the Namespace → Storage section). See preparing the image and registry before deployment.
4. Check the pod events (Events tab) - the exact reason is often indicated there (for example, 401 Unauthorized, 404 Not Found).

Official: Pull an Image from a Private Registry, ImagePullBackOff.

Init container crashes (Init:Error / Init:CrashLoopBackOff) #

Symptom: the pod stays out of Running; the status shows that an init container failed.

What to do: look at the logs of the init container (in the GUI - on the Logs tab, select this container; in the console - kubectl logs <pod-name> -n <namespace> -c <init-container-name>). Check init container scripts, environment variables, access to dependencies (networks, secrets, volumes). Pod events (Events tab) will also show the reason for the restart.

Liveness / Readiness probe failed #

Symptom: in pod events messages about failed liveness or readiness probe; pod is restarted or does not get into Service.

What to do:

1. Check the application logs (Logs tab) to see if the application crashes due to a timeout or an error along the scan path.
2. Make sure that the port, path and check period in livenessProbe / readinessProbe are appropriate for the application (the initial delay initialDelaySeconds may be too low).
3. If necessary, temporarily relax or disable the probe (debug only).

Network problems #

Pod cannot connect to another service #

Check:

1. Does Service exist for the target application: in the GUI - the Services section in the namespace; in the console - kubectl get svc -n <namespace>.
2. DNS name: inside the cluster - <service-name>.<namespace>.svc.cluster.local; in the same namespace you can use the short name <service-name>.
3. The ports of the Service and the container match.
4. Network policies (NetworkPolicy) do not block traffic: kubectl get networkpolicy -n <namespace>. If necessary, contact your cluster administrator.

Ingress does not open the application #

Check: presence and functionality of Ingress Controller; correctness of host, path and backend in the Ingress resource; DNS and TLS certificate when using HTTPS. If necessary, check the Ingress and controller pod events (Events tabs in the GUI).

No requests/limits #

Problem: containers do not have requests and limits set.

Consequences: HPA over CPU/memory does not work; VPA cannot calculate recommendations correctly; Node overload and unpredictable scheduling are possible.

Solution: set requests and limits in the manifest (in the GUI - the form for creating/editing a pod or the Manifest tab):

resources:
  requests:
    cpu: "100m"
    memory: "128Mi"
  limits:
    cpu: "500m"
    memory: "512Mi"

VPA does not calculate recommendations #

Problem: the VPA tab has no recommendations, or the VPA object is not created.

Check:

1. The cluster collects metrics: the workload page shows CPU and RAM charts. If there are no charts, install or enable shturval-metrics-collector. Without metrics, VPA cannot compute recommended resources.
2. The workload has only one VPA object. Multiple VPAs matching the same pods have undefined behavior.
3. HPA and VPA do not control the same resource (CPU or Memory). If you need both, configure different resources or use VPA in Off / Initial mode.
4. VPA conditions on the tab: green indicates status True, red indicates any other value. Click a condition type to see the reason, message, and last check time.

More details: VPA on deployment.

Exceeding the namespace quota #

Symptom: the pod is not created, in the events there is an error about exceeding the quota (ResourceQuota).

Solution: check the namespace quotas (in the GUI - namespace dashboard Quotas block Quotas; in the console - kubectl describe quota -n <namespace>). Reduce the total requests of the pods in the namespace or ask the administrator to increase the quota.

Lack of resources on nodes #

Symptom: pod in Pending, in events - insufficient CPU/memory on nodes.

Solution: check node usage (kubectl top nodes); reduce pod requests or contact your admin to add nodes/clean up unused pods and images.

Incorrect Tolerations #

Symptom: pod in Pending; in events - cannot be scheduled due to taints of nodes.

Solution: check the taints of the nodes (kubectl describe node <node-name> | grep Taints) and add the appropriate tolerations to the pod spec (or agree with the administrator on changing the taints). Example:

spec:
  tolerations:
  - key: "key1"
    operator: "Equal"
    value: "value1"
    effect: "NoSchedule"

General recommendations for troubleshooting #

1. Events first - the Events tab on the namespace dashboard or on the workload page often immediately indicates the reason (FailedScheduling, ImagePullBackOff, Killing, probe failed).
2. Then logs - Logs tab on the pod page (in case of crashes, turn on the “previous log”).
3. Pod Terminal - for manually checking files and commands inside the container.
4. Check dependencies - DB, external APIs, ConfigMap/Secret and volume mounting.
5. Check the manifest - in the GUI, the Manifest tab on the workload page; make sure that the image, resources, probes and environment are set correctly.

Useful kubectl commands #

# Pod description (events, conditions, containers)
kubectl describe pod <pod-name> -n <namespace>

# Namespace events
kubectl get events -n <namespace> --sort-by='.lastTimestamp'

# Events for a specific pod
kubectl get events -n <namespace> --field-selector involvedObject.name=<pod-name>

# Resource usage
kubectl top nodes
kubectl top pods -n <namespace>

# Network policies
kubectl get networkpolicy -n <namespace>

# Service and endpoints
kubectl get svc, endpoints -n <namespace>

Additional materials #

• Troubleshooting Applications - overview of debugging applications in Kubernetes.
• Determine the Reason for Pod Failure - termination message of the container.
• Debug Init Containers - debugging init containers.
• Images (ImagePullBackOff) - images and loading errors.
• How to deploy an application - creating and managing workloads in the GUI.
• Namespace dashboard overview - “Events” tab for namespace.