[Merged by Bors] - Add getting started guide

docs/antora.yml

@@ -2,5 +2,6 @@ name: opa
 version: "nightly"
 title: Stackable Operator for OPA
 nav:
+  - modules/getting_started/nav.adoc
   - modules/ROOT/nav.adoc
 prerelease: true

docs/modules/ROOT/nav.adoc

@@ -1,4 +1,3 @@
-* xref:installation.adoc[]
 * xref:usage.adoc[]
 * xref:configuration.adoc[]
 * xref:implementation-notes.adoc[]

docs/modules/getting_started/examples/code/expected_response_hello.json

@@ -0,0 +1 @@
+{"result":true}

docs/modules/getting_started/examples/code/expected_response_world.json

@@ -0,0 +1 @@
+{}

docs/modules/getting_started/examples/code/getting_started.sh

@@ -0,0 +1,95 @@
+#! /usr/bin/env bash
+set -euo pipefail
+
+# This script contains all the code snippets from the guide, as well as some assert tests
+# to test if the instructions in the guide work. The user *could* use it, but it is intended
+# for testing only.
+# The script will install the operator, create an OPA instance and briefly open a port
+# forward and query the OPA.
+# No running processes are left behind (i.e. the port-forwarding is closed at the end)
+
+if [ $# -eq 0 ]
+then
+  echo "Installation method argument ('helm' or 'stackablectl') required."
+  exit 1
+fi
+
+case "$1" in
+"helm")
+echo "Adding 'stackable-dev' Helm Chart repository"
+# tag::helm-add-repo[]
+helm repo add stackable-dev https://repo.stackable.tech/repository/helm-dev/
+# end::helm-add-repo[]
+echo "Installing Operators with Helm"
+# tag::helm-install-operators[]
+helm install --wait opa-operator stackable-dev/opa-operator --version 0.10.0-nightly
+# end::helm-install-operators[]
+;;
+"stackablectl")
+echo "installing Operators with stackablectl"
+# tag::stackablectl-install-operators[]
+stackablectl operator install opa=0.10.0-nightly
+# end::stackablectl-install-operators[]
+;;
+*)
+echo "Need to provide 'helm' or 'stackablectl' as an argument for which installation method to use!"
+exit 1
+;;
+esac
+
+echo "Creating OPA cluster"
+# tag::apply-opa-cluster[]
+kubectl apply -f opa.yaml
+# end::apply-opa-cluster[]
+
+sleep 5
+
+echo "Waiting on rollout ..."
+kubectl rollout status --watch daemonset/simple-opa-server-default
+
+echo "Applying the rule file"
+# tag::apply-rule-file[]
+kubectl apply -f simple-rule.yaml
+# end::apply-rule-file[]
+
+echo "Starting port-forwarding of port 8081"
+# tag::port-forwarding[]
+kubectl port-forward svc/simple-opa 8081 2>&1 >/dev/null &
+# end::port-forwarding[]
+PORT_FORWARD_PID=$!
+trap "kill $PORT_FORWARD_PID" EXIT
+sleep 5
+
+request_hello() {
+# tag::request-hello[]
+curl -s http://localhost:8081/v1/data/test/hello
+# end::request-hello[]
+}
+
+echo "Checking policy decision for 'hello' rule ..."
+test_hello=$(request_hello)
+if [ "$test_hello" == "$(cat expected_response_hello.json)" ]; then
+  echo "The 'hello' rule returned the correct response!"
+else
+  echo "The 'hello' rule returned an incorrect response."
+  echo "Received: $test_hello"
+  echo "Expected: $(cat expected_response_hello.json)"
+  exit 1
+fi
+
+request_world() {
+# tag::request-world[]
+curl -s http://localhost:8081/v1/data/test/world
+# end::request-world[]
+}
+
+echo "Checking policy decision for 'world' rule ..."
+test_world=$(request_world)
+if [ "$test_world" == "$(cat expected_response_world.json)" ]; then
+  echo "The 'world' rule returned the correct response!"
+else
+  echo "The 'world' rule returned an incorrect response."
+  echo "Received: $test_world"
+  echo "Expected: $(cat expected_response_world.json)"
+  exit 1
+fi

docs/modules/getting_started/examples/code/getting_started.sh.j2

