Merge branch 'main' into fix/activity-policy-2xx-gate

Author: ecv

.claude/settings.json

@@ -0,0 +1,14 @@
+{
+  "extraKnownMarketplaces": {
+    "datum-claude-code-plugins": {
+      "source": {
+        "source": "github",
+        "repo": "datum-cloud/claude-code-plugins"
+      }
+    }
+  },
+  "enabledPlugins": {
+    "datum-platform@datum-claude-code-plugins": true,
+    "datum-gtm@datum-claude-code-plugins": true
+  }
+}

Taskfile.yaml

@@ -1,6 +1,10 @@
 version: '3'
 
 includes:
+  # Documentation tasks
+  docs:
+    taskfile: ./docs/Taskfile.yaml
+    dir: ./docs
   dev:
     taskfile: ./Taskfile.dev.yaml
 
@@ -77,4 +81,9 @@ tasks:
             echo ""
             echo "🎉 All Prometheus rule tests passed."
           fi
-      silent: false
+      silent: false
+
+  generate:
+    desc: Run code generation (deepcopy, defaults)
+    deps:
+      - task: docs:generate

api/v1alpha/trafficprotectionpolicy_types.go

@@ -91,7 +91,7 @@ type OWASPCRS struct {
 	// ParanoiaLevels specifies the OWASP ModSecurity Core Rule Set (CRS)
 	// paranoia levels to use.
 	//
-	// +kubebuilder:default={}
+	// +kubebuilder:default={blocking:1,detection:1}
 	ParanoiaLevels ParanoiaLevels `json:"paranoiaLevels,omitempty"`
 
 	// ScoreThresholds specifies the OWASP ModSecurity Core Rule Set (CRS)
@@ -110,6 +110,7 @@ type OWASPCRS struct {
 	RuleExclusions *OWASPRuleExclusions `json:"ruleExclusions,omitempty"`
 }
 
+// +kubebuilder:validation:XValidation:message="detection paranoia level must be greater than or equal to blocking paranoia level",rule="self.detection >= self.blocking"
 type ParanoiaLevels struct {
 	// Blocking specifies the paranoia level for blocking requests or responses.
 	//

config/crd/bases/networking.datumapis.com_trafficprotectionpolicies.yaml

@@ -67,7 +67,9 @@ spec:
                         Core Rule Set (CRS).
                       properties:
                         paranoiaLevels:
-                          default: {}
+                          default:
+                            blocking: 1
+                            detection: 1
                           description: |-
                             ParanoiaLevels specifies the OWASP ModSecurity Core Rule Set (CRS)
                             paranoia levels to use.
@@ -89,6 +91,10 @@ spec:
                               minimum: 1
                               type: integer
                           type: object
+                          x-kubernetes-validations:
+                          - message: detection paranoia level must be greater than
+                              or equal to blocking paranoia level
+                            rule: self.detection >= self.blocking
                         ruleExclusions:
                           description: |-
                             RuleExclusions can be used to disable specific OWASP ModSecurity Rules.

config/dev/downstream_resources/downstream-gateway.yaml

@@ -63,7 +63,7 @@ spec:
               mountPath: /opt/coraza-waf
         initContainers:
           - name: coraza-waf
-            image: coraza-waf:v1.1.1-dev2
+            image: ghcr.io/datum-labs/coraza-envoy-go-filter/coraza-waf:v1.3.0-alpha10
             imagePullPolicy: IfNotPresent
             command:
               - cp

docs/Taskfile.yaml

@@ -0,0 +1,69 @@
+version: '3'
+
+vars:
+  DIAGRAMS_DIR: "{{.ROOT_DIR}}/docs/diagrams"
+  OUTPUT_FORMAT: "png"
+  PLANTUML_IMAGE: plantuml/plantuml:1.2026.4
+
+tasks:
+  generate:
+    desc: Generate all documentation artifacts (diagrams, etc.)
+    cmds:
+      - task: diagrams:render
+    silent: true
+
+  diagrams:
+    desc: Generate all architecture diagrams from PlantUML
+    cmds:
+      - task: diagrams:render
+    silent: true
+
+  diagrams:render:
+    desc: Render PlantUML diagrams to PNG format using Docker
+    cmds:
+      - |
+        set -e
+        echo "Rendering PlantUML diagrams..."
+        echo ""
+
+        # Check if PlantUML files exist
+        if ! ls {{.DIAGRAMS_DIR}}/*.puml >/dev/null 2>&1; then
+          echo "❌ Error: PlantUML source files (*.puml) not found in {{.DIAGRAMS_DIR}}"
+          exit 1
+        fi
+
+        # Render using Docker (no local installation required)
+        docker run --rm \
+          -v "{{.DIAGRAMS_DIR}}":/data \
+          {{.PLANTUML_IMAGE}} \
+          -t{{.OUTPUT_FORMAT}} \
+          /data/*.puml
+
+        echo ""
+        echo "✅ Diagrams rendered in {{.DIAGRAMS_DIR}}"
+        echo ""
+        echo "Generated files:"
+        ls -1 {{.DIAGRAMS_DIR}}/*.{{.OUTPUT_FORMAT}} 2>/dev/null | xargs -n1 basename || echo "No output files found"
+    silent: true
+
+  diagrams:clean:
+    desc: Remove generated diagram files
+    cmds:
+      - |
+        rm -f {{.DIAGRAMS_DIR}}/*.png {{.DIAGRAMS_DIR}}/*.svg
+        echo "✅ Generated diagram files removed"
+    silent: true
+
+  diagrams:validate:
+    desc: Validate PlantUML syntax using Docker
+    cmds:
+      - |
+        set -e
+        echo "Validating PlantUML diagrams..."
+        docker run --rm \
+          -v "{{.DIAGRAMS_DIR}}":/data \
+          {{.PLANTUML_IMAGE}} \
+          -syntax \
+          /data/*.puml
+        echo "✅ All diagrams are valid"
+    silent: true

docs/api/trafficprotectionpolicies.md

@@ -191,6 +191,7 @@ Core Rule Set (CRS).
           ParanoiaLevels specifies the OWASP ModSecurity Core Rule Set (CRS)
 paranoia levels to use.<br/>
           <br/>
+            <i>Validations</i>:<li>self.detection >= self.blocking: detection paranoia level must be greater than or equal to blocking paranoia level</li>
             <i>Default</i>: map[]<br/>
         </td>
         <td>false</td>

docs/diagrams/http-metering-c4.png

@@ -0,0 +1,25 @@
+@startuml http-metering-c4
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
+
+LAYOUT_WITH_LEGEND()
+
+title C4 Container Diagram - HTTP Traffic Metering System
+
+Person(client, "End User / Client", "Requests services exposed via Datum Cloud Edge")
+
+System_Boundary(edge_cluster, "Edge Cluster") {
+    Container(envoy, "Envoy Gateway Proxy", "Envoy/Go", "Handles ingress HTTP traffic, terminates TLS, enforces WAF/rate-limiting, emits JSON access logs to stdout")
+    Container(vector_collector, "billing-usage-collector-vector", "Vector DaemonSet (Billing)", "Tails Envoy container logs, parses JSON access logs, translates to CloudEvents, and forwards them to the Billing System")
+    Container(nso, "Network Services Operator", "Go", "Deploys Envoy Gateway and configures EnvoyProxy logging policies")
+}
+
+System_Boundary(control_plane, "Platform Control Plane") {
+    Container(billing_system, "Billing System & Service Catalog", "Platform Service", "Handles service registration, event validation, attribution, and storage")
+}
+
+Rel(client, envoy, "Sends HTTPS requests to", "HTTPS")
+Rel(nso, envoy, "Configures & manages", "Kubernetes API / EnvoyProxy CR")
+Rel_D(envoy, vector_collector, "Outputs JSON access logs to", "stdout / container logs")
+Rel_D(vector_collector, billing_system, "Forwards batched events to", "HTTPS CloudEvents")
+
+@enduml