What is the difference between /etc/group and /etc/subgid?

Question

I am in a Docker context and i am using user namespaces to map my container's user into my host's user (let's say foo). As i use portainer (As a container), i need to bind the Docker socket.

$ll /var/run/docker.sock                                                                                                                                                 
srw-rw---- 1 root docker 0 nov.  14 11:47 /var/run/docker.sock

$sudo cat /etc/docker/daemon.json
{
  "userns-remap": "foo"
}

$id
uid=1000(foo) gid=1000(foo) groupes=1000(foo),999(docker)

$getent group docker
docker:x:999:foo

Even if my foo user is allowed to access the docker group's files and Docker is using my foo user to run docker processes, my portainer is not allowed to access to socket.

Now, if i add this line to /etc/subgid, my problem is solved:

foo:999:1

My understanding of this line is: foo user is allowed to access to first group with gid starting from 999, which is 999 (999+0). My foo user is allowed to access 999 gid which is docker group.

As i can see, there is a difference between:

$getent group docker
docker:x:999:foo

and

grep 999 /etc/subgid
foo:999:1

My question: What is the difference between these two configurations and why do i need the subgid setup to allow my container to access my Docker socket ?

Thanks !

Answer 1

with user namespace mapping

/etc/subuid for User IDs
/etc/subgid for Group IDs

are used to determine the range where user IDs in a container's context are mapped to the actual host ID.

So, for a

 /etc/subuid > foo:100000:5000

for example a process belonging '0' in the container might actually belong on the host User NS to a user ID somewhere in 100000+5000.

If now in the host context some resource is limited to specific user IDs, it might be that while in the container the user ID look good in the actual host context the ID is somewhere in the upper ranges and thus cannot access the resource.