docs: improve boundary docs (#22183)

docs/ai-coder/agent-boundaries/nsjail/ecs.md

@@ -0,0 +1,38 @@
+# nsjail on ECS
+
+This page describes the runtime and permission requirements for running
+Boundary with the **nsjail** jail type on **Amazon ECS**.
+
+## Runtime & Permission Requirements for Running Boundary in ECS
+
+The setup for ECS is similar to [nsjail on Kubernetes](./k8s.md); that environment
+is better explored and tested, so the Kubernetes page is a useful reference. On
+ECS, requirements depend on the node OS and how ECS runs your tasks. The
+following examples use **ECS with Self Managed Node Groups** (EC2 launch type).
+
+---
+
+### Example 1: ECS + Self Managed Node Groups + Amazon Linux
+
+On **Amazon Linux** nodes with ECS, the default Docker seccomp profile enforced
+by ECS blocks the syscalls needed for Boundary. Because it is difficult to
+disable or modify the seccomp profile on ECS, you must grant `SYS_ADMIN` (along
+with `NET_ADMIN`) so that Boundary can create namespaces and run nsjail.
+
+**Task definition (Terraform) — `linuxParameters`:**
+
+```hcl
+container_definitions = jsonencode([{
+  name      = "coder-agent"
+  image     = "your-coder-agent-image"
+
+  linuxParameters = {
+    capabilities = {
+      add = ["NET_ADMIN", "SYS_ADMIN"]
+    }
+  }
+}])
+```
+
+This gives the container the capabilities required for nsjail when ECS uses the
+default Docker seccomp profile.

docs/ai-coder/agent-boundaries/nsjail/index.md

@@ -4,11 +4,12 @@ nsjail is Agent Boundaries' default jail type that uses Linux namespaces to
 provide process isolation. It creates unprivileged network namespaces to control
 and monitor network access for processes running under Boundary.
 
-**Running on Docker?** See [nsjail on Docker](./docker.md) for runtime
-and permission requirements.
+**Running on Docker, Kubernetes, or ECS?** See the relevant page for runtime
+and permission requirements:
 
-**Running on Kubernetes?** See [nsjail on Kubernetes](./k8s.md) for runtime
-and permission requirements.
+- [nsjail on Docker](./docker.md)
+- [nsjail on Kubernetes](./k8s.md)
+- [nsjail on ECS](./ecs.md)
 
 ## Overview
 

docs/ai-coder/agent-boundaries/nsjail/k8s.md

@@ -111,3 +111,19 @@ EOT
 ```
 
 This ensures Boundary can create user namespaces with nsjail.
+
+### Running without user namespaces
+
+If the environment is restricted and you cannot enable user namespaces (e.g.
+Bottlerocket in EKS auto-mode), you can run Boundary with the
+`--no-user-namespace` flag. Use this when you have no way to allow user namespace creation.
+
+---
+
+### Example 3: EKS + Fargate (Firecracker VMs)
+
+nsjail is not currently supported on **EKS Fargate** (Firecracker-based VMs), which
+blocks the capabilities needed for nsjail.
+
+If you run on Fargate, we recommend using [landjail](../landjail.md) instead,
+provided kernel version supports it (Linux 6.7+).

docs/manifest.json

@@ -1024,6 +1024,11 @@
 											"title": "NS Jail on Kubernetes",
 											"description": "Runtime and permission requirements for running NS Jail on Kubernetes",
 											"path": "./ai-coder/agent-boundaries/nsjail/k8s.md"
+										},
+										{
+											"title": "NS Jail on ECS",
+											"description": "Runtime and permission requirements for running NS Jail on ECS",
+											"path": "./ai-coder/agent-boundaries/nsjail/ecs.md"
 										}
 									]
 								},