[ros-users] [Discourse.ros.org] [Buildfarm] Changes to buildfarm_deployment for Jenkins JEP-200

Steven! Ragnarök ros.discourse at gmail.com
Fri Nov 30 14:48:52 UTC 2018

For the past several months, the example [buildfarm_deployment_config] has included a pinned Jenkins version to prevent using versions that comply with [JEP-200](https://github.com/jenkinsci/jep/tree/master/jep/200) from being used due to issues with the ros_buildfarm scripts and the plugin versions they use. (First reported by @gavanderhoorn in https://github.com/ros-infrastructure/buildfarm_deployment/issues/193)

I've been working on upgrading the buildfarm deployment and ros_buildfarm scripts to work on post-JEP-200 deployments and am happy to report that we're now using the latest Jenkins LTS on both build.ros.org and build.ros2.org\.

That work is being prepared for merging across three pull requests:

* https://github.com/ros-infrastructure/buildfarm_deployment/pull/207

* https://github.com/ros-infrastructure/buildfarm_deployment_config/pull/37

* https://github.com/ros-infrastructure/ros_buildfarm/pull/587

To allow time for community members using the master branch of buildfarm_deployment to make the transition we won't be merging these changes right away. The important dates are here:

* 2018-12-17 buildfarm_deployment `master` branch will require Jenkins >= 2.138.3 and updated plugins.

* 2019-01-17 buildfarm_deployment transitional branch `jenkins-lts-upgrade` will be removed from [buildfarm_deployment].

For those who aren't able to schedule the upgrade before 2018-12-17, the [pre-jep-200](https://github.com/ros-infrastructure/buildfarm_deployment/tree/pre-jep-200) branch is a snapshot of the current master which won't be receiving further updates and moving your existing deployments to this branch will keep you in the current state as long as you need.

[buildfarm_deployment]: https://github.com/ros-infrastructure/buildfarm_deployment

[buildfarm_deployment_config]: https://github.com/ros-infrastructure/buildfarm_deployment_config

[ros_builfdarm]: https://github.com/ros-infrastructure/ros_buildfarm

Additionally, I've written the guide below based on my experiences updated build.ros.org and build.ros2.org with review and testing from some intrepid community members. I've done my best to communicate everything I encountered during the upgrade process but I can't make any guarantees that the guide below will cover every contingency. If you do run into trouble feel free to [open an issue](https://github.com/ros-infrastructure/buildfarm_deployment/issues) or ask a question with the [buildfarm_deployment](https://answers.ros.org/questions/scope:all/sort:activity-desc/tags:buildfarm_deployment/) tag on https://answers.ros.org

# ROS Buildfarm Deployment JEP-200 Upgrade Guide

The last LTS version prior to JEP-200 was 2.89.4 which has been the pinned version for new deployments since https://github.com/ros-infrastructure/buildfarm_deployment_config/pull/31.

The current Jenkins LTS as of this writing is 2.138.3.

## Overview

Due to the way the buildfarm_deployment is put together, it is not recommended to re-run puppet or the reconfigure.bash script on the Jenkins master after initial configuration (see [#160](https://github.com/ros-infrastructure/buildfarm_deployment/issues/160)).

Buildfarm deployments wishing to update existing deployments will need to take manual steps on their jenkins hosts to migrate successfully to the latest version of ros_buildfarm (forthcoming).

## Notable changes

#### User-facing changes:

Aside from some minor changes to the Jenkins sign in page and other visual updates, most users of ROS Buildfarm deployments will not notice any significant differences.

The minor issue [#166](https://github.com/ros-infrastructure/buildfarm_deployment/issues/166) has been resolved with updates to the GitHub API and GitHub Pull Request Builder plugins.

Users with Jenkins API tokens may need to recreate them after coordinating operators.

#### Operator-facing changes

[JEP-200](https://jenkins.io/blog/2018/01/13/jep-200/) mandated that a large number of plugins used by the buildfarm be updated,

so I took the opportunity to update all of them and test comprehensively rather than trying to work out only those updates that are necessary.

Jenkins upstream recommendeds revoking existing "Legacy" API tokens and replacing them with the new token system.

Legacy tokens are not revoked on upgrade and there's a dedicated UI for reviewing and revoking tokens as you have the opportunity to reprovision them. See https://jenkins.io/blog/2018/07/02/new-api-token-system/ for details.

ROS Buildfarm aspects which can make use of API tokens:

- Swarm agent client authentication  

  If your organization's clone of the buildfarm_deployment_config repository uses GitHub for authentication, switching to use of Jenkins API tokens from GitHub API tokens will reduce the number of GitHub API calls necessary to manage authentication to your buildfarm deployment.

  The token can be used for [this config value](https://github.com/ros-infrastructure/buildfarm_deployment_config/blob/9a9cff7a05b93fe3f4bdd93702030bb38a927ea1/hiera/hieradata/common.yaml#L6).

- ~/.buildfarm/jenkins.ini may contain a Jenkins token rather than a password  

  Especially if your buildfarm deployment uses GitHub for authentication it's recommended that operators create and use Jenkins API tokens rather than GitHub API tokens for authenticating to your buildfarm when running ros_buildfarm scripts.

  The GitHub API tokens will require your buildfarm to authenticate the token with GitHub on each request, which can exhaust your Jenkins instance's API rate limit for large deployments.

  Using a Jenkins API token to avoid a GitHub API request for each authentication is also anecdotally faster, resulting in faster reconfigurations. 

## Actions Required

### Before you start

 ___Make backups and test them!___ 

Unless you've made a reliable backup before you start I cannot recommend proceeding with this guide.

Backups aren't real until you've validated the restore procedure.

__Review this guide in full.__

This guide was written after upgrading build.ros2.org revised after upgrading build.ros.org and should be used as a starting point.

There may be other necessary actions for your setup that this guide does not capture.

__System requirements:__ These upgrades are only recommended if you're running a relatively recent Ubuntu 16.04 based buildfarm that was set up after the buildfarm_deployment migration to xenial or has undergone the procedure described in https://discourse.ros.org/t/ros-buildfarm-october-2017-guide-to-new-changes/2840

### Updating buildfarm_deployment_config

Your buildfarm deployment config is likely a duplicate of the `master` branch from https://github.com/ros-infrastructure/buildfarm_deployment_config. This repository, like https://github.com/ros-infrastructure/buildfarm_deployment, has a master branch which roughly tracks the production deployments build.ros.org and build.ros2.org and updates to the buildfarm_deployment puppet logic may not be compatible with your existing configuration.

Some changes to deployment behavior are also implemented directly via configuration directive.

To review your buildfarm_deployment_config against the changes made since, I'd suggest creating a local clone and using git-diff to compare the state of your config against the upstream one.

##### Upstream configuration url

Before merge of https://github.com/ros-infrastructure/

### Updating Jenkins

1. Put jenkins into shutdown mode and let any outstanding jobs complete.

2. Take jenkins offline with `systemctl stop jenkins`. If there are many jobs queued, Jenkins may take a while to shut down. Waiting until the jenkins java process stops is recommended.

3. Stop jenkins agent on master with `systemctl stop jenkins-slave`

4. (Optional) Run `apt-get update && apt-get upgrade`. Review the list of upgraded packages

5. Remove any holds placed on jenkins and run `apt-get update && apt-get install jenkins`.

6. If prompted to update the `/etc/default/jenkins` file, you may either reject the changes (what I did) or review them to be integrated with your setup.

7. Install updated plugins. I'v prepared [a script](https://gist.github.com/nuclearsandwich/cfc272e7efd82384accd0cf595656dea#file-02-download-jenkins-plugins-bash) which will use bash and curl to install plugins by dropping them in the correct location. You could also modify this script to use the jenkins-cli.jar, or just use it as a list of plugin updates to perform with an online jenkins instance although I experienced filesystem permissions issues when doing so and the resulting state left my Jenkins un-bootable. However, if you check filesystem permissions beforehand to make sure all plugins are owned by `jenkins` rather than `root` it may work for you.

8. Remove any .pinned files from your jenkins plugin directory `rm /var/lib/jenkins/plugins/*.pinned`. You may save the list of pinned files if you wish to restore them later.

9. Start jenkins, watch the logs for any issues failing to initialize plugins

10. From the Jenkins UI, review any administrator warnings.

11. (Optional, but recommended) Disable JNLPv2 and JNLPv3 on the Jenkins Global Security Configuration screen.

12. Sign into Jenkins as the user your agent hosts authenticate as and generate an API token for use as the `Buildfarm Swarm Agent` copy this token into your buildfarm_deployment_config as the `jenkins::slave::ui_pass` value.

13. SSH Credentials can no longer be read from a file on disk due to [this vulnerability](https://jenkins.io/security/advisory/2018-06-25/#SECURITY-440). Credentials using the key from disk get migrated to "Directly entered" keys without the key being read from disk. Very early or modified deployments of the buildfarm may have been using an ssh key read from a file. This can be fixed with the following steps

  - Copy the text of your ssh key from the buildfarm_deployment_config master.yaml field `jenkins::private_ssh_key`. Take care to trip the leading whitespace if you copy it from the YAML block text format.

  - Open the Credentials UI and select the global credential matching your ssh username (jenkins-agent by default). Select "Update"

  - Paste the ssh key text into the text area and select "Save". No other field should need to be changed.

14. Reconfigure Jenkins using a compatible branch of ros_buildfarm.

As of 2018-11-16 the Jenkins LTS work for ros_buildfarm is not yet merged into master or released. The pull request https://github.com/ros-infrastructure/ros_buildfarm/pull/587 has a branch with some workarounds for plugin issues and template updates for plugin versions in configuration structures.

15. Update the Script Approval whitelist. If you have a highly customized ROS buildfarm deployment your scriptApproval.xml whitelist of allowed scripts and Groovy signatures might have diverged. To proceed you have three options:  

  A. Let jobs fail due to sandbox violations and whitelist them as needed.  

  B. Manually apply [the additions](https://github.com/ros-infrastructure/buildfarm_deployment/pull/207/files#diff-ff43ec85b9b332437c9ad8f86c2cf7d1) to the scriptApproval.xml file in buildfarm_deployment to your deployment's `/var/lib/jenkins/scriptApproval.xml` and restart Jenkins.  

  C. Copy the [scriptApproval.xml](https://github.com/ros-infrastructure/buildfarm_deployment/blob/56b4a196a3aa064f6472fb506996c0b597f95a2c/modules/jenkins_files/files/var/lib/jenkins/scriptApproval.xml) file to your instance replacing your existing `/var/lib/jenkins/scriptApproval.xml` and restart Jenkins.

### Updating Agent on Master

1. Download the swarm client jar version 3.14 from [this link](https://repo.jenkins-ci.org/releases/org/jenkins-ci/plugins/swarm-client/3.14/swarm-client-3.14.jar) and place it in `/home/jenkins-agent` on the master host. Make sure it's owned by the jenkins-agent user.

2. Open `/etc/default/jenkins-slave` and make the following changes:

  - Update the line for `JENKINS_SLAVE_JAR` to `JENKINS_SLAVE_JAR="${JENKINS_SLAVE_HOME}/swarm-client-3.14.jar"`

  - Update the line for `JENKINS_PASSWORD` to match the API token used for step 12 when updating the Jenkins master.

3. Remove the old swarm client jar `rm /home/jenkins-agent/swarm-client-2.0-jar-with-dependencies.jar`

4. Start the Jenkins agent `systemctl start jenkins-slave` and verify that it is able to connect to your master host.

### Updating Repo and Agent hosts

1. Pull the latest version of your buildfarm_deployment_config and run `./reconfigure.bash` from the repository root.

2. Verify that both the `building_repository-*` and `agent-*` nodes have successfully reconnected.


If you follow this guide, please report back your successes or any problems you encounter.


[Visit Topic](https://discourse.ros.org/t/changes-to-buildfarm-deployment-for-jenkins-jep-200/7014/1) or reply to this email to respond.

More information about the ros-users mailing list