diff --git a/docs/ai-coder/agent-boundaries/index.md b/docs/ai-coder/agent-boundaries/index.md index f6ef508183..836cc0e831 100644 --- a/docs/ai-coder/agent-boundaries/index.md +++ b/docs/ai-coder/agent-boundaries/index.md @@ -130,7 +130,7 @@ with different characteristics and requirements: 1. **nsjail** - Uses Linux namespaces for isolation. This is the default jail type and provides network namespace isolation. See - [nsjail documentation](./nsjail.md) for detailed information about runtime + [nsjail documentation](./nsjail/index.md) for detailed information about runtime requirements and Docker configuration. 2. **landjail** - Uses Landlock V4 for network isolation. This provides network diff --git a/docs/ai-coder/agent-boundaries/nsjail.md b/docs/ai-coder/agent-boundaries/nsjail/docker.md similarity index 77% rename from docs/ai-coder/agent-boundaries/nsjail.md rename to docs/ai-coder/agent-boundaries/nsjail/docker.md index a7963e96d8..fe948d62dc 100644 --- a/docs/ai-coder/agent-boundaries/nsjail.md +++ b/docs/ai-coder/agent-boundaries/nsjail/docker.md @@ -1,25 +1,11 @@ -# nsjail Jail Type +# nsjail on Docker -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. +This page describes the runtime and permission requirements for running Agent +Boundaries with the **nsjail** jail type on **Docker**. -## Overview +For an overview of nsjail, see [nsjail](./index.md). -nsjail leverages Linux namespace technology to isolate processes at the network -level. When Agent Boundaries runs with nsjail, it creates a separate network -namespace for the isolated process, allowing Agent Boundaries to intercept and -filter all network traffic according to the configured policy. - -This jail type requires Linux capabilities to create and manage network -namespaces, which means it has specific runtime requirements when running in -containerized environments like Docker. - -## Architecture - -Boundary - -## Runtime & Permission Requirements for Running Agent Boundaries in Docker +## Runtime & Permission Requirements for Running Boundary in Docker This section describes the Linux capabilities and runtime configurations required to run Agent Boundaries with nsjail inside a Docker container. diff --git a/docs/ai-coder/agent-boundaries/nsjail/index.md b/docs/ai-coder/agent-boundaries/nsjail/index.md new file mode 100644 index 0000000000..5b1f7b6449 --- /dev/null +++ b/docs/ai-coder/agent-boundaries/nsjail/index.md @@ -0,0 +1,26 @@ +# nsjail Jail Type + +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 Kubernetes?** See [nsjail on Kubernetes](./k8s.md) for runtime +and permission requirements. + +## Overview + +nsjail leverages Linux namespace technology to isolate processes at the network +level. When Agent Boundaries runs with nsjail, it creates a separate network +namespace for the isolated process, allowing Agent Boundaries to intercept and +filter all network traffic according to the configured policy. + +This jail type requires Linux capabilities to create and manage network +namespaces, which means it has specific runtime requirements when running in +containerized environments like Docker and Kubernetes. + +## Architecture + +Boundary diff --git a/docs/ai-coder/agent-boundaries/nsjail/k8s.md b/docs/ai-coder/agent-boundaries/nsjail/k8s.md new file mode 100644 index 0000000000..b1ff6ba655 --- /dev/null +++ b/docs/ai-coder/agent-boundaries/nsjail/k8s.md @@ -0,0 +1,113 @@ +# nsjail on Kubernetes + +This page describes the runtime and permission requirements for running Agent +Boundaries with the **nsjail** jail type on **Kubernetes**. + +## Runtime & Permission Requirements for Running Boundary in Kubernetes + +Requirements depend on the node OS and the container runtime. The following +examples use **EKS with Managed Node Groups** for two common node AMIs. + +--- + +### Example 1: EKS + Managed Node Groups + Amazon Linux + +On **Amazon Linux** nodes, the default seccomp and runtime behavior typically +allow the syscalls needed for Boundary. You only need to +grant `NET_ADMIN`. + +**Container `securityContext`:** + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: coder-agent +spec: + containers: + - name: coder-agent + image: your-coder-agent-image + securityContext: + capabilities: + add: + - NET_ADMIN + # ... rest of container spec +``` + +--- + +### Example 2: EKS + Managed Node Groups + Bottlerocket + +On **Bottlerocket** nodes, the default seccomp profile often blocks the `clone` +syscalls required for unprivileged user namespaces. You must either disable or +modify seccomp for the pod (see [Docker Seccomp Profile Considerations](./docker.md#docker-seccomp-profile-considerations)) or grant `SYS_ADMIN`. + +**Option A: `NET_ADMIN` + disable seccomp** + +Disabling the seccomp profile allows the container to create namespaces +without granting `SYS_ADMIN` capabilities. + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: coder-agent +spec: + containers: + - name: coder-agent + image: your-coder-agent-image + securityContext: + capabilities: + add: + - NET_ADMIN + seccompProfile: + type: Unconfined + # ... rest of container spec +``` + +**Option B: `NET_ADMIN` + `SYS_ADMIN`** + +Granting `SYS_ADMIN` bypasses many seccomp restrictions and allows namespace +creation. + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: coder-agent +spec: + containers: + - name: coder-agent + image: your-coder-agent-image + securityContext: + capabilities: + add: + - NET_ADMIN + - SYS_ADMIN + # ... rest of container spec +``` + +### User namespaces on Bottlerocket + +User namespaces are often disabled (`user.max_user_namespaces=0`) on Bottlerocket +nodes. Check and enable user namespaces: + +```bash +# Check current value +sysctl user.max_user_namespaces + +# If it returns 0, enable user namespaces +sysctl -w user.max_user_namespaces=65536 +``` + +If `sysctl -w` is not allowed, configure it via Bottlerocket bootstrap settings +when creating the node group (e.g., in Terraform): + +```hcl +bootstrap_extra_args = <<-EOT + [settings.kernel.sysctl] + "user.max_user_namespaces" = "65536" +EOT +``` + +This ensures Boundary can create user namespaces with nsjail. diff --git a/docs/manifest.json b/docs/manifest.json index f6ebff7526..fcf4fd8778 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -1013,7 +1013,19 @@ { "title": "NS Jail", "description": "Documentation for Namespace Jail", - "path": "./ai-coder/agent-boundaries/nsjail.md" + "path": "./ai-coder/agent-boundaries/nsjail/index.md", + "children": [ + { + "title": "NS Jail on Docker", + "description": "Runtime and permission requirements for running NS Jail on Docker", + "path": "./ai-coder/agent-boundaries/nsjail/docker.md" + }, + { + "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": "LandJail",