feat(networking): add tenant agent isolation NetworkPolicy

Implements Phase 1 of the DevOps roadmap: zero-trust network
isolation for agent pods across tenant namespaces.

Changes:
- internal/controller/agentdeployment_controller.go: Add
  'agentrax.io/agent: true' label to agentLabels(). This label
  acts as the NetworkPolicy pod selector key. Safe for existing
  Deployments because reconcileDeployment() only writes
  spec.selector on creation (ResourceVersion == '').

- config/network-policy/tenant-agent-isolation.yaml: New
  NetworkPolicy targeting pods with agentrax.io/agent=true.
  Default-denies all ingress/egress, then allows:
    - Ingress: Prometheus scrape on port 8080 from namespaces
      labelled monitoring=enabled
    - Egress: kube-apiserver port 6443, CoreDNS port 53 UDP+TCP

- config/network-policy/kustomization.yaml: Add new manifest
  to the network-policy Kustomize component.

- config/default/kustomization.yaml: Uncomment the network-policy
  component so it is included in the default overlay.

- docs/networking/README.md: Two-tier policy model documentation,
  traffic diagrams, and per-tenant application instructions.

Verified:
  make test   -> all packages pass (controller: 71.8%)
  make lint   -> 0 errors
  make manifests -> 0 errors
  helm lint   -> 0 failures
  YAML validate -> NetworkPolicy schema correct

Author: gitcommitankit

config/default/kustomization.yaml

@@ -31,7 +31,7 @@ resources:
 # Only Pod(s) running a namespace labeled with 'metrics: enabled' will be able to gather the metrics.
 # Only CR(s) which requires webhooks and are applied on namespaces labeled with 'webhooks: enabled' will
 # be able to communicate with the Webhook Server.
-#- ../network-policy
+- ../network-policy
 
 # Uncomment the patches line if you enable Metrics, and/or are using webhooks and cert-manager
 patches:

config/network-policy/kustomization.yaml

@@ -1,2 +1,3 @@
 resources:
 - allow-metrics-traffic.yaml
+- tenant-agent-isolation.yaml

config/network-policy/tenant-agent-isolation.yaml

@@ -0,0 +1,65 @@
+---
+# Tenant Agent Isolation NetworkPolicy
+#
+# Purpose: Restricts agent pods across tenant namespaces, enforcing zero-trust
+#          isolation between tenants and preventing unauthorized outbound traffic.
+#
+# Selector: Matches all pods labelled `agentrax.io/agent: "true"`.
+#           The AgentDeployment reconciler sets this label on every pod template
+#           it manages, so this policy applies to all managed agent pods.
+#
+# Ingress rules:
+#   - Allow Prometheus to scrape metrics on port 8080 from namespaces
+#     labelled `monitoring: enabled` (kube-prometheus-stack namespace).
+#
+# Egress rules:
+#   - Allow egress to kube-apiserver on port 6443 (required for agent-to-API
+#     communication and tool-calling via the Kubernetes API).
+#   - Allow CoreDNS lookups on port 53 (UDP and TCP) for service discovery
+#     within the cluster.
+#   - All other egress (internet, cross-tenant) is denied by default.
+#
+# Usage: Apply this manifest to every tenant namespace:
+#   kubectl apply -n tenant-<name> -f tenant-agent-isolation.yaml
+#
+# Note: This policy does NOT apply to the agentrax-system namespace (operator pods).
+#       The operator namespace is protected by allow-metrics-traffic.yaml.
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: tenant-agent-isolation
+  labels:
+    app.kubernetes.io/name: agentrax
+    app.kubernetes.io/managed-by: kustomize
+spec:
+  # Select all pods carrying the agentrax.io/agent=true label.
+  # This label is set by agentLabels() in the AgentDeployment reconciler.
+  podSelector:
+    matchLabels:
+      agentrax.io/agent: "true"
+  policyTypes:
+    - Ingress
+    - Egress
+  ingress:
+    # Allow Prometheus to scrape /metrics on port 8080.
+    # Prometheus Operator runs in a namespace labelled `monitoring: enabled`.
+    - from:
+        - namespaceSelector:
+            matchLabels:
+              monitoring: enabled
+      ports:
+        - port: 8080
+          protocol: TCP
+  egress:
+    # Allow outbound to kube-apiserver on port 6443.
+    # Agents may call the Kubernetes API to discover services or use cluster tools.
+    - ports:
+        - port: 6443
+          protocol: TCP
+    # Allow CoreDNS resolution on UDP and TCP port 53.
+    # Without this, service name lookups fail and MCP tool endpoints are unreachable.
+    - ports:
+        - port: 53
+          protocol: UDP
+        - port: 53
+          protocol: TCP

docs/networking/README.md

