[Merged by Bors] - 274 document the bundlebuilder and rego rule configmaps

CHANGELOG.md

@@ -7,8 +7,10 @@ All notable changes to this project will be documented in this file.
 ### Added
 
 - CPU and memory limits are now configurable ([#347]).
+- Better documentation on the bundle builder ([#350])
 
 [#347]: https://github.com/stackabletech/opa-operator/pull/347
+[#350]: https://github.com/stackabletech/opa-operator/pull/350
 
 ## [0.10.0] - 2022-09-06
 

docs/modules/ROOT/pages/discovery.adoc

@@ -39,8 +39,8 @@ A connection string for cluster internal OPA requests. Provided the cluster exam
 [subs="attributes"]
     http://{clusterName}.{namespace}.svc.cluster.local:8081/
 
-This connection string points to the base URL (and web UI) of the OPA cluster. In order to query policies you have to configure your product and its OPA url as follows, given the rego package name `{packageName}` and the policy name `{policyName}`:
+This connection string points to the base URL (and web UI) of the OPA cluster. In order to query policies you have to configure your product and its OPA url as follows, given the bundle package name `{packageName}` and the policy name `{policyName}`:
 
 [subs="attributes"]
     http://{clusterName}.{namespace}.svc.cluster.local:8081/v1/data/{packageName}/{policyName}
-====
+====

docs/modules/ROOT/pages/implementation-notes.adoc

@@ -12,5 +12,15 @@ We ensure local access via an https://kubernetes.io/docs/concepts/services-netwo
 
 == OPA Bundle Builder
 
-Each OPA pod runs a container that watches for `ConfigMap` objects labeled `opa.stackable.tech/bundle`.
-All `ConfigMap`s are bundled together in a single `bundle.tar.gz` file that is served to the colocated OPA container.
+Users can manage policy rules by creating, updating and deleting `ConfigMap` resources.
+
+The role of the bundle builder is to convert these resources to bundles (`tar.gz` files) and make them available as an HTTP endpoint.
+The bundle builder runs in a side container of the OPA `Pod` as a simple HTTP server that OPA is querying regularly
+(every 20 to 30 seconds) for updates.
+
+NOTE: Kubernetes limits the size of `ConfigMap`s to 1MB. Users have to take this limit into consideration when manging policy rules.
+
+Only ConfigMaps labeled with `opa.stackable.tech/bundle: "true"` are considered by the builder when updating bundles. The name of
+the `data` entries in the `ConfigMap` are used as file names when storing the rules in the bundle.
+
+NOTE: Currently it is the user's responsibility to make sure these names do not collide (as they will override each other).

docs/modules/ROOT/pages/usage.adoc

@@ -30,11 +30,38 @@ This Stackable version is the version of the underlying container image which is
 For a list of available versions please check our https://repo.stackable.tech/#browse/browse:docker:v2%2Fstackable%2Fdruid%2Ftags[image registry].
 It should generally be safe to simply use the latest image version that is available.
 
-== Bundle Sources
+== Policy Language
 
-OPA bundles are generated from `ConfigMap` objects by a side car container running along side the OPA server.
+Users can define policies by using Rego, OPAs https://www.openpolicyagent.org/docs/latest/policy-language/[policy language].
+
+Policy definitionas are deployed as `ConfigMap` resources as described in xref:implementation-notes.adoc[implementation notes].
+
+Here is an example:
+
+[source,yaml]
+----
+---
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: test
+  labels:
+    opa.stackable.tech/bundle: "true" # <1>
+data:
+  test.rego: | # <2>
+    package test
+
+    hello {
+      true
+    }
+
+    world {
+      false
+    }
+----
+<1> Mark this `ConfigMap` as a bundle source.
+<2> `test.rego` is the file name to use inside the bundle for these rules.
 
-Alternatively, the OPA servers can load bundles from a remote server when a `regoRuleReference` is configured in the role group's `config` section.
 
 == Monitoring
 

docs/modules/getting_started/pages/first_steps.adoc

@@ -16,9 +16,9 @@ include::example$code/getting_started.sh[tag=apply-opa-cluster]
 
 This will create an OPA cluster. The Operator deploys a DaemonSet, so every node in your cluster will have an OPA instance.
 
-== Deploy a rule
+== Deploy a policy rule
 
-Now deploy first link:https://www.openpolicyagent.org/docs/latest/policy-language/[Rego rule] to the Agent. Rules are deployed in ConfigMaps. Create a file `simple-rule.yaml` with the following contents:
+Now deploy first link:https://www.openpolicyagent.org/docs/latest/policy-language/[policy rule] to the Agent. Rules are deployed in ConfigMaps. Create a file `simple-rule.yaml` with the following contents:
 
 [source,yaml]
 ----
@@ -63,4 +63,4 @@ Great! You've set up OPA, deployed a rule and queried it!
 
 == What's next
 
-Have a look at the xref:ROOT:usage.adoc[] page for more configuration options of the Operator.
+Have a look at the xref:ROOT:usage.adoc[] page for more configuration options of the Operator.

tests/templates/kuttl/smoke/02-install-test-regorule.yaml

@@ -17,6 +17,6 @@ spec:
     spec:
       containers:
       - name: test-regorule
-        image: python:3.10-slim
+        image: docker.stackable.tech/stackable/testing-tools:0.1.0-stackable0.1.0
         stdin: true
         tty: true

tests/templates/kuttl/smoke/03-prepare-test-regorule.yaml

@@ -2,5 +2,3 @@ apiVersion: kuttl.dev/v1beta1
 kind: TestStep
 commands:
   - script: kubectl cp -n $NAMESPACE ./test-regorule.py  test-regorule-0:/tmp
-  - script: kubectl cp -n $NAMESPACE ./requirements.txt test-regorule-0:/tmp
-  - script: kubectl exec -n $NAMESPACE test-regorule-0 -- pip install --user -r /tmp/requirements.txt