@@ -0,0 +1,95 @@
+#! /usr/bin/env bash
+set -euo pipefail
+
+# This script contains all the code snippets from the guide, as well as some assert tests
+# to test if the instructions in the guide work. The user *could* use it, but it is intended
+# for testing only.
+# The script will install the operator, create an OPA instance and briefly open a port
+# forward and query the OPA.
+# No running processes are left behind (i.e. the port-forwarding is closed at the end)
+
+if [ $# -eq 0 ]
+then
+  echo "Installation method argument ('helm' or 'stackablectl') required."
+  exit 1
+fi
+
+case "$1" in
+"helm")
+echo "Adding 'stackable-dev' Helm Chart repository"
+# tag::helm-add-repo[]
+helm repo add {{ helm.repo_name }} {{ helm.repo_url }}
+# end::helm-add-repo[]
+echo "Installing Operators with Helm"
+# tag::helm-install-operators[]
+helm install --wait opa-operator {{ helm.repo_name }}/opa-operator --version {{ versions.opa }}
+# end::helm-install-operators[]
+;;
+"stackablectl")
+echo "installing Operators with stackablectl"
+# tag::stackablectl-install-operators[]
+stackablectl operator install opa={{ versions.opa }}
+# end::stackablectl-install-operators[]
+;;
+*)
+echo "Need to provide 'helm' or 'stackablectl' as an argument for which installation method to use!"
+exit 1
+;;
+esac
+
+echo "Creating OPA cluster"
+# tag::apply-opa-cluster[]
+kubectl apply -f opa.yaml
+# end::apply-opa-cluster[]
+
+sleep 5
+
+echo "Waiting on rollout ..."
+kubectl rollout status --watch daemonset/simple-opa-server-default
+
+echo "Applying the rule file"
+# tag::apply-rule-file[]
+kubectl apply -f simple-rule.yaml
+# end::apply-rule-file[]
+
+echo "Starting port-forwarding of port 8081"
+# tag::port-forwarding[]
+kubectl port-forward svc/simple-opa 8081 2>&1 >/dev/null &
+# end::port-forwarding[]
+PORT_FORWARD_PID=$!
+trap "kill $PORT_FORWARD_PID" EXIT
+sleep 5
+
+request_hello() {
+# tag::request-hello[]
+curl -s http://localhost:8081/v1/data/test/hello
+# end::request-hello[]
+}
+
+echo "Checking policy decision for 'hello' rule ..."
+test_hello=$(request_hello)
+if [ "$test_hello" == "$(cat expected_response_hello.json)" ]; then
+  echo "The 'hello' rule returned the correct response!"
+else
+  echo "The 'hello' rule returned an incorrect response."
+  echo "Received: $test_hello"
+  echo "Expected: $(cat expected_response_hello.json)"
+  exit 1
+fi
+
+request_world() {
+# tag::request-world[]
+curl -s http://localhost:8081/v1/data/test/world
+# end::request-world[]
+}
+
+echo "Checking policy decision for 'world' rule ..."
+test_world=$(request_world)
+if [ "$test_world" == "$(cat expected_response_world.json)" ]; then
+  echo "The 'world' rule returned the correct response!"
+else
+  echo "The 'world' rule returned an incorrect response."
+  echo "Received: $test_world"
+  echo "Expected: $(cat expected_response_world.json)"
+  exit 1
+fi

docs/modules/getting_started/nav.adoc

@@ -0,0 +1,3 @@
+* xref:index.adoc[]
+** xref:installation.adoc[]
+** xref:first_steps.adoc[]

docs/modules/getting_started/pages/first_steps.adoc

@@ -0,0 +1,66 @@
+= First steps
+
+After you went through the xref:installation.adoc[], on this page you will deploy OPA, deploy your first rule and query it from the command line.
+
+== Deploy OPA
+
+To deploy OPA, you just need to create an OpaCluster resource in Kubernetes and the Operator will create the OPA instances. Create a file called `opa.yaml` with the following contents:
+
+[source,yaml]
+include::example$code/opa.yaml[]
+
+and apply it:
+
+[source,bash]
+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
+
+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:
+
+[source,yaml]
+----
+include::example$code/simple-rule.yaml[]
+----
+
+and apply it:
+
+[source,bash]
+include::example$code/getting_started.sh[tag=apply-rule-file]
+
+The Operator will read the rule file, bundle it and publish the bundle to all OPA instances.
+
+== Make policy requests
+
+Now that you have deployed the rule, you can query OPA for it. First, port-forward the service so you can query it from outside the Kubernetes cluster:
+
+[source,bash]
+include::example$code/getting_started.sh[tag=port-forwarding]
+
+Then, request the `hello` rule:
+
+[source,bash]
+include::example$code/getting_started.sh[tag=request-hello]
+
+As it was defined in the rule file, the response should be `true`:
+
+[source,json]
+include::example$code/expected_response_hello.json[]
+
+You can also request the other rule, `world`:
+
+[source,bash]
+include::example$code/getting_started.sh[tag=request-world]
+
+And see a different response:
+
+[source,json]
+include::example$code/expected_response_world.json[]
+
+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.

docs/modules/getting_started/pages/index.adoc

@@ -0,0 +1,19 @@
+= Getting started
+
+This guide will get you started with the OpenPolicyAgent (OPA) using the Stackable Operator. It will guide you through the installation of the Operator, setting up your first OPA instance, creating a policy rule and querying it.
+
+== Prerequisites
+
+You will need:
+
+* a Kubernetes cluster
+* kubectl
+* curl
+* optional: Helm
+
+== What's next
+
+The Guide is divided into two steps:
+
+* xref:installation.adoc[Installing the Operator].
+* xref:first_steps.adoc[Setting up an OPA, a policy rule and querying it].