From 25c5f5cc2b0dff07132062b440a266d1b9e0ff50 Mon Sep 17 00:00:00 2001 From: Nader Ziada Date: Tue, 21 Oct 2025 12:26:38 -0400 Subject: [PATCH 1/2] add document for secure-pod-defaults feature and settings --- docs/versioned/.nav.yml | 1 + .../app-security/secure-pod-defaults.md | 89 +++++++++++++++++++ 2 files changed, 90 insertions(+) create mode 100644 docs/versioned/serving/app-security/secure-pod-defaults.md diff --git a/docs/versioned/.nav.yml b/docs/versioned/.nav.yml index 75968b917d2..c2ff363c39c 100644 --- a/docs/versioned/.nav.yml +++ b/docs/versioned/.nav.yml @@ -106,6 +106,7 @@ nav: - Installing Security-Guard: serving/app-security/security-guard-install.md - Security-guard quickstart: serving/app-security/security-guard-quickstart.md - Security-Guard example alerts: serving/app-security/security-guard-example-alerts.md + - SecurePodDefaults: serving/app-security/secure-pod-defaults.md # Serving - observability - Observability: - Collecting metrics: serving/observability/metrics/collecting-metrics.md diff --git a/docs/versioned/serving/app-security/secure-pod-defaults.md b/docs/versioned/serving/app-security/secure-pod-defaults.md new file mode 100644 index 00000000000..e7adacffb2e --- /dev/null +++ b/docs/versioned/serving/app-security/secure-pod-defaults.md @@ -0,0 +1,89 @@ +--- +audience: administrator +components: + - serving +function: how-to +--- + + +## SecurePodDefaults + +Knative Serving provides a `secure-pod-defaults` configuration option that gives operators granular control over pod security defaults, enabling progressive adoption of more secure pod configurations while maintaining backward compatibility with existing workloads. This feature offers three security levels—`disabled`, `root-allowed`, and `enabled` allowing organizations to gradually adopt security best practices without breaking container images that require specific permissions. The default is `disabled` to ensure existing deployments continue to work without modification. + + +### Security Levels + +| Level | Description | Use Case | +|-------|-------------|----------| +| **disabled** | No security defaults applied | Legacy workloads, maximum compatibility | +| **root-allowed** | Applies security defaults (blocks privilege escalation, runtime-default seccomp, drops capabilities) but allows root containers if not already set | Transition period, balanced security | +| **enabled** | Applies all `root-allowed` defaults plus enforces non-root execution if not already set | Maximum security for production | + + +## Key Features + +### 1. **Backward Compatible Default** +- Default remains `disabled` to prevent breaking existing deployments +- Only affects newly created Revisions (admission webhook behavior) + +### 2. **Progressive Security Hardening** +When `root-allowed` is configured: +- Sets `allowPrivilegeEscalation` to `false` if not specified +- Sets `seccompProfile` to `RuntimeDefault` if not specified +- Drops all capabilities if not specified +- Conditionally adds `NET_BIND_SERVICE` capability if a container port below 1024 is detected and capabilities are not already configured +- **Does NOT** enforce `runAsNonRoot` (allows root containers) + +When `enabled` is configured: +- All of the above, PLUS +- Sets `runAsNonRoot` to `true` if not already specified + +### 3. **Respects User Intent** +- Only applies defaults when values are not explicitly set by users +- Never overrides user-specified security contexts + +!!! important + To customize PodSecurityContext properties, you must enable the `kubernetes.podspec-securitycontext` feature flag. When set to `enabled` or `allowed`, it permits the following PodSecurityContext properties: + + - `FSGroup` + - `RunAsGroup` + - `RunAsNonRoot` + - `SupplementalGroups` + - `RunAsUser` + - `SeccompProfile` + + By default, this flag is set to `disabled`. For more information, see [Kubernetes security context](https://knative.dev/docs/serving/feature-flags/#kubernetes-security-context). + +## Configuration + +Update the `config-features` ConfigMap in `knative-serving` namespace: + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: config-features + namespace: knative-serving +data: + secure-pod-defaults: "root-allowed" # or "disabled", "enabled" +``` + +## Container compatibility + +### Breaking Changes +When switching from `disabled` to `enabled`, containers that require root access will fail: + +**Example: nginx** +``` +nginx: [emerg] chown("/var/cache/nginx/client_temp", 101) failed +(1: Operation not permitted) +``` + +**Example: Caddy** (runs as root by default) +``` +container has runAsNonRoot and image will run as root +reason: CreateContainerConfigError +``` + +### Compatible Workloads +Most modern container images following best practices will work with `enabled` mode without modification. From 44a389a9f50ef9029dcd9ec3001fdaebb6416b40 Mon Sep 17 00:00:00 2001 From: Nader Ziada Date: Wed, 22 Oct 2025 09:58:34 -0400 Subject: [PATCH 2/2] update secure pod defaults page to be more clear --- docs/versioned/.nav.yml | 2 +- .../app-security/secure-pod-defaults.md | 35 +++++++++---------- 2 files changed, 18 insertions(+), 19 deletions(-) diff --git a/docs/versioned/.nav.yml b/docs/versioned/.nav.yml index c2ff363c39c..eba5380782b 100644 --- a/docs/versioned/.nav.yml +++ b/docs/versioned/.nav.yml @@ -106,7 +106,6 @@ nav: - Installing Security-Guard: serving/app-security/security-guard-install.md - Security-guard quickstart: serving/app-security/security-guard-quickstart.md - Security-Guard example alerts: serving/app-security/security-guard-example-alerts.md - - SecurePodDefaults: serving/app-security/secure-pod-defaults.md # Serving - observability - Observability: - Collecting metrics: serving/observability/metrics/collecting-metrics.md @@ -279,6 +278,7 @@ nav: - Configure gradual rollout of traffic to Revisions: serving/configuration/rolling-out-latest-revision-configmap.md - Config Revision Garbage Collection: serving/revisions/revision-admin-config-options.md - Configure the Defaults ConfigMap: serving/configuration/config-defaults.md + - Secure Pod Defaults: serving/app-security/secure-pod-defaults.md - Serving encryption configuration: - Overview: serving/encryption/encryption-overview.md - Configure cert-manager integration: serving/encryption/configure-certmanager-integration.md diff --git a/docs/versioned/serving/app-security/secure-pod-defaults.md b/docs/versioned/serving/app-security/secure-pod-defaults.md index e7adacffb2e..010522ad450 100644 --- a/docs/versioned/serving/app-security/secure-pod-defaults.md +++ b/docs/versioned/serving/app-security/secure-pod-defaults.md @@ -5,40 +5,37 @@ components: function: how-to --- +!!! important + The default setting of `diabled` will be changed in the upcoming release of knative 1.21 to be more secure. -## SecurePodDefaults - -Knative Serving provides a `secure-pod-defaults` configuration option that gives operators granular control over pod security defaults, enabling progressive adoption of more secure pod configurations while maintaining backward compatibility with existing workloads. This feature offers three security levels—`disabled`, `root-allowed`, and `enabled` allowing organizations to gradually adopt security best practices without breaking container images that require specific permissions. The default is `disabled` to ensure existing deployments continue to work without modification. +Knative Serving provides a `secure-pod-defaults` configuration option that allows the default Service configuration to run in the Kubernetes [restricted](https://kubernetes.io/docs/concepts/security/pod-security-standards/#restricted) Pod Security Standard profile without requiring application developers to explicitly set security properties. This feature offers three security levels: `disabled`, `root-allowed`, and `enabled` allowing organizations to gradually adopt security best practices without breaking container images that require specific permissions. The default is `disabled` to ensure existing deployments continue to work without modification. -### Security Levels +## Security Levels | Level | Description | Use Case | |-------|-------------|----------| | **disabled** | No security defaults applied | Legacy workloads, maximum compatibility | -| **root-allowed** | Applies security defaults (blocks privilege escalation, runtime-default seccomp, drops capabilities) but allows root containers if not already set | Transition period, balanced security | -| **enabled** | Applies all `root-allowed` defaults plus enforces non-root execution if not already set | Maximum security for production | - +| **root-allowed** | Implements most of the Kubernetes [restricted](https://kubernetes.io/docs/concepts/security/pod-security-standards/#restricted) Pod Security Standard profile requirements, with the exception of `runAsNonRoot`, allowing containers to run as root when needed. | Transition period, balanced security | +| **enabled** | Aligns with the Kubernetes [restricted](https://kubernetes.io/docs/concepts/security/pod-security-standards/#restricted) Pod Security Standard in addition to enforcing non-root execution if not already set | Maximum security for production | ## Key Features -### 1. **Backward Compatible Default** -- Default remains `disabled` to prevent breaking existing deployments -- Only affects newly created Revisions (admission webhook behavior) - -### 2. **Progressive Security Hardening** +### **Progressive Security Hardening** When `root-allowed` is configured: -- Sets `allowPrivilegeEscalation` to `false` if not specified -- Sets `seccompProfile` to `RuntimeDefault` if not specified -- Drops all capabilities if not specified -- Conditionally adds `NET_BIND_SERVICE` capability if a container port below 1024 is detected and capabilities are not already configured +security settings only apply if the field is not set -- if it is explicitly set to any value, it's assumed to be intentional, and not modified. +- Sets `allowPrivilegeEscalation` to `false` +- Sets `seccompProfile` to `RuntimeDefault`, see [Seccomp and Kubernetes](https://kubernetes.io/docs/reference/node/seccomp/) for more details +- Drops all capabilities + - Conditionally adds `NET_BIND_SERVICE` capability if a container port below 1024 is detected and capabilities are not already configured - **Does NOT** enforce `runAsNonRoot` (allows root containers) When `enabled` is configured: + - All of the above, PLUS - Sets `runAsNonRoot` to `true` if not already specified -### 3. **Respects User Intent** +### **Respects User Intent** - Only applies defaults when values are not explicitly set by users - Never overrides user-specified security contexts @@ -52,10 +49,12 @@ When `enabled` is configured: - `RunAsUser` - `SeccompProfile` - By default, this flag is set to `disabled`. For more information, see [Kubernetes security context](https://knative.dev/docs/serving/feature-flags/#kubernetes-security-context). + By default, this flag is set to `disabled`. For more information, see [Kubernetes security context](../configuration/feature-flags/#kubernetes-security-context). ## Configuration +See [Configuring the Defaults](../configuration/config-defaults/) ConfigMap + Update the `config-features` ConfigMap in `knative-serving` namespace: ```yaml