Feat: AIAC Event Broker + Keycloak SPI listener (phase 2, PR 2)

aiac/docs/specs/components/event-broker.md

@@ -69,7 +69,7 @@ No authentication credentials are required. The NATS server runs with no-auth co
 
 ## Runtime
 
-- Image: `nats:latest` with JetStream enabled (`-js` flag)
+- Image: `nats:2.14-alpine` with JetStream enabled (`-js` flag)
 - Bind: `0.0.0.0:4222` (NATS client port)
 - Kubernetes ClusterIP service: `aiac-event-broker-service:4222`
 - Base image: official `nats` Docker image

aiac/k8s/agent-deployment.yaml

@@ -90,9 +90,34 @@ spec:
         fsGroup: 10001
         seccompProfile:
           type: RuntimeDefault
-      # aiac-init init container is deferred to Phase 2 (issue 4.21).
-      # It will gate startup on NATS + IdP Config + PDP Policy + RAG Ingest health
-      # and provision the aiac-events JetStream stream.
+      initContainers:
+        # Gates Agent startup on NATS + IdP Config + PDP Policy (+ optional RAG
+        # Ingest) health, then provisions the aiac-events JetStream stream.
+        # Reuses the aiac-agent image (see src/aiac/agent/init/wait_and_provision.py).
+        - name: aiac-init
+          image: localhost/aiac-agent:local
+          imagePullPolicy: Never
+          command: ["python", "-m", "aiac.agent.init.wait_and_provision"]
+          envFrom:
+            - configMapRef:
+                name: aiac-pdp-config
+          # Same hardening baseline as the app container; temp writes go to /tmp.
+          securityContext:
+            allowPrivilegeEscalation: false
+            readOnlyRootFilesystem: true
+            capabilities:
+              drop:
+                - ALL
+          resources:
+            requests:
+              cpu: 50m
+              memory: 64Mi
+            limits:
+              cpu: 250m
+              memory: 128Mi
+          volumeMounts:
+            - name: tmp
+              mountPath: /tmp
       containers:
         - name: aiac-agent
           image: localhost/aiac-agent:local

aiac/k8s/aiac-deployment-guide.md

@@ -8,7 +8,8 @@ This guide covers the full AIAC deployment in the `aiac-system` namespace.
 |---|---|---|
 | `pdp-interface-deployment.yaml` | Rossoctl Interface Pod (IdP Configuration Service + PDP Policy Writer **Phase 1 rego-file mock** `aiac-pdp-policy-opa`) + 2 ClusterIP Services | 7071, 7072 |
 | `policy-model-store-statefulset.yaml` | Policy Model Store StatefulSet + 1 Gi PVC + headless Service + ClusterIP Service | 7074 |
-| `agent-deployment.yaml` | Agent Pod Deployment (AIAC Agent) + ClusterIP Service | 7070 |
+| `event-broker-deployment.yaml` | NATS JetStream Event Broker Deployment + ClusterIP Service | 4222 |
+| `agent-deployment.yaml` | Agent Pod Deployment (`aiac-init` init container + AIAC Agent) + ClusterIP Service | 7070 |
 
 ## Prerequisites
 
@@ -37,11 +38,13 @@ docker build -f aiac/src/aiac/pdp/service/policy/opa/Dockerfile \
 docker build -f aiac/src/aiac/policy/model_store/service/Dockerfile \
   -t localhost/aiac-policy-model-store:local aiac/src/
 
-# AIAC Agent
+# AIAC Agent (also used as the aiac-init init container, via a command override) — context: aiac/src/
 docker build -f aiac/src/aiac/agent/controller/Dockerfile \
   -t localhost/aiac-agent:local aiac/src/
 ```
 
+The Event Broker uses the stock `nats:latest` image — no build step.
+
 ## 2 — Load images into the cluster
 
 **Kind (local development)**
@@ -53,15 +56,26 @@ kind load docker-image localhost/aiac-policy-model-store:local     --name <clust
 kind load docker-image localhost/aiac-agent:local            --name <cluster-name>
 ```
 
