From 85972c44a41b850d7ec1d76f3d32ab962a431d7b Mon Sep 17 00:00:00 2001 From: Dai Zuozhuo Date: Thu, 13 Aug 2015 16:31:38 +0800 Subject: [PATCH] jsonpath user guide docs --- docs/man/man1/kubectl-annotate.1 | 3 +- docs/man/man1/kubectl-config-view.1 | 3 +- docs/man/man1/kubectl-expose.1 | 3 +- docs/man/man1/kubectl-get.1 | 3 +- docs/man/man1/kubectl-label.1 | 3 +- docs/man/man1/kubectl-rolling-update.1 | 3 +- docs/man/man1/kubectl-run.1 | 3 +- docs/user-guide/jsonpath.md | 103 ++++++++++ docs/user-guide/kubectl/kubectl_annotate.md | 4 +- .../user-guide/kubectl/kubectl_config_view.md | 8 +- docs/user-guide/kubectl/kubectl_expose.md | 8 +- docs/user-guide/kubectl/kubectl_get.md | 29 +-- docs/user-guide/kubectl/kubectl_label.md | 12 +- .../kubectl/kubectl_rolling-update.md | 13 +- docs/user-guide/kubectl/kubectl_run.md | 12 +- pkg/kubectl/cmd/get.go | 2 +- pkg/kubectl/cmd/util/printing.go | 2 +- pkg/kubectl/resource_printer_test.go | 186 ++++++------------ pkg/util/jsonpath/jsonpath_test.go | 3 +- pkg/util/jsonpath/parser.go | 2 +- 20 files changed, 198 insertions(+), 207 deletions(-) create mode 100644 docs/user-guide/jsonpath.md diff --git a/docs/man/man1/kubectl-annotate.1 b/docs/man/man1/kubectl-annotate.1 index 515880efe20..c218eb0cea1 100644 --- a/docs/man/man1/kubectl-annotate.1 +++ b/docs/man/man1/kubectl-annotate.1 @@ -68,7 +68,8 @@ resourcequotas (quota) or secrets. .PP \fB\-t\fP, \fB\-\-template\fP="" Template string or path to template file to use when \-o=template, \-o=templatefile or \-o=jsonpath. The template format is golang templates [ -\[la]http://golang.org/pkg/text/template/#pkg-overview\[ra]]. The jsonpath template is composed of jsonpath expressions enclosed by {} +\[la]http://golang.org/pkg/text/template/#pkg-overview\[ra]]. The jsonpath template is composed of jsonpath expressions enclosed by {} [ +\[la]http://releases.k8s.io/HEAD/docs/user-guide/jsonpath.md\[ra]] .SH OPTIONS INHERITED FROM PARENT COMMANDS diff --git a/docs/man/man1/kubectl-config-view.1 b/docs/man/man1/kubectl-config-view.1 index 94c5bd6c854..eee772a414c 100644 --- a/docs/man/man1/kubectl-config-view.1 +++ b/docs/man/man1/kubectl-config-view.1 @@ -63,7 +63,8 @@ You can use \-\-output=template \-\-template=TEMPLATE to extract specific values .PP \fB\-t\fP, \fB\-\-template\fP="" Template string or path to template file to use when \-o=template, \-o=templatefile or \-o=jsonpath. The template format is golang templates [ -\[la]http://golang.org/pkg/text/template/#pkg-overview\[ra]]. The jsonpath template is composed of jsonpath expressions enclosed by {} +\[la]http://golang.org/pkg/text/template/#pkg-overview\[ra]]. The jsonpath template is composed of jsonpath expressions enclosed by {} [ +\[la]http://releases.k8s.io/HEAD/docs/user-guide/jsonpath.md\[ra]] .SH OPTIONS INHERITED FROM PARENT COMMANDS diff --git a/docs/man/man1/kubectl-expose.1 b/docs/man/man1/kubectl-expose.1 index 2ca7cda8839..b756c84d31c 100644 --- a/docs/man/man1/kubectl-expose.1 +++ b/docs/man/man1/kubectl-expose.1 @@ -105,7 +105,8 @@ re\-use the labels from the resource it exposes. .PP \fB\-t\fP, \fB\-\-template\fP="" Template string or path to template file to use when \-o=template, \-o=templatefile or \-o=jsonpath. The template format is golang templates [ -\[la]http://golang.org/pkg/text/template/#pkg-overview\[ra]]. The jsonpath template is composed of jsonpath expressions enclosed by {} +\[la]http://golang.org/pkg/text/template/#pkg-overview\[ra]]. The jsonpath template is composed of jsonpath expressions enclosed by {} [ +\[la]http://releases.k8s.io/HEAD/docs/user-guide/jsonpath.md\[ra]] .PP \fB\-\-type\fP="" diff --git a/docs/man/man1/kubectl-get.1 b/docs/man/man1/kubectl-get.1 index c7e04253c89..3bd96d0d7dd 100644 --- a/docs/man/man1/kubectl-get.1 +++ b/docs/man/man1/kubectl-get.1 @@ -70,7 +70,8 @@ of the \-\-template flag, you can filter the attributes of the fetched resource( .PP \fB\-t\fP, \fB\-\-template\fP="" Template string or path to template file to use when \-o=template, \-o=templatefile or \-o=jsonpath. The template format is golang templates [ -\[la]http://golang.org/pkg/text/template/#pkg-overview\[ra]]. The jsonpath template is composed of jsonpath expressions enclosed by {} +\[la]http://golang.org/pkg/text/template/#pkg-overview\[ra]]. The jsonpath template is composed of jsonpath expressions enclosed by {} [ +\[la]http://releases.k8s.io/HEAD/docs/user-guide/jsonpath.md\[ra]] .PP \fB\-w\fP, \fB\-\-watch\fP=false diff --git a/docs/man/man1/kubectl-label.1 b/docs/man/man1/kubectl-label.1 index cb0a6e1a97b..8a80008cf9b 100644 --- a/docs/man/man1/kubectl-label.1 +++ b/docs/man/man1/kubectl-label.1 @@ -69,7 +69,8 @@ If \-\-resource\-version is specified, then updates will use this resource versi .PP \fB\-t\fP, \fB\-\-template\fP="" Template string or path to template file to use when \-o=template, \-o=templatefile or \-o=jsonpath. The template format is golang templates [ -\[la]http://golang.org/pkg/text/template/#pkg-overview\[ra]]. The jsonpath template is composed of jsonpath expressions enclosed by {} +\[la]http://golang.org/pkg/text/template/#pkg-overview\[ra]]. The jsonpath template is composed of jsonpath expressions enclosed by {} [ +\[la]http://releases.k8s.io/HEAD/docs/user-guide/jsonpath.md\[ra]] .SH OPTIONS INHERITED FROM PARENT COMMANDS diff --git a/docs/man/man1/kubectl-rolling-update.1 b/docs/man/man1/kubectl-rolling-update.1 index 9e30eb1d676..954eb0c3dd3 100644 --- a/docs/man/man1/kubectl-rolling-update.1 +++ b/docs/man/man1/kubectl-rolling-update.1 @@ -73,7 +73,8 @@ existing replication controller and overwrite at least one (common) label in its .PP \fB\-t\fP, \fB\-\-template\fP="" Template string or path to template file to use when \-o=template, \-o=templatefile or \-o=jsonpath. The template format is golang templates [ -\[la]http://golang.org/pkg/text/template/#pkg-overview\[ra]]. The jsonpath template is composed of jsonpath expressions enclosed by {} +\[la]http://golang.org/pkg/text/template/#pkg-overview\[ra]]. The jsonpath template is composed of jsonpath expressions enclosed by {} [ +\[la]http://releases.k8s.io/HEAD/docs/user-guide/jsonpath.md\[ra]] .PP \fB\-\-timeout\fP=5m0s diff --git a/docs/man/man1/kubectl-run.1 b/docs/man/man1/kubectl-run.1 index 23415306db2..b28b60d606b 100644 --- a/docs/man/man1/kubectl-run.1 +++ b/docs/man/man1/kubectl-run.1 @@ -93,7 +93,8 @@ Creates a replication controller to manage the created container(s). .PP \fB\-t\fP, \fB\-\-template\fP="" Template string or path to template file to use when \-o=template, \-o=templatefile or \-o=jsonpath. The template format is golang templates [ -\[la]http://golang.org/pkg/text/template/#pkg-overview\[ra]]. The jsonpath template is composed of jsonpath expressions enclosed by {} +\[la]http://golang.org/pkg/text/template/#pkg-overview\[ra]]. The jsonpath template is composed of jsonpath expressions enclosed by {} [ +\[la]http://releases.k8s.io/HEAD/docs/user-guide/jsonpath.md\[ra]] .PP \fB\-\-tty\fP=false diff --git a/docs/user-guide/jsonpath.md b/docs/user-guide/jsonpath.md new file mode 100644 index 00000000000..9c5ca3a511b --- /dev/null +++ b/docs/user-guide/jsonpath.md @@ -0,0 +1,103 @@ + + + + +WARNING +WARNING +WARNING +WARNING +WARNING + +

PLEASE NOTE: This document applies to the HEAD of the source tree

+ +If you are using a released version of Kubernetes, you should +refer to the docs that go with that version. + + +The latest 1.0.x release of this document can be found +[here](http://releases.k8s.io/release-1.0/docs/user-guide/jsonpath.md). + +Documentation for other releases can be found at +[releases.k8s.io](http://releases.k8s.io). + +-- + + + + + +# JSONPath template syntax + +JSONPath template is composed of JSONPath expressions enclosed by {}. +And we add three functions in addition to the original JSONPath syntax: + +1. The `$` operator is optional since the expression always start from the root object by default. +2. We can use `""` to quote text inside JSONPath expression. +3. We can use `range` operator to iterate list. + + +The result object is printed as its String() function. + +Given the input: + +```json +{ + "kind": "List", + "items":[ + { + "kind":"None", + "metadata":{"name":"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"} + } + ] +} +``` + +Function | Description | Example | Result +---------|--------------------|--------------------|------------------ +text | the plain text | kind is {.kind} | kind is List +"" | quote | {"{"} | { +@ | the current object | {@} | the same as input +. or [] | child operator | {.kind} or {['kind']}| List +.. | recursive descent | {..name} | 127.0.0.1 127.0.0.2 myself e2e +* | wildcard. Get all objects| {.items[*].metadata.name} | [127.0.0.1 127.0.0.2] +[start:end :step] | subscript operator | {.users[0].name}| myself +[,] | union operator | {.items[*]['metadata.name', 'status.capacity']} | 127.0.0.1 127.0.0.2 map[cpu:4] map[cpu:8] +?() | filter | {.users[?(@.name=="e2e")].user.password} | secret +range, end | iterate list | {range .items[*]}[{.metadata.name}, {.status.capacity}] {end} | [127.0.0.1, map[cpu:4]] [127.0.0.2, map[cpu:8]] + + + + + +[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/user-guide/jsonpath.md?pixel)]() + diff --git a/docs/user-guide/kubectl/kubectl_annotate.md b/docs/user-guide/kubectl/kubectl_annotate.md index 2c81262c0ce..2b8b9c33a79 100644 --- a/docs/user-guide/kubectl/kubectl_annotate.md +++ b/docs/user-guide/kubectl/kubectl_annotate.md @@ -87,7 +87,7 @@ $ kubectl annotate pods foo description- --resource-version="": If non-empty, the annotation update will only succeed if this is the current resource-version for the object. Only valid when specifying a single resource. -a, --show-all[=false]: When printing, show all resources (default hide terminated pods.) --sort-by="": If non-empty, sort list types using this field specification. The field specification is expressed as a JSONPath expression (e.g. 'ObjectMeta.Name'). The field in the API resource specified by this JSONPath expression must be an integer or a string. - -t, --template="": Template string or path to template file to use when -o=template, -o=templatefile or -o=jsonpath. The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview]. The jsonpath template is composed of jsonpath expressions enclosed by {} + -t, --template="": Template string or path to template file to use when -o=template, -o=templatefile or -o=jsonpath. The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview]. The jsonpath template is composed of jsonpath expressions enclosed by {} [http://releases.k8s.io/HEAD/docs/user-guide/jsonpath.md] ``` ### Options inherited from parent commands @@ -123,7 +123,7 @@ $ kubectl annotate pods foo description- * [kubectl](kubectl.md) - kubectl controls the Kubernetes cluster manager -###### Auto generated by spf13/cobra at 2015-08-18 17:36:23.97715989 +0000 UTC +###### Auto generated by spf13/cobra at 2015-08-13 08:45:23.477684199 +0000 UTC [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/user-guide/kubectl/kubectl_annotate.md?pixel)]() diff --git a/docs/user-guide/kubectl/kubectl_config_view.md b/docs/user-guide/kubectl/kubectl_config_view.md index c1c3c585210..06e13690d22 100644 --- a/docs/user-guide/kubectl/kubectl_config_view.md +++ b/docs/user-guide/kubectl/kubectl_config_view.md @@ -69,7 +69,7 @@ $ kubectl config view -o template --template='{{range .users}}{{ if eq .name "e2 --raw[=false]: display raw byte data -a, --show-all[=false]: When printing, show all resources (default hide terminated pods.) --sort-by="": If non-empty, sort list types using this field specification. The field specification is expressed as a JSONPath expression (e.g. 'ObjectMeta.Name'). The field in the API resource specified by this JSONPath expression must be an integer or a string. - -t, --template="": Template string or path to template file to use when -o=template, -o=templatefile or -o=jsonpath. The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview]. The jsonpath template is composed of jsonpath expressions enclosed by {} + -t, --template="": Template string or path to template file to use when -o=template, -o=templatefile or -o=jsonpath. The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview]. The jsonpath template is composed of jsonpath expressions enclosed by {} [http://releases.k8s.io/HEAD/docs/user-guide/jsonpath.md] ``` ### Options inherited from parent commands @@ -105,11 +105,7 @@ $ kubectl config view -o template --template='{{range .users}}{{ if eq .name "e2 * [kubectl config](kubectl_config.md) - config modifies kubeconfig files -<<<<<<< HEAD -###### Auto generated by spf13/cobra at 2015-08-12 23:41:01.310054033 +0000 UTC -======= -###### Auto generated by spf13/cobra at 2015-08-11 10:20:05.920471764 +0000 UTC ->>>>>>> add jsonpath to kubectl +###### Auto generated by spf13/cobra at 2015-08-13 08:45:23.478129098 +0000 UTC [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/user-guide/kubectl/kubectl_config_view.md?pixel)]() diff --git a/docs/user-guide/kubectl/kubectl_expose.md b/docs/user-guide/kubectl/kubectl_expose.md index 086be677edc..5da034512c3 100644 --- a/docs/user-guide/kubectl/kubectl_expose.md +++ b/docs/user-guide/kubectl/kubectl_expose.md @@ -87,7 +87,7 @@ $ kubectl expose rc streamer --port=4100 --protocol=udp --name=video-stream -a, --show-all[=false]: When printing, show all resources (default hide terminated pods.) --sort-by="": If non-empty, sort list types using this field specification. The field specification is expressed as a JSONPath expression (e.g. 'ObjectMeta.Name'). The field in the API resource specified by this JSONPath expression must be an integer or a string. --target-port="": Name or number for the port on the container that the service should direct traffic to. Optional. - -t, --template="": Template string or path to template file to use when -o=template, -o=templatefile or -o=jsonpath. The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview]. The jsonpath template is composed of jsonpath expressions enclosed by {} + -t, --template="": Template string or path to template file to use when -o=template, -o=templatefile or -o=jsonpath. The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview]. The jsonpath template is composed of jsonpath expressions enclosed by {} [http://releases.k8s.io/HEAD/docs/user-guide/jsonpath.md] --type="": Type for this service: ClusterIP, NodePort, or LoadBalancer. Default is 'ClusterIP' unless --create-external-load-balancer is specified. ``` @@ -124,11 +124,7 @@ $ kubectl expose rc streamer --port=4100 --protocol=udp --name=video-stream * [kubectl](kubectl.md) - kubectl controls the Kubernetes cluster manager -<<<<<<< HEAD -###### Auto generated by spf13/cobra at 2015-08-12 23:41:01.308576759 +0000 UTC -======= -###### Auto generated by spf13/cobra at 2015-08-11 10:20:05.919806434 +0000 UTC ->>>>>>> add jsonpath to kubectl +###### Auto generated by spf13/cobra at 2015-08-13 08:45:23.476872373 +0000 UTC [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/user-guide/kubectl/kubectl_expose.md?pixel)]() diff --git a/docs/user-guide/kubectl/kubectl_get.md b/docs/user-guide/kubectl/kubectl_get.md index 672969b0602..2bfca8ae7eb 100644 --- a/docs/user-guide/kubectl/kubectl_get.md +++ b/docs/user-guide/kubectl/kubectl_get.md @@ -49,11 +49,7 @@ By specifying the output as 'template' and providing a Go template as the value of the --template flag, you can filter the attributes of the fetched resource(s). ``` -<<<<<<< HEAD -kubectl get [(-o|--output=)json|yaml|template|wide|...] (TYPE [(NAME | -l label] | TYPE/NAME ...) [flags] -======= -kubectl get [(-o|--output=)json|yaml|template|templatefile|wide|jsonpath|...] (TYPE [NAME | -l label] | TYPE/NAME ...) ->>>>>>> add jsonpath to kubectl +kubectl get [(-o|--output=)json|yaml|template|templatefile|wide|jsonpath|...] (TYPE [NAME | -l label] | TYPE/NAME ...) [flags] ``` ### Examples @@ -95,16 +91,9 @@ $ kubectl get rc/web service/frontend pods/web-pod-13je7 -o, --output="": Output format. One of: json|yaml|template|templatefile|wide|jsonpath. --output-version="": Output the formatted object with the given version (default api-version). -l, --selector="": Selector (label query) to filter on -<<<<<<< HEAD -a, --show-all[=false]: When printing, show all resources (default hide terminated pods.) -======= -<<<<<<< HEAD ->>>>>>> add jsonpath to kubectl --sort-by="": If non-empty, sort list types using this field specification. The field specification is expressed as a JSONPath expression (e.g. 'ObjectMeta.Name'). The field in the API resource specified by this JSONPath expression must be an integer or a string. - -t, --template="": Template string or path to template file to use when -o=template or -o=templatefile. The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview] -======= - -t, --template="": Template string or path to template file to use when -o=template, -o=templatefile or -o=jsonpath. The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview]. The jsonpath template is composed of jsonpath expressions enclosed by {} ->>>>>>> add jsonpath to kubectl + -t, --template="": Template string or path to template file to use when -o=template, -o=templatefile or -o=jsonpath. The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview]. The jsonpath template is composed of jsonpath expressions enclosed by {} [http://releases.k8s.io/HEAD/docs/user-guide/jsonpath.md] -w, --watch[=false]: After listing/getting the requested object, watch for changes. --watch-only[=false]: Watch for changes to the requested object(s), without listing/getting first. ``` @@ -142,19 +131,7 @@ $ kubectl get rc/web service/frontend pods/web-pod-13je7 * [kubectl](kubectl.md) - kubectl controls the Kubernetes cluster manager -<<<<<<< HEAD -###### Auto generated by spf13/cobra at 2015-08-18 17:36:23.974605429 +0000 UTC -======= -<<<<<<< HEAD -###### Auto generated by spf13/cobra at 2015-08-13 06:12:05.386038784 +0000 UTC -======= -<<<<<<< HEAD -###### Auto generated by spf13/cobra at 2015-08-12 23:41:01.301023165 +0000 UTC -======= -###### Auto generated by spf13/cobra at 2015-08-11 10:20:05.915175811 +0000 UTC ->>>>>>> add jsonpath to kubectl ->>>>>>> add jsonpath to kubectl ->>>>>>> add jsonpath to kubectl +###### Auto generated by spf13/cobra at 2015-08-20 01:10:19.603989785 +0000 UTC [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/user-guide/kubectl/kubectl_get.md?pixel)]() diff --git a/docs/user-guide/kubectl/kubectl_label.md b/docs/user-guide/kubectl/kubectl_label.md index 46d625eff9e..ae776d89ec8 100644 --- a/docs/user-guide/kubectl/kubectl_label.md +++ b/docs/user-guide/kubectl/kubectl_label.md @@ -85,7 +85,7 @@ $ kubectl label pods foo bar- -l, --selector="": Selector (label query) to filter on -a, --show-all[=false]: When printing, show all resources (default hide terminated pods.) --sort-by="": If non-empty, sort list types using this field specification. The field specification is expressed as a JSONPath expression (e.g. 'ObjectMeta.Name'). The field in the API resource specified by this JSONPath expression must be an integer or a string. - -t, --template="": Template string or path to template file to use when -o=template, -o=templatefile or -o=jsonpath. The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview]. The jsonpath template is composed of jsonpath expressions enclosed by {} + -t, --template="": Template string or path to template file to use when -o=template, -o=templatefile or -o=jsonpath. The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview]. The jsonpath template is composed of jsonpath expressions enclosed by {} [http://releases.k8s.io/HEAD/docs/user-guide/jsonpath.md] ``` ### Options inherited from parent commands @@ -121,15 +121,7 @@ $ kubectl label pods foo bar- * [kubectl](kubectl.md) - kubectl controls the Kubernetes cluster manager -<<<<<<< HEAD -###### Auto generated by spf13/cobra at 2015-08-13 02:21:16.349210188 +0000 UTC -======= -<<<<<<< HEAD -###### Auto generated by spf13/cobra at 2015-08-12 23:41:01.309176995 +0000 UTC -======= -###### Auto generated by spf13/cobra at 2015-08-11 10:20:05.920043611 +0000 UTC ->>>>>>> add jsonpath to kubectl ->>>>>>> add jsonpath to kubectl +###### Auto generated by spf13/cobra at 2015-08-20 01:10:19.61318045 +0000 UTC [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/user-guide/kubectl/kubectl_label.md?pixel)]() diff --git a/docs/user-guide/kubectl/kubectl_rolling-update.md b/docs/user-guide/kubectl/kubectl_rolling-update.md index e33c6059b32..c65b2dd895c 100644 --- a/docs/user-guide/kubectl/kubectl_rolling-update.md +++ b/docs/user-guide/kubectl/kubectl_rolling-update.md @@ -79,12 +79,9 @@ $ kubectl rolling-update frontend --image=image:v2 --output-version="": Output the formatted object with the given version (default api-version). --poll-interval=3s: Time delay between polling for replication controller status after the update. Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". --rollback[=false]: If true, this is a request to abort an existing rollout that is partially rolled out. It effectively reverses current and next and runs a rollout -<<<<<<< HEAD + -a, --show-all[=false]: When printing, show all resources (default hide terminated pods.) --sort-by="": If non-empty, sort list types using this field specification. The field specification is expressed as a JSONPath expression (e.g. 'ObjectMeta.Name'). The field in the API resource specified by this JSONPath expression must be an integer or a string. - -t, --template="": Template string or path to template file to use when -o=template or -o=templatefile. The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview] -======= - -t, --template="": Template string or path to template file to use when -o=template, -o=templatefile or -o=jsonpath. The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview]. The jsonpath template is composed of jsonpath expressions enclosed by {} ->>>>>>> add jsonpath to kubectl + -t, --template="": Template string or path to template file to use when -o=template, -o=templatefile or -o=jsonpath. The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview]. The jsonpath template is composed of jsonpath expressions enclosed by {} [http://releases.k8s.io/HEAD/docs/user-guide/jsonpath.md] --timeout=5m0s: Max time to wait for a replication controller to update before giving up. Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". --update-period=1m0s: Time to wait between updating pods. Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". ``` @@ -122,11 +119,7 @@ $ kubectl rolling-update frontend --image=image:v2 * [kubectl](kubectl.md) - kubectl controls the Kubernetes cluster manager -<<<<<<< HEAD -###### Auto generated by spf13/cobra at 2015-08-12 23:41:01.305486289 +0000 UTC -======= -###### Auto generated by spf13/cobra at 2015-08-11 10:20:05.917101859 +0000 UTC ->>>>>>> add jsonpath to kubectl +###### Auto generated by spf13/cobra at 2015-08-20 01:10:19.606885893 +0000 UTC [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/user-guide/kubectl/kubectl_rolling-update.md?pixel)]() diff --git a/docs/user-guide/kubectl/kubectl_run.md b/docs/user-guide/kubectl/kubectl_run.md index cd4bea9f4bf..fc7b118d21d 100644 --- a/docs/user-guide/kubectl/kubectl_run.md +++ b/docs/user-guide/kubectl/kubectl_run.md @@ -91,7 +91,7 @@ $ kubectl run nginx --image=nginx --command -- ... -a, --show-all[=false]: When printing, show all resources (default hide terminated pods.) --sort-by="": If non-empty, sort list types using this field specification. The field specification is expressed as a JSONPath expression (e.g. 'ObjectMeta.Name'). The field in the API resource specified by this JSONPath expression must be an integer or a string. -i, --stdin[=false]: Keep stdin open on the container(s) in the pod, even if nothing is attached. - -t, --template="": Template string or path to template file to use when -o=template, -o=templatefile or -o=jsonpath. The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview]. The jsonpath template is composed of jsonpath expressions enclosed by {} + -t, --template="": Template string or path to template file to use when -o=template, -o=templatefile or -o=jsonpath. The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview]. The jsonpath template is composed of jsonpath expressions enclosed by {} [http://releases.k8s.io/HEAD/docs/user-guide/jsonpath.md] --tty[=false]: Allocated a TTY for each container in the pod. Because -t is currently shorthand for --template, -t is not supported for --tty. This shorthand is deprecated and we expect to adopt -t for --tty soon. ``` @@ -128,15 +128,7 @@ $ kubectl run nginx --image=nginx --command -- ... * [kubectl](kubectl.md) - kubectl controls the Kubernetes cluster manager -<<<<<<< HEAD -###### Auto generated by spf13/cobra at 2015-08-13 16:41:44.465440991 +0000 UTC -======= -<<<<<<< HEAD -###### Auto generated by spf13/cobra at 2015-08-12 23:41:01.307766241 +0000 UTC -======= -###### Auto generated by spf13/cobra at 2015-08-11 10:20:05.919181854 +0000 UTC ->>>>>>> add jsonpath to kubectl ->>>>>>> add jsonpath to kubectl +###### Auto generated by spf13/cobra at 2015-08-14 06:15:57.11465464 +0000 UTC [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/user-guide/kubectl/kubectl_run.md?pixel)]() diff --git a/pkg/kubectl/cmd/get.go b/pkg/kubectl/cmd/get.go index b5028b057c4..83409ac857d 100644 --- a/pkg/kubectl/cmd/get.go +++ b/pkg/kubectl/cmd/get.go @@ -69,7 +69,7 @@ func NewCmdGet(f *cmdutil.Factory, out io.Writer) *cobra.Command { validArgs := p.HandledResources() cmd := &cobra.Command{ - Use: "get [(-o|--output=)json|yaml|template|templatefile|wide|jsonpath|...] (TYPE [NAME | -l label] | TYPE/NAME ...)", + Use: "get [(-o|--output=)json|yaml|template|templatefile|wide|jsonpath|...] (TYPE [NAME | -l label] | TYPE/NAME ...) [flags]", Short: "Display one or many resources", Long: get_long, Example: get_example, diff --git a/pkg/kubectl/cmd/util/printing.go b/pkg/kubectl/cmd/util/printing.go index 31e93ae9336..c33f8b4994e 100644 --- a/pkg/kubectl/cmd/util/printing.go +++ b/pkg/kubectl/cmd/util/printing.go @@ -31,7 +31,7 @@ func AddPrinterFlags(cmd *cobra.Command) { cmd.Flags().StringP("output", "o", "", "Output format. One of: json|yaml|template|templatefile|wide|jsonpath.") cmd.Flags().String("output-version", "", "Output the formatted object with the given version (default api-version).") cmd.Flags().Bool("no-headers", false, "When using the default output, don't print headers.") - cmd.Flags().StringP("template", "t", "", "Template string or path to template file to use when -o=template, -o=templatefile or -o=jsonpath. The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview]. The jsonpath template is composed of jsonpath expressions enclosed by {}") + cmd.Flags().StringP("template", "t", "", "Template string or path to template file to use when -o=template, -o=templatefile or -o=jsonpath. The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview]. The jsonpath template is composed of jsonpath expressions enclosed by {} [http://releases.k8s.io/HEAD/docs/user-guide/jsonpath.md]") cmd.Flags().String("sort-by", "", "If non-empty, sort list types using this field specification. The field specification is expressed as a JSONPath expression (e.g. 'ObjectMeta.Name'). The field in the API resource specified by this JSONPath expression must be an integer or a string.") cmd.Flags().BoolP("show-all", "a", false, "When printing, show all resources (default hide terminated pods.)") } diff --git a/pkg/kubectl/resource_printer_test.go b/pkg/kubectl/resource_printer_test.go index 1ea94797002..031a16df366 100644 --- a/pkg/kubectl/resource_printer_test.go +++ b/pkg/kubectl/resource_printer_test.go @@ -77,14 +77,6 @@ func TestVersionedPrinter(t *testing.T) { } } -func TestYAMLPrinter(t *testing.T) { - testPrinter(t, &YAMLPrinter{}, yaml.Unmarshal) -} - -func TestJSONPrinter(t *testing.T) { - testPrinter(t, &JSONPrinter{}, json.Unmarshal) -} - func TestPrintDefault(t *testing.T) { printer, found, err := GetPrinter("", "") if err != nil { @@ -95,107 +87,72 @@ func TestPrintDefault(t *testing.T) { } } -type internalType struct { - Name string +type TestPrintType struct { + Data string } -func (*internalType) IsAnAPIObject() { +func (*TestPrintType) IsAnAPIObject() {} -} +type TestUnknownType struct{} -func TestPrintJSONForObject(t *testing.T) { - buf := bytes.NewBuffer([]byte{}) - printer, found, err := GetPrinter("json", "") - if err != nil || !found { - t.Fatalf("unexpected error: %#v", err) - } - if err := printer.PrintObj(&internalType{Name: "foo"}, buf); err != nil { - t.Fatalf("unexpected error: %#v", err) - } - obj := map[string]interface{}{} - if err := json.Unmarshal(buf.Bytes(), &obj); err != nil { - t.Fatalf("unexpected error: %#v\n%s", err, buf.String()) - } - if obj["Name"] != "foo" { - t.Errorf("unexpected field: %#v", obj) - } -} +func (*TestUnknownType) IsAnAPIObject() {} -func TestPrintJSON(t *testing.T) { - buf := bytes.NewBuffer([]byte{}) - printer, found, err := GetPrinter("json", "") - if err != nil || !found { - t.Fatalf("unexpected error: %#v", err) - } - printer.PrintObj(&api.Pod{ObjectMeta: api.ObjectMeta{Name: "foo"}}, buf) - obj := map[string]interface{}{} - if err := json.Unmarshal(buf.Bytes(), &obj); err != nil { - t.Errorf("unexpected error: %#v\n%s", err, buf.String()) - } -} - -func TestPrintYAML(t *testing.T) { - buf := bytes.NewBuffer([]byte{}) - printer, found, err := GetPrinter("yaml", "") - if err != nil || !found { - t.Fatalf("unexpected error: %#v", err) - } - printer.PrintObj(&api.Pod{ObjectMeta: api.ObjectMeta{Name: "foo"}}, buf) - obj := map[string]interface{}{} - if err := yaml.Unmarshal(buf.Bytes(), &obj); err != nil { - t.Errorf("unexpected error: %#v\n%s", err, buf.String()) - } -} - -func TestPrintTemplate(t *testing.T) { - buf := bytes.NewBuffer([]byte{}) - printer, found, err := GetPrinter("template", "{{if .id}}{{.id}}{{end}}{{if .metadata.name}}{{.metadata.name}}{{end}}") - if err != nil || !found { - t.Fatalf("unexpected error: %#v", err) - } - unversionedPod := &api.Pod{ObjectMeta: api.ObjectMeta{Name: "foo"}} - obj, err := api.Scheme.ConvertToVersion(unversionedPod, testapi.Version()) - err = printer.PrintObj(obj, buf) +func TestPrinter(t *testing.T) { + //test inputs + simpleTest := &TestPrintType{"foo"} + podTest := &api.Pod{ObjectMeta: api.ObjectMeta{Name: "foo"}} + testapi, err := api.Scheme.ConvertToVersion(podTest, testapi.Version()) if err != nil { - t.Fatalf("unexpected error: %#v", err) + t.Fatalf("unexpected error: %v", err) } - if buf.String() != "foo" { - t.Errorf("unexpected output: %s", buf.String()) + + printerTests := []struct { + Name string + Format string + FormatArgument string + Input runtime.Object + Expect string + }{ + {"test json", "json", "", simpleTest, "{\n \"Data\": \"foo\"\n}\n"}, + {"test yaml", "yaml", "", simpleTest, "Data: foo\n"}, + {"test template", "template", "{{if .id}}{{.id}}{{end}}{{if .metadata.name}}{{.metadata.name}}{{end}}", + podTest, "foo"}, + {"test jsonpath", "jsonpath", "{.metadata.name}", podTest, "foo"}, + {"emits versioned objects", "template", "{{.kind}}", testapi, "Pod"}, } + for _, test := range printerTests { + buf := bytes.NewBuffer([]byte{}) + printer, found, err := GetPrinter(test.Format, test.FormatArgument) + if err != nil || !found { + t.Errorf("unexpected error: %#v", err) + } + if err := printer.PrintObj(test.Input, buf); err != nil { + t.Errorf("unexpected error: %#v", err) + } + if buf.String() != test.Expect { + t.Errorf("in %s, expect %q, got %q", test.Name, test.Expect, buf.String(), buf.String()) + } + } + } -func TestPrintJSONPath(t *testing.T) { - buf := bytes.NewBuffer([]byte{}) - printer, found, err := GetPrinter("jsonpath", "{.metadata.name}") - if err != nil || !found { - t.Fatalf("unexpected error: %#v", err) +func TestBadPrinter(t *testing.T) { + badPrinterTests := []struct { + Name string + Format string + FormatArgument string + Error error + }{ + {"empty template", "template", "", fmt.Errorf("template format specified but no template given")}, + {"bad template", "template", "{{ .Name", fmt.Errorf("error parsing template {{ .Name, template: output:1: unclosed action\n")}, + {"bad templatefile", "templatefile", "", fmt.Errorf("templatefile format specified but no template file given")}, + {"bad jsonpath", "jsonpath", "{.Name", fmt.Errorf("error parsing jsonpath {.Name, unclosed action\n")}, } - unversionedPod := &api.Pod{ObjectMeta: api.ObjectMeta{Name: "foo"}} - obj, err := api.Scheme.ConvertToVersion(unversionedPod, testapi.Version()) - err = printer.PrintObj(obj, buf) - if err != nil { - t.Fatalf("unexpected error: %s %#v", buf, err) - } - if buf.String() != "foo" { - t.Errorf("unexpected output: %s", buf.String()) - } -} - -func TestPrintEmptyTemplate(t *testing.T) { - if _, _, err := GetPrinter("template", ""); err == nil { - t.Errorf("unexpected non-error") - } -} - -func TestPrintBadTemplate(t *testing.T) { - if _, _, err := GetPrinter("template", "{{ .Name"); err == nil { - t.Errorf("unexpected non-error") - } -} - -func TestPrintBadTemplateFile(t *testing.T) { - if _, _, err := GetPrinter("templatefile", ""); err == nil { - t.Errorf("unexpected non-error") + for _, test := range badPrinterTests { + _, _, err := GetPrinter(test.Format, test.FormatArgument) + if err == nil || err.Error() != test.Error.Error() { + t.Errorf("in %s, expect %s, got %s", test.Name, test.Error, err) + } } } @@ -244,15 +201,13 @@ func testPrinter(t *testing.T, printer ResourcePrinter, unmarshalFunc func(data } } -type TestPrintType struct { - Data string +func TestYAMLPrinter(t *testing.T) { + testPrinter(t, &YAMLPrinter{}, yaml.Unmarshal) } -func (*TestPrintType) IsAnAPIObject() {} - -type TestUnknownType struct{} - -func (*TestUnknownType) IsAnAPIObject() {} +func TestJSONPrinter(t *testing.T) { + testPrinter(t, &JSONPrinter{}, json.Unmarshal) +} func PrintCustomType(obj *TestPrintType, w io.Writer, withNamespace bool, wide bool, showAll bool, columnLabels []string) error { _, err := fmt.Fprintf(w, "%s", obj.Data) @@ -301,27 +256,6 @@ func TestUnknownTypePrinting(t *testing.T) { } } -func TestTemplateEmitsVersionedObjects(t *testing.T) { - // kind is always blank in memory and set on the wire - printer, err := NewTemplatePrinter([]byte(`{{.kind}}`)) - if err != nil { - t.Fatalf("tmpl fail: %v", err) - } - obj, err := api.Scheme.ConvertToVersion(&api.Pod{}, testapi.Version()) - if err != nil { - t.Fatalf("unexpected error: %v", err) - } - - buffer := &bytes.Buffer{} - err = printer.PrintObj(obj, buffer) - if err != nil { - t.Fatalf("print fail: %v", err) - } - if e, a := "Pod", string(buffer.Bytes()); e != a { - t.Errorf("Expected %v, got %v", e, a) - } -} - func TestTemplatePanic(t *testing.T) { tmpl := `{{and ((index .currentState.info "foo").state.running.startedAt) .currentState.info.net.state.running.startedAt}}` printer, err := NewTemplatePrinter([]byte(tmpl)) diff --git a/pkg/util/jsonpath/jsonpath_test.go b/pkg/util/jsonpath/jsonpath_test.go index 879c0a691ae..4a98a7261d2 100644 --- a/pkg/util/jsonpath/jsonpath_test.go +++ b/pkg/util/jsonpath/jsonpath_test.go @@ -118,7 +118,7 @@ func TestStructInput(t *testing.T) { {"union", "{[1,3,4]}", []int{0, 1, 2, 3, 4}, "1 3 4"}, {"array", "{[0:2]}", []string{"Monday", "Tudesday"}, "Monday Tudesday"}, {"variable", "hello {.Name}", storeData, "hello jsonpath"}, - {"dict/", "{.Labels.web/html}", storeData, "15"}, + {"dict/", "{$.Labels.web/html}", storeData, "15"}, {"dict-", "{.Labels.k8s-app}", storeData, "20"}, {"nest", "{.Bicycle.Color}", storeData, "red"}, {"allarray", "{.Book[*].Author}", storeData, "Nigel Rees Evelyn Waugh Herman Melville"}, @@ -210,6 +210,7 @@ func TestKubenates(t *testing.T) { `127.0.0.1 127.0.0.2 127.0.0.3`}, {"double range", "{range .items[*]}{range .status.addresses[*]}{.address}, {end}{end}", nodesData, `127.0.0.1, 127.0.0.2, 127.0.0.3, `}, + {"recursive name", "{..name}", nodesData, `127.0.0.1 127.0.0.2 myself e2e`}, {"item name", "{.items[*].metadata.name}", nodesData, `127.0.0.1 127.0.0.2`}, {"union nodes capacity", "{.items[*]['metadata.name', 'status.capacity']}", nodesData, `127.0.0.1 127.0.0.2 map[cpu:4] map[cpu:8]`}, diff --git a/pkg/util/jsonpath/parser.go b/pkg/util/jsonpath/parser.go index fafecdf087a..85aa2c1316e 100644 --- a/pkg/util/jsonpath/parser.go +++ b/pkg/util/jsonpath/parser.go @@ -151,7 +151,7 @@ func (p *Parser) parseInsideAction(cur *ListNode) error { return fmt.Errorf("unclosed action") case r == ' ': p.consumeText() - case r == '@': //the current object, just pass it + case r == '@' || r == '$': //the current object, just pass it p.consumeText() case r == '[': return p.parseArray(cur)