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

Doc update for userns in 1.28 #41908

Merged
merged 6 commits into from
Aug 8, 2023
Merged

Doc update for userns in 1.28 #41908

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
73d698e
content: Fix typos in versions requirements for userns
rata Jul 6, 2023
5e70c9a
content: Remove old note about userns
rata Jul 7, 2023
922458d
content: Make userns statement about dockerd timeless
rata Jul 7, 2023
c34f1eb
content: Userns now supports stateful pods
rata Jul 6, 2023
6c2a9c5
content: Expand version requirements for userns explanation
rata Aug 7, 2023
c250efb
content: Fix typo
rata Aug 7, 2023
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
30 changes: 12 additions & 18 deletions content/en/docs/concepts/workloads/pods/user-namespaces.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,19 +46,22 @@ tmpfs, Secrets use a tmpfs, etc.)
Some popular filesystems that support idmap mounts in Linux 6.3 are: btrfs,
ext4, xfs, fat, tmpfs, overlayfs.

<!-- When merging this with the dev-1.27 branch conflicts will arise. The text
as it is in the dev-1.27 branch should be used. -->
In addition, support is needed in the
{{< glossary_tooltip text="container runtime" term_id="container-runtime" >}}
to use this feature with Kubernetes stateless pods:
to use this feature with Kubernetes pods:

* CRI-O: version 1.25 (and later) supports user namespaces for containers.

Please note that containerd v1.7 supports user namespaces for containers,
compatible with Kubernetes {{< skew currentPatchVersion >}}. It should not be used
with Kubernetes 1.27 (and later).
containerd v1.7 is not compatible with the userns support in Kubernetes v1.27 to v{{< skew latestVersion >}}.
Copy link
Contributor

Choose a reason for hiding this comment

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

?
What does this mean?

Copy link
Member Author

Choose a reason for hiding this comment

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

@tengqm that you can't use userns with containerd 1.7 and those k8s versions

Copy link
Member Author

Choose a reason for hiding this comment

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

It won't work, it will throw an error.

Copy link
Contributor

Choose a reason for hiding this comment

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

Let me try understand the situation.
containerd 1.7 + k8s 1.25/1.26 -> worked;
containerd 1.7 + k8s 1.27 -> this doesn't work;

If my understanding is correct, how about adjust the order of the two statements?

Copy link
Member Author

Choose a reason for hiding this comment

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

@tengqm Your understanding is correct. But can you make a specific suggestion here on github? I mean, just changing the order doesn't make much sense IMHO, as the second sentence highlights that some version do support it. It would be weird to say that before sayin some version does NOT support it.

I can do the change that you want, but give me github suggestion to avoid misunderstandings :)

Kubernetes v1.25 and v1.26 used an earlier implementation that **is** compatible with containerd v1.7,
in terms of userns support.
If you are using a version of Kubernetes other than {{< skew currentVersion >}},
check the documentation for that version of Kubernetes for the most relevant information.
If there is a newer release of containerd than v1.7 available for use, also check the containerd
documentation for compatibility information.

Support for this in [cri-dockerd is not planned][CRI-dockerd-issue] yet.
You can see the status of user namespaces support in cri-dockerd tracked in an [issue][CRI-dockerd-issue]
on GitHub.

[CRI-dockerd-issue]: https://github.com/Mirantis/cri-dockerd/issues/74

Expand All @@ -72,7 +75,7 @@ A pod can opt-in to use user namespaces by setting the `pod.spec.hostUsers` fiel
to `false`.

The kubelet will pick host UIDs/GIDs a pod is mapped to, and will do so in a way
to guarantee that no two stateless pods on the same node use the same mapping.
to guarantee that no two pods on the same node use the same mapping.

The `runAsUser`, `runAsGroup`, `fsGroup`, etc. fields in the `pod.spec` always
refer to the user inside the container.
Expand All @@ -89,7 +92,7 @@ Most applications that need to run as root but don't access other host
namespaces or resources, should continue to run fine without any changes needed
if user namespaces is activated.

## Understanding user namespaces for stateless pods
## Understanding user namespaces for pods {#pods-and-userns}

