Kubectl get JSONPath Support

From NovaOrdis Knowledge Base
Jump to navigation Jump to search

External

Internal

Overview

kubectl get -o jsonpath='{<jsonpath-expression>}' ...

supports a JSONPath template, which consists in JSONPath expressions enclosed by curly braces.

kubectl get pod some-pod -o jsonpath='{.status.phase}'

More than one JSONPath expressions can be concatenated in a JSON template:

kubectl get pod some-pod -o jsonpath='the pod name {.metadata.name} and phase {.status.phase}'

The JSONPath expression are mainly used to:

  • Filter the JSON content to only allow specific fields in the JSON object, using filter expressions.
  • Format the output.

The result object is printed as its String() function.

In addition to the original JSONPath syntax, kubectl provides the following extensions:

  • The possibility to use double quotes to quote text inside JSONPath expressions.
  • The availability of the range and end operators to iterate lists.

Note that when the result of the kubectl query contains more than one item, it is returned as a "List" top-level JSON Object, where individual results are element of an ".items" array:

{
  "apiVersion": "v1",
  "kind": "List",
  "metadata": {
    "resourceVersion": "..."
    ...
  }
  "items": [ 
    {
      "apiVersion": "v1",
      "kind": "Namespace", 
      ...
    },
    ...
  ]
}

The result should be processed as such:

kubectl get pods -o jsonpath="{.items[*]...}"

jsonpath and Queries that Return Arrays

⚠️ If the kubectl query returns an array, as when --selector is used, ensure the JSONPath expression includes .items[*], otherwise the filter will not work correctly.

kubectl get pod --selector=app=someapp -o jsonpath='{.metadata.name}'

will return an empty string, even if there is a pod with a "app=someapp" selector. The correct query is:

kubectl get pod --selector=app=someapp -o jsonpath='{.items[*].metadata.name}'

Syntax

$

As in the generic case, the $ operator is optional, since the expression always starts from the root object by default. However, the leading dot is not optional. More details on $:

JSONPath $

Element Selection

Object Fields Selection

Individual Fields

JSONPath .field
JSONPath ['field']

The value of a specified field can be obtained with the child operator:

kubectl get pod <pod-name> -o jsonpath="{.status.phase}"
kubectl get pod <pod-name> -o jsonpath="{['status']['phase']}"

When more than one resource is returned as result, the result is a JSON "List" Object with an .items field, which can be queried as such:

kubectl get pods -o jsonpath="{.items[*].status.phase}"

Field Recursive Descent

All values for a specific field can be obtained recursively with:

kubectl get pod <pod-name> -o jsonpath="{..name}"

More details:

JSONPath ..field (field recursive descent)

Array Element Selection

Subscript operators:

Wildcard

Wildcard can be used to iterated over the elements of an Array:

kubectl get nodes -o jsonpath='{.items[*]}'

Iterate over the elements of an Array and display a specific key:

kubectl get pod <pod-name> -o jsonpath=".status.conditions[*].lastTransitionTime"

More details:

JSONPath * (wildcard)

@

"@" represents the current object. For more details, see:

JSONPath @

[,]

[,] is the union operator that allows combining and displaying side by side multiple fields of the same object:

kubectl get pod <pod-name> -o jsonpath="{.status.conditions[*]['status', 'type']}"

More details:

JSONPath Union Operator

Filter Expressions

Filter expressions can be applied to Array elements or Object fields. Filter expressions can provide the same results, and are more flexible than the built-in kubectl get field selector.

To apply to Array elements:

[?(expression)]
kubectl get pods -o jsonpath='{.items[?(@.status.phase=="Running")].metadata.name}'

For syntactic details and various particular cases see:

JSONPath Filter Expressions

Filter Expressions Examples

kubectl get pods -o jsonpath='{.items[?(@.metadata.labels.name=="web")].metadata.name}'

Filter by an element:

kubectl get nodes -o jsonpath='{.items[*].status.addresses[?(@.type=="InternalIP")]}'

Print the element "address"

kubectl get nodes -o jsonpath='{.items[*].status.addresses[?(@.type=="InternalIP")].address}'

JSONPath Extensions

range and end Operators

JSONPath and Regular Expression Support

JSONPath regular expressions are not supported by kubectl -o jsonpath. If you want to match using regular expressions, use jq:

kubectl get pods -o json | jq -r '.items[] | select(.metadata.name | test("test-")).spec.containers[].image'

Other Examples

Select and Combine Two or More Elements

kubectl get pod \
-o jsonpath='{.items[0].spec.volumes[?(@.name=="A")].hostPath.path}'+'{.items[0].spec.volumes[?(@.name=="B")].hostPath.path}'

returns "/some/path/a+/some/path/b"

Array Length

jq Array Length

Selecting a Pod Based on the Value of an Annotation

Assuming the pod returns the following to kubectl get pod -o json:

{
    "apiVersion": "v1",
    "items": [
        {
            "apiVersion": "v1",
            "kind": "Pod",
            "metadata": {
                "annotations": {
                    "some.random.annotation": "some value",
                    ...

then the following jsonpath selects the pod. Note that all dots in the annotation name must be escaped:

kubectl get pod -o=jsonpath='{.items[?(@.metadata.annotations.some\.random\.annotation=="some value")].metadata.name}'; echo ""