Skip to content

Add NGF permissions document #810

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Jul 15, 2025
Merged

Add NGF permissions document #810

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b1a0f98
Add NGF permissions document
Jul 14, 2025
d6e3b8b
Reformat NGF permissions doc for readability
Jul 14, 2025
a261738
Update permissions documentation based on PR feedback
Jul 14, 2025
c922ca5
Update volumes secret mount line to include JWT token for NGINX Plus
Jul 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 7 additions & 21 deletions content/ngf/reference/permissions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,18 +22,18 @@ All components share these security settings:
- **User ID**: 101 (non-root)
- **Group ID**: 1001
- **Capabilities**: All dropped (`drop: ALL`)
- **Root Filesystem**: Read-only
- **Root Filesystem**: Read-only except for specific writable volumes
- **Seccomp**: Runtime default profile

## Control Plane

Runs as a single container in the `nginx-gateway` deployment.

**Additional Security Settings:**
- **Privilege Escalation**: Disabled (may need enabling for NGINX reload in some environments)
- **Privilege Escalation**: Disabled

**Volumes:**
- `nginx-agent-tls` (Secret) - TLS certificates for control plane communication
- Secret mounts for TLS certificates

**RBAC Permissions:**
- **Secrets, ConfigMaps, Services**: Create, update, delete, list, get, watch
Expand All @@ -57,21 +57,9 @@ NGINX containers managed by the control plane. No RBAC permissions needed since
- **Sysctl**: `net.ipv4.ip_unprivileged_port_start=0` (enables binding to ports < 1024)

**Volumes:**

| Volume | Type | Purpose |
|--------|------|---------|
| `nginx-conf` | EmptyDir | Main NGINX configuration |
| `nginx-stream-conf` | EmptyDir | Stream configuration |
| `nginx-secrets` | EmptyDir | TLS secrets for NGINX |
| `nginx-run` | EmptyDir | Runtime files (PID, sockets) |
| `nginx-cache` | EmptyDir | Cache directory |
| `nginx-main-includes` | EmptyDir | Main context includes |
| `nginx-includes` | EmptyDir | HTTP context includes |
| `nginx-agent` | EmptyDir | NGINX Agent configuration |
| `nginx-agent-tls` | Secret | TLS certificates for control plane communication |
| `nginx-agent-log` | EmptyDir | NGINX Agent logs |
| `nginx-agent-lib` | EmptyDir | NGINX Agent runtime data |
| `token` | Projected | Service account token |
- EmptyDir volumes for NGINX configuration, runtime files, logs, and cache
- Secret mounts for TLS certificates
- Projected token mounts for service account authentication

**Volume Permissions:**
- **EmptyDir**: Read-write (required for NGINX operation)
Expand All @@ -82,7 +70,7 @@ NGINX containers managed by the control plane. No RBAC permissions needed since
Kubernetes Job that creates initial TLS certificates.

**RBAC Permissions:**
- **Secrets**: Create, update, get (NGINX Gateway Fabric namespace only)
- **Secrets**: Create, update, get (control plane namespace only)

## Platform-Specific Considerations

Expand Down Expand Up @@ -110,8 +98,6 @@ NGINX Gateway Fabric drops ALL Linux capabilities and adds none, following secur
- **Port Binding**: Uses sysctl `net.ipv4.ip_unprivileged_port_start=0` for ports < 1024
- **File Operations**: Volume mounts provide necessary write access

**Troubleshooting:**
If you encounter "operation not permitted" errors during NGINX reload, temporarily enable `allowPrivilegeEscalation: true` while investigating the root cause.

## Security Features

Expand Down
Loading