Introduction

kubectl -o jsonpath=... is useful for extracting specific fields from Kubernetes objects, but the syntax becomes awkward when the path contains keys with dots, slashes, or other special characters. In those cases, the answer is usually to switch from dot notation to bracket notation so the field name is treated as a literal key.

Use Dot Notation for Simple Paths

For ordinary field names, dot notation is fine.

kubectl get pod my-pod -o jsonpath='{.metadata.name}'

That works because metadata and name are normal path components.

Use Bracket Notation for Named Keys with Special Characters

Annotations and labels often contain dots or slashes, which break plain dot notation. Use brackets with quoted keys instead.

kubectl get ingress my-ingress \
  -o jsonpath="{.metadata.annotations['nginx.ingress.kubernetes.io/rewrite-target']}"

That pattern is the main answer when people ask about a "named path" in kubectl JSONPath. The key is not a nested object path. It is one literal key string.

The same rule applies to labels:

kubectl get pod my-pod \
  -o jsonpath="{.metadata.labels['app.kubernetes.io/name']}"

Iterate Over Arrays and Print Named Fields

JSONPath becomes more useful when you combine iteration with named fields.

kubectl get pods -A \
  -o jsonpath='{range .items[*]}{.metadata.namespace}{"/"}{.metadata.name}{"\t"}{.status.phase}{"\n"}{end}'

This loops over the items array and prints selected fields from each object.

If a label key includes punctuation, combine iteration and bracket notation:

kubectl get pods -A \
  -o jsonpath="{range .items[*]}{.metadata.name}{': '}{.metadata.labels['app.kubernetes.io/name']}{'\n'}{end}"

Debug with Full YAML or JSON First

When the JSONPath expression does not work, inspect the real object structure first.

kubectl get pod my-pod -o yaml

This is especially important for annotations, nested status fields, or list structures. Many JSONPath mistakes come from guessing the object shape rather than reading it.

Watch the Quoting Rules in Your Shell

A correct JSONPath expression can still fail because of shell quoting. Single quotes, double quotes, and backslashes all matter.

A practical rule is:

• use outer single quotes when the expression itself does not need shell interpolation
• use outer double quotes when the expression contains inner single-quoted bracket keys

That is why many examples use a mix of both.

JSONPath Is Great for Extraction, Not Complex Logic

Once the expression starts looking like a small programming language, it is often simpler to switch to -o json and pipe the result into jq. kubectl JSONPath is excellent for concise field extraction, but it is not the most ergonomic tool for complicated transformations or conditional formatting.

Format Output Deliberately for Shell Use

A small JSONPath expression often becomes much more useful once you add separators such as tabs and newlines intentionally. Good output formatting turns the command from a one-off inspection trick into something that can be piped into other shell tools or pasted into logs without extra cleanup.

Common Pitfalls

• Using dot notation for annotation or label keys that contain dots or slashes.
• Guessing the object structure without checking -o yaml or -o json output first.
• Forgetting that arrays need iteration such as {range .items[*]}.
• Blaming JSONPath when the real issue is shell quoting.
• Treating a literal key name as if it were a nested JSON path.

Summary

• Use dot notation for simple Kubernetes field paths.
• Use bracket notation for literal keys such as annotations and labels with punctuation.
• Combine range with JSONPath to print repeated fields from arrays.
• Inspect the real object structure before writing complex expressions.
• Most named-path problems in kubectl are really key-literal and quoting problems.