FreeIPA Pull Request CI

Scripts that are used by the PR CI testing infrastructure.

Contributor's Guide

If you're looking for an overview of what the system looks like for contributors, you can check out this video.

Slides from the video are also available in contributors_guide_slides.pdf.

Update 2017-09-20: It is no longer necessary to open a PR against multiple branches if code for different branches is the same. Backporting will be handled by our tooling. (Details)

Setting up runner

Prerequisites

Runner

• Dedicated machine: runners have some configuration and behaviour that's not desirable for a workstation. Virtual machine can be used if the hypervisor has support for nested virtualization.
• Root access: set up root access to the machine. This can be done with ssh_config, ansible inventory parameters or ansible configuration. (Note: please use freeipa_pr_ci key for root access if you have it)
• Hostname: short hostname is used as the runner identifier, please make sure it is unique.
• Persistent configuration: runner may be rebooted occasionally. All configuration including hostname and networking should persist after reboot.
• Minimum specs: 4 vCPUs, 8 GB RAM, 30 GB disk.
• Operating system: currently, only Fedora is supported.
• Partitioning: /var/lib/libvirt/images and /root/.vagrant.d/ have to be on the same partition.

Other

• ansible >= 2.3 on the control machine
• GitHub token with Full control of private repositories (Settings -> Developer settings -> Personal access tokens)
• freeipa_pr_ci private key placed in keys/
• Cloud config and credentials files in keys/
• private keys in keys/ have permissions set to 0600

Development runner deployment

The development runner can be deployed to monitor any FreeIPA fork while executing any FreeIPA PR CI fork (any owner and branch). This is useful for testing and development purposes.

1. Create ansible inventory ansible/hosts/runners (Replace 2.3.4.5 with the machine's IP address)

   [runners_devel]
   2.3.4.5
   
   [runners_devel:vars]
   ansible_python_interpreter=/usr/bin/python3
   

2. Run the prepare_devel_test_runners.yml playbook, specify which repository should be monitored and which code repository and branch should be used to deploy the runner

   ansible-playbook \
     -i ansible/hosts/runners \
     ansible/prepare_devel_test_runners.yml
   

"Production" Runner deployment

1. Create ansible inventory ansible/hosts/runners (Replace 1.2.3.4 with the machine's IP address)

   [runners]
   1.2.3.4
   
   [runners:vars]
   ansible_python_interpreter=/usr/bin/python3
   

2. Run the prepare_test_runners.yml playbook

   ansible-playbook \
     -i ansible/hosts/runners \
     ansible/prepare_test_runners.yml
   

This will set up the runner machine with prci service, which is configured to start at boot. The runner is periodically updated to use the latest code. In the unfortunate event the update didn't execute successfully, the service will enter a failed state. Re-running the above ansible-playbook command from the up-to-date code should fix such issues.

Side notes about deployment

Firewall configuration

If it happened you use firewalld on your machine you wish to install runner on you should open ports for nfs, ipp, rpc-bind and mountd. Otherwise Vagrant will not mount the shared volume.

If you're deploying freeipa-pr-ci on the FreeIPA infrastructure you don't need to care about firewalld as all of the security rules are managed by external firewall.

Runner deployment automation

By default, ansible will prompt for API token and other variables. To fully automate the deployment, you can pass the variables as arguments to the ansible-playbook command with -e key=value. Arguments might be seen in the following table. Availability of arguments is also mentioned in the table.

Key	Value	Production	Development
github_token	GitHub API token	x	x
monitored_repo_owner	FreeIPA repo owner		x
pr_ci_repo_owner	PR CI repo owner		x
pr_ci_repo_branch	PR CI repo branch		x

Monitoring runner activity

systemctl status prci
journalctl -fu prci

Autocleaning

By default, after deployment there is an autocleaner job scheduled to run every Sunday to clean unused Vagrant boxes, old libvirt images and optionally old jobs directories.

This feature can be disabled setting activate_autocleaner: false in the particular playbook.

Vagrant box hosting

PR-CI is capable of proxying and hosting boxes from Vagrant, speeding up the provisioning phase if the box is not in place.

For that you need to provision runners answering the question: "Custom vagrant catalog host (ip address) (Press enter to ignore)"

If you provide the IP address of prci-automation then all runners will set that to VAGRANT_SERVER_URL environment variable and Vagrant will fetch boxesq from that address.

Cache vagrant boxes

On prci-automation you can run the following script to download the boxes, making them available locally:

$ scripts/cache-vagrant-box.py {username} {boxname} {version}

E.g:

scripts/cache-vagrant-box.py freeipa ci-master-f31 0.0.1

User Guide

Re-running tasks

You can use the re-run label to:

• re-run failing tasks: once the label is added, the tasks with status error or failure will be mark as unassigned, and later they will be run.

• New tasks were added to config file in the target branch: If the config file was changed in the target branch, the re-run label will create the missing tasks and will run them.

Important: If you are running it against your fork, you'll need to create the label.

Creating vagrant template box

1. Make sure you've configured ~/.config/atlas_box_uploader.yaml to enable box upload to vagrantcloud.

   url: https://vagrantcloud.com
   username: freeipa
   token: $TOKEN

2. If you're creating a brand new box that has no previous versions, go to vagrantcloud.com and create the box manually. Follow the convention of freeipa/ci-$BRANCH_NAME-fXX. You also need to create a first version of the box, e.g. 0.1.0 (it doesn't need to be released or uploaded).

3. Make sure correct variables for Fedora version are configured in ansible/vars/fedora/.

4. Run create-template-box

   This will create a vagrant box in /tmp/$box_name/. It will also be published on vagrantcloud.

Developer Documentation

You can find the latest developer documentation in doc/README.md.