# JSONPath Support

LLMS index: [llms.txt](/llms.txt)

---

<!-- overview -->
The <a class='glossary-tooltip' title='A command line tool for communicating with a Kubernetes cluster.' data-bs-toggle='tooltip' data-bs-placement='top' href='/docs/reference/kubectl/' target='_blank' aria-label='kubectl'>kubectl</a> tool supports JSONPath templates as an output format.


<!-- body -->

A _JSONPath template_ is composed of JSONPath expressions enclosed by curly braces: `{` and `}`.
Kubectl uses JSONPath expressions to filter on specific fields in the JSON object and format the output.
In addition to the original JSONPath template syntax, the following functions and syntax are valid:

1. Use double quotes to quote text inside JSONPath expressions.
2. Use the `range`, `end` operators to iterate lists.
3. Use negative slice indices to step backwards through a list.  
   Negative indices do _not_ "wrap around" a list and are valid as long as \\( ( - index + listLength ) \ge 0 \\).


<div class="alert alert-info" role="note"><h4 class="alert-heading">Note:</h4><ul>
<li>
<p>The <code>$</code> operator is optional since the expression always starts from the root object by default.</p>
</li>
<li>
<p>The result object is printed as its <code>String()</code> function.</p>
</li>
</ul>
</div>


## Functions in Kubernetes JSONPath {#functions}

Given the JSON input:

```json
{
  "kind": "List",
  "items":[
    {
      "kind":"None",
      "metadata":{
        "name":"127.0.0.1",
        "labels":{
          "kubernetes.io/hostname":"127.0.0.1"
        }
      },
      "status":{
        "capacity":{"cpu":"4"},
        "addresses":[{"type": "LegacyHostIP", "address":"127.0.0.1"}]
      }
    },
    {
      "kind":"None",
      "metadata":{"name":"127.0.0.2"},
      "status":{
        "capacity":{"cpu":"8"},
        "addresses":[
          {"type": "LegacyHostIP", "address":"127.0.0.2"},
          {"type": "another", "address":"127.0.0.3"}
        ]
      }
    }
  ],
  "users":[
    {
      "name": "myself",
      "user": {}
    },
    {
      "name": "e2e",
      "user": {"username": "admin", "password": "secret"}
    }
  ]
}
```



 





<table><caption style="display: none;">Functions, their parameters, an example invocation, and the result</caption>
	<thead>
			<tr>
					<th>Function</th>
					<th>Description</th>
					<th>Example</th>
					<th>Result</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>text</code></td>
					<td>the plain text</td>
					<td><code>kind is {.kind}</code></td>
					<td><code>kind is List</code></td>
			</tr>
			<tr>
					<td><code>@</code></td>
					<td>the current object</td>
					<td><code>{@}</code></td>
					<td>the same as input</td>
			</tr>
			<tr>
					<td><code>.</code> or <code>[]</code></td>
					<td>child operator</td>
					<td><code>{.kind}</code>, <code>{['kind']}</code> or <code>{['name\.type']}</code></td>
					<td><code>List</code></td>
			</tr>
			<tr>
					<td><code>..</code></td>
					<td>recursive descent</td>
					<td><code>{..name}</code></td>
					<td><code>127.0.0.1 127.0.0.2 myself e2e</code></td>
			</tr>
			<tr>
					<td><code>*</code></td>
					<td>wildcard. Get all objects</td>
					<td><code>{.items[*].metadata.name}</code></td>
					<td><code>[127.0.0.1 127.0.0.2]</code></td>
			</tr>
			<tr>
					<td><code>[start:end:step]</code></td>
					<td>subscript operator</td>
					<td><code>{.users[0].name}</code></td>
					<td><code>myself</code></td>
			</tr>
			<tr>
					<td><code>[,]</code></td>
					<td>union operator</td>
					<td><code>{.items[*]['metadata.name', 'status.capacity']}</code></td>
					<td><code>127.0.0.1 127.0.0.2 map[cpu:4] map[cpu:8]</code></td>
			</tr>
			<tr>
					<td><code>?()</code></td>
					<td>filter</td>
					<td><code>{.users[?(@.name==&quot;e2e&quot;)].user.password}</code></td>
					<td><code>secret</code></td>
			</tr>
			<tr>
					<td><code>range</code>, <code>end</code></td>
					<td>iterate list</td>
					<td><code>{range .items[*]}[{.metadata.name}, {.status.capacity}] {end}</code></td>
					<td><code>[127.0.0.1, map[cpu:4]] [127.0.0.2, map[cpu:8]]</code></td>
			</tr>
			<tr>
					<td><code>''</code></td>
					<td>quote interpreted string</td>
					<td><code>{range .items[*]}{.metadata.name}{'\t'}{end}</code></td>
					<td><code>127.0.0.1      127.0.0.2</code></td>
			</tr>
			<tr>
					<td><code>\</code></td>
					<td>escape termination character</td>
					<td><code>{.items[0].metadata.labels.kubernetes\.io/hostname}</code></td>
					<td><code>127.0.0.1</code></td>
			</tr>
	</tbody>
</table>


## Using JSONPath expressions with kubectl {#use-with-kubectl}

Examples using `kubectl` and JSONPath expressions:

```shell
kubectl get pods -o json
kubectl get pods -o=jsonpath='{@}'
kubectl get pods -o=jsonpath='{.items[0]}'
kubectl get pods -o=jsonpath='{.items[0].metadata.name}'
kubectl get pods -o=jsonpath="{.items[*]['metadata.name', 'status.capacity']}"
kubectl get pods -o=jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.startTime}{"\n"}{end}'
kubectl get pods -o=jsonpath='{.items[0].metadata.labels.kubernetes\.io/hostname}'
```

Or, with a "my_pod" and "my_namespace" (adjust these names to your environment):

```shell
kubectl get pod/my_pod -n my_namespace -o=jsonpath='{@}'
kubectl get pod/my_pod -n my_namespace -o=jsonpath='{.metadata.name}'
kubectl get pod/my_pod -n my_namespace -o=jsonpath='{.status}'
```


<div class="alert alert-info" role="note"><h4 class="alert-heading">Note:</h4><p>On Windows, you must <em>double</em> quote any JSONPath template that contains spaces (not single quote as shown above for bash). This in turn means that you must use a single quote or escaped double quote around any literals in the template. For example:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-cmd" data-lang="cmd"><span class="line"><span class="cl">kubectl get pods -o=jsonpath=<span class="s2">&#34;{range .items[*]}{.metadata.name}{&#39;\t&#39;}{.status.startTime}{&#39;\n&#39;}{end}&#34;</span>
</span></span><span class="line"><span class="cl">kubectl get pods -o=jsonpath=<span class="s2">&#34;{range .items[*]}{.metadata.name}{\&#34;</span>\t\<span class="s2">&#34;}{.status.startTime}{\&#34;</span>\n\<span class="s2">&#34;}{end}&#34;</span>
</span></span></code></pre></div></div>


## Regular expressions in JSONPath

JSONPath regular expressions are not supported. If you want to match using regular expressions, you can use a tool such as `jq`.

```shell
# kubectl does not support regular expressions for JSONpath output
# The following command does not work
kubectl get pods -o jsonpath='{.items[?(@.metadata.name=~/^test$/)].metadata.name}'

# The following command achieves the desired result
kubectl get pods -o json | jq -r '.items[] | select(.metadata.name | test("test-")).metadata.name'
```