kubectl
JSON output
kubernetes
command line
data formatting

How to format the output of kubectl describe to JSON

System Design practice on Codemia

Work through 120+ system design problems with detailed solutions, from rate limiters to multi-region storage.

Practice system design

Introduction

kubectl describe is designed for human-readable diagnostics, not machine parsing. If you need JSON for scripts, dashboards, or automation, the correct approach is to query the same resource with kubectl get -o json and optionally combine it with field filtering. Understanding this distinction prevents brittle parsing pipelines.

Why describe Cannot Be Reliably Converted

kubectl describe prints formatted text that mixes sections, nested lists, and event tables. The exact layout can vary by Kubernetes version and resource type. Text scraping this output with ad hoc regular expressions is fragile and usually breaks during upgrades.

Instead of converting describe output, fetch the resource object directly:

bash
kubectl get pod my-pod -n prod -o json

This returns stable JSON fields under metadata, spec, and status, which are intended for API consumers.

Map Common describe Needs to JSON Queries

Most information people seek in describe already exists in structured fields.

Pod images and restart counts:

bash
kubectl get pod my-pod -n prod -o json \
| jq '.spec.containers[] | {name: .name, image: .image}' kubectl get pod my-pod -n prod -o json \ | jq '.status.containerStatuses[] | {name: .name, restartCount: .restartCount}' ``` Node selector and tolerations from a deployment: ```bash kubectl get deploy api -n prod -o json \ | jq '.spec.template.spec | {nodeSelector, tolerations}' ``` These commands are deterministic and safer for automation than free-form text parsing. ## Use JSONPath for Lightweight Extraction If you want quick shell output without `jq`, JSONPath is built into `kubectl`. ```bash kubectl get pods -n prod \ -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.phase}{"\n"}{end}' ``` For a single field: ```bash kubectl get svc web -n prod -o jsonpath='{.spec.clusterIP}' ``` JSONPath is convenient for one-line extraction, while `jq` is better for complex transformations. ## Recreate Event Insights from `describe` Many users rely on `describe` for event history. You can query events directly in JSON and filter by object reference. ```bash kubectl get events -n prod -o json \ | jq '.items[] | select(.involvedObject.kind == "Pod" and .involvedObject.name == "my-pod") | {type: .type, reason: .reason, message: .message, time: .lastTimestamp}' ``` For modern clusters, event timestamps may be exposed in multiple fields, so include a fallback when building automation. ## Build Robust Automation Scripts The script below checks every pod in a namespace and prints any container waiting reason. ```bash #!/usr/bin/env bash set -euo pipefail ns="prod" json=$(kubectl get pods -n "$ns" -o json) echo "$json" | jq -r ' .items[] as $pod | $pod.status.containerStatuses[]? | select(.state.waiting != null) | [$pod.metadata.name, .name, .state.waiting.reason] | @tsv ' ``` This style is resilient because it uses the Kubernetes API schema instead of terminal formatting. ## When You Still Need `describe` `describe` remains useful for human triage because it summarizes conditions and recent events in one screen. The key practice is using `describe` for interactive investigation and `get -o json` for tooling. A balanced workflow looks like this: * run `describe` when debugging manually * switch to JSON queries for repeatable checks * codify query logic in scripts and CI jobs ## Common Pitfalls * Trying to parse `kubectl describe` output with regular expressions in production scripts. * Assuming event field names are identical across all cluster versions. * Forgetting namespace flags, which causes queries to read from the default namespace. * Mixing JSONPath quoting styles incorrectly in shell commands. * Writing automation that depends on column order from table-formatted output. ## Summary * `kubectl describe` is for people, not for machine-stable JSON workflows. * Use `kubectl get ... -o json` to retrieve structured resource data. * Prefer `jq` for complex transformations and JSONPath for quick field extraction. * Query events directly when reproducing diagnostic context from `describe`. * Keep automation tied to API schema, not human-formatted terminal output.

Related reading
Course
Beginner
27 lessons
10 hours
System Design Fundamentals

Build a strong foundation in designing scalable, reliable distributed systems.

View the course
Track what you have practised

A free account saves your progress, solutions and study plan across every problem on Codemia.

System Design practice on Codemia

Work through 120+ system design problems with detailed solutions, from rate limiters to multi-region storage.

Practice system design

All Rights Reserved.