Container image for rpki-client

About

Source files and build instructions for an OCI image (compatible with e.g. Docker or Podman) for rpki-client. It's an RPKI validator to support BGP Origin Validation.

Usage

The OCI image automatically refreshs the Validated ROA Payloads (VRPs) hourly. It may be started with Docker using:

docker run --name rpki-client \
           --volume /path/to/rpki-client/tals/arin.tal:/etc/tals/arin.tal \
           --volume /path/to/rpki-client/output:/var/lib/rpki-client \
           --volume /path/to/rpki-client/cache:/var/cache/rpki-client \
           --detach rpki/rpki-client:latest

And it may be started with Podman using:

podman run --name rpki-client \
           --volume /path/to/rpki-client/tals/arin.tal:/etc/tals/arin.tal \
           --volume /path/to/rpki-client/output:/var/lib/rpki-client \
           --volume /path/to/rpki-client/cache:/var/cache/rpki-client \
           --detach quay.io/rpki/rpki-client:latest

Volumes

• /etc/tals - Directory for Trust Anchor Location (TAL) files that rpki-client will load by default. ARIN TAL must be downloaded separately in RFC 7730 format, because the ARIN Relying Party Agreement (RPA) must be accepted.
• /var/lib/rpki-client - Directory where rpki-client will write the output files. By default BIRD and OpenBGPD compatible outputs as well as CSV and JSON formats are generated.
• /var/cache/rpki-client - Directory where rpki-client will store the cached repository data. To speed-up the performance, persistent storage is recommented.

While none of the volumes is required, meaningful usage requires at least persistent storage for /var/lib/rpki-client and the ARIN TAL.

Environment Variables

• TZ - Time zone according to IANA's time zone database, e.g. Europe/Amsterdam, defaults to UTC.
• ONESHOT - Set to true to run rpki-client only once instead of periodically, defaults to false.
• WAIT - Seconds to wait before restarting after rpki-client exited successfully, defaults to 600.

Exposed Ports

• 9099 - TCP port for optional rpki-client output in OpenMetrics format via HTTP endpoint /metrics.

Custom images

For custom OCI images, the following build arguments can be passed:

• VERSION - Version of the signed portability shim release tarball, defaults to 9.3.
• PORTABLE_GIT - Git repository URL of the portability shim, defaults to https://github.com/rpki-client/rpki-client-portable.git.
• PORTABLE_COMMIT - Git commit, branch or tag of the portability shim, e.g. master, unset by default.
• OPENBSD_GIT - Git repository URL of the OpenBSD source code, defaults to https://github.com/rpki-client/rpki-client-openbsd.git.
• OPENBSD_COMMIT - Git commit, branch or tag of the OpenBSD source code, e.g. master, unset by default.

To build a custom OCI image from current Git, e.g. --build-arg PORTABLE_COMMIT=master needs to be passed.

Pipeline / Workflow

Docker Hub and Quay can both automatically build OCI images from a linked GitHub account and automatically push the built image to the respective container repository. However, as of writing, this leads to OCI images for only the amd64 CPU architecture. To support as many CPU architectures as possible (currently 386, amd64, arm/v6, arm/v7, arm64/v8, ppc64le, riscv64 and s390x), GitHub Actions are used. There, the current standard workflow "Build and push OCI image" roughly uses first a GitHub Action to install QEMU static binaries, then a GitHub Action to set up Docker Buildx and finally a GitHub Action to build and push Docker images with Buildx.

Thus the OCI images are effectively built within the GitHub infrastructure (using free minutes for public repositories) and then only pushed to both container repositories, Docker Hub and Quay (which are also free for public repositories). This not only saves repeated CPU resources but also ensures identical bugs independent from which container repository the OCI image gets finally pulled (and somehow tries to keep it distant from program changes such as Docker Hub Rate Limiting in 2020). The authentication for the pushes to the container repositories happen using access tokens, which at Docker Hub need to be bound to a (community) user and at Quay using a robot account as part of the organization. These access tokens are saved as "repository secrets" as part of the settings of the GitHub project.

For each release of the project, a new Git branch (named like the version of the release, e.g. 9.3) is created (based on the default branch, e.g. master). The workflow takes care about creating and moving container tags, such as latest. By not using Git tags but branches, downstream bug fixes can be easily applied to the OCI image (e.g. for bugs in the Dockerfile or patches for the source code itself). Old branches are not touched anymore, equivalent to old release archives.

Each commit to a Git branch triggers the workflow and leads to OCI images being pushed (except for GitHub pull requests), where the container tag is always based on the Git branch name. OCI images with non-release container tags pushed for testing purposes need to be cleaned up manually at the container repositories. Additionally, a cron-like option in the workflow leads to a nightly build being also tagged as edge.

Re-running a workflow for failed builds can be performed using the GitHub web interface at the "Actions" section. However, to re-run older or successful builds (e.g. to achieve a newer operating system base image layer for an existing release), git commit --allow-empty -m "Reason" && git push might do the trick (because the GitHub Actions API doesn't seem to allow such re-runs either).

License

This project is licensed under the ISC License - see the LICENSE file for details.

As with all OCI images, these also contain other software under other licenses (such as BusyBox, HAProxy, OpenSSL etc. from the base distribution, along with any direct or indirect dependencies of the contained rpki-client).

As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.