kubemod · vassilvk · Apr 11, 2022 · Apr 11, 2022 · Apr 11, 2022 · Apr 11, 2022
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,7 @@ All notable changes to this project will be documented in this file.
 
 ## Unreleased
 
+- 87: Extend JSPONPath with select functions isUndefined, isDefined, isEmpty and isNotEmpty
 - 70: Add support for ARM64
 
 ## 0.14.0 - 2022-01-29

diff --git a/Makefile b/Makefile
@@ -14,12 +14,11 @@ all: manager
 
 # Run tests
 test: generate fmt vet manifests
-	go test ./core ./util -coverprofile cover.out
+	go test ./core ./util ./jsonpath -coverprofile cover.out
 
 # Run tests -v
 testv: generate fmt vet manifests
-	go test -v ./core ./util -coverprofile cover.out
-
+	go test -v ./core ./util ./jsonpath -coverprofile cover.out
 
 # Run benchmarks
 bench: generate fmt vet manifests

diff --git a/README.md b/README.md
@@ -29,6 +29,7 @@ Use KubeMod to:
     * [Target resources](#target-resources)
     * [Note on idempotency](#note-on-idempotency)
     * [Debugging ModRules](#debugging-modrules)
+    * [KubeMod's version of JSONPath](#kubemods-version-of-jsonpath)
     * [Declarative kubectl apply](#declarative-kubectl-apply)
     * [Gotchas](#gotchas)
 
@@ -431,6 +432,8 @@ A criteria item whose `select` expression yields no results is considered non-ma
 
 The `select` field of a criteria item is a [JSONPath](https://goessner.net/articles/JsonPath/) expression.
 
+[See more on KubeMod's version of JSONPath](#kubemods-version-of-jsonpath).
+
 When a `select` expression is evaluated against a Kubernetes object definition, it yields zero or more values.
 
 Let's consider the following JSONPath select expression:
@@ -993,6 +996,85 @@ When an object is patched by a ModRule, if the object has a `kubectl.kubernetes.
 
 KubeMod supports both client-side and server-side declarative management through `kubectl apply`.
 
+### KubeMod's version of JSONPath
+
+KubeMod implements a modified (extended) version of [JSONPath](https://goessner.net/articles/JsonPath/).
+
+This version introduces the following new features:
+
+#### Value `undefined`
+- Includes internal representation of value `undefined`.
+- Resolves each path that includes undefined properties to value `undefined`.
+  For example `$.a.b.c` will resolve to `undefined` if any of the `a`, `b` or `c` properties do not exist.
+- Filters out all `undefined` values on partial matches.
+- Makes all equality and arithmetic comparisons to `undefined` return `false`.
+  For example, assuming that `$.a.b.c` is a path to undefined property, all of the following expressions will yield `false`:
+  - `$.a.b.c == 12`
+  - `$.a.b.c != 12`
+  - `$.a.b.c > 12`
+  -  `$.a.b.c < 12`
+  -   `$.a.b.c == true`
+  -   `$.a.b.c == false`
+- Makes all boolean operators (`&&` and `||`) require boolean operands.
+
+#### `undefined`-based functions
+- `isDefined()` - returns `true` if the passed in path leads to a defined property, otherwise return `false`.
+- `isUndefined()` - returns `true` if the passed in path leads to an undefined property, otherwise return `false`.
+- `isEmpty()` - returns `true` if the passed in path leads to one of the following values:
+  - An empty array
+  - An empty object
+  - An empty string
+  - Null
+  - `undefined`
+- `isNotEmpty()` - equivalent to evaluating `!isEmpty()`
+- `length()` - returns the length of arrays, objects and strings. Returns `0` for Nulls and `undefined`.
+
+#### Note on presence check
+
+KubeMod uses the above `undefined` based functions to provide both presence (`isDefined`) and negative-presence (`isUndefined`) filters - see next section for an example.
+
+These functions should be used in place of the standard JSONPath's presence-based `[?(@.property)]` filter [discussed here](https://goessner.net/articles/JsonPath/).
+
+#### Usage in ModRules
+
+For example, to patch all deployments' containers which have either no `securityContext` defined, or `securityContext` is empty, one would use the following KubeMod rule.
+
+```yaml
+apiVersion: api.kubemod.io/v1beta1
+kind: ModRule
+metadata:
+  name: kubemod-patch-deployments-containers-securitycontext
+  namespace: kubemod-system
+spec:
+  targetNamespaceRegex: .*
+  type: Patch
+  match:
+    - matchValue: Deployment
+      select: $.kind
+  patch:
+    - op: add
+      select: '$.spec.template.spec.containers[? isEmpty(@.securityContex)]'
+      path: '/spec/template/spec/containers/#0/securityContext'
+      value: |-
+        runAsNonRoot: true
+        capabilities:
+          drop:
+          - ALL
+```
+The rule uses `isEmpty` which returns `true` when the passed in path is not defined or if it points to an empty object.
+
+If we wanted to only patch the containers which have no `securityContex` defined, but leave the ones which have an empty `securityContex`, we would use the following `select`:
+
+```yaml
+select: '$.spec.template.spec.containers[? isUndefined(@.securityContex)]'
+```
+
+If we wanted to only patch the containers which have an empty `securityContex`, but leave the ones which have no `securityContex` defined, we would use the following `select`:
+
+```yaml
+select: '$.spec.template.spec.containers[? isDefined(@.securityContex) && isEmpty(@.securityContex)]'
+```
+
 ### Gotchas
 
 When multiple ModRules match the same resource object, all of the ModRule patches are executed against the object in an indeterminate order.

diff --git a/api/v1beta1/modrule_webhook.go b/api/v1beta1/modrule_webhook.go
@@ -32,7 +32,7 @@ import (
 // log is for logging in this package.
 var (
 	modrulelog       = logf.Log.WithName("modrule-resource")
-	jsonPathLanguage = expressions.NewJSONPathLanguage()
+	jsonPathLanguage = expressions.NewKubeModJSONPathLanguage()
 )
 
 // SetupWebhookWithManager hooks up the web hook with a manager.

diff --git a/app/wire.go b/app/wire.go
@@ -39,7 +39,7 @@ func InitializeKubeModOperatorApp(
 	enableLeaderElection EnableLeaderElection,
 	log logr.Logger) (*KubeModOperatorApp, error) {
 	wire.Build(
-		expressions.NewJSONPathLanguage,
+		expressions.NewKubeModJSONPathLanguage,
 		core.NewModRuleStoreItemFactory,
 		core.NewModRuleStore,
 		core.NewDragnetWebhookHandler,
@@ -56,7 +56,7 @@ func InitializeKubeModWebApp(
 	clusterModRulesNamespace core.ClusterModRulesNamespace,
 	log logr.Logger) (*KubeModWebApp, error) {
 	wire.Build(
-		expressions.NewJSONPathLanguage,
+		expressions.NewKubeModJSONPathLanguage,
 		core.NewModRuleStoreItemFactory,
 		NewKubeModWebApp,
 	)

diff --git a/app/wire_gen.go b/app/wire_gen.go
diff --git a/core/modrulestore_test.go b/core/modrulestore_test.go
@@ -139,6 +139,12 @@ var _ = Describe("ModRuleStore", func() {
 		Entry("patch-13 on deployment-2 should work - ModRule in kubemod-system and targetNamespaceRegex matches", []string{"patch/patch-13.yaml"}, "deployment-2.json", "patch-13-deployment-2.txt"),
 		Entry("patch-14 on deployment-2 should not work - ModRule in kubemod-system, missing targetNamespaceRegex", []string{"patch/patch-14.yaml"}, "deployment-2.json", "empty-array.txt"),
 		Entry("patch-15 on deployment-2 should not work - ModRule in kubemod-system, empty targetNamespaceRegex", []string{"patch/patch-15.yaml"}, "deployment-2.json", "empty-array.txt"),
+		Entry("patch-16 on deployment-4 should work as expected", []string{"patch/patch-16.yaml"}, "deployment-4.json", "patch-16-deployment-4.txt"),
+		Entry("patch-17 on deployment-4 should work as expected", []string{"patch/patch-17.yaml"}, "deployment-4.json", "patch-17-deployment-4.txt"),
+		Entry("patch-18 on deployment-4 should work as expected", []string{"patch/patch-18.yaml"}, "deployment-4.json", "patch-18-deployment-4.txt"),
+		Entry("patch-19 on deployment-4 should work as expected", []string{"patch/patch-19.yaml"}, "deployment-4.json", "patch-19-deployment-4.txt"),
+		Entry("patch-20 on deployment-4 should work as expected", []string{"patch/patch-20.yaml"}, "deployment-4.json", "patch-20-deployment-4.txt"),
+		Entry("patch-21 on deployment-4 should work as expected", []string{"patch/patch-21.yaml"}, "deployment-4.json", "patch-21-deployment-4.txt"),
 	)
 
 	DescribeTable("DetermineRejections", modRuleStoreDetermineRejectionsTableFunction,

diff --git a/core/testdata/expectations/patch-16-deployment-4.txt b/core/testdata/expectations/patch-16-deployment-4.txt
@@ -0,0 +1,2 @@
+
+[{add /spec/template/spec/containers/0/securityContext map[capabilities:map[drop:[ALL]] runAsNonRoot:true]} {add /spec/template/spec/containers/1/securityContext/capabilities map[drop:[ALL]]} {add /spec/template/spec/containers/1/securityContext/runAsNonRoot true}]
diff --git a/core/testdata/expectations/patch-17-deployment-4.txt b/core/testdata/expectations/patch-17-deployment-4.txt
@@ -0,0 +1 @@
+[{add /spec/template/spec/containers/0/securityContext map[capabilities:map[drop:[ALL]] runAsNonRoot:true]}]
diff --git a/core/testdata/expectations/patch-18-deployment-4.txt b/core/testdata/expectations/patch-18-deployment-4.txt
@@ -0,0 +1 @@
+[{add /spec/template/spec/containers/1/securityContext/capabilities map[drop:[ALL]]} {add /spec/template/spec/containers/1/securityContext/runAsNonRoot true} {add /spec/template/spec/containers/2/securityContext/capabilities map[drop:[ALL]]} {remove /spec/template/spec/containers/2/securityContext/allowPrivilegeEscalation <nil>}]
diff --git a/core/testdata/expectations/patch-19-deployment-4.txt b/core/testdata/expectations/patch-19-deployment-4.txt
@@ -0,0 +1 @@
+[{add /spec/template/spec/containers/2/securityContext/capabilities map[drop:[ALL]]} {remove /spec/template/spec/containers/2/securityContext/allowPrivilegeEscalation <nil>}]
diff --git a/core/testdata/expectations/patch-20-deployment-4.txt b/core/testdata/expectations/patch-20-deployment-4.txt
@@ -0,0 +1 @@
+[{add /spec/template/spec/containers/0/securityContext map[capabilities:map[drop:[ALL]] runAsNonRoot:true]} {add /spec/template/spec/containers/2/securityContext/capabilities map[drop:[ALL]]} {remove /spec/template/spec/containers/2/securityContext/allowPrivilegeEscalation <nil>}]
diff --git a/core/testdata/expectations/patch-21-deployment-4.txt b/core/testdata/expectations/patch-21-deployment-4.txt
@@ -0,0 +1 @@
+[{add /spec/template/spec/containers/1/securityContext/capabilities map[drop:[ALL]]} {add /spec/template/spec/containers/1/securityContext/runAsNonRoot true}]
diff --git a/core/testdata/modrules/patch/patch-16.yaml b/core/testdata/modrules/patch/patch-16.yaml
@@ -0,0 +1,22 @@
+apiVersion: api.kubemod.io/v1beta1
+kind: ModRule
+metadata:
+  name: modrule-1
+spec:
+  type: Patch
+  # optional targetNamespaceRegex missing -- when missing, rules in 
+  # kubemod-system namespace can only target non-namespaced resources
+
+  match:
+    - select: '$.kind'
+      matchValue: 'Deployment'
+
+  patch:
+    - op: add
+      select: '$.spec.template.spec.containers[? isEmpty(@.securityContext)]'
+      path: /spec/template/spec/containers/#0/securityContext
+      value: |-
+        runAsNonRoot: true
+        capabilities:
+          drop:
+            - ALL
diff --git a/core/testdata/modrules/patch/patch-17.yaml b/core/testdata/modrules/patch/patch-17.yaml
@@ -0,0 +1,22 @@
+apiVersion: api.kubemod.io/v1beta1
+kind: ModRule
+metadata:
+  name: modrule-1
+spec:
+  type: Patch
+  # optional targetNamespaceRegex missing -- when missing, rules in 
+  # kubemod-system namespace can only target non-namespaced resources
+
+  match:
+    - select: '$.kind'
+      matchValue: 'Deployment'
+
+  patch:
+    - op: add
+      select: '$.spec.template.spec.containers[? isUndefined(@.securityContext)]'
+      path: /spec/template/spec/containers/#0/securityContext
+      value: |-
+        runAsNonRoot: true
+        capabilities:
+          drop:
+            - ALL
diff --git a/core/testdata/modrules/patch/patch-18.yaml b/core/testdata/modrules/patch/patch-18.yaml
@@ -0,0 +1,22 @@
+apiVersion: api.kubemod.io/v1beta1
+kind: ModRule
+metadata:
+  name: modrule-1
+spec:
+  type: Patch
+  # optional targetNamespaceRegex missing -- when missing, rules in 
+  # kubemod-system namespace can only target non-namespaced resources
+
+  match:
+    - select: '$.kind'
+      matchValue: 'Deployment'
+
+  patch:
+    - op: add
+      select: '$.spec.template.spec.containers[? isDefined(@.securityContext)]'
+      path: /spec/template/spec/containers/#0/securityContext
+      value: |-
+        runAsNonRoot: true
+        capabilities:
+          drop:
+            - ALL
diff --git a/core/testdata/modrules/patch/patch-19.yaml b/core/testdata/modrules/patch/patch-19.yaml
@@ -0,0 +1,22 @@
+apiVersion: api.kubemod.io/v1beta1
+kind: ModRule
+metadata:
+  name: modrule-1
+spec:
+  type: Patch
+  # optional targetNamespaceRegex missing -- when missing, rules in 
+  # kubemod-system namespace can only target non-namespaced resources
+
+  match:
+    - select: '$.kind'
+      matchValue: 'Deployment'
+
+  patch:
+    - op: add
+      select: '$.spec.template.spec.containers[? isNotEmpty(@.securityContext)]'
+      path: /spec/template/spec/containers/#0/securityContext
+      value: |-
+        runAsNonRoot: true
+        capabilities:
+          drop:
+            - ALL
diff --git a/core/testdata/modrules/patch/patch-20.yaml b/core/testdata/modrules/patch/patch-20.yaml
@@ -0,0 +1,22 @@
+apiVersion: api.kubemod.io/v1beta1
+kind: ModRule
+metadata:
+  name: modrule-1
+spec:
+  type: Patch
+  # optional targetNamespaceRegex missing -- when missing, rules in 
+  # kubemod-system namespace can only target non-namespaced resources
+
+  match:
+    - select: '$.kind'
+      matchValue: 'Deployment'
+
+  patch:
+    - op: add
+      select: '$.spec.template.spec.containers[? isUndefined(@.securityContext) || isNotEmpty(@.securityContext)]'
+      path: /spec/template/spec/containers/#0/securityContext
+      value: |-
+        runAsNonRoot: true
+        capabilities:
+          drop:
+            - ALL
diff --git a/core/testdata/modrules/patch/patch-21.yaml b/core/testdata/modrules/patch/patch-21.yaml
@@ -0,0 +1,22 @@
+apiVersion: api.kubemod.io/v1beta1
+kind: ModRule
+metadata:
+  name: modrule-1
+spec:
+  type: Patch
+  # optional targetNamespaceRegex missing -- when missing, rules in 
+  # kubemod-system namespace can only target non-namespaced resources
+
+  match:
+    - select: '$.kind'
+      matchValue: 'Deployment'
+
+  patch:
+    - op: add
+      select: '$.spec.template.spec.containers[? isDefined(@.securityContext) && isEmpty(@.securityContext)]'
+      path: /spec/template/spec/containers/#0/securityContext
+      value: |-
+        runAsNonRoot: true
+        capabilities:
+          drop:
+            - ALL
diff --git a/core/testdata/modrules/reject/boolean-pod-negative-run-as-non-root.yaml b/core/testdata/modrules/reject/boolean-pod-negative-run-as-non-root.yaml
@@ -9,5 +9,5 @@ spec:
     - select: "$.kind"
       matchValue: Pod
 
-    - select: "$.spec.securityContext.runAsNonRoot == true"
+    - select: '$.spec.securityContext.runAsNonRoot == true'
       negate: true
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@

		[{add /spec/template/spec/containers/0/securityContext map[capabilities:map[drop:[ALL]] runAsNonRoot:true]} {add /spec/template/spec/containers/1/securityContext/capabilities map[drop:[ALL]]} {add /spec/template/spec/containers/1/securityContext/runAsNonRoot true}]
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		[{add /spec/template/spec/containers/0/securityContext map[capabilities:map[drop:[ALL]] runAsNonRoot:true]}]
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		[{add /spec/template/spec/containers/1/securityContext/capabilities map[drop:[ALL]]} {add /spec/template/spec/containers/1/securityContext/runAsNonRoot true} {add /spec/template/spec/containers/2/securityContext/capabilities map[drop:[ALL]]} {remove /spec/template/spec/containers/2/securityContext/allowPrivilegeEscalation <nil>}]
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		[{add /spec/template/spec/containers/2/securityContext/capabilities map[drop:[ALL]]} {remove /spec/template/spec/containers/2/securityContext/allowPrivilegeEscalation <nil>}]