Gatekeeper policy generation (#12)

* Fix reference yaml to be valid

Signed-off-by: Dale Haiducek <[email protected]>

* Update contributing guide

Signed-off-by: Dale Haiducek <[email protected]>

* Add support for informing on Gatekeeper policy violations

Signed-off-by: Dale Haiducek <[email protected]>

* Document the expanders and code structure

Signed-off-by: Dale Haiducek <[email protected]>

* Update with Gatekeeper examples

Signed-off-by: Dale Haiducek <[email protected]>

* Add Gatekeeper expander tests

Signed-off-by: Dale Haiducek <[email protected]>

Author: dhaiducek

CONTRIBUTING.md

@@ -62,10 +62,12 @@ comment on the issue or pull request (PR).
 
 ## Pre-check before submitting a PR
 
-Before submitting a PR, please perform the following steps:
+Before submitting a PR, perform the following steps:
 
 ```shell
 make fmt
 make lint
 make test
 ```
+
+If there are any updates to the YAML, also make sure to update the [policy-generator.yaml](./docs/policy-generator.yaml) file.

docs/policygenerator-reference.yaml

@@ -95,7 +95,8 @@ policies:
     # a namespace is specified in the manifest, the selector is not necessary. This defaults to no
     # selectors.
     namespaceSelector:
-      include: [] exclude: []
+      include: []
+      exclude: []
     # Optional. (See policyDefaults.placement for description.)
     placement: {}
     # Optional. (See policyDefaults.remediationAction for description.)

docs/policygenerator.md

@@ -22,3 +22,50 @@ PlacementBinding, either specify `placement.placementRulePath` to an existing Pl
 set `placement.name` along with `placement.clusterSelectors`. When the PlacementBinding is
 consolidated in this way, `placementBindingDefaults.name` must be specified so that the generator
 can create unique names for the bindings.
+
+## Policy expanders
+
+Policy expanders provide logic to create additional policies based on a given kind to give a
+complete picture of violations or status using Open Cluster Management policies. Generally the
+expanders point to kinds provided by policy engines such as [Kyverno](https://kyverno.io/) and
+[Gatekeeper](https://open-policy-agent.github.io/gatekeeper/). These expanders are enabled by
+default but can be disabled individually by setting the flag associated with the expander in the
+`PolicyGenerator` manifest either in `policyDefaults` or for a particular manifest in the `policies`
+array.
+
+### Contributing a policy expander
+
+To contribute a policy expander, you'll need to:
+
+1. Add your expander to the `getExpanders()` method in
+   [expanders.go](../internal/expanders/expanders.go) and familiarize yourself with the Interface
+   there that you'll be implementing.
+2. Add your expander file to the [internal/expanders/](../internal/expanders/) directory. You can
+   follow the other files there as an example.
+3. Choose a name for your boolean expander setting. (Existing names have followed the pattern
+   `Inform<engine-name>Policies`.)
+4. Add your expander setting to both the `PolicyDefaults` and the `PolicyConfig` array in
+   [types.go](../types/types.go)
+5. Add your expander setting to the `applyDefaults()` method in [plugin.go](../internal/plugin.go)
+   to set a defaults for both `PolicyDefaults` and `Policies`.
+6. Update the [policygenerator-reference.yaml](./policygenerator-reference.yaml) with your expander
+   setting.
+7. Add tests for your expander to the [internal/expanders/](../internal/expanders/) directory.
+
+## PolicyGenerator code structure
+
+```
+DIRECTORY TREE              PACKAGE                 DESCRIPTION
+================================================================================================
+.
+├── cmd
+│   └── main.go             main                    Parent binary (imports the internal package)
+└── internal
+    ├── expanders
+    │   ├── expanders.go    expanders               Policy expander interface
+    ├── types
+    │   └── types.go        types                   Generator structs
+    ├── patches.go          internal                Code to patch input manifests
+    ├── plugin.go           internal                Primary generator methods
+    ├── utils.go            internal                Helper/utility methods
+```

examples/input2/configmap-fish.yaml renamed to examples/input-folder/configmap-fish.yaml

@@ -0,0 +1,42 @@
+# Taken from https://open-policy-agent.github.io/gatekeeper/website/docs/howto
+---
+apiVersion: templates.gatekeeper.sh/v1beta1
+kind: ConstraintTemplate
+metadata:
+  name: k8srequiredlabels
+spec:
+  crd:
+    spec:
+      names:
+        kind: K8sRequiredLabels
+      validation:
+        # Schema for the `parameters` field
+        openAPIV3Schema:
+          properties:
+            labels:
+              type: array
+              items: string
+  targets:
+    - target: admission.k8s.gatekeeper.sh
+      rego: |
+        package k8srequiredlabels
+
+        violation[{"msg": msg, "details": {"missing_labels": missing}}] {
+          provided := {label | input.review.object.metadata.labels[label]}
+          required := {label | label := input.parameters.labels[_]}
+          missing := required - provided
+          count(missing) > 0
+          msg := sprintf("you must provide labels: %v", [missing])
+        }
+---
+apiVersion: constraints.gatekeeper.sh/v1beta1
+kind: K8sRequiredLabels
+metadata:
+  name: ns-must-have-gk
+spec:
+  match:
+    kinds:
+      - apiGroups: [""]
+        kinds: ["Namespace"]
+  parameters:
+    labels: ["gatekeeper"]

examples/input2/configmap-toads.yaml renamed to examples/input-folder/configmap-toads.yaml

@@ -34,7 +34,7 @@ policies:
 - name: policy-app-config-others
   disabled: true
   manifests:
-    - path: input2/
+    - path: input-folder/
       patches:
         - apiVersion: v1
           kind: ConfigMap
@@ -46,4 +46,7 @@ policies:
 - name: policy-require-labels
   disabled: true
   manifests:
-    - path: input3/
+    - path: input-kyverno/
+- name: policy-require-ns-labels
+  manifests:
+    - path: input-gatekeeper/

examples/input-gatekeeper/gatekeeper.yaml

@@ -5,15 +5,21 @@ import (
 	"github.com/open-cluster-management/policy-generator-plugin/internal/types"
 )
 
+// GetExpanders returns the list of available expanders.
 func GetExpanders() map[string]Expander {
 	return map[string]Expander{
-		"kyverno": KyvernoPolicyExpander{},
+		"gatekeeper": GatekeeperPolicyExpander{},
+		"kyverno":    KyvernoPolicyExpander{},
 	}
 }
 
+// Expander is the interface for all policy expander instances.
 type Expander interface {
+	// CanHandle determines if the manifest is a policy that can be expanded.
 	CanHandle(manifest map[string]interface{}) bool
+	// Enabled determines if the policy configuration allows a policy to be expanded.
 	Enabled(policyConf *types.PolicyConfig) bool
+	// Expand will generate additional policy templates for the policy for auditing purposes.
 	Expand(manifest map[string]interface{}, severity string) []map[string]map[string]interface{}
 }
 

examples/input3/kyverno.yaml renamed to examples/input-kyverno/kyverno.yaml

@@ -0,0 +1,20 @@
+package expanders
+
+import (
+	"reflect"
+	"testing"
+)
+
+func assertEqual(t *testing.T, a interface{}, b interface{}) {
+	t.Helper()
+	if a != b {
+		t.Fatalf("%s != %s", a, b)
+	}
+}
+
+func assertReflectEqual(t *testing.T, a interface{}, b interface{}) {
+	t.Helper()
+	if !reflect.DeepEqual(a, b) {
+		t.Fatalf("%s != %s", a, b)
+	}
+}