diff --git a/README.md b/README.md index dd0015a..7f86808 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,26 @@ root access on the system. $ sudo loginctl enable-linger $USER ``` -#### Runner registration (step 2) +#### Expanded user-namespace (step 2) + +Some nested container images need to utilize high UID/GID values +like `65535`. However, many distributions set that as the default max +number of user-namespace IDs. Since three IDs are needed inside the +`pipglr` container, a larger range is required on the host. As root, +edit the two files `/etc/subuid` and `/etc/subgid` to expand the range. +For example assuming a local user called `pipglr` is used to run the +container, the contents of these files should be edited to allocate +`65539` IDs like: + +`pipglr::65539` + +Where `` was set by your OS when the `pipglr` user was created. +If you don't make this change, you're likely to experience errors starting +containers for CI jobs, such as: + +`E: setgroups 65534 failed - setgroups (22: Invalid argument)` + +#### Runner registration (step 3) All runners must be connected to a project or group runner configuration on your gitlab instance (or `gitlab.com`). This is done using a special @@ -87,7 +106,7 @@ $ podman container runlabel register $IMAGE $ podman secret rm REGISTRATION_TOKEN # if desired ``` -#### Runner Configuration (step 3) +#### Runner Configuration (step 4) During the registration process (above), a boiler-plate (default) `config.toml` file will be created/updated for you. At this point you may edit the configuration @@ -103,10 +122,10 @@ $ rm ./config.toml # if desired This may be necessary, for example, to increase the default `concurrency` value to reflect the number of registered runners. If you need to edit this file -after commiting it as a secret, there's +after committing it as a secret, there's [ a `dumpconfig` *runlabel* for that](README.md#configuration-editing). -#### Volume setup (step 4) +#### Volume setup (step 5) Since several users are utilized inside the container volumes must be specifically configured to permit access. This is done using several @@ -121,10 +140,10 @@ $ podman container runlabel setupcache $IMAGE Note: These volumes generally do not contain any critical operational data, they may be re-created anytime to quickly free up host disk-space if it's running low. Simply remove them with the command - `podman volume rm pipglr-storage pipglr-cache`. The reuse the `setupstorage` + `podman volume rm pipglr-storage pipglr-cache`. Then reuse the `setupstorage` and `setupcache` *runlabels* as in the above example. -#### Runner Startup (step 5) +#### Runner Startup (step 6) With the runner configuration saved as a Podman secret, and the runner volumes created, the GitLab runner container may be launched with the following commands: diff --git a/setup.sh b/setup.sh index a293083..74c6056 100644 --- a/setup.sh +++ b/setup.sh @@ -69,9 +69,12 @@ useradd -M -u 1001 -g runner runner chmod 770 /home/runner # Overwrite defaults, only user 'podman' permited to have a user-namespace -# Split the namespaced ID's around the containers root (ID 0) and the user -# IDs 1000 and 1001 (defined above) to prevent hijacking from a nested container. -echo -e "podman:1:999\npodman:1002:64533" | tee /etc/subuid > /etc/subgid +# Split the namespaced ID's around the containers root (ID 0), podman (ID 1000), and +# runner (ID 1001) such that the user-namespace of any nested containers cannot +# read or write any files owned by these users (and/or hijack nested container processes). +# N/B: The range-end (999+64536) ensures a total of 65535 IDs are available for nested-containers. +# This requires the host provide a sufficiently large range, i.e. `pipglr::65539` +echo -e "podman:1:999\npodman:1002:64536" | tee /etc/subuid > /etc/subgid # Host volume mount necessary for nested-podman to use overlayfs2 for container & volume storage. mkdir -p /home/podman/.local/share/containers # Nested-container's local container-cache volume mount, recommended by gitlab-runner docs.