krateoplatformops · lucasepe · Oct 24, 2025 · Oct 24, 2025
diff --git a/README.md b/README.md
@@ -8,9 +8,18 @@ It handles on-demand resolution of the `RESTAction` custom resource and all Krat
 
 ## Learn More
 
-- [Developer Guide: Building and Installing `snowplow` on Kind](howto/developer-guide-build-and-install.md)
-- [Installing `snowplow` on Kind](howto/install.md)
+### Developer Guide
+
+- [Building `snowplow`](howto/developer-guide.md)
 - [ADR: Decoupling `authn` from `snowplow` for Testing and Operations](howto/decoupling-authn-from-snowplow-for-testing.md)
+
+### User Guide
+
 - [`Endpoint` reference](howto/endpoints.md)
 - [`RESTAction` reference](howto/restactions.md)
 - [Understanding the `Widget` Custom Resource](howto/widgets.md)
+- [Installing `snowplow` on Kind](howto/install.md)
+
+### Examples
+
+- [RESTAction: list _cluster namespaces_](howto/restactions/example-cluster-namespaces.md)
diff --git a/howto/developer-guide-build-and-install.md → howto/developer-guide.md b/howto/developer-guide-build-and-install.md → howto/developer-guide.md
@@ -22,14 +22,9 @@ nodes:
     hostPort: 30081
     listenAddress: "127.0.0.1"
     protocol: TCP
-  - containerPort: 30082
-    hostPort: 30082
-    listenAddress: "127.0.0.1"
-    protocol: TCP
 EOF
 ```
 
-
 ## 2. Create a namespace
 
 Create a dedicated namespace where `snowplow` and its related resources will live.
@@ -39,7 +34,6 @@ export NAMESPACE="demo-system"
 kubectl create namespace ${NAMESPACE}
 ```
 
