Compare commits
1 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
942d58d41c |
1
.gitignore
vendored
Normal file
1
.gitignore
vendored
Normal file
@@ -0,0 +1 @@
|
||||
/.pre-commit-config.yaml
|
||||
@@ -1,21 +1,10 @@
|
||||
---
|
||||
|
||||
default:
|
||||
image: quay.io/buildah/stable:v1.32
|
||||
image: quay.io/buildah/stable:v1.31.0
|
||||
tags:
|
||||
- saas-linux-small-amd64
|
||||
|
||||
workflow:
|
||||
rules:
|
||||
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
|
||||
- if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS
|
||||
when: never
|
||||
- if: $CI_COMMIT_BRANCH
|
||||
|
||||
include:
|
||||
- component: gitlab.com/blue42u/ci.pre-commit/lite@0.2.0
|
||||
inputs:
|
||||
job_stage: test
|
||||
- docker
|
||||
- linux
|
||||
|
||||
envars:
|
||||
stage: test
|
||||
@@ -25,9 +14,6 @@ envars:
|
||||
|
||||
commit_check:
|
||||
stage: test
|
||||
rules:
|
||||
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
|
||||
- when: never
|
||||
variables:
|
||||
BADRX: '^(squash!)|(fixup!)'
|
||||
script: |
|
||||
@@ -40,8 +26,6 @@ commit_check:
|
||||
fi
|
||||
|
||||
build:
|
||||
tags:
|
||||
- saas-linux-medium-amd64
|
||||
stage: deploy
|
||||
variables:
|
||||
BUILDAH_FORMAT: docker
|
||||
|
||||
@@ -1,48 +0,0 @@
|
||||
default_language_version:
|
||||
python: python3
|
||||
default_install_hook_types: [pre-commit, commit-msg]
|
||||
default_stages: [pre-commit]
|
||||
|
||||
repos:
|
||||
- repo: https://github.com/executablebooks/mdformat
|
||||
rev: '0.7.17'
|
||||
hooks:
|
||||
- id: mdformat
|
||||
additional_dependencies:
|
||||
- mdformat-footnote
|
||||
- mdformat-tables
|
||||
|
||||
- repo: https://github.com/pre-commit/pre-commit-hooks
|
||||
rev: v4.5.0
|
||||
hooks:
|
||||
- id: trailing-whitespace
|
||||
- id: end-of-file-fixer
|
||||
- id: fix-byte-order-marker
|
||||
- id: mixed-line-ending
|
||||
- id: check-executables-have-shebangs
|
||||
- id: check-symlinks
|
||||
- id: destroyed-symlinks
|
||||
- id: check-merge-conflict
|
||||
- id: check-case-conflict
|
||||
- id: no-commit-to-branch
|
||||
args: [--branch, main]
|
||||
- id: check-yaml
|
||||
|
||||
- repo: https://github.com/python-jsonschema/check-jsonschema
|
||||
rev: '0.28.0'
|
||||
hooks:
|
||||
# Validate the GitLab CI scripts against the schema. Doesn't catch everything but helps.
|
||||
- id: check-gitlab-ci
|
||||
files: '.*\.gitlab-ci\.yml$'
|
||||
|
||||
- repo: https://github.com/jumanjihouse/pre-commit-hooks
|
||||
rev: '3.0.0'
|
||||
hooks:
|
||||
- id: forbid-binary
|
||||
- id: require-ascii
|
||||
|
||||
- repo: meta
|
||||
hooks:
|
||||
# Un-comment (maybe temporarily) to check which hooks don't apply.
|
||||
# - id: check-hooks-apply
|
||||
- id: check-useless-excludes
|
||||
@@ -24,7 +24,7 @@ ADD /home/ /home/
|
||||
# an incompatible change be introduced.
|
||||
ARG RUNNER_VERSION=latest
|
||||
|
||||
# Permit building containers for alternate architectures. At the time
|
||||
# Permit building containers for alternate architectures. At the time
|
||||
# of this commit, only 'arm64' is available.
|
||||
ARG TARGETARCH=amd64
|
||||
|
||||
@@ -45,17 +45,12 @@ ENTRYPOINT /lib/systemd/systemd
|
||||
# Gitlab-runner configuration options, may be freely overridden at
|
||||
# container image build time.
|
||||
ARG DEFAULT_JOB_IMAGE=registry.fedoraproject.org/fedora-minimal:latest
|
||||
|
||||
# Allow image-builders to override the Gitlab URL
|
||||
ARG GITLAB_URL=https://gitlab.com/
|
||||
|
||||
# Run nested containers in --privileged mode - required to allow building
|
||||
# container images using podman or buildah. Otherwise may be set 'false'.
|
||||
ARG NESTED_PRIVILEGED=true
|
||||
|
||||
# Download the FIPS version of gitlab-runner when enabled on the host system.
|
||||
ARG ENABLE_FIPS=true
|
||||
|
||||
# The registration runlabel may be called multiple times to register more than
|
||||
# one runner. Each expects a REGISTRATION_TOKEN secret to be pre-defined and
|
||||
# the file './config.toml' to exist (may be empty). A local-cache volume
|
||||
@@ -77,21 +72,17 @@ LABEL register="podman run -it --rm \
|
||||
-e DOCKER_NETWORK_MODE=host \
|
||||
-e DOCKER_PRIVILEGED=${NESTED_PRIVILEGED} \
|
||||
--entrypoint=/usr/bin/gitlab-runner \$IMAGE register"
|
||||
|
||||
# Additionally, the nested-podman storage volumes must be pre-created with
|
||||
# 'podman' UID/GID values to allow nested containers access.
|
||||
LABEL setupstorage="podman volume create --opt o=uid=1000,gid=1000 pipglr-storage"
|
||||
|
||||
# Lastly, the gitlab-runner will manage container-cache in this directory,
|
||||
# which will also be bind-mounted into every container. So it must be
|
||||
# writable by both 'podman' user and 'runner' group.
|
||||
LABEL setupcache="podman volume create --opt o=uid=1000,gid=1001 pipglr-cache"
|
||||
|
||||
# Helper to extract the current configuration secret to allow editing.
|
||||
LABEL dumpconfig="podman run -it --rm \
|
||||
--secret config.toml --entrypoint=/bin/cat \
|
||||
\$IMAGE /var/run/secrets/config.toml"
|
||||
|
||||
# Executing the runner container depends on the config.toml secret being
|
||||
# set (see above) and two volumes existing with correct permissions set.
|
||||
# Note: The contents of the volumes are not critical, they may be removed
|
||||
@@ -102,4 +93,3 @@ LABEL run="podman run -dt --name pipglr \
|
||||
-v pipglr-cache:/cache \
|
||||
--systemd true --privileged \
|
||||
--device /dev/fuse \$IMAGE"
|
||||
# ==========================
|
||||
|
||||
278
README.md
278
README.md
@@ -1,84 +1,79 @@
|
||||
# Podmand-In-Podman Gitlab Runner
|
||||
|
||||
This project provides a Gitlab Runner which runs inside a container launched
|
||||
with `podman`. The Gitlab Runner itself uses an independent `podman` instance
|
||||
inside to launch jobs.
|
||||
|
||||
## Overview
|
||||
|
||||
This container image is built weekly from this `Containerfile`, and made
|
||||
available as:
|
||||
This container image is built daily from this `Containerfile`, and
|
||||
made available as:
|
||||
|
||||
- `registry.gitlab.com/qontainers/pipglr:latest`
|
||||
* `registry.gitlab.com/qontainers/pipglr:latest`
|
||||
|
||||
-or-
|
||||
|
||||
- `registry.gitlab.com/qontainers/pipglr:<version>`
|
||||
* `registry.gitlab.com/qontainers/pipglr:<version>`
|
||||
|
||||
It's purpose is to provide an easy method to execute a GitLab runner, to service
|
||||
CI/CD jobs for groups and/or repositories on [gitlab.com](https://gitlab.com).
|
||||
It comes pre-configured to utilize the gitlab-runner app to execute within a
|
||||
rootless podman container, nested inside a rootless podman container.
|
||||
It's purpose is to provide an easy method to execute a GitLab runner,
|
||||
to service CI/CD jobs for groups and/or repositories on
|
||||
[gitlab.com](https://gitlab.com). It comes pre-configured to utilize
|
||||
the gitlab-runner app to execute within a rootless podman container,
|
||||
nested inside a rootless podman container.
|
||||
|
||||
This is intended to provide additional layers of security for the host, when
|
||||
running potentially arbitrary CI/CD code. Though, the ultimate responsibility
|
||||
still rests with the end-user to review the setup and configuration relative to
|
||||
their own security situation/environment.
|
||||
This is intended to provide additional layers of security for the host,
|
||||
when running potentially arbitrary CI/CD code. Though, the ultimate
|
||||
responsibility still rests with the end-user to review the setup and
|
||||
configuration relative to their own security situation/environment.
|
||||
|
||||
**Note**: While this can run entirely under a regular user, it will require root
|
||||
access for the first two setup steps (below).
|
||||
**Note**: While this can run entirely under a regular user, it will require
|
||||
root access for the first two setup steps (below).
|
||||
|
||||
### Operation
|
||||
|
||||
This image leverages the podman `runlabel` feature heavily. Several labels are
|
||||
set on the image to support easy registration and execution of the runner
|
||||
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.
|
||||
This image leverages the podman `runlabel` feature heavily. Several
|
||||
labels are set on the image to support easy registration and execution
|
||||
of the runner 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.):
|
||||
***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>)
|
||||
```
|
||||
|
||||
#### Persistent Containers (step 1)
|
||||
#### 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.
|
||||
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.
|
||||
|
||||
```bash
|
||||
$ sudo loginctl enable-linger $USER
|
||||
```
|
||||
|
||||
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
|
||||
[setup quadlet](https://www.redhat.com/sysadmin/quadlet-podman) or a systemd
|
||||
unit so pipglr starts up on system boot.
|
||||
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 user-namespace (step 2) ***This is probably important***
|
||||
|
||||
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`).
|
||||
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`).
|
||||
|
||||
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):
|
||||
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
|
||||
@@ -87,71 +82,71 @@ Error: cannot set up namespace using "/usr/bin/newuidmap": exit status 1
|
||||
|
||||
or
|
||||
|
||||
```text
|
||||
```
|
||||
E: setgroups 65534 failed - setgroups (22: Invalid argument)
|
||||
```
|
||||
|
||||
**_The good news is, working around this is relatively simple:_**
|
||||
***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:
|
||||
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:
|
||||
|
||||
`johndoe:<some number>:65539`
|
||||
`jogndoe:<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:
|
||||
(you can ignore this). Only the last number needs to be increased. This
|
||||
change will be effective on next login, or immediately by running:
|
||||
|
||||
`podman system migrate`
|
||||
|
||||
_Note:_ This will stop any currently running containers.
|
||||
*Note:* This will stop any currently running containers.
|
||||
|
||||
#### Runner Registration (step 3)
|
||||
#### 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 registration
|
||||
_runlabel_. The command can (and probably should) be run more than once (using
|
||||
the same `config.toml`) to configure and register multiple runners. This is
|
||||
necessary for the _pipglr_ container to execute multiple jobs in parallel. For
|
||||
example, if you want to support running four jobs at the same time, you would
|
||||
use the `register` _runlabel_ four times.
|
||||
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 *runlabel*. The command can (and probably should) be run
|
||||
more than once (using the same `config.toml`) to configure and register
|
||||
multiple runners. This is necessary for the *pipglr* container to execute
|
||||
multiple jobs in parallel. For example, if you want to support running
|
||||
four jobs at the same time, you would use the `register` *runlabel*
|
||||
four times.
|
||||
|
||||
Before using the `register` _runlabel_, you must set your unique _registration_
|
||||
(a.k.a. _activation_) token as a podman _secret_. This secret may be removed
|
||||
once the registration step is complete. The **`<actual registration token>`**
|
||||
value (below) should be replaced with the value obtained from the `runners`
|
||||
settings page of a gitlab group or project's _CI/CD Settings_. Gitlab version 16
|
||||
and later refers to this value as an _activation_ token, but the usage is the
|
||||
same.
|
||||
Before using the `register` *runlabel*, you must set your unique
|
||||
*registration* (a.k.a. *activation*) token as a podman *secret*. This
|
||||
secret may be removed once the registration step is complete. The
|
||||
**<actual registration token>** value (below) should be replaced with
|
||||
the value obtained from the "runners" settings page of a gitlab
|
||||
group or project's *CI/CD Settings*. Gitlab version 16 and later
|
||||
refers to this value as an *activation* token, but the usage is the same.
|
||||
|
||||
```bash
|
||||
$ IMAGE="registry.gitlab.com/qontainers/pipglr:latest"
|
||||
$ echo '<actual registration token>' | podman secret create REGISTRATION_TOKEN -
|
||||
```
|
||||
|
||||
Next, **_a blank `config.toml` file_** needs to be created. Without this, the
|
||||
`reigster` _runlabel_ will return a permission-denied error. Once the empty
|
||||
Next, ***a blank `config.toml` file*** needs to be created. Without this, the
|
||||
`reigster` *runlabel* will return a permission-denied error. Once the empty
|
||||
`config.toml` file is created, you may register one or more runners by repeating
|
||||
the registration _runlabel_ as follows:
|
||||
the registration *runlabel* as follows:
|
||||
|
||||
```bash
|
||||
$ IMAGE="registry.gitlab.com/qontainers/pipglr:latest"
|
||||
$ touch ./config.toml # important: file must exist, even if empty.
|
||||
$ podman container runlabel register $IMAGE
|
||||
# ...repeat as desired...
|
||||
...repeat as desired...
|
||||
$ podman secret rm REGISTRATION_TOKEN # if desired
|
||||
```
|
||||
|
||||
#### 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 if desired before committing it as a _podman secret_. Please refer
|
||||
to the
|
||||
[gitlab runner documentation](https://docs.gitlab.com/runner/configuration/) for
|
||||
details.
|
||||
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
|
||||
if desired before committing it as a *podman secret*. Please refer to the
|
||||
[gitlab runner documentation](https://docs.gitlab.com/runner/configuration/)
|
||||
for details.
|
||||
|
||||
```bash
|
||||
$ $EDITOR ./config.toml # if desired
|
||||
@@ -160,45 +155,41 @@ $ 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
|
||||
committing it as a secret, there's
|
||||
[a `dumpconfig` _runlabel_ for that](README.md#configuration-editing).
|
||||
to reflect the number of registered runners. If you need to edit this file
|
||||
after committing it as a secret, there's
|
||||
[ a `dumpconfig` *runlabel* for that](README.md#configuration-editing).
|
||||
|
||||
#### Volume Setup (step 5)
|
||||
#### Quadlet setup and container start (step 5)
|
||||
|
||||
Since several users are utilized inside the container volumes must be
|
||||
specifically configured to permit access. This is done using several _runlabels_
|
||||
as follows:
|
||||
**Note**: If your system is missing or does not support the use of quadlet
|
||||
(`man 5 podman-systemd.unit`), you'll find [manual volume setup steps
|
||||
here](manual_setup.md).
|
||||
|
||||
Create and copy the quadlet configuration files:
|
||||
|
||||
```bash
|
||||
$ IMAGE="registry.gitlab.com/qontainers/pipglr:latest"
|
||||
$ podman container runlabel setupstorage $IMAGE
|
||||
$ podman container runlabel setupcache $IMAGE
|
||||
$ mkdir -p ~/.config/containers/systemd
|
||||
$ cp quadlet/* ~/.config/containers/systemd/
|
||||
```
|
||||
|
||||
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`. Then reuse the `setupstorage`
|
||||
and `setupcache` _runlabels_ as in the above example.
|
||||
|
||||
#### 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:
|
||||
Finally, reload the local systemd user-slice to generate the unit files,
|
||||
and fire up pipglr!
|
||||
|
||||
```bash
|
||||
$ IMAGE="registry.gitlab.com/qontainers/pipglr:latest"
|
||||
$ podman container runlabel run $IMAGE
|
||||
$ systemd --user daemon-reload
|
||||
$ systemd start pipglr
|
||||
```
|
||||
|
||||
If you want the service to start automatically on boot, you may run
|
||||
`systemctl --user enable podman-restart.service`
|
||||
|
||||
### Configuration Editing
|
||||
|
||||
The gitlab-runner configuration contains some sensitive values which should be
|
||||
protected. The pipglr container assumes the entire configuration will be passed
|
||||
in as a Podman secret. This makes editing it slightly convoluted, so a handy
|
||||
_runlabel_ `dumpconfig` is available. It's intended use is as follows:
|
||||
The gitlab-runner configuration contains some sensitive values which
|
||||
should be protected. The pipglr container assumes the entire configuration
|
||||
will be passed in as a Podman secret. This makes editing it slightly
|
||||
convoluted, so a handy *runlabel* `dumpconfig` is available.
|
||||
It's intended use is as follows:
|
||||
|
||||
```bash
|
||||
$ IMAGE="registry.gitlab.com/qontainers/pipglr:latest"
|
||||
@@ -211,17 +202,17 @@ $ rm ./config.toml # if desired
|
||||
|
||||
### Debugging
|
||||
|
||||
The first thing to check is the container output. This shows three things:
|
||||
Systemd, Podman, and GitLab-Runner output. For example:
|
||||
The first thing to check is the container output. This shows three things:
|
||||
Systemd, Podman, and GitLab-Runner output. For example:
|
||||
|
||||
```bash
|
||||
$ podman logs --since 0 pipglr
|
||||
```
|
||||
|
||||
Next, try running a pipglr image built with more verbose logging. Both the
|
||||
`runner.service` and `podman.service` files have a `log-level` option. Simply
|
||||
increase one or both to the `info`, or `debug` level. Start the debug container,
|
||||
and reproduce the problem.
|
||||
Next, try running a pipglr image built with more verbose logging. Both
|
||||
the `runner.service` and `podman.service` files have a `log-level` option.
|
||||
Simply increase one or both to the "info", or "debug" level. Start the
|
||||
debug container, and reproduce the problem.
|
||||
|
||||
## Building
|
||||
|
||||
@@ -231,36 +222,39 @@ This image may be built simply with:
|
||||
$ podman build -t registry.gitlab.com/qontainers/pipglr:latest .
|
||||
```
|
||||
|
||||
This will utilize the latest stable version of podman and the latest stable
|
||||
version of the gitlab runner.
|
||||
This will utilize the latest stable version of podman and the latest
|
||||
stable version of the gitlab runner.
|
||||
|
||||
### Build-Arguments
|
||||
### Build-args
|
||||
|
||||
Several build arguments are available to control the output image:
|
||||
|
||||
- `PRUNE_INTERVAL`: A systemd.timer compatible `OnCalendar` value that
|
||||
* `PRUNE_INTERVAL` - A systemd.timer compatible `OnCalendar` value that
|
||||
determines how often to prune Podman's storage of disused containers and
|
||||
images. Defaults to `daily`, but should be adjusted based on desired
|
||||
caching-effect balanced against available storage space and job execution
|
||||
rate.
|
||||
- `RUNNER_VERSION`: Allows specifying an exact gitlab runner version. By default
|
||||
the `latest` is used, assuming the user is building a tagged image anyway.
|
||||
Valid versions may be found on the
|
||||
[runner release page](https://gitlab.com/gitlab-org/gitlab-runner/-/releases).
|
||||
- `TARGETARCH`: Supports inclusion of non-x86_64 gitlab runners. This value is
|
||||
assumed to match the image's architecture. If using the `--platform` build
|
||||
argument, it will be set automatically. Note: as of this writing, only `amd64`
|
||||
and `arm64` builds of the gitlab-runner are available.
|
||||
- `GITLAB_URL`: Defaults to `https://gitlab.com/` but can be set to point to a
|
||||
self hosted instance of Gitlab.
|
||||
- `NESTED_PRIVILEGED`: Defaults to `true`, may be set `false` to prevent nested
|
||||
containers running in `--privileged` mode. This will affect the ability to
|
||||
build container images in CI jobs using tools like podman or buildah.
|
||||
images. Defaults to "daily", but should be adjusted based on desired
|
||||
caching-effect balanced against available storage space and job
|
||||
execution rate.
|
||||
* `RUNNER_VERSION` - Allows specifying an exact gitlab runner version.
|
||||
By default the `latest` is used, assuming the user is building a tagged
|
||||
image anyway. Valid versions may be found on the [runner
|
||||
release page](https://gitlab.com/gitlab-org/gitlab-runner/-/releases).
|
||||
* `TARGETARCH` - Supports inclusion of non-x86_64 gitlab runners. This
|
||||
value is assumed to match the image's architecture. If using the
|
||||
`--platform` build argument, it will be set automatically. Note:
|
||||
as of this writing, only `amd64` and `arm64` builds of the gitlab-runner
|
||||
are available.
|
||||
* `GITLAB_URL` - Defaults to 'https://gitlab.com/' but can be set to point
|
||||
to a self hosted instance of Gitlab.
|
||||
* `NESTED_PRIVILEGED` - Defaults to 'true', may be set 'false' to prevent
|
||||
nested containers running in `--privileged` mode. This will affect
|
||||
the ability to build container images in CI jobs using tools like
|
||||
podman or buildah.
|
||||
|
||||
### Environment Variables
|
||||
### Environment variables
|
||||
|
||||
Nearly every option to every gitlab-runner sub-command may be specified via
|
||||
environment variable. Some of these are set in the `Containerfile` for the
|
||||
`register` _runlabel_. If you need to set additional runtime env. vars., please
|
||||
do so via additional `Environment` optionns in the `runner.service` file. See
|
||||
the _systemd.nspawn_ man page for important value-format details.
|
||||
environment variable. Some of these are set in the `Containerfile` for
|
||||
the `register` *runlabel*. If you need to set additional runtime
|
||||
env. vars., please do so via additional `Environment` optionns in the
|
||||
`runner.service` file. See the *systemd.nspawn* man page for important
|
||||
value-format details.
|
||||
|
||||
32
manual_setup.md
Normal file
32
manual_setup.md
Normal file
@@ -0,0 +1,32 @@
|
||||
### Additional Manual steps
|
||||
|
||||
On systems without Quadlet, some additional steps are required
|
||||
to get the pipglr container up and running.
|
||||
|
||||
### Manual Volume setup
|
||||
|
||||
Since several users are utilized inside the container volumes must be
|
||||
specifically configured to permit access. This is done using several
|
||||
*runlabels* as follows:
|
||||
|
||||
```bash
|
||||
$ IMAGE="registry.gitlab.com/qontainers/pipglr:latest"
|
||||
$ podman container runlabel setupstorage $IMAGE
|
||||
$ 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`. Then reuse the `setupstorage`
|
||||
and `setupcache` *runlabels* as in the above example.
|
||||
|
||||
#### Manual Runner Startup
|
||||
|
||||
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:
|
||||
|
||||
```bash
|
||||
$ IMAGE="registry.gitlab.com/qontainers/pipglr:latest"
|
||||
$ podman container runlabel run $IMAGE
|
||||
```
|
||||
13
quadlet/pipglr-cache.volume
Normal file
13
quadlet/pipglr-cache.volume
Normal file
@@ -0,0 +1,13 @@
|
||||
[Unit]
|
||||
Description=Podman-in-podman GitLab Runner job cache storage volume
|
||||
Documentation=https://gitlab.com/qontainers/pipglr/-/blob/main/README.md
|
||||
After=local-fs.target
|
||||
Requires=podman.socket
|
||||
|
||||
[Volume]
|
||||
VolumeName=pipglr-cache
|
||||
Copy=false
|
||||
# The `podman` user inside the container should own everything
|
||||
Options=o=uid=1000,gid=1000
|
||||
# Support podman...prune --filters=persistent!=true
|
||||
Label=persistent=true
|
||||
13
quadlet/pipglr-storage.volume
Normal file
13
quadlet/pipglr-storage.volume
Normal file
@@ -0,0 +1,13 @@
|
||||
[Unit]
|
||||
Description=Podman-in-podman GitLab Runner nested-container storage volume
|
||||
Documentation=https://gitlab.com/qontainers/pipglr/-/blob/main/README.md
|
||||
After=local-fs.target
|
||||
Requires=podman.socket
|
||||
|
||||
[Volume]
|
||||
VolumeName=pipglr-storage
|
||||
Copy=false
|
||||
# The `podman` user inside the container should own everything
|
||||
Options=o=uid=1000,gid=1000
|
||||
# Support podman...prune --filters=persistent!=true
|
||||
Label=persistent=true
|
||||
33
quadlet/pipglr.container
Normal file
33
quadlet/pipglr.container
Normal file
@@ -0,0 +1,33 @@
|
||||
[Unit]
|
||||
Description=Podman-in-podman GitLab Runner
|
||||
Documentation=https://gitlab.com/qontainers/pipglr/-/blob/main/README.md
|
||||
After=pipglr-storage-volume.service pipglr-cache-volume.service
|
||||
Requires=podman.socket pipglr-storage-volume.service pipglr-cache-volume.service
|
||||
|
||||
[Container]
|
||||
ContainerName=pipglr
|
||||
Image=registry.gitlab.com/qontainers/pipglr
|
||||
|
||||
# Required to run containers inside a container and ensure
|
||||
# container can be managed with podman-restart.service
|
||||
# Note: See https://github.com/containers/podman/issues/20418
|
||||
PodmanArgs=--privileged --restart=always
|
||||
|
||||
# A nested systemd is used to manage nested podman & gitlab runner services
|
||||
Systemd=true
|
||||
|
||||
# Allow jobs access to utilize fuse-overlayfs, for example to build container images.
|
||||
Device=/dev/fuse
|
||||
|
||||
# Must be owned by the gitlab-runner user
|
||||
Secret config.toml,uid=1001,gid=1001
|
||||
|
||||
# Add network isolation from other containers
|
||||
Network=pipglr.network
|
||||
|
||||
# Storage for nested container images and job cache
|
||||
Volume=pipglr-storage:/home/podman/.local/share/containers
|
||||
Volume=pipglr-cache:/cache
|
||||
|
||||
# No need to preserve this between runs
|
||||
VolatileTmp=true
|
||||
11
quadlet/pipglr.network
Normal file
11
quadlet/pipglr.network
Normal file
@@ -0,0 +1,11 @@
|
||||
[Unit]
|
||||
Description=Podman-in-podman GitLab Runner dedicated network
|
||||
Documentation=https://gitlab.com/qontainers/pipglr/-/blob/main/README.md
|
||||
After=network-online.target
|
||||
Requires=podman.socket network.target
|
||||
|
||||
[Network]
|
||||
Driver=bridge
|
||||
# The pipglr container never accesses other containers on/or the host
|
||||
Options=isolate
|
||||
DisableDNS=true
|
||||
254
root/setup.sh
254
root/setup.sh
@@ -1,5 +1,4 @@
|
||||
#!/usr/bin/env bash
|
||||
#
|
||||
|
||||
# This script is intended to be run during container-image build. Any
|
||||
# other usage outside this context is likely to cause harm.
|
||||
#
|
||||
@@ -21,185 +20,108 @@
|
||||
|
||||
set -eo pipefail
|
||||
|
||||
function die() {
|
||||
echo -n '!! ERROR:' >&2
|
||||
printf " %s\n" "$@" >&2
|
||||
exit 1
|
||||
}
|
||||
|
||||
function check_vars() {
|
||||
for varname in PRUNE_INTERVAL RUNNER_VERSION TARGETARCH; do
|
||||
if [[ -z "${!varname}" ]]; then
|
||||
die "Env. variable '$varname' must be non-empty."
|
||||
fi
|
||||
done
|
||||
}
|
||||
|
||||
function main() {
|
||||
# Show what's happening to make debugging easier
|
||||
set -x
|
||||
|
||||
# Make image smaller by not installing docs.
|
||||
dnf=(dnf --setopt=tsflags=nodocs -y)
|
||||
|
||||
install_packages
|
||||
setup_user
|
||||
setup_service_podman
|
||||
setup_service_runner
|
||||
setup_gitlab_config
|
||||
|
||||
finalize_ownership
|
||||
}
|
||||
|
||||
function install_packages() {
|
||||
readarray xpackages < <(grep -vE '^(# )+' </root/xpackages.txt)
|
||||
local exclude_args=()
|
||||
for rpm in "${xpackages[@]}"; do
|
||||
exclude_args+=("--exclude=$rpm")
|
||||
done
|
||||
|
||||
# DNF itself or a dependence may need upgrading, take care of it first.
|
||||
"${dnf[@]}" upgrade &&
|
||||
"${dnf[@]}" "${exclude_args[@]}" install \
|
||||
podman \
|
||||
systemd
|
||||
|
||||
# Gitlab-runner package contains scriptlets which do not function properly inside a
|
||||
# container-build environment where systemd is not active/running.
|
||||
if [[ ${ENABLE_FIPS} == true && $(cat /proc/sys/crypto/fips_enabled) == 1 ]]; then
|
||||
PACKAGE_FILE="gitlab-runner_${TARGETARCH}-fips.rpm"
|
||||
else
|
||||
PACKAGE_FILE="gitlab-runner_${TARGETARCH}.rpm"
|
||||
for varname in PRUNE_INTERVAL RUNNER_VERSION TARGETARCH; do
|
||||
if [[ -z "${!varname}" ]]; then
|
||||
echo "Error: \$$varname must be non-empty."
|
||||
fi
|
||||
done
|
||||
|
||||
"${dnf[@]}" "${exclude_args[@]}" \
|
||||
--setopt=tsflags=noscripts install \
|
||||
"https://gitlab-runner-downloads.s3.amazonaws.com/$RUNNER_VERSION/rpm/${PACKAGE_FILE}"
|
||||
# Make image smaller by not installing docs.
|
||||
DNF="dnf --setopt=tsflags=nodocs -y"
|
||||
|
||||
for rpm in $(egrep -v '^(# )+' < /root/xpackages.txt); do
|
||||
x+="--exclude=$rpm ";
|
||||
done
|
||||
|
||||
set -x # show what's happening to make debugging easier
|
||||
|
||||
# DNF itself or a dependence may need upgrading, take care of it first.
|
||||
$DNF upgrade
|
||||
|
||||
$DNF $x install \
|
||||
podman \
|
||||
systemd
|
||||
|
||||
# Gitlab-runner package contains scriptlets which do not function properly inside a
|
||||
# container-build environment where systemd is not active/running.
|
||||
$DNF $x --setopt=tsflags=noscripts install \
|
||||
https://gitlab-runner-downloads.s3.amazonaws.com/$RUNNER_VERSION/rpm/gitlab-runner_${TARGETARCH}.rpm
|
||||
|
||||
# Allow removing dnf, sudo, etc. packages. Also don't start unnecessary or broken
|
||||
# systemd services, like anything kernel related or login gettys.
|
||||
rm -rf \
|
||||
/etc/dnf/protected.d/* \
|
||||
/etc/systemd/system/getty.target.wants/* \
|
||||
/etc/systemd/system/multi-user.target.wants/* \
|
||||
/etc/systemd/system/sysinit.target.wants/* \
|
||||
/etc/systemd/system/timers.target.wants/* \
|
||||
/etc/sytemd/system/getty.target.wants/* \
|
||||
/etc/sytemd/system/multi-user.target.wants/* \
|
||||
/etc/sytemd/system/sysinit.target.wants/* \
|
||||
/etc/sytemd/system/timers.target.wants/* \
|
||||
/lib/systemd/system/graphical.target.wants/* \
|
||||
/lib/systemd/system/multi-user.target.wants/{getty.target,systemd-ask-password-wall.path} \
|
||||
/lib/systemd/system/sys-kernel*.mount
|
||||
|
||||
# Allow removing dnf, sudo, etc. packages.
|
||||
rm -rf \
|
||||
/etc/dnf/protected.d/*
|
||||
# Remove unnecessary packages, see xpackages.txt to learn how this list was generated.
|
||||
# This makes the image smaller and reduces the attack-surface.
|
||||
dnf remove -y "${xpackages[@]}"
|
||||
# Remove unnecessary packages, see xpackages.txt to learn how this list was generated.
|
||||
# This makes the image smaller and reduces the attack-surface.
|
||||
dnf remove -y $(egrep -v '^(# )+' /root/xpackages.txt)
|
||||
|
||||
# Wipe out the DNF cache, then remove it entirely, again to make the image smaller.
|
||||
"${dnf[@]}" clean all
|
||||
rm -rf /var/cache/dnf /var/log/dnf* /var/log/yum.*
|
||||
rpm -e dnf
|
||||
# Wipe out the DNF cache, then remove it entirely, again to make the image smaller.
|
||||
$DNF clean all
|
||||
rm -rf /var/cache/dnf /var/log/dnf* /var/log/yum.*
|
||||
rpm -e dnf
|
||||
|
||||
# Workaround base-image failing to confer capabilties properly on
|
||||
# /usr/bin/new{u,g}idmap to `cap_set{u,g}id=ep` in new image layers.
|
||||
rpm --setcaps shadow-utils
|
||||
}
|
||||
# Workaround https://bugzilla.redhat.com/show_bug.cgi?id=1995337
|
||||
rpm --setcaps shadow-utils
|
||||
|
||||
function setup_user() {
|
||||
# Guarantee uid/gid 1000 for user 'podman' / 1001 for user 'runner'.
|
||||
groupadd -g 1000 podman
|
||||
groupadd -g 1001 runner
|
||||
# Prevent copying of skel since it can interfere with the gitlab-runner
|
||||
mkdir -p /home/podman /home/runner
|
||||
# Guarantee uid/gid 1000 for user 'podman' / 1001 for user 'runner'.
|
||||
groupadd -g 1000 podman
|
||||
groupadd -g 1001 runner
|
||||
# Separate users for services to increase process isolation.
|
||||
# The 'podman' user's socket service writes /home/runner/podman.socket
|
||||
useradd -M -u 1000 -g podman -G runner podman
|
||||
useradd -M -u 1001 -g runner runner
|
||||
# Allow 'podman' user to create socket file under /home/runner.
|
||||
chmod 770 /home/runner
|
||||
|
||||
# Separate users for services to increase process isolation.
|
||||
# The 'podman' user's socket service writes /home/runner/podman.socket
|
||||
# Prevent copying of skel since it can interfere with the gitlab-runner
|
||||
mkdir -p /home/podman /home/runner
|
||||
useradd -M -u 1000 -g podman -G runner podman
|
||||
useradd -M -u 1001 -g runner runner
|
||||
# Overwrite defaults, only user 'podman' permited to have a user-namespace
|
||||
# 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:<start>: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.
|
||||
mkdir -p /cache
|
||||
# Both the gitlab-runner and podman need access to the cache directory / volume mount.
|
||||
chown podman:runner /cache
|
||||
|
||||
# Allow only podman in `/home/podman`.
|
||||
chmod 700 /home/podman
|
||||
# Allow 'podman' user to create socket file under `/home/runner`.
|
||||
chmod 770 /home/runner
|
||||
# Setup persistent 'podman' user services to start & run without a login.
|
||||
mkdir -p /var/lib/systemd/linger
|
||||
touch /var/lib/systemd/linger/podman
|
||||
# Setup 'podman' socket and a container-storage pruning service for 'podman' user.
|
||||
mkdir -p /home/podman/.config/systemd/user/{sockets.target.wants,default.target.wants}
|
||||
cd /home/podman/.config/systemd/user/
|
||||
ln -s $PWD/podman.socket ./sockets.target.wants/ # Added from Containerfile
|
||||
ln -s $PWD/prune.timer ./default.target.wants/ # also from Containerfile
|
||||
# Substitute value from --build-arg if specified, otherwise use default from Containerfile.
|
||||
sed -i -e "s/@@@PRUNE_INTERVAL@@@/$PRUNE_INTERVAL/" ./prune.timer
|
||||
# Containerfile ADD instruction does not properly set ownership/permissions.
|
||||
chown -R 1000:1000 /home/podman
|
||||
chmod 700 /home/podman
|
||||
|
||||
# Set permissions.
|
||||
chown -R runner:runner /home/runner
|
||||
chown -R podman:podman /home/podman
|
||||
|
||||
# Overwrite defaults, only user 'podman' permitted to have a user-namespace
|
||||
# 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:<start>:65539`
|
||||
echo -e "podman:1:999\npodman:1002:64536" | tee /etc/subuid >/etc/subgid
|
||||
}
|
||||
|
||||
function setup_volumes() {
|
||||
# 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.
|
||||
mkdir -p /cache
|
||||
|
||||
# Both the gitlab-runner and podman need access to the cache directory / volume mount.
|
||||
chown podman:runner /cache
|
||||
}
|
||||
|
||||
function setup_service_podman() {
|
||||
# Setup persistent 'podman' user services to start & run without a login.
|
||||
mkdir -p /var/lib/systemd/linger
|
||||
touch /var/lib/systemd/linger/podman
|
||||
|
||||
# Setup 'podman' socket and a container-storage pruning service for 'podman' user.
|
||||
mkdir -p /home/podman/.config/systemd/user/{sockets.target.wants,default.target.wants}
|
||||
|
||||
cd /home/podman/.config/systemd/user/
|
||||
ln -s "$(pwd)/podman.socket" ./sockets.target.wants/ # Added from Containerfile
|
||||
ln -s "$(pwd)/prune.timer" ./default.target.wants/ # also from Containerfile
|
||||
|
||||
# Substitute value from --build-arg if specified, otherwise use default from Containerfile.
|
||||
sed -i -e "s/@@@PRUNE_INTERVAL@@@/$PRUNE_INTERVAL/" ./prune.timer
|
||||
}
|
||||
|
||||
function setup_service_runner() {
|
||||
# Setup persistent 'runner' user services to start & run without a login.
|
||||
touch /var/lib/systemd/linger/runner
|
||||
|
||||
# Setup persistent 'runner' user services to start & run without a login.
|
||||
mkdir -p /home/runner/.config/systemd/user/default.target.wants
|
||||
|
||||
cd /home/runner/.config/systemd/user/
|
||||
# Does not depend on podman.socket file availability, will retry if not present.
|
||||
ln -s "$(pwd)/runner.service" ./default.target.wants/
|
||||
}
|
||||
|
||||
function setup_gitlab_config() {
|
||||
# gitlab-runner will create side-car '.runner_system_id' file next to 'config.toml'
|
||||
# on first startup. Ensure access is allowed. Also link to future config file
|
||||
# presented as a container-secret.
|
||||
mkdir -p /home/runner/.gitlab-runner
|
||||
ln -s /var/run/secrets/config.toml /home/runner/.gitlab-runner/config.toml
|
||||
|
||||
chmod -R 700 /home/runner/.gitlab-runner
|
||||
}
|
||||
|
||||
function finalize_ownership() {
|
||||
# Adjust ownership to all files created after `setup_user`.
|
||||
# and also to the `ADD` instruction in the `Containerfile`.
|
||||
chown -R runner:runner /home/runner
|
||||
chown -R podman:podman /home/podman
|
||||
|
||||
# Ensure correct permissions of system configuration files.
|
||||
# Somehow these can be set incorrectly during Containerfile
|
||||
# ADD instruction.
|
||||
local path
|
||||
for path in "/etc/systemd/system.conf.d" "/etc/systemd/system/user-.slice.d"; do
|
||||
chown root:root ${path}/*
|
||||
chmod 0644 ${path}/*
|
||||
done
|
||||
}
|
||||
|
||||
check_vars
|
||||
main
|
||||
# Setup persistent 'runner' user services to start & run without a login.
|
||||
touch /var/lib/systemd/linger/runner
|
||||
mkdir -p /home/runner/.config/systemd/user/default.target.wants
|
||||
cd /home/runner/.config/systemd/user/
|
||||
# Does not depend on podman.socket file availablility, will retry if not present.
|
||||
ln -s $PWD/runner.service ./default.target.wants/
|
||||
# gitlab-runner will create side-car '.runner_system_id' file next to 'config.toml'
|
||||
# on first startup. Ensure access is allowed. Also link to future config file
|
||||
# presented as a container-secret.
|
||||
mkdir -p /home/runner/.gitlab-runner
|
||||
ln -s /var/run/secrets/config.toml /home/runner/.gitlab-runner/config.toml
|
||||
# Containerfile ADD instruction does not properly set ownership/permissions.
|
||||
chown -R runner:runner /home/runner
|
||||
chmod -R 700 /home/runner/.gitlab-runner
|
||||
|
||||
Reference in New Issue
Block a user