CP2K Continuous Integration

The CP2K-CI system is a custom solution to run our resource intensive integration tests in a swift and affordable manner. It is based on Kubernetes and currently deployed on the Google Cloud Platform using preemptible virtual machines.

Overview

The typical use case consists of the following steps:

1. User opens a pull request on Github.
2. Github sends webhook events to frontend.
3. Frontend places message into Pub/Sub queue.
4. Backend receives Pub/Sub message and launches Kubernetes jobs.
5. Backend continuously monitors the jobs and updates their status in the Github UI.
6. The jobs upload their reports to Cloud Storage via signed urls.
7. The user sees job summaries on Github and may download full reports from Cloud Storage.

Configuration

Repository Configuration

The CP2K-CI can be enabled for any repository within the CP2K GitHub organization. The repositories are configured via the repository_config.py file. The fields have the following meaning.

Field	Description
name	Name of repository below https://github.com/cp2k/ .
targets_config	Path to targets configuration file within the given repository.
required_checks	List of targets that should run automatically for every pull request.

Targets Configuration

The targets of a repository are configured via a file within the repository itself, e.g. like this.

The file has the format of the python configparser. Each section is refereed to as a target. Typical sections looks like this:

[sdbg]
display_name: Regtest sdbg
tags:         daily
cpu:          32
nodepools:    pool-t2d-32
build_path:   /
dockerfile:   /tools/docker/Dockerfile.test_sdbg

The fields have the following meaning. All lists are white-space separated.

Field	Description
[foo-bar]	Internal name used e.g. in report url.
display_name	Visible name of check run.
tags	List of tags, e.g. asap, daily, or weekly used for cron scheduling.
cpu	Number of CPUs to allocate for building and running.
gpu	Number of GPUs to allocate for building and running.
arch	Architecture of the CPU, possible values are "arm64" and "x86", defaults to "x86".
nodepools	List of eligible nodepools, see also.
build_args	List of Docker build arguments.
build_path	Path to build context within given repository.
dockerfile	Path to Dockerfile within given repository.
cache_from	Optional name of target that should be used as additional cache source during the build.
trigger_path	Regular expression that forces a check run if it matches any of the modified files.

Communication with Containers

The CP2K-CI communication with its container via a simple protocol. See the ci_entrypoint.sh script for an example implementation.

The CP2K-CI passes as input the following environment variables to its containers:

Environment Variable	Description
GIT_BRANCH	Git branch to test, e.g. master or pull/42/merge.
GIT_REF	Git ref to test from given branch, typically the SHA of the latest commit.

The container must output a report using the dashboard format. Additionally, the container can make files available to the user by writting them to /workspace/artifacts.

Implementation

The CP2K-CI system consists of three components. Each resides in its own sub directory and gets automatically deployed as a container by Cloud Build.

Frontend

• Hosted on Cloud Run, reachable at https://ci.cp2k.org.
• Runs a simple Flask application for receiving events from Github via webhooks.
• After validating their signature the Github events are placed into a Pub/Sub message queue.

Backend

• A Python daemon that contains all the logic.
• Runs as a Kubernetes Deployment on a preemptible n1-standard-1 instance.
• Receives messages from Pub/Sub.
• Polls Kubernetes job statuses every 5 seconds.
• Polls Github pull requests every 2.5 minutes as safeguard against lost events.
• All state information is stored in the job's metadata and the check run's external_id.

Toolbox

• Collection of utility scripts.
• Used for building and running targets.
• Used for running CronJobs, e.g. for the Dashboard.
• Cron jobs use the cp2kcictl.py command line tool to inject Pub/Sub messages. It doubles as admin tool.

Installation

The CP2K-CI system is a one-off implementation that is not meant to be installed multiple times. Nevertheless, the following steps are roughly what needs to be done to re-install the CP2K-CI system:

• Run scripts in ./setup (finding the right order is left as an exercise ;-)
• Run kubectl apply -f manifests/ repeatedly until ''convergence''.
• Register Cloud Build triggers for all cloudbuild.yaml files and run them once manually.
• Request quota for PREEMPTIBLE_CPUS and IN_USE_ADDRESSES.