Several container runtimes with their default configuration (like Docker Engine,
containerd, CRI-O) use Linux namespaces for isolation. Other technologies exist
Expand Down Expand Up @@ -159,15 +162,6 @@ allowed to set any of:
* `hostIPC: true`
* `hostPID: true`

The pod is allowed to use no volumes at all or, if using volumes, only these
volume types are allowed:

* configmap
* secret
* projected
* downwardAPI
* emptyDir

## {{% heading "whatsnext" %}}

* Take a look at [Use a User Namespace With a Pod](/docs/tasks/configure-pod-container/user-namespaces/)
6 changes: 4 additions & 2 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 @@ -203,7 +203,8 @@ For a reference to old feature gates that are removed, please refer to
| `TopologyManagerPolicyOptions` | `false` | Alpha | 1.26 | 1.27 |
| `TopologyManagerPolicyOptions` | `true` | Beta | 1.28 | |
| `UnknownVersionInteroperabilityProxy` | `false` | Alpha | 1.28 | |
| `UserNamespacesStatelessPodsSupport` | `false` | Alpha | 1.25 | |
rata marked this conversation as resolved.
Show resolved Hide resolved
| `UserNamespacesStatelessPodsSupport` | `false` | Alpha | 1.25 | 1.27 |
rata marked this conversation as resolved.
Show resolved Hide resolved
| `UserNamespacesSupport` | `false` | Alpha | 1.28 | |
| `ValidatingAdmissionPolicy` | `false` | Alpha | 1.26 | |
| `VolumeCapacityPriority` | `false` | Alpha | 1.21 | - |
| `WatchList` | false | Alpha | 1.27 | |
Expand Down Expand Up @@ -764,7 +765,8 @@ 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.
- `UserNamespacesStatelessPodsSupport`: Enable user namespace support for stateless Pods.
rata marked this conversation as resolved.
Show resolved Hide resolved
- `UserNamespacesStatelessPodsSupport`: Enable user namespace support for stateless Pods. This flag was renamed on newer releases to `UserNamespacesSupport`.
- `UserNamespacesSupport`: Enable user namespace support for Pods.
rata marked this conversation as resolved.
Show resolved Hide resolved
- `ValidatingAdmissionPolicy`: Enable [ValidatingAdmissionPolicy](/docs/reference/access-authn-authz/validating-admission-policy/) support for CEL validations be used in Admission Control.
- `VolumeCapacityPriority`: Enable support for prioritizing nodes in different
topologies based on available PV capacity.
Expand Down
18 changes: 12 additions & 6 deletions content/en/docs/tasks/configure-pod-container/user-namespaces.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,8 @@ min-kubernetes-server-version: v1.25
<!-- overview -->
{{< feature-state for_k8s_version="v1.25" state="alpha" >}}

This page shows how to configure a user namespace for stateless pods. This
allows to isolate the user running inside the container from the one in the
host.
This page shows how to configure a user namespace for pods. This allows you to
isolate the user running inside the container from the one in the host.

A process running as root in a container can run as a different (non-root) user
in the host; in other words, the process has full privileges for operations
Expand Down Expand Up @@ -41,7 +40,14 @@ this is true when user namespaces are used.
* The node OS needs to be Linux
* You need to exec commands in the host
* You need to be able to exec into pods
* Feature gate `UserNamespacesStatelessPodsSupport` need to be enabled.
* You need to enable the `UserNamespacesSupport`
[feature gate](/docs/reference/command-line-tools-reference/feature-gates/)

{{< note >}}
The feature gate to enable user namespaces was previously named
`UserNamespacesStatelessPodsSupport`, when only stateless pods were supported.
Only Kubernetes v1.25 through to v1.27 recognise `UserNamespacesStatelessPodsSupport`.
{{</ note >}}

The cluster that you're using **must** include at least one node that meets the
[requirements](/docs/concepts/workloads/pods/user-namespaces/#before-you-begin)
Expand All @@ -59,8 +65,8 @@ created without user namespaces.**

## Run a Pod that uses a user namespace {#create-pod}

A user namespace for a stateless pod is enabled setting the `hostUsers` field of
`.spec` to `false`. For example:
A user namespace for a pod is enabled setting the `hostUsers` field of `.spec`
to `false`. For example:

{{< codenew file="pods/user-namespaces-stateless.yaml" >}}

Expand Down