Kubectl get JSONPath Support: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
 
(2 intermediate revisions by the same user not shown)
Line 122: Line 122:


==Filter Expressions==
==Filter Expressions==
Filter expressions can be applied to Array elements or Object fields.  
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_Support#Overview|kubectl get field selector]].


To apply to Array elements:
To apply to Array elements:
Line 155: Line 155:
</syntaxhighlight>
</syntaxhighlight>
=Other Examples=
=Other Examples=
====Select and Combine Two or More Elements====
==Select and Combine Two or More Elements==
<syntaxhighlight lang='bash'>
<syntaxhighlight lang='bash'>
kubectl get pod \
kubectl get pod \
Line 161: Line 161:
</syntaxhighlight>
</syntaxhighlight>
returns "/some/path/a+/some/path/b"
returns "/some/path/a+/some/path/b"
====Array Length====
==Array Length==
{{Internal|Jq_Usage#Array_Length|jq Array Length}}
{{Internal|Jq_Usage#Array_Length|jq Array Length}}
==Selecting a Pod Based on the Value of an Annotation==
Assuming the pod returns the following to <code>kubectl get pod -o json</code>:
<syntaxhighlight lang='json'>
{
    "apiVersion": "v1",
    "items": [
        {
            "apiVersion": "v1",
            "kind": "Pod",
            "metadata": {
                "annotations": {
                    "some.random.annotation": "some value",
                    ...
</syntaxhighlight>
then the following jsonpath selects the pod. Note that all dots in the annotation name must be escaped:
<syntaxhighlight lang='bash'>
kubectl get pod -o=jsonpath='{.items[?(@.metadata.annotations.some\.random\.annotation=="some value")].metadata.name}'; echo ""
</syntaxhighlight>

Latest revision as of 02:45, 16 March 2024

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 ""