feat: add support for userns #3941

Shubhranshu153 · 2025-02-26T23:18:30Z

Adds support for running containers with custom user namespace mappings through
the --userns flag in 'run' and 'create' commands.

Key Features:

Parse and utilize UID/GID mappings from /etc/subuid and /etc/subgid
Support multi-entry mappings for user namespace configurations
Integrate with containerd's remapping capabilities

Technical Details:

Depends containerd.WithUserNSRemapperLabels for namespace configuration. So containerd mainline is required to compile. It can be run on containerd 1.7 if snapshotter support remap-ids.
For native snapshotter overlay snapshotter with remapping support is added in containerd 2.x (>2.0.x)

Dependencies:

Requires containerd with UserNSRemapperLabels support
Compatible with overlay snapshotter in containerd mainline

Testing:

Added unit tests for mapping configurations
Added integration tests for container isolation

This enhancement improves container isolation by providing
flexible user namespace mapping capabilities.

Size: XL

cmd/nerdctl/container/container_create_linux_test.go

go.mod

pkg/api/types/container_types.go

pkg/cmd/container/create.go

AkihiroSuda · 2025-02-27T00:17:24Z

cmd/nerdctl/container/container_run.go

@@ -279,6 +279,7 @@ func setCreateFlags(cmd *cobra.Command) {
 	cmd.Flags().String("ipfs-address", "", "multiaddr of IPFS API (default uses $IPFS_PATH env variable if defined or local directory ~/.ipfs)")

 	cmd.Flags().String("isolation", "default", "Specify isolation technology for container. On Linux the only valid value is default. Windows options are host, process and hyperv with process isolation as the default")
+	cmd.Flags().String("userns", "", "Support idmapping of containers. This options is only supported on linux. If `host` is passed, no idmapping is done. if a user name is passed, it does idmapping based on the uidmap and gidmap ranges specified in /etc/subuid and /etc/subgid respectively")


Please add docs/command-reference.md.

Also, the command line seems incompatible with Docker?
Docker doesn't accept a username here, and the name is hardcoded to "dockremap".
Maybe we should have its equivalent as "nerdremap"?

Podman accepts --subuidname string --subgidname string to specify a custom user name

Also, the command line seems incompatible with Docker?
if they add host it will behave as docker as we check for that string and create the default snapshot.

For other names it behaves as docker daemon but at a container level rather than at daemon level. Will you suggest we configure it in nerdctl config instead?

For other names it behaves as docker daemon but at a container level rather than at daemon level. Will you suggest we configure it in nerdctl config instead?

Eventually, the both level should be supported, as in Podman: https://github.com/containers/podman/blob/v5.4.1/docs/source/markdown/options/userns.container.md?plain=1

podman run --userns=auto allocates subuids from the "containers" entry in /etc/subuid.

When userns=... is specified in containers.conf, Podman enables UserNS globally, unless --userns=host is specified.

nerdctl should probably follow the same convention, but s/containers.conf/nerdctl.toml/

Not all the features need to be implemented at once. Can just begin with the easiest one.

ping @Shubhranshu153

It does sound good to me in terms of supporting all the things that podman supports but would like to create a separate PR as this one has already been quite long. Can probably get in by 2.1.

No need to support all the things, but --userns=<USERNAME> is a new syntax that is not adopted by either Docker nor Podman, and is hard to adopt here unless there is a strong reason

dockerd --userns-remap="testuser:testuser"

For docker it is a docker daemon entry although i have not added all the different option and patterns to support. Should i add userns-remap instead of userns?

Docker has a daemon so it applies it to all containers launched for the daemon.

userns-remap SGTM.

It should be also available in /etc/nerdctl/nerdctl.toml
https://github.com/containerd/nerdctl/blob/main/docs/config.md#properties

sure i can add to the nerdctl.toml

pkg/testutil/testutil.go

pkg/testutil/nerdtest/requirements.go

go.mod

cmd/nerdctl/container/container_create_linux_test.go

pkg/cmd/container/create_userns_opts_linux_test.go

apostasie · 2025-04-21T16:35:44Z

@Shubhranshu153 I need to do some reading on userns to get a better grasp first, but short term, happy to help you review testing / overall. Hit me up when ready.

Shubhranshu153 · 2025-05-05T15:30:01Z

Almalinux test seems to be flaky,

apostasie · 2025-05-05T16:27:56Z

Almalinux test seems to be flaky,

Mmmm... failure is #4132 - but 4 fails out of 4 tries is no longer "flaky", it is a cold hard clusterf...

Do you mind closing and reopening?

Shubhranshu153 · 2025-05-05T17:40:02Z

ok this is repeatable.

Shubhranshu153 · 2025-05-05T19:57:51Z

		{
			Description: "start",
			NoParallel:  true,
			Command: func(data test.Data, helpers test.Helpers) test.TestableCommand {
				return helpers.Command("start", data.Labels().Get("cID"))
			},
			Expected: test.Expects(0, nil, nil),
		},
		{
			Description: "logs",
			NoParallel:  true,
			Command: func(data test.Data, helpers test.Helpers) test.TestableCommand {
				return helpers.Command("logs", data.Labels().Get("cID"))
			},
			Expected: test.Expects(0, nil, expect.Contains("foo")),
		},
	}

