README
¶
Jacamar CI
Jacamar CI is the HPC focused CI/CD driver using GitLab’s custom executor model. The core goal of this project is to establish a maintainable, yet extensively configurable tool that will allow for the use of GitLab’s robust testing on unique resources. Allowing code teams to integrate potentially existing pipelines on powerful scientific development environments.
Documentation
For complete documentation regarding all aspects of deployment and administration of Jacamar CI please see ecp-ci.gitlab.io.
Quick Start
If new to Jacamar CI we recommend viewing the administrator tutorial before continuing. This hands-on tutorial will take ~15 minutes. It will provide a basic introduction to deployment, configuration, and a simple process for testing the majority of functionality within a container/virtual-environment.
Installation
See our documentation on installing the release RPM. If you wish to build from source you will need:
- Bash
- Git versions 2.9+
- Optionally Git 2.31+ is recommended
- GitLab Server & Runner 16+
- Go versions 1.20+ (see official instructions)
- libc
- libseccomp 2.3.1+
- Make
git clone https://gitlab.com/ecp-ci/jacamar-ci.git
cd jacamar-ci
make build
make install PREFIX=/usr/local
Though the custom executor has been officially supported through the GitLab
Runner for several major releases, due to required functionality Jacamar CI
necessitates the use of upstream runner version 14.3+. Please see the
official releases to
obtain your required version.
Configuration
If you've administered a GitLab Runner before, the configuration will be familiar. With Jacamar CI, it not only relies upon specific management of the upstream runner but also its own configuration. Both applications leverage TOML.
GitLab Runner
When using the custom executor
there are additional one time configuration (e.g., /etc/gitlab-runner/config.toml)
requirements. This example targets the full path to our jacamar-auth
application as we wish to leverage the supported
authorization and downscoping mechanisms.
Please note that the *_args are required as shown.
[[runners]]
name = "Custom Executor Example"
url = "https://gitlab.example.com/"
token = "T0k3n"
executor = "custom"
[runners.custom]
config_exec = "/opt/jacamar/bin/jacamar-auth"
config_args = ["config", "--configuration", "/etc/gitlab-runner/custom-config.toml"]
prepare_exec = "/opt/jacamar/bin/jacamar-auth"
prepare_args = ["prepare"]
run_exec = "/opt/jacamar/bin/jacamar-auth"
run_args = ["run"]
cleanup_exec = "/opt/jacamar/bin/jacamar-auth"
cleanup_args = ["cleanup", "--configuration", "/etc/gitlab-runner/custom-config.toml"]
Jacamar
You will notice a Jacamar CI specific configuration is required
(--configuration /etc/gitlab-runner/custom-config.toml). This is to
support the plethora of
configuration options:
[general]
executor = "slurm"
data_dir = "/ecp"
[auth]
downscope = "setuid"
The above demonstrates the minimally required configuration in order to run. We highly encourage you to explore our documentation for a comprehensive look at options available and recommended practices.
Breaking Changes in GitLab Server v17.0+
With the upcoming release of GitLab server 17.0 (planned for May 15, 2024) there are several breaking changes that you should be aware of:
-
Old versions of the JWT are being deprecated in favor of id_tokens. If you are un-familiar with the
CI_JOB_JWTin Jacamar CI, it is utilized to consistently and securely identify key information about the CI job and most importantly the user responsible for triggering it.- Complete details on the changes required by users of Jacamar CI as well as steps to handle the migration can be found in the Migrating to new id_tokens from CI_JOB_JWT guide.
-
JWKS instance endpoint (
/-/jwks) is being removed in favor of the/oauth/discovery/keys. Upgrading to Jacamar CI 0.18+ is the only fix for this. -
The ci_job_token_scope_enabled field in projects API will be removed breaking the
auth.job_token_scope_enforcedconfiguration. There is no fix for this.
Attributions
- The logo was created by @admgc and is a remix of the Rufous-tailed jacamar by Charles J. Sharp from Sharp Photography, licensed under CC BY-SA-4.0.
_male_2.JPG){kind=link}
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
internal
|
|
|
arguments
Package arguments manages the command line subcommands and shared arguments for the Jacamar CI applications.
|
Package arguments manages the command line subcommands and shared arguments for the Jacamar CI applications. |
|
augmenter
Package augmenter offers a rule enforced mechanism for updating the GitLab generated CI job script to conform to required behaviors.
|
Package augmenter offers a rule enforced mechanism for updating the GitLab generated CI job script to conform to required behaviors. |
|
authuser
Package authuser (authorize user) maintains the interface for the complete authorization flow, leveraging the job's configuration as well as context provided by the custom executor to ensure a fully authorized user is identified for the local job.
|
Package authuser (authorize user) maintains the interface for the complete authorization flow, leveraging the job's configuration as well as context provided by the custom executor to ensure a fully authorized user is identified for the local job. |
|
authuser/datadir
Package datadir maintains procedures for establishing core directory structures the meet CI job requirements.
|
Package datadir maintains procedures for establishing core directory structures the meet CI job requirements. |
|
authuser/validation
Package validation maintains Jacamar's interactions with an admin defined validation script.
|
Package validation maintains Jacamar's interactions with an admin defined validation script. |
|
cmd/auth
Package auth realizes the core of the jacamar-auth application by ensuring the strict adherence to the authorization flow and the validity of the subsequent user context used to execute the configured downscope mechanism.
|
Package auth realizes the core of the jacamar-auth application by ensuring the strict adherence to the authorization flow and the validity of the subsequent user context used to execute the configured downscope mechanism. |
|
cmd/preparations
Package preparations realizes universal actions taken by different applications / sub-commands to prepare for an upcoming CI job.
|
Package preparations realizes universal actions taken by different applications / sub-commands to prepare for an upcoming CI job. |
|
envkeys
Package envkeys maintains constants for all potentially required environment variable keys.
|
Package envkeys maintains constants for all potentially required environment variable keys. |
|
errorhandling
Package errorhandling maintains all interfaces by which the Jacamar CI applications should handle specialized errors specifically formatted to align with the custom executor model.
|
Package errorhandling maintains all interfaces by which the Jacamar CI applications should handle specialized errors specifically formatted to align with the custom executor model. |
|
executors
Package executors manages global aspects of the CI job before final responsibility for execution is handed over to the specified interface.
|
Package executors manages global aspects of the CI job before final responsibility for execution is handed over to the specified interface. |
|
flock
Package flock leverages the underlying system call (flock(2)) in conjunction with pre-established rules to generate unique directories on supporting systems that will not conflict with other jobs running across a range of resources.
|
Package flock leverages the underlying system call (flock(2)) in conjunction with pre-established rules to generate unique directories on supporting systems that will not conflict with other jobs running across a range of resources. |
|
rules
Package rules maintains established validation for shared aspects relating to either Jacamar specifically or the ECP CI effort as a whole.
|
Package rules maintains established validation for shared aspects relating to either Jacamar specifically or the ECP CI effort as a whole. |
|
runmechanisms/basic
Package basic implements a non-interfering runner interface that redirects all input to the underlying commander for execution.
|
Package basic implements a non-interfering runner interface that redirects all input to the underlying commander for execution. |
|
runmechanisms/runnerinit
Package runnerinit handles methods associated with initializing the correct RunMechanism based upon configuration, stage, and user settings.
|
Package runnerinit handles methods associated with initializing the correct RunMechanism based upon configuration, stage, and user settings. |
|
seccomp
Package seccomp manages bindings for libseccomp.
|
Package seccomp manages bindings for libseccomp. |
|
usertools
Package usertools is a generic catch-all for Jacamar CI that is meant to support any range of functionality required by CI jobs within userspace.
|
Package usertools is a generic catch-all for Jacamar CI that is meant to support any range of functionality required by CI jobs within userspace. |
|
verifycaps
Package verifycaps manages interactions with the underlying system to verify and enforce supported usage of Linux capabilities(7).
|
Package verifycaps manages interactions with the underlying system to verify and enforce supported usage of Linux capabilities(7). |
|
pkg
|
|
|
abstracts
Package abstracts maintains interfaces/structures that are shared between internal workflows and potential plugins.
|
Package abstracts maintains interfaces/structures that are shared between internal workflows and potential plugins. |
|
configure
Package configure maintains all related structures for the Jacamar CI configuration through the supplied TOML file.
|
Package configure maintains all related structures for the Jacamar CI configuration through the supplied TOML file. |
|
envparser
Package envparser manages actions related to the retrieval and validation of key environment variables used by the GitLab Runner in order to provide context to a custom executor driver.
|
Package envparser manages actions related to the retrieval and validation of key environment variables used by the GitLab Runner in order to provide context to a custom executor driver. |
|
logging
Package logging maintains interface for two core supported types of logging that occur within Jacamar.
|
Package logging maintains interface for two core supported types of logging that occur within Jacamar. |
|
test
|
|
|
mocks/mock_authuser
Package mock_authuser is a generated GoMock package.
|
Package mock_authuser is a generated GoMock package. |
|
mocks/mock_batch
Package mock_batch is a generated GoMock package.
|
Package mock_batch is a generated GoMock package. |
|
mocks/mock_command
Package mock_command is a generated GoMock package.
|
Package mock_command is a generated GoMock package. |
|
mocks/mock_configure
Package mock_configure is a generated GoMock package.
|
Package mock_configure is a generated GoMock package. |
|
mocks/mock_executors
Package mock_executors is a generated GoMock package.
|
Package mock_executors is a generated GoMock package. |
|
mocks/mock_gitwebapis
Package mock_gitwebapis is a generated GoMock package.
|
Package mock_gitwebapis is a generated GoMock package. |
|
mocks/mock_gljobctx
Package mock_gljobctx is a generated GoMock package.
|
Package mock_gljobctx is a generated GoMock package. |
|
mocks/mock_jobtoken
Package mock_jobtoken is a generated GoMock package.
|
Package mock_jobtoken is a generated GoMock package. |
|
mocks/mock_logging
Package mock_logging is a generated GoMock package.
|
Package mock_logging is a generated GoMock package. |
|
mocks/mock_runmechanisms
Package mock_runmechanisms is a generated GoMock package.
|
Package mock_runmechanisms is a generated GoMock package. |
|
mocks/mock_validation
Package mock_validation is a generated GoMock package.
|
Package mock_validation is a generated GoMock package. |
|
tools
|
|
|
exec_testing
Package exec_testing supports basic testing/mocks for any of the "batch" executor types.
|
Package exec_testing supports basic testing/mocks for any of the "batch" executor types. |
|
jacamar-testing
Package jacamartst maintains shared test functionality.
|
Package jacamartst maintains shared test functionality. |