@@ -0,0 +1,138 @@
+# Agentrax — Tenant Network Isolation
+
+This document explains the two-tier network policy model shipped with Agentrax
+and how platform operators apply it to tenant namespaces.
+
+## Overview
+
+Agentrax uses Kubernetes `NetworkPolicy` to enforce a **zero-trust perimeter**
+around all agent pods. This prevents a compromised or misbehaving agent in one
+tenant from reaching another tenant's services, the operator control plane, or
+arbitrary internet destinations.
+
+Two policies are maintained:
+
+| Policy File                   | Namespace                  | Purpose                                                                    |
+| ----------------------------- | -------------------------- | -------------------------------------------------------------------------- |
+| `allow-metrics-traffic.yaml`  | `agentrax-system`          | Allows Prometheus to scrape the operator `/metrics` endpoint               |
+| `tenant-agent-isolation.yaml` | Every `tenant-*` namespace | Isolates agent pods — restricts all ingress/egress to the minimum required |
+
+## How the Label Selector Works
+
+The `tenant-agent-isolation` policy uses `podSelector.matchLabels`:
+
+```yaml
+podSelector:
+  matchLabels:
+    agentrax.io/agent: "true"
+```
+
+The `AgentDeployment` reconciler (`internal/controller/agentdeployment_controller.go`)
+stamps this label onto every agent `Deployment`'s pod template via `agentLabels()`.
+No manual labelling is needed — all agent pods are automatically covered.
+
+## Traffic Model
+
+```
+┌─────────────────────────────────────────────────────┐
+│                 tenant-finance namespace            │
+│                                                     │
+│   [Agent Pod] agentrax.io/agent=true                │
+│       │                                             │
+│       ├─ Ingress ← port 8080 ← [Prometheus]         │
+│       │           (monitoring namespace only)       │
+│       │                                             │
+│       ├─ Egress → port 6443 → [kube-apiserver]      │
+│       ├─ Egress → port 53   → [CoreDNS]             │
+│       │                                             │
+│       └─ ALL OTHER TRAFFIC: BLOCKED                 │
+└─────────────────────────────────────────────────────┘
+```
+
+## Applying the Policy to Tenant Namespaces
+
+The `tenant-agent-isolation.yaml` NetworkPolicy must be applied to each tenant
+namespace. The policy is **not** automatically applied by the operator — it is
+applied once by a platform admin when provisioning a tenant namespace.
+
+### Apply Manually
+
+```bash
+# Apply to a specific tenant namespace:
+kubectl apply -n tenant-finance \
+  -f config/network-policy/tenant-agent-isolation.yaml
+
+kubectl apply -n tenant-marketing \
+  -f config/network-policy/tenant-agent-isolation.yaml
+```
+
+### Apply via Kustomize (Development)
+
+The default Kustomize overlay applies both network policies to the `agentrax-system`
+namespace for development/testing. The `tenant-agent-isolation` policy in this
+context validates the manifest schema; in production it must be applied per tenant
+namespace as above.
+
+```bash
+kubectl apply -k config/default/
+```
+
+### Apply via Helm (Recommended for Production)
+
+When installing via Helm, set `networkPolicy.enabled: true` (Phase 1 Helm
+integration — coming in a future release):
+
+```bash
+helm upgrade --install agentrax charts/agentrax/ \
+  --set networkPolicy.enabled=true
+```
+
+## Labelling the Prometheus Namespace
+
+The ingress rule allows traffic from namespaces labelled `monitoring: enabled`.
+Apply this label to the namespace where Prometheus Operator / kube-prometheus-stack
+is installed:
+
+```bash
+kubectl label namespace monitoring monitoring=enabled
+# Or, if using the default kube-prometheus-stack namespace name:
+kubectl label namespace monitoring monitoring=enabled
+```
+
+## Required CNI Support
+
+This NetworkPolicy relies on a Container Network Interface (CNI) plugin that
+**enforces** `NetworkPolicy` objects. Verify your CNI supports this:
+
+| Environment      | Supported CNI                 |
+| ---------------- | ----------------------------- |
+| Kind (local dev) | Kindnet (default) ✅          |
+| Azure AKS        | Azure CNI or Calico ✅        |
+| AWS EKS          | VPC CNI + Calico or Cilium ✅ |
+| GKE              | Dataplane V2 (Cilium) ✅      |
+
+> **Note**: Flannel does **not** enforce NetworkPolicy by default. Use Calico or
+> Cilium as a replacement CNI if Flannel is your cluster default.
+
+## Verifying the Policy
+
+After applying, verify that the policy is active and that an agent pod has
+the correct label:
+
+```bash
+# Confirm agent pod has the isolation label:
+kubectl get pods -n tenant-finance -L agentrax.io/agent
+
+# Confirm the NetworkPolicy is present:
+kubectl get networkpolicy -n tenant-finance
+
+# Test that cross-tenant traffic is blocked (from within an agent pod):
+kubectl exec -n tenant-finance <agent-pod> -- \
+  curl --connect-timeout 2 http://<service-in-tenant-marketing>
+# Expected: connection timed out (blocked)
+
+# Test that Kubernetes API access is allowed:
+kubectl exec -n tenant-finance <agent-pod> -- \
+  curl -k https://kubernetes.default.svc:443/healthz
+# Expected: "ok"
+```

internal/controller/agentdeployment_controller.go

@@ -659,12 +659,15 @@ func (r *AgentDeploymentReconciler) reconcileMCPRegistration(ctx context.Context
 
 // agentLabels returns the canonical label set applied to all resources owned by ad.
 // For stable resources (Deployment, Service), this includes variant=stable.
+// The agentrax.io/agent label is the NetworkPolicy selector key — all agent pod
+// templates carry it so the tenant-agent-isolation policy applies automatically.
 func agentLabels(ad *agentraxv1alpha1.AgentDeployment) map[string]string {
 	return map[string]string{
 		"app.kubernetes.io/name":       ad.Name,
 		"app.kubernetes.io/managed-by": "agentrax",
 		"agentrax.io/tenant":           ad.Spec.TenantRef,
 		"agentrax.io/variant":          "stable",
+		"agentrax.io/agent":            "true",
 	}
 }