this test is racy in sense we cant guarantee the echo to complete before checking the logs. Needs to wait or retry

Shubhranshu153 · 2025-05-05T20:50:50Z

For test create:
Running in attach mode which will ensure the echo hello gets completed and put into stdout along with the logs so checking logs should have the foo text.

Shubhranshu153 · 2025-05-05T21:21:22Z

Not to de-sanitize this PR will create a separate PR to improve the TestCreate, for other bugs i still dont know what is the flakiness.

apostasie · 2025-05-05T21:29:52Z

Not to de-sanitize this PR will create a separate PR to improve the TestCreate, for other bugs i still dont know what is the flakiness.

Thanks a lot @Shubhranshu153 - the log you just identified is #3717

Our other main PITA (especially on EL) is #4132

Your latest Docker issue is some networking issue connecting to ghcr.io

The motherload (most known flaky issues) is here: #4120

Shubhranshu153 · 2025-05-05T23:22:37Z

@apostasie ok got it, i think this is great to have a list to be able to focus on. I will try to pick some of these.
Will request a assignment so that we are not re-doing things.

Shubhranshu153 · 2025-05-06T20:10:53Z

Flaky Test PR's:
#4196
#4198
#4199

Shubhranshu153 · 2025-05-07T01:13:40Z

Rerunning the test for flaky test.

AkihiroSuda · 2025-05-07T03:34:10Z

docs/command-reference.md

@@ -235,6 +235,9 @@ User flags:
 - :nerd_face: `--umask`: Set the umask inside the container. Defaults to 0022.
  Corresponds to Podman CLI.
 - :whale: `--group-add`: Add additional groups to join
+- :nerd_face: `--userns-remap=<username>:<groupname>`: Support idmapping of containers. This options is only supported on rootful linux for container create and run if a user name and optionally group name is passed, it does idmapping based on the uidmap and gidmap ranges specified in /etc/subuid and /etc/subgid respectively. Note: `--userns-remap` is not supported for building containers. Nerdctl Build doesn't support userns-remap feature. (format: <name|uid>[:<group|gid>])


Isn't this a top-level flag?

you are right after the refactor. let me update it.

Signed-off-by: Shubharanshu Mahapatra <[email protected]>

AkihiroSuda

Thanks

Shubhranshu153 commented Feb 26, 2025

View reviewed changes

cmd/nerdctl/container/container_create_linux_test.go Outdated Show resolved Hide resolved

AkihiroSuda added impact/major kind/feature labels Feb 27, 2025