diff --git a/docs/versioned/.nav.yml b/docs/versioned/.nav.yml index 75968b917d2..eba5380782b 100644 --- a/docs/versioned/.nav.yml +++ b/docs/versioned/.nav.yml @@ -278,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 new file mode 100644 index 00000000000..010522ad450 --- /dev/null +++ b/docs/versioned/serving/app-security/secure-pod-defaults.md @@ -0,0 +1,88 @@ +--- +audience: administrator +components: + - serving +function: how-to +--- + +!!! important + The default setting of `diabled` will be changed in the upcoming release of knative 1.21 to be more secure. + +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 + +| Level | Description | Use Case | +|-------|-------------|----------| +| **disabled** | No security defaults applied | Legacy workloads, maximum compatibility | +| **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 + +### **Progressive Security Hardening** +When `root-allowed` is 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 + +### **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](../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 +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.