test(e2e): add cilium IPAM pool coverage and runbook docs

Author: syscod3

README.md

@@ -200,6 +200,8 @@ Imp provides first-class integration with **Cilium**. When Cilium is detected:
 
 For non-Cilium CNIs (Flannel/Calico/Weave/etc.), Imp uses a VXLAN fallback for cross-node VM connectivity.
 
+Cilium IPAM runbook: `docs/networking/cilium-ipam.md`
+
 ## Metrics & Observability
 
 Imp exposes operator and agent metrics so you can monitor VM lifecycle and platform health:
@@ -237,6 +239,8 @@ sequenceDiagram
   `kubectl -n imp-system logs ds/imp-agent`
 - Cilium features not active: verify Cilium CRDs exist and cni detection events.
   `kubectl get crd | grep cilium`
+- Cilium IPAM/pool issues: verify `CiliumPodIPPool` exists and `ImpNetwork.spec.ipam.cilium.poolRef` matches.
+  `kubectl get ciliumpodippool`
 - Webhook admission failures: check cert-manager/webhook pods and certificates.
   `kubectl -n imp-system get pods,certificates,issuers`
 - Snapshot or migration stalls: inspect related CR conditions.

docs/networking/cilium-ipam.md

@@ -0,0 +1,73 @@
+# Cilium IPAM Runbook
+
+This runbook covers Imp networks that delegate IP allocation to Cilium.
+
+## Scope
+
+- Decision: use per-network pools.
+- Source of truth: `ImpNetwork.spec.ipam.cilium.poolRef`.
+- Allocation flow: agent resolves CIDR from `CiliumPodIPPool`, then allocates VM IPs from that CIDR.
+
+## Prerequisites
+
+- Cilium installed in the cluster.
+- `CiliumPodIPPool` CRD present:
+  - `kubectl get crd ciliumpodippools.cilium.io`
+- A pool created for the target network.
+
+## Minimal Example
+
+```yaml
+apiVersion: cilium.io/v2alpha1
+kind: CiliumPodIPPool
+metadata:
+  name: vm-net-a
+spec:
+  ipv4:
+    cidrs:
+      - 10.77.0.0/24
+    maskSize: 30
+---
+apiVersion: imp.dev/v1alpha1
+kind: ImpNetwork
+metadata:
+  name: vm-net-a
+  namespace: default
+spec:
+  subnet: 10.44.0.0/24
+  ipam:
+    provider: cilium
+    cilium:
+      poolRef: vm-net-a
+```
+
+Note: `spec.subnet` remains required for API compatibility, but VM allocation CIDR comes from the referenced Cilium pool when `provider=cilium`.
+
+## Verification
+
+1. Confirm pool exists:
+   - `kubectl get ciliumpodippool vm-net-a -o yaml`
+2. Confirm network references pool:
+   - `kubectl get impnetwork vm-net-a -n default -o jsonpath='{.spec.ipam.cilium.poolRef}'`
+3. Confirm agent logs are clean:
+   - `kubectl -n imp-system logs ds/imp-agent`
+
+## Failure Modes
+
+- `CiliumPodIPPool` missing:
+  - Symptom: VM start fails; agent logs include pool lookup failure.
+  - Fix: create pool or correct `poolRef`.
+- Pool has no `spec.cidrs`:
+  - Symptom: allocation subnet resolution error.
+  - Fix: configure at least one CIDR in the pool spec.
+- Cilium CRD not installed:
+  - Symptom: pool lookup fails with resource mismatch/not found.
+  - Fix: install Cilium (or switch network IPAM provider to `internal`).
+
+## Rollback
+
+To stop using Cilium pool delegation for a network:
+
+1. Patch network provider:
+   - `kubectl patch impnetwork vm-net-a -n default --type merge -p '{"spec":{"ipam":{"provider":"internal"}}}'`
+2. Keep or remove pool resources based on cluster policy.

test/e2e/e2e_test.go

@@ -193,6 +193,72 @@ spec:
 		})
 	})
 
+	Context("Cilium IPAM", func() {
+		const (
+			poolName    = "e2e-imp-pool"
+			networkName = "e2e-cilium-ipam-net"
+		)
+
+		AfterEach(func() {
+			_, _ = utils.Run(exec.Command("kubectl", "delete", "impnetwork", networkName,
+				"-n", "default", "--ignore-not-found"))
+			_, _ = utils.Run(exec.Command("kubectl", "delete", "ciliumpodippool", poolName,
+				"--ignore-not-found"))
+		})
+
+		It("accepts ImpNetwork with ipam.provider=cilium and existing CiliumPodIPPool", func() {
+			By("ensuring CiliumPodIPPool CRD exists")
+			if _, err := utils.Run(exec.Command("kubectl", "get", "crd", "ciliumpodippools.cilium.io")); err != nil {
+				Skip("CiliumPodIPPool CRD not installed in this cluster")
+			}
+
+			By("creating CiliumPodIPPool")
+			poolManifest := fmt.Sprintf(`
+apiVersion: cilium.io/v2alpha1
+kind: CiliumPodIPPool
+metadata:
+  name: %s
+spec:
+  ipv4:
+    cidrs:
+      - 10.123.0.0/24
+    maskSize: 30
+`, poolName)
+			applyPool := exec.Command("kubectl", "apply", "-f", "-")
+			applyPool.Stdin = strings.NewReader(poolManifest)
+			_, err := utils.Run(applyPool)
+			Expect(err).NotTo(HaveOccurred())
+
+			By("creating ImpNetwork that delegates IPAM to Cilium pool")
+			netManifest := fmt.Sprintf(`
+apiVersion: imp.dev/v1alpha1
+kind: ImpNetwork
+metadata:
+  name: %s
+  namespace: default
+spec:
+  subnet: 10.44.0.0/24
+  ipam:
+    provider: cilium
+    cilium:
+      poolRef: %s
+`, networkName, poolName)
+			applyNet := exec.Command("kubectl", "apply", "-f", "-")
+			applyNet.Stdin = strings.NewReader(netManifest)
+			_, err = utils.Run(applyNet)
+			Expect(err).NotTo(HaveOccurred())
+
+			By("verifying poolRef is persisted")
+			Eventually(func(g Gomega) {
+				getCmd := exec.Command("kubectl", "get", "impnetwork", networkName, "-n", "default",
+					"-o", "jsonpath={.spec.ipam.cilium.poolRef}")
+				out, getErr := utils.Run(getCmd)
+				g.Expect(getErr).NotTo(HaveOccurred())
+				g.Expect(strings.TrimSpace(out)).To(Equal(poolName))
+			}).Should(Succeed())
+		})
+	})
+
 	Context("Metrics", func() {
 		It("operator /metrics endpoint responds 200", func() {
 			pf := exec.Command("kubectl", "port-forward",