+For a fully air-gapped Kind cluster (no outbound network access), also pull and load the
+NATS image; `event-broker-deployment.yaml` uses `imagePullPolicy: IfNotPresent`, so a
+networked cluster can skip this and pull it directly:
+
+```bash
+docker pull nats:latest
+kind load docker-image nats:latest --name <cluster-name>
+```
+
 **Remote registry** — tag, push, then update the `image:` fields in the manifests to match.
 
-> **Note:** the manifests set `imagePullPolicy: Never` because images are side-loaded
-> into a local Kind cluster (dev only). For a real cluster that pulls from a registry,
-> change these to `imagePullPolicy: IfNotPresent` (or `Always`).
+## 3 — Create the secrets
 
-## 3 — Create the admin secret
+Two Secrets must exist in `aiac-system` before applying the manifests. Create the namespace first, then both secrets.
 
-The Interface Pod requires a `keycloak-admin-secret` Secret. Create it once per cluster before applying the manifests:
+```bash
+kubectl create namespace aiac-system
+```
+
+**`keycloak-admin-secret`** — required by the Interface Pod:
 
 ```bash
 kubectl create secret generic keycloak-admin-secret \
@@ -114,10 +128,13 @@ Edit the `aiac-pdp-config` ConfigMap in `pdp-interface-deployment.yaml` to match
 | `AIAC_PDP_POLICY_URL` | `http://aiac-pdp-policy-service:7072` | Agent |
 | `AIAC_POLICY_MODEL_STORE_URL` | `http://aiac-policy-model-store-service:7074` | Agent |
 | `SERVICEPOLICY_DB_PATH` | `/data/policy_model.db` | Policy Model Store |
-| `NATS_URL` | `nats://aiac-event-broker-service:4222` | Agent — **added in Phase 2** (Event Broker, issue 4.19) |
+| `NATS_URL` | `nats://aiac-event-broker-service:4222` | Agent, `aiac-init` — Event Broker ClusterIP address |
 | `AIAC_RAG_INGEST_URL` | `http://aiac-rag-service:7073` | Init container — **added in Phase 3** (RAG Pod, issue 4.20) |
 | `AIAC_CHROMADB_URL` | `http://aiac-rag-service:8000` | Agent — **added in Phase 3** (RAG Pod, issue 4.20) |
 
+`aiac-init` treats `AIAC_RAG_INGEST_URL` as optional and skips the RAG Ingest health check
+when it is unset (the current phase has no RAG pod deployed yet).
+
 ## 5 — Deploy
 
 Apply in dependency order:
@@ -126,17 +143,21 @@ Apply in dependency order:
 # 1. Interface Pod — creates the namespace, ConfigMap, Secret, and ClusterIP Services
 kubectl apply -f aiac/k8s/pdp-interface-deployment.yaml
 
-# 2. Policy Model Store — needs the aiac-system namespace
+# 2. Event Broker — NATS JetStream, no dependencies
+kubectl apply -f aiac/k8s/event-broker-deployment.yaml
+
+# 3. Policy Model Store — needs the aiac-system namespace
 kubectl apply -f aiac/k8s/policy-model-store-statefulset.yaml
 
-# 3. Agent — depends on the Interface Pod + Policy Model Store already being healthy
+# 4. Agent — aiac-init waits for NATS + Interface Pod + Policy Model Store to be healthy
 kubectl apply -f aiac/k8s/agent-deployment.yaml
 ```
 
 Wait for all pods to be ready:
 
 ```bash
 kubectl wait deployment/aiac-interface     -n aiac-system --for=condition=Available --timeout=120s
+kubectl wait deployment/aiac-event-broker  -n aiac-system --for=condition=Available --timeout=120s
 kubectl wait statefulset/aiac-policy-model-store -n aiac-system --for=jsonpath='{.status.readyReplicas}'=1 --timeout=120s
 kubectl wait deployment/aiac-agent         -n aiac-system --for=condition=Available --timeout=120s
 ```
@@ -166,9 +187,29 @@ kubectl port-forward svc/aiac-agent-service 7070:7070 -n aiac-system &
 curl http://localhost:7070/health
 # {"status":"ok"}
 
+#cleanup all the tunnels that were opended to the cluster
 pkill -f "port-forward"
 ```
 
