Skip to content
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

[KEP-127] Add documentation about user namespaces and PSS #43803

Merged
merged 1 commit into from
Nov 28, 2023
Merged

[KEP-127] Add documentation about user namespaces and PSS #43803

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
29 changes: 29 additions & 0 deletions content/en/docs/concepts/workloads/pods/user-namespaces.md
View file
Open in desktop
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if the change should really be made to https://kubernetes.io/docs/concepts/security/pod-security-admission/, and then have a small section in the user namespaces concept that links to the relevant part of the PSA docs.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you mean pod security admission or pod security standards? That page you link doesn't seem related, but this one (about pod security standards) does: https://kubernetes.io/docs/concepts/security/pod-security-standards/

Can you explain why pod security admisions?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, because that's where the feature gate has an effect.

Think about it like this: imagine we were adding support for TLS 1.3; we'd document that in our pages about configuring transport layer security and maybe around setting which TLS versions were supported. But we wouldn't propose an update to https://datatracker.ietf.org/doc/html/rfc8446

On the other hand, if someone does want to revise the TLS standard, they don't put the update to the standard behind a feature gate. But they might have a feature gate to - eg - enable the RSASSA-PSS signature scheme.

I don't really understand how you feature gate a standard.

Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,35 @@ host's file owner/group.

[CVE-2021-25741]: https://github.com/kubernetes/kubernetes/issues/104980

## Integration with Pod security admission checks

{{< feature-state state="alpha" for_k8s_version="v1.29" >}}

For Linux Pods that enable user namespaces, Kubernetes relaxes the application of
[Pod Security Standards](/docs/concepts/security/pod-security-standards) in a controlled way.
This behavior can be controlled by the [feature
gate](/docs/reference/command-line-tools-reference/feature-gates/)
`UserNamespacesPodSecurityStandards`, which allows an early opt-in for end
users. Admins have to ensure that user namespaces are enabled by all nodes
within the cluster if using the feature gate.

If you enable the associated feature gate and create a Pod that uses user
namespaces, the following fields won't be constrained even in contexts that enforce the
_Baseline_ or _Restricted_ pod security standard. This behavior does not
present a security concern because `root` inside a Pod with user namespaces
actually refers to the user inside the container, that is never mapped to a
privileged user on the host. Here's the list of fields that are **not** checks for Pods in those
circumstances:

- `spec.securityContext.runAsNonRoot`
- `spec.containers[*].securityContext.runAsNonRoot`
- `spec.initContainers[*].securityContext.runAsNonRoot`
- `spec.ephemeralContainers[*].securityContext.runAsNonRoot`
- `spec.securityContext.runAsUser`
- `spec.containers[*].securityContext.runAsUser`
- `spec.initContainers[*].securityContext.runAsUser`
- `spec.ephemeralContainers[*].securityContext.runAsUser`

## Limitations

When using a user namespace for the pod, it is disallowed to use other host
Expand Down
5 changes: 5 additions & 0 deletions content/en/docs/reference/command-line-tools-reference/feature-gates.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -212,6 +212,7 @@ For a reference to old feature gates that are removed, please refer to
| `TopologyManagerPolicyOptions` | `true` | Beta | 1.28 | |
| `TranslateStreamCloseWebsocketRequests` | `false` | Alpha | 1.29 | |
| `UnknownVersionInteroperabilityProxy` | `false` | Alpha | 1.28 | |
| `UserNamespacesPodSecurityStandards` | `false` | Alpha | 1.29 | |
| `UserNamespacesSupport` | `false` | Alpha | 1.28 | |
| `ValidatingAdmissionPolicy` | `false` | Alpha | 1.26 | 1.27 |
| `ValidatingAdmissionPolicy` | `false` | Beta | 1.28 | |
Expand Down Expand Up @@ -803,6 +804,10 @@ Each feature gate is designed for enabling/disabling a specific feature:
- `UnknownVersionInteroperabilityProxy`: Proxy resource requests to the correct peer kube-apiserver when
multiple kube-apiservers exist at varied versions.
See [Mixed version proxy](/docs/concepts/architecture/mixed-version-proxy/) for more information.
- `UserNamespacesPodSecurityStandards`: Enable Pod Security Standards policies relaxation for pods
that run with namespaces. You must set the value of this feature gate consistently across all nodes in
your cluster, and you must also enable `UserNamespacesSupport` to use this feature.
See [User Namespaces](/docs/concepts/workloads/pods/user-namespaces/#integration-with-pod-security-standards) for more details.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oops. Should be:

-  See [User Namespaces](/docs/concepts/workloads/pods/user-namespaces/#integration-with-pod-security-standards) for more details.
+  See [User Namespaces](/docs/concepts/workloads/pods/user-namespaces/#integration-with-pod-security-admission-checks) for more details.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixing in the follow-up PR.

- `UserNamespacesSupport`: Enable user namespace support for Pods.
Before Kubernetes v1.28, this feature gate was named `UserNamespacesStatelessPodsSupport`.
- `ValidatingAdmissionPolicy`: Enable [ValidatingAdmissionPolicy](/docs/reference/access-authn-authz/validating-admission-policy/)
Expand Down