How to Inspect Kubernetes Workloads

This guide shows you how to read the status of every Axual pod, how to get the events behind a pod that will not start, how to read a pod’s logs including the logs of the run before it crashed, and where log files sit on a local installation.

Type

How-to guide

Goal

Establish what a failing component is doing, from its status, its events and its logs.

Audience

Platform Operator with read access to pods and their logs in the Axual namespaces.

When to use

Use this guide as the first step on any component problem, before changing anything.
For an alert firing on a production cluster that has to be resolved now, go to Acting on Alerts instead. This guide is for diagnosis, not for a runbook response.

Contents

The sections below cover each task in this guide:

Prerequisites

Confirm the following before you begin.

Access and permissions required

You need the following access and permissions:

  • Read access to pods, pod events and pod logs in the namespaces the platform runs in.

  • Access to the cluster’s central logging stack, for anything beyond the last run of a single pod.

Tools and versions required

You need the following tools:

  • kubectl >= 1.28, configured for the target cluster. The kubectl reference covers the commands below in full.

  • docker, for the local-installation section only.

Resources that must exist before starting

The following must already exist:

  • The namespace names your platform uses. The examples below use kafka for the platform and nginx for the ingress controller.

The ingress namespace is often not nginx. The community ingress-nginx controller was deprecated in March 2026 and Axual migrated its managed clusters to a supported controller, so check with your cluster administrator which namespace the ingress runs in.

List the status of every pod

Kubernetes manages the platform’s containers and restarts them when a health check fails, so pod status is the fastest read on what is wrong.

Replace every <VALUE> placeholder with your own value before running a command. 
kubectl get pods --namespace kafka
kubectl get pods --namespace nginx

Expected output lists every pod with its state:

NAME                                                  READY   STATUS      RESTARTS        AGE
axual-governance-api-gateway-6dff79c9d9-rrckq         1/1     Running     1 (2d22h ago)   4d3h
axual-governance-keycloak-0                           1/1     Running     2 (7h3m ago)    6d1h
axual-governance-platform-manager-694475c59c-kn9x4    1/1     Running     4 (7h3m ago)    6d1h

Every pod should read Running or Completed. Completed is correct for the initialisation pods, which do their work and stop. On a system that started recently, give the rest time to reach Running before treating anything as a failure.

Read the events behind a failing pod

A pod that never starts usually has no logs to read, because nothing got as far as running. Its events do hold the reason.

kubectl describe pod <POD_NAME> --namespace kafka

Read the status block and the Events list at the bottom. Events routinely name a cause that never appears in the logs, such as an image that cannot be pulled or a Secret that does not exist, which is why this is worth running on every failed startup.

Read a pod’s logs

Read the logs directly for a problem you can reproduce. For anything historical, or spanning more than one pod, use the central stack instead: central logging holds what kubectl no longer can.

kubectl logs <POD_NAME> --namespace kafka
kubectl logs <POD_NAME> --namespace kafka --previous

--previous returns the logs of the run before the current one, which is the only way to see why a pod that is now restarting crashed.

If the logs say nothing useful, raise the level. See How to Configure Logging, which also covers doing it in place while diagnosing rather than through a full deployment cycle.

Obtain log files on a local installation

A local installation usually has no central stack, so reading the log files off disk is sometimes the only option. Kubernetes writes them under /var/log/pods/<namespace>_<pod_name>_<pod_id>/<container_name>/, and most Axual pods hold more than one container.

On macOS, Kubernetes runs inside a virtual machine, so the files are not on the host filesystem and you have to enter that machine first. Attaching a container that shares the log directory is the more reliable of the two routes:

This command starts a privileged container in the host PID namespace and gives you a root shell on the virtual machine itself, outside every Kubernetes boundary. Run it only on a local development machine, never on a shared or production cluster, and exit the shell as soon as you have the logs. 
docker run -it --privileged --pid=host debian nsenter -t 1 -m -u -n -i sh

Attaching to the virtual machine’s console also works on some versions, though the path differs between macOS releases:

screen ~/Library/Containers/com.docker.docker/Data/vms/0/tty