+### NATS Event Broker — end-to-end check
+
+Requires the [`nats` CLI](https://github.com/nats-io/natscli).
+
+```bash
+kubectl port-forward svc/aiac-event-broker-service 4222:4222 -n aiac-system &
+nats context save aiac --server nats://localhost:4222
+nats context select aiac
+
+# Publish a test service-onboarding event (use a real IdP client UUID to see it
+# processed end to end; any string will demonstrate delivery either way):
+nats pub aiac.apply.service.<test-uuid> '{"id":"<test-uuid>"}'
+
+# Confirm the Agent processed and acked it (no redelivery):
+kubectl logs deployment/aiac-agent -n aiac-system -c aiac-agent --tail=50
+
+pkill -f "port-forward.*4222"
+```
+
 Run the IdP data smoke test:
 
 ```bash
@@ -181,9 +222,10 @@ pkill -f "port-forward.*7071"
 ## Redeploying after a code change
 
 ```bash
-# Rebuild the changed image, e.g. IdP Configuration Service:
+# Rebuild the changed image, e.g. IdP Configuration Service (context: the service dir):
 docker build -f aiac/src/aiac/idp/service/configuration/keycloak/Dockerfile \
-  -t localhost/aiac-pdp-config:local aiac/src/
+  -t localhost/aiac-pdp-config:local \
+  aiac/src/aiac/idp/service/configuration/keycloak/
 kind load docker-image localhost/aiac-pdp-config:local --name <cluster-name>
 
 # Restart the affected deployment:

aiac/k8s/event-broker-deployment.yaml

@@ -0,0 +1,43 @@
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: aiac-event-broker
+  namespace: aiac-system
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: aiac-event-broker
+  template:
+    metadata:
+      labels:
+        app: aiac-event-broker
+    spec:
+      containers:
+        - name: nats
+          image: nats:2.14-alpine
+          imagePullPolicy: IfNotPresent
+          args: ["-js", "-sd", "/data/jetstream"]
+          ports:
+            - containerPort: 4222
+          volumeMounts:
+            - name: jetstream-data
+              mountPath: /data/jetstream
+      volumes:
+        - name: jetstream-data
+          emptyDir: {}
+
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: aiac-event-broker-service
+  namespace: aiac-system
+spec:
+  selector:
+    app: aiac-event-broker
+  ports:
+    - name: nats
+      port: 4222
+      targetPort: 4222

aiac/k8s/pdp-interface-deployment.yaml

@@ -22,7 +22,8 @@ data:
   # PLATFORM_SOURCE_CLIENTS is the comma-separated list of platform bypass
   # clients the inbound Rego admits without a user role.
   PLATFORM_SOURCE_CLIENTS: "rossoctl"
-  # NATS_URL is added to this ConfigMap in Phase 2 (Event Broker, issue 4.19).
+  # NATS_URL points the PDP services at the Event Broker (Phase 2, issue 4.19).
+  NATS_URL: "nats://aiac-event-broker-service:4222"
   # AIAC_RAG_INGEST_URL and AIAC_CHROMADB_URL are added in Phase 3 (RAG Pod, issue 4.20).
 
 ---

aiac/keycloak-spi/.dockerignore

@@ -0,0 +1,8 @@
+target/
+.idea/
+.vscode/
+.git/
+.gitignore
+*.iml
+README.md
+Makefile

aiac/keycloak-spi/.gitignore

@@ -0,0 +1,2 @@
+# Maven build output — regenerated by `mvn package`, never committed.
+target/

aiac/keycloak-spi/Dockerfile

@@ -0,0 +1,22 @@
+# syntax=docker/dockerfile:1.7
+
+ARG KEYCLOAK_IMAGE=quay.io/keycloak/keycloak:26.6.3
+
+# Stage 1: build the SPI JAR (shaded — bundles jnats, since it isn't on Keycloak's classpath).
+FROM maven:3.9-eclipse-temurin-17 AS jar-builder
+WORKDIR /build
+COPY pom.xml .
+COPY src ./src
+RUN --mount=type=cache,target=/root/.m2 mvn -B -DskipTests package
+
+# Stage 2: drop the JAR into Keycloak and run `kc.sh build` so the augmented server is baked
+# into the final image (no per-pod build at startup).
+FROM ${KEYCLOAK_IMAGE} AS keycloak-builder
+COPY --from=jar-builder /build/target/aiac-event-listener-*.jar /opt/keycloak/providers/
+RUN /opt/keycloak/bin/kc.sh build
+
+# Stage 3: final runtime image — copy the augmented Keycloak from stage 2.
+FROM ${KEYCLOAK_IMAGE}
+COPY --from=keycloak-builder /opt/keycloak/ /opt/keycloak/
+ENTRYPOINT ["/opt/keycloak/bin/kc.sh"]
+CMD ["start"]

aiac/keycloak-spi/Makefile

@@ -0,0 +1,75 @@
+SPI_VERSION      := 0.1.0
+KEYCLOAK_VERSION := 26.6.3
+
+JAR := target/aiac-event-listener-$(SPI_VERSION).jar
+
+REGISTRY  ?= ghcr.io/rossoctl/cortex
+IMAGE     ?= aiac-keycloak-event-listener
+IMAGE_TAG ?= $(SPI_VERSION)-kc$(KEYCLOAK_VERSION)
+IMAGE_REF := $(REGISTRY)/$(IMAGE):$(IMAGE_TAG)
+
+# Auto-detect if the 'docker' client is using a Podman backend.
+IS_PODMAN_DETECT := $(shell docker info 2>/dev/null | grep -q "/var/lib/containers/storage" && echo "true")
+ifeq ($(DOCKER_IS_PODMAN),)
+  DOCKER_IS_PODMAN := $(IS_PODMAN_DETECT)
+endif
+
+PLATFORMS ?= linux/amd64,linux/arm64
+
+HOST_ARCH := $(shell uname -m)
+ifeq ($(HOST_ARCH),x86_64)
+  HOST_PLATFORM := linux/amd64
+else ifeq ($(HOST_ARCH),aarch64)
+  HOST_PLATFORM := linux/arm64
+else ifeq ($(HOST_ARCH),arm64)
+  HOST_PLATFORM := linux/arm64
+else
+  HOST_PLATFORM := linux/amd64
+endif
+
+.PHONY: all package test clean image push install-info
+
+all: package
+
+package: $(JAR)
+
+$(JAR):
+	mvn package
+
+test:
+	mvn test
+
+clean:
+	mvn clean
+
+image:
+	@if [ "$(DOCKER_IS_PODMAN)" = "true" ]; then \
+		echo "Info: Podman backend detected."; \
+	fi
+	docker buildx build \
+	    --platform $(PLATFORMS) \
+	    --build-arg KEYCLOAK_IMAGE=quay.io/keycloak/keycloak:$(KEYCLOAK_VERSION) \
+	    -t $(IMAGE_REF) .
+	docker buildx build \
+	    --platform $(HOST_PLATFORM) \
+	    --build-arg KEYCLOAK_IMAGE=quay.io/keycloak/keycloak:$(KEYCLOAK_VERSION) \
+	    -t $(IMAGE_REF) --load .
+	@echo "Built $(IMAGE_REF) for $(PLATFORMS) (loaded $(HOST_PLATFORM) locally)"
+
+push:
+	docker buildx build \
+	    --platform $(PLATFORMS) \
+	    --build-arg KEYCLOAK_IMAGE=quay.io/keycloak/keycloak:$(KEYCLOAK_VERSION) \
+	    -t $(IMAGE_REF) --push .
+	@echo "Pushed $(IMAGE_REF) for $(PLATFORMS)"
+
+install-info:
+	@echo "JAR-only install:"
+	@echo "  Copy $(JAR) into your Keycloak/RHBK providers directory, then run:"
+	@echo "    kc.sh build"
+	@echo "  and restart Keycloak."
+	@echo
+	@echo "Custom image install:"
+	@echo "  make push                                # builds and pushes $(IMAGE_REF)"
+	@echo "  Override the Keycloak image in your Helm values / Operator CR to: $(IMAGE_REF)"
+	@echo "  (this repo does not manage that Helm chart — see README.md)"