lookout state volumes

When pods hang in ContainerCreating with Multi-Attach or FailedAttachVolume events — join VolumeAttachment + PV/PVC + pods to name the exact conflict: RWO claims wanted on two nodes, attachments stuck in error, cross-zone PV locks, orphaned attachments.

MCP tool: k8s_volume_conflicts

Usage

lookout state volumes [flags]

Common flags (every lookout command)

Flag	Type	Default	Meaning
--namespace	string	—	limit the scan to one namespace
-A	bool	—	scan all namespaces
--workload	string	—	target one workload as <Kind>/<namespace>/<name>, e.g. Deployment/prod/api
--since	duration	—	how far back to look (0 = command default)
--format	string	logfmt	output format: logfmt|json (one record per line either way)
--timeout	duration	10s	abort the invocation after this long (exit 1)
--kubeconfig	string	—	path to a kubeconfig file, instead of $KUBECONFIG / ~/.kube/config
--context	string	—	kubeconfig context to read, instead of its current-context. Selects a cluster for THIS invocation only — nothing is written back — so concurrent invocations can target different clusters. Reported as context=<name> in the summary line
--exemptions	string	—	path to a git-reviewed exemption file (YAML); covered findings are ANNOTATED with their reason and expiry and counted as exempt=<n> in the summary, never dropped

Finding kinds

Every kind= this command can emit, and the severities it carries them at. Nothing else appears in its output; a kind absent from a run means the check looked and found nothing. See the finding-kind glossary for the whole vocabulary.

Kind	Severity	Claim
volume.multi_attach	critical	an RWO claim is wanted by pods on more than one node — the second pod never starts
volume.zone_conflict	critical	the PV is locked to a zone the pod’s node is not in
volume.attach_error	critical, warning	the attach or detach is failing; critical once it has been failing long enough to be stuck rather than slow
volume.orphaned_attachment	info	a VolumeAttachment survives its PV or its node

Output fields

Beyond the shared envelope fields (kind, severity, namespace, kind_of_object, name, reason, message, fingerprint, exempt_reason, exempt_expires):

Field	Meaning
pods	scheduled pods referencing the conflicted claim, sorted (list capped, then +K more)
nodes	distinct nodes those pods are scheduled on, sorted
access_modes	the claim’s declared access modes
pv	PersistentVolume behind the claim or attachment
pvc	PersistentVolumeClaim the pod mounts (same namespace as the pod)
node	node the attachment targets or the pod is scheduled on
attacher	CSI driver responsible for the attachment (spec.attacher)
age	how long the attach/detach error has persisted, truncated to seconds
error	the attach/detach error message, truncated to 200 chars
attached	the attachment’s status.attached at scan time
pv_zones	zones the PV’s node affinity allows, sorted
node_zone	zone label of the node the pod is scheduled on
orphan	which referenced side is gone: “pv missing”, “node missing”, or both

Output contract

Output: one finding per line (logfmt; —format=json for one JSON object per line), keys in fixed order; healthy resources emit nothing. The final line is always the summary: scanned= findings= elapsed= — findings=0 with a summary present means “scanned and healthy”; a stream without a summary line is void. Exit 0 data, 1 runtime error (diagnostics on stderr only), 2 usage.

Examples

lookout state volumes
lookout state volumes --namespace=prod
lookout state volumes --format=json