mirror of
https://github.com/coder/coder.git
synced 2026-09-24 15:04:27 +08:00
chore: add boundary and k8s docs (#22153)
This commit is contained in:
Yevhenii Shcherbina
@@ -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
|
||||
|
||||
+5
-19
@@ -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
|
||||
|
||||
<img width="1228" height="604" alt="Boundary" src="https://github.com/user-attachments/assets/1b7c8c5b-7b8f-4adf-8795-325bd28715c6" />
|
||||
|
||||
## 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.
|
||||
@@ -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
|
||||
|
||||
<img width="1228" height="604" alt="Boundary" src="https://github.com/user-attachments/assets/1b7c8c5b-7b8f-4adf-8795-325bd28715c6" />
|
||||
@@ -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.
|
||||
+13
-1
@@ -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",
|
||||
|
||||
Reference in New Issue
Block a user