public/pipglr
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update setup docs

Browse Source 
* Simplify the overview, include minimum podman version.
* Clarify linger setup
* Overhaul user-namespace setup section
* Rename "registration" to "activation" (gitlab 16+)

Signed-off-by: Chris Evich <cevich@redhat.com>
This commit is contained in:
Chris Evich
2024-05-08 11:01:46 -04:00
parent be51686020
commit adf47d94a5
1 changed files with 29 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files

79
README.md
View File

@@ -36,79 +36,55 @@ container. While it's possible to use the container with your own command-line,
it's highly recommended to base them off of one of the labels. See the examples
below for more information.
**_Note:_** Some older versions of podman don't support the `container runlabel`
sub-command. If this is the case, you may simulate it with the following,
substituting `<label>` with one of the predefined values (i.e. `register`,
`setupconfig`, etc.):
```bash
$ IMAGE="registry.gitlab.com/qontainers/pipglr:latest"
$ eval $(podman inspect --format=json $IMAGE | jq -r .[].Labels.<label>)
```
*_Only podman versions 4.8.x and later are supported by pipglr._*
#### Persistent Containers (step 1)
By default on many distributions, regular users aren't permitted to leave
background processes running after they log out. Since this is likely desired
for running the pipglr container long-term, `systemd` needs to be configured to
override this policy. For this, you (`$USER`) will need root access on the
system.
override this policy. Doing so requires root or `sudo` access on the
system. Assuming the user `johndoe` will be executing the pipglr container,
linger may be enabled (as the admin user or root) with a command like:
```bash
$ sudo loginctl enable-linger $USER
$ sudo loginctl enable-linger `johndoe`
```
Side-effect: This will allow your user to persist other user-level systemd
services as well. For example `podman.socket` is handy to enable for
`podman remote` access. You could also
Side-effect: This will allow the user (`johndoe` for example) to persist
other user-level systemd services as well. For example `podman.socket` is
handy to enable for `podman remote` access. You could also
[setup quadlet](https://www.redhat.com/sysadmin/quadlet-podman) or a systemd
unit so pipglr starts up on system boot.
#### Expanded User-Namespace (step 2) **_This is probably important_**
#### Expanded Host-system User-Namespace (step 2)
As an added protection/safety measure, pipglr excludes three UID/GIDs from being
used by job-level containers. One for `root`, another for `runner` and a third
for `podman`. However, some container images you may want to use for jobs
(mainly Debian/Ubuntu), assign one/more essential users a high UID/GID value
(like `65535`).
**_This is really important and frequently the cause of pipglr issues_**
At the same time, most distributions also set `65536` as the default maximum
number (including ID `0`) of IDs to allocate for user-namespaces (via
`/etc/login.defs`). This creates a problem you won't realize until the runner
actually picks up a job. The main symptom of this issue will be messages in
the pipglr containers log, similar to (abbreviated):
```text
...cut...
running `/usr/bin/newuidmap ...cut...`: newuidmap: write to uid_map failed: Operation not permitted
Error: cannot set up namespace using "/usr/bin/newuidmap": exit status 1
...cut...
```
or
```text
E: setgroups 65534 failed - setgroups (22: Invalid argument)
```
**_The good news is, working around this is relatively simple:_**
As root, edit the two files `/etc/subuid` and `/etc/subgid` to expand the by 3
IDs. For example assuming a user running the pipglr container is called
`johndoe`, the contents of these files should be edited to allocate `65539` IDs
like:
On the host, as root, edit the two files `/etc/subuid` and `/etc/subgid` to
expand the pipglr user's ID allocation by 3. For example if the host user
running the pipglr container is named `johndoe`, this entry in the files should
be edited like:
`johndoe:<some number>:65539`
Where `<some number>` was set by your OS when the `johndoe` user was created
(you can ignore this). Only the last number needs to be increased. This change
will be effective on next login, or immediately by running:
Where `<some number>` was set by the OS when the `johndoe` user was created
(you can ignore this). Only the last number needs to be increased by three.
This change will be effective on the user's next login, or immediately
by running (as the host pipglr user):
`podman system migrate`
_Note:_ This will stop any currently running containers.
#### Runner Registration (step 3)
_Details:_ As an added protection/safety measure, pipglr excludes three UID/GIDs
from being used by job-level (nested) containers. One for `root`, another for
`runner` and a third for `podman`. This necessitates expanding the number of
available UIDs/GIDs from the host machine, to the pipglr container. This way,
the full set of 65535 UIDs/GIDs may be utilized by job-level (nested)
sub-containers.
#### Runner Activation/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 registration
@@ -257,6 +233,9 @@ Several build arguments are available to control the output image:
containers running in `--privileged` mode. This will affect the ability to
build container images in CI jobs using tools like podman or buildah.
Additional build-args are available as well. See the `Containerfile` comments
for more details.
### Environment Variables
Nearly every option to every gitlab-runner sub-command may be specified via