Update bindings.md with 'x_k8s_get()' example (#1915)

* Update bindings.md with 'x_k8s_get()' example

Added a commented example on how to bind other objects with the 'x_k8s_get()' function, then refer and assert against.

Signed-off-by: James Lucktaylor <[email protected]>

* docs: move x_k8s_get example to its own page

Signed-off-by: James Lucktaylor <[email protected]>

* restructure

Signed-off-by: Charles-Edouard Brétéché <[email protected]>

---------

Signed-off-by: James Lucktaylor <[email protected]>
Signed-off-by: James Lucktaylor <[email protected]>
Signed-off-by: Charles-Edouard Brétéché <[email protected]>
Co-authored-by: Charles-Edouard Brétéché <[email protected]>

Author: jlucktay

Makefile

@@ -146,7 +146,6 @@ codegen-cli-docs: ## Generate CLI docs
 codegen-cli-docs: build
 	@echo Generate cli docs... >&2
 	@rm -rf website/docs/reference/commands && mkdir -p website/reference/docs/commands
-	@rm -rf docs/user/commands && mkdir -p docs/user/commands
 	@./$(CLI_BIN) docs -o website/docs/reference/commands --autogenTag=false
 
 .PHONY: codegen-api-docs
@@ -162,7 +161,7 @@ codegen-api-docs: codegen-conversion
 .PHONY: codegen-jp-docs
 codegen-jp-docs: ## Generate JP docs
 	@echo Generate jp docs... >&2
-	@rm -rf ./website/docs/reference/jp && mkdir -p ./website/docs/reference/jp
+	@mkdir -p ./website/docs/reference/jp
 	@go run ./website/jp/main.go > ./website/docs/reference/jp/functions.md
 
 .PHONY: codegen-mkdocs

website/docs/reference/jp/examples/x_k8s_get.md

@@ -0,0 +1,64 @@
+# `x_k8s_get`
+
+```yaml
+    - description: >-
+        1. Look up some details about a Deployment object with 'x_k8s_get(...)', and store them in a binding.
+        2. Make use of the binding in a `script` block through environment variables.
+        3. Refer to the same bound Deployment object in an `assert` block.
+      bindings:
+        - name: xpNS
+          value: crossplane-system
+        - name: xpDeploy
+          # Arguments to 'x_k8s_get(any, string, string, string, string)':
+          #
+          # 1. any: Supply the '$client' built-in binding here, which is needed to connect to the cluster:
+          #         https://kyverno.github.io/chainsaw/latest/reference/builtins/
+          #
+          # 2. string: 'apiVersion' field on the object.
+          #
+          # 3. string: 'Kind' field on the object.
+          #
+          # 4. string: The namespace of the object. If the object type is not namespaced, this field can be an empty
+          #            string, or any string; it doesn't seem to matter.
+          #
+          # 5. string: The name of the object.
+          value: (x_k8s_get($client, 'apps/v1', 'Deployment', $xpNS, 'crossplane'))
+      try:
+        - script:
+            bindings:
+              - # Re-bind the version label from the Deployment to give us a more succinct name to refer to.
+                name: deployVersion
+                # If the label key has any periods in it, double-quote the whole key.
+                value: ($xpDeploy.metadata.labels."app.kubernetes.io/version")
+            env:
+              - # Refer to the Deployment version label the long way.
+                name: DEP_VER_LONG
+                value: ($xpDeploy.metadata.labels."app.kubernetes.io/version")
+              - # Refer to the Deployment version label the short way, through the additional binding scoped to this
+                # 'script' block.
+                name: DEP_VER_SHORT
+                value: ($deployVersion)
+            # The version values printed by the script here will be the same, even though they were derived through
+            # slightly different routes.
+            content: |-
+              echo "DEP_VER_LONG:  '$DEP_VER_LONG'"
+              echo "DEP_VER_SHORT: '$DEP_VER_SHORT'"
+        - assert:
+            bindings:
+              - name: depVer
+                value: ($xpDeploy.metadata.labels."app.kubernetes.io/version")
+            resource:
+              apiVersion: v1
+              kind: Pod
+              metadata:
+                # Match the pod(s) with namespace and label selectors.
+                namespace: ($xpNS)
+                labels:
+                  app: crossplane
+              # Make a binding that holds this Pod's version from its label.
+              (metadata.labels."app.kubernetes.io/version")->podVer:
+                # Assert that the version labels for the Deployment and this Pod equal each other, using the
+                # 'semver_compare()' function described here:
+                # https://kyverno.io/docs/writing-policies/jmespath/#semver_compare
+                (semver_compare($depVer, $podVer)): true
+```

website/docs/reference/jp/functions.md

@@ -126,3 +126,7 @@
 | trim_space | `trim_space(string)` |
 | as_string | `as_string(any)` |
 
+## examples
+
+- [x_k8s_get](./examples/x_k8s_get.md)
+

website/jp/main.go

@@ -35,6 +35,10 @@ func main() {
 	fmt.Println()
 	printFunctions(chainsawfunctions.GetFunctions()...)
 	fmt.Println()
+	fmt.Println("## examples")
+	fmt.Println()
+	fmt.Println("- [x_k8s_get](./examples/x_k8s_get.md)")
+	fmt.Println()
 }
 
 func printFunctions(funcs ...jpfunctions.FunctionEntry) {

website/mkdocs.yaml

@@ -86,6 +86,8 @@ nav:
     - v1alpha2: reference/apis/chainsaw.v1alpha2.md
   - JMESPath:
     - Functions: reference/jp/functions.md
+    - Examples:
+      - reference/jp/examples/x_k8s_get.md
   - Command Line:
     - chainsaw: reference/commands/chainsaw.md
     - chainsaw assert: reference/commands/chainsaw_assert.md