-
 ## 3. Build the `snowplow` image with `ko`
 
 Use [`ko`](https://ko.build/) to build and push the `snowplow` Docker image directly to the **Kind internal registry** (`kind.local`).
@@ -48,7 +42,6 @@ Use [`ko`](https://ko.build/) to build and push the `snowplow` Docker image dire
 KO_DOCKER_REPO=kind.local ko build --base-import-paths .
 ```
 
-
 ## 4. Create a ConfigMap for custom `jq` modules
 
 `Snowplow` uses custom `jq` modules during runtime. Create a ConfigMap to store them.
@@ -90,6 +83,8 @@ Deploy `snowplow` using a single manifest that includes:
 * RBAC roles and bindings
 
 ```sh {name=deploy depends=jq-custom-modules}
+export JWT_SECRET=AbbraCadabbra
+
 cat <<EOF | kubectl apply -f -
 ---
 kind: ServiceAccount
@@ -143,11 +138,11 @@ spec:
         image: kind.local/snowplow:latest
         imagePullPolicy: Never
         args:
-          - --debug=false
+          - --debug=true
           - --blizzard=false
           - --port=8081
           - --authn-namespace=${NAMESPACE}
-          - --jwt-sign-key=AbbraCadabbra
+          - --jwt-sign-key=${JWT_SECRET}
           - --pretty-log=false
           - --jq-modules-path=/jq-modules
         ports:
@@ -191,7 +186,6 @@ subjects:
 EOF
 ```
 
-
 ## 6. Wait until the `snowplow` deployment is ready
 
 Finally, wait for the `snowplow` deployment to become **available**.
@@ -203,3 +197,62 @@ kubectl wait deployment/snowplow \
   --for=condition=available \
   --timeout=90s
 ```
+
+## 9. Apply the `RESTAction` CRD
+
+```sh {name=install-restaction-crd depends=wait-for-snowplow}
+kubectl apply -f ./crds/templates.krateo.io_restactions.yaml
+```
+
+## 8. Create a Krateo PlatformOps User
+
+To quickly create a Krateo PlatformOps user, install [`krateoctl`][krateoctl] and run the following command:
+
+```sh {name=create-krateo-user}
+export KRATEO_USER=cyberjoker
+export KRATEO_ACCESS_TOKEN=$(krateoctl add-user -k "${JWT_SECRET}" -n "${NAMESPACE}" "${KRATEO_USER}")
+
+echo "KRATEO_USER=${KRATEO_USER}" > .env
+echo "KRATEO_ACCESS_TOKEN=${KRATEO_ACCESS_TOKEN}" >> .env
+```
+
+## 9. RBACs for the Krateo PlatformOps User
+
+After creating a new user, you must assign them a minimal set of RBAC permissions.
+In this case, since we are testing [RESTActions][restactions], the user needs at least read access to this resource.
+> Write, create, or delete permissions can be granted at the discretion of the cluster administrator.
+
+Moreover, if the [RESTAction][restactions] invokes any internal cluster APIs (for example, to list other resources), the user must also have the necessary permissions to access those resources.
+
+For now, we will grant read-only permissions on [RESTActions][restactions].
+Since the user created earlier belongs to the _"devs"_ group, we will, for simplicity, assign these permissions to the entire _"devs"_ group:
+
+```sh
+cat <<EOF | kubectl apply -f -
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: restactions-viewer
+rules:
+- apiGroups:
+  - templates.krateo.io
+  resources:
+  - restactions
+  verbs:
+  - get
+  - list
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: restactions-viewer
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name:  restactions-viewer
+subjects:
+- kind: Group
+  name: devs
+  apiGroup: rbac.authorization.k8s.io
+EOF
+```
diff --git a/howto/install.md b/howto/install.md
@@ -10,20 +10,16 @@ apiVersion: kind.x-k8s.io/v1alpha4
 nodes:
 - role: control-plane
   extraPortMappings:
-  - containerPort: 30081 # Krateo Snowplow
+  - containerPort: 30081
     hostPort: 30081
     listenAddress: "127.0.0.1"
     protocol: TCP
-  - containerPort: 30082 # Krateo AuthN Service
-    hostPort: 30082
-    listenAddress: "127.0.0.1"
-    protocol: TCP
 EOF
 ```
 
 ## 2. Create a namespace
 
-Create a dedicated namespace where `snowplow` and its related resources will live.
+Create a dedicated namespace where Snowplow and its related resources will live.
 
 ```sh {name=create-namespace depends=kind-up}
 export NAMESPACE="demo-system"
@@ -35,7 +31,7 @@ kubectl create namespace ${NAMESPACE}
 ```sh {name=create-jwt-secret depends=create-namespace}
 export JWT_SECRET=AbbraCadabbra
 kubectl create secret generic jwt-sign-key \
-  --from-literal=key=${JWT_SECRET} -n ${NAMESPACE}
+  --from-literal=JWT_SIGN_KEY=${JWT_SECRET} -n ${NAMESPACE}
 ```
 
 ## 4. Create a Krateo PlatformOps User
@@ -50,15 +46,73 @@ echo "KRATEO_USER=${KRATEO_USER}" > .env
 echo "KRATEO_ACCESS_TOKEN=${KRATEO_ACCESS_TOKEN}" >> .env
 ```
 
-## 5. Deploy snowplow
+## 5. RBACs for the Krateo PlatformOps User
+
+After creating a new user, you must assign them a minimal set of RBAC permissions.
+In this case, since we are testing [RESTActions][restactions], the user needs at least read access to this resource.
+> Write, create, or delete permissions can be granted at the discretion of the cluster administrator.
+
+Moreover, if the [RESTAction][restactions] invokes any internal cluster APIs (for example, to list other resources), the user must also have the necessary permissions to access those resources.
+
+For now, we will grant read-only permissions on [RESTActions][restactions].
+Since the user created earlier belongs to the _"devs"_ group, we will, for simplicity, assign these permissions to the entire _"devs"_ group:
+
+```sh
+cat <<EOF | kubectl apply -f -
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: restactions-viewer
+rules:
+- apiGroups:
+  - templates.krateo.io
+  resources:
+  - restactions
+  verbs:
+  - get
+  - list
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: restactions-viewer
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name:  restactions-viewer
+subjects:
+- kind: Group
+  name: devs
+  apiGroup: rbac.authorization.k8s.io
+EOF
+```
+
+
+## 6. Deploy snowplow
 
 Finally, install `snowplow` using the Helm chart:
 
-```sh {name=install-snowplow depends=create-jwt-secret}
+```sh {name=install depends=create-jwt-secret}
 helm install snowplow https://github.com/krateoplatformops/helm-charts/raw/gh-pages/snowplow-0.20.2.tgz \
-  --namespace ${NAMESPACE}
+  --namespace ${NAMESPACE} \
+  --set service.type=NodePort --set service.nodePort=30081 \
+  --set env.DEBUG=true
 ```
 
+
+## 7. Wait until the `snowplow` deployment is ready
+
+Finally, wait for the `snowplow` deployment to become **available**.
+This ensures all pods are up and running before proceeding.
+
+```sh {name=wait-for-snowplow depends=install}
+kubectl wait deployment/snowplow \
+  --namespace ${NAMESPACE} \
+  --for=condition=available \
+  --timeout=90s
+```
+
+
 You are now ready to move on to the next steps. From here, you can start testing the [RESTActions][restactions] to see how the different use cases work in practice. 
 
 Experiment with creating, updating, and querying resources to get a hands-on understanding of the platform's capabilities.

diff --git a/howto/restactions.md b/howto/restactions.md
@@ -7,11 +7,18 @@
 
 ## Overview
 
+The `RESTAction` is a Krateo PlatformOps resource that enables users to **declaratively define one or more REST API calls** within Kubernetes.
+
+It allows you to chain HTTP requests, handle dependencies between them, extract data, and use filters to process results — all through a Kubernetes-native manifest.
+
+This approach is particularly useful for integrating external systems or Kubernetes APIs into workflows managed by Krateo PlatformOps.
+
 > `RESTAction` defines one or more declarative HTTP (REST) calls that can optionally depend on other calls.
 
 It allows you to orchestrate a chain of API requests across multiple endpoints using Kubernetes resources.
 
-A `RESTAction` resource declaratively defines one or more HTTP calls (`spec.api`) that can depend on each other.  
+A `RESTAction` resource declaratively defines one or more HTTP calls (`spec.api`) that can depend on each other.
+
 Each call can produce a JSON response that becomes part of a **shared global context**, enabling subsequent calls to reference previous results using **JQ expressions**, iterators, and filters.
 
 To fully leverage these advanced capabilities — such as resolving JQ expressions, using custom JQ functions or modules, and managing interdependent API calls — the `RESTAction` must be executed through the `snowplow` service endpoint (`/call`).