Gerrit Module

Table of Contents

1. Overview
2. Module Description - What the module does and why it is useful
3. Setup - The basics of getting started with gerrit
   • What gerrit affects
   • Setup requirements
4. Usage - Configuration options and additional functionality
5. Reference - An under-the-hood peek at what the module is doing and how
6. Limitations - OS compatibility, etc.
7. Development - Guide for contributing to the module

Overview

This module installs and configures a Gerrit system. It is intended to work with Puppet >= v3.7 as that is what it is developed against.

Module Description

The Gerrit module provides an easy way of standing up a Gerrit server, an open source web based code review system.

The optional MySQL integration works with the puppetlabs-mysql module to export a database configuration for automatic pick-up and creation of the database. The module does not presently probe to see if the database has been created as this is not a feature of the puppetlabs-mysql module like it is in the puppetlabs-postgresql module. As such, if the exported DB has not been picked up yet this module will fail to initialize Gerrit until the database is available.

The module may optionally modify the firewall for the web and ssh services.

You may optionally manage your Gerrit site Header, Footer and CSS as well as the static resources.

You may optionally install and configure the plugins that ship with Gerrit. The default is to install the full list of plugins that v2.9.3 shipped. One of these plugins (replication) requires a separate config file, no default configuration file is created so the plugin will load and then do nothing until a configuration file is managed in and the plugin is either restarted or the Gerrit service is restarted.

Setup

What gerrit affects

• The gerrit service will be installed and managed
• May optionally install java (NOTE: java is required for Gerrit to work)
• May optionally install git (NOTE: git is required for Gerrit to work)
• Gerrit site Header, Footer and CSS may be optionally managed. If they are not managed then dummy files will be put in place (also optional) so that adding managed files later will not require a restart.
• May optionally install gitweb
• May optionally manage the firewall rules for access to Gerrit resources
• May optionally handle setting up the database (potential cross-system dependencies)
• May optionally acquire and install 3rd party plugins

Setup Requirements

• puppetlabs/git is required for the optional git installation. If you wish to manage git via a different module / method make sure to set $manage_git to false
• puppetlabs/java >= v1.2.0 is required for the optional java installation. If you wish to use manage java via a different module / method make sure to set $manage_java to false
• puppetlabs/mysql >= 3.0.0 is required for the optional MySQL management as well as having store configs enabled.
• puppetlabs/firewall >= 1.2.0 is required for the optional firewall management
• maestrodev/wget >= 1.5.7 is required for optional 3rd party plugin installation if a http or https url is provided for the plugin source

Usage

This module is designed to do automatic hiera lookups a fairly common setup might look like the following. A note about the database password, if you feel uncomfortable about having your passwords in the clear in your hiera, it is recommendend that you look into hiera-eyaml and hiera-eyaml-gpg

---

# The DB tag that will be used to pickup our MySQL export
gerrit::db_tag: 'myenv-db'

# Use a version newer than the default of 2.9.3
gerrit::version: '2.11'

# Manage a replication.config
gerrit::extra_configs:
  replication_config:
    config_file: '/opt/gerrit/etc/replication.config'
    mode: '0644'
    options:
      'remote.github':
        url: 'git@github.com:exampleco/${name}.git'
        push:
          - '+refs/heads/*:refs/heads/*'
          - '+refs/tags/*:refs/tags/*'
        timeout: '5'
        threads: '5'
        authGroup: 'GitHub Replication'
        remoteNameStyle: 'dash'

# Manage the gerrit system itself
gerrit::override_options:
  auth:
    type: 'OPENID'
  cache:
    directory: 'cache'
  database:
    type: 'MYSQL'
    hostname: 'mysql.exampleco.com'
    database: 'gerrit'
    username: 'gerrit'
  gerrit:
    basePath: '/srv/gerrit'
    canonicalWebUrl: 'https://gerrit.exampleco.com/r'
  gitweb:
    cgi: '/var/www/git/gitweb.cgi'
  httpd:
    listenUrl: 'proxy-https://*:8080/r'
  sendemail:
    smtpServer: 'localhost'
    from: 'ExampleCo Code Review <gerrit@exampleco.com>'
  sshd:
    listenAddress: '*:29418'
  user:
    email: 'gerrit@exampleco.com'
  commentlink.bugzilla:
    match: '([Bb][Uu][Gg]\\s*[:-]?\\s*)(\\d+)'
    link: 'https://bugs.exampleco.com/show_bug.cgi?id=$2'

gerrit::override_secure_options:
  database:
    password: 'My$up3r@wes0mePASSw0rd'

include ::gerrit

Reference

db_tag

The tag to be used by exported database resource records so that a collecting system may easily pick up the database resource

download_location

Base location for downloading the Gerrit war from. Defaults to the official Gerrit download location

extra_configs

A hash that is used to add additional configuration files to the Gerrit system. The hash is a hash of hashes where the top level keys are the resource identifier for a configuration file and each config_file option is the fully qualified filename that should be written out.

The hash is formatted as follows:

extra_configs               => {
  configID1                 => {
    config_file             => 'fully_qualified_file_name',
    mode                    => '0644',
    options                 => {
      'section1'            => {
        'option1'           => 'basic string option',
        'option2'           => [
          'option2 array entry 1',
          'option2 array entry 2'
        ],
      },
      'section2.subsection' => {
        'option3' => 'option 3 in [section2 "subsection"]'
      },
    },
  },
  configID2                 => {
    config_file             => 'another_fully_qualified_file_name',
    mode                    => '0644',
    options                 => {
      'section1'            => {
        'option1'           => 'one more option string',
      },
    }
  }
}

This is most useful when managing the replication.config file for the replication plugin a hiera config would look something like this:

gerrit::extra_configs:
  replication_config:
    config_file: '/opt/gerrit/etc/replication.config'
    mode: '0644'
    options:
      'remote.github':
        url: 'git@github.com:exampleco/${name}.git'
        push:
          - '+refs/heads/*:refs/heads/*'
          - '+refs/tags/*:refs/tags/*'
        timeout: '5'
        threads: '5'
        authGroup: 'GitHub Replication'
        remoteNameStyle: 'dash'

gerrit_group

The primary group of the gerrit user. Default value: gerrit

gerrit_home

The home directory for the gerrit user / installation path. Default value: /opt/gerrit

gerrit_site_options

Override options for installation of the 3 Gerrit site files. The format of this option hash is as follows:

gerrit_site_options       => {
  'GerritSite.css'        => 'a valid file resource source',
  'GerritSiteHeader.html' => 'a valid file resource source',
  'GerritSiteFooter.html' => 'a valid file resource source',
}

If an option is not present then the default "blank" file will be used.

This hash is only used if manage_site_skin is true (default)

gerrit_user

The user that Gerrit runs as. Default gerrit

gerrit_version

The version of the Gerrit war that will be downloaded. Default 2.9.3

gitweb_package_name

The name of the package to install for gitweb should install_gitweb be true. Defaults to gitweb

install_default_plugins

Should the default plugins be installed? If true (default) then use the plugin_list array to specify which plugins specifically should be installed.

install_git

Should this module make sure that git is installed? (NOTE: a git installation is required for Gerrit to be able to operate. If this is true (default) then a module named ::git will be included. puppetlabs/git is the expected module but any module that can be blindly included and use APL to configure it that matches on the include will work.)

install_gitweb

Should this module make sure that gitweb is installed? (NOTE: This will use the system package manager to install gitweb but will do no extra configuration as it will be expected to be managed via gerrit)

install_java

Should this module make sure that a JRE is installed? (NOTE: a JRE installation is required for Gerrit to operate. If this is true (default) then a module named ::java will be included. puppetlabs/java is the expected module but any module that can be blindly included and use APL to configure it that matches on the include will work.)

manage_database

Should the database be managed. The default option of true means that if a MySQL or PostgresQL database is detected in the options then resources will be exporte via the puppetlabs/{mysql/postgresql} module API. A db_tag (see above) needs to be set as well so that a system picking up the resource can acquire the appropriate exported resources.

NOTE: PostgreSQL resource exports do not presently work.

manage_firewall

Should the module insert firewall rules for the webUI and SSH? Default setting: true

NOTE: This requires a module compatible with the puppetlabs/firewall API

manage_site_skin

Should the Gerrit site theming be managed by the module? If true (default) then passing an options hash to gerrit_site_options (see above) will override the default "blank" skin files that get pushed.

manage_static_site

Should the ~gerrit/static structure be managed by the module? Default setting: false

If true then static_source (see below) is required.

manage_user

Should this module create the gerrit_user and gerrit_group (true) or will they be managed elsewhere (false)? Default setting: true

override_options

A variable hash for configuration settings of Gerrit. These options are mreged into the default option define and then written to ~gerrit/etc/gerrit.config. The default Gerrit options are as follows:

default_options => {
  'auth'        => {
    'type'      => 'OpenID',
  },
  'container'   => {
    'javaHome'  => '/usr/lib/jvm/jre',
  },
  'gerrit'      => {
    'basePath'  => '/srv/gerrit',
  },
  'index'       => {
    'type'      => 'LUCENE',
  },
}

override_secure_options

Similar to override_options, this hash is used for setting the options in the ~gerrit/etc/secure.config file. The defult secure options are as follows:

default_secure_options        => {
  'auth'                      => {
    'registerEmailPrivateKey' => 'GENERATE',
    'restTokenPrivateKey'     => 'GENERATE',
  },
}

The special GENERATE keywords will be replaced by host fqdn stable random strings. The option is only valid on the two default keys and will not operate on any other keys passed in. This is done to mimic a manual installation as those strings are generated normally for you.

They may, of course, be overriden by this override hash.

plugin_list

An array specifying the default plugins that should be installed. The names are specified without the .jar. The current plugins auto-installed are the ones that ship with v2.9.3 the list is as follows:

plugin_list => [
  'commit-message-length-validator',
  'download-commands',
  'replication',
  'reviewnotes'
]

refresh_service

Should the gerrit service be refreshed on modifications to either the gerrit.config or sercure.config? Default: true

service_enabled

Determines the mode that the service is configured for:

true: (default) service is ensured started and enabled for reboot

false: service is ensured stopped and disabled for reboot

manual: service is configured as a manual service, refreshes will behave per normal when a service is configured with enable => manual. The service is not specified specifically started or stopped.

static_source

A File resource source that will be recursively pushed if manage_static_site is set to true. All files in the source will be pushed to the ~gerrit/site.

third_party_plugins

A hash declaring all the third party plugins that should be installed. The sources may be file, puppet or http(s) sources.

If http or https resources are defined thanmaestrodev/wget is needed for fetching the resources.

The hash looks like the following:

third_party_plugins => {
  'delete-project'  => {
    plugin_source   =>
    'https://gerrit-ci.gerritforge.com/view/Plugins-stable-2.11/job/plugin-delete-project-stable-2.11/lastSuccessfulBuild/artifact/buck-out/gen/plugins/delete-project/delete-project.jar',
  },
}

Limitations

Tested against RedHat / CentOS v7

##2016-0611 - v1.1.1 - Fix java max heap parameter

• Java heap parameter Xmx should not have a trailing = before the value

##2016-05-25 - v1.1.0 - Java Tuning

• Allow tuning of Java on systemd based systems (F21+ and EL7+) this was not initially supported. This will utilize the same options as the SysV init script for setting the heapLimit or other generic Java options.

##2016-03-16 - v1.0.0 - Roll up and bump to 1.0.0

• Breaking change! Puppet 4 is now required for the module.

• User and group managemnt is now optional - Bob Vincent

• Firewall rules now optionally support source address requirements - Jordan Evans

• Changes to support source address clamping are utilizing Puppet 4+ features to build out the proper firewall rule definition. As the syntax being introduced does not exist before Puppet 4 (or in puppet 3 with future_parser enabled) the supported Puppet version has been bumped to >= 4

• Make gitweb package configurable in support of folks installing packages that are not in the upstream repos (say for instance IUS) - Andrew Grimberg

##2015-12-03 - v0.9.4 - Silence wget::fetch notices

• Third party plugins were being downloaded into a cache directory which causes the wget exec to emit a notice on every puppet run. This notice does not occur if the download is happening in place (provided that the file isn't changing). This update fixes it so that the downloads happen in place, but only if needed.

• v0.9.3 introduced a cache directory as $gerrit_home/plugin_cache. Since this is no longer needed it is now being purged should it exist on disk. This purge will be removed with v1.0.0

##2015-12-02 - v0.9.3 - Add ability to deploy 3rd party plugins

• Make it possible to specify 3rd party plugins to install. Caveat on the plugins being raw jar files available on the system already (via a file source) in a puppet fileserver or available via HTTP(S). Configuration management for 3rd party config files already exists we just didn't have a way to manage deploying them.

##2015-10-30 - v0.9.2 - Fix up init scripts

• Make systemd based RH systems use a systemd init instead of the init.d script that ships with gerrit. This fixes issues with puppet constantly trying to ensure that the service is enabled on every run

##2015-10-30 - v0.9.1 - Update to fix firewall port usage

• Start using dport instead of the less specific port option in the firewall rules.

##2015-06-09 - Update to documentation and release ###Summary

• Update the docs to resolve Issue #6

• Release update metadata for release to version 0.9.0 it would be v1.0.0 if the postgresql exporting was working as the other issues currently logged are nice to haves and not requirements.

##2015-06-08 - Plugin management and extra config files ###Summary

• Resolve Issue #2, we can now install all or some of the shipped plugins (the all option is the list of plugins that shipped with v2.9.3 of Gerrit)

• Resolve Issue #11 as at least one of the shipped plugins needed to have a configuration file separate from the base gerrit and secure configuration files. It is now possible to manage any number of extra configuration. Removal of the files is not presently support, just the creation and managemnt of the file contents. These files do not cause a refresh of the Gerrit service.

##2015-06-04 - Support refresh of service on change to config files ###Summary

• Resolve Issue #10 where the gerrit service was not being refreshed when gerrit.config or secure.config were changed

##2015-06-03 - Support static site content push ###Summary

• Start supporting pushing of content to ~gerrit/static which is useful for any custom headers / footers that may be already pushed

##2015-05-28 - Refactor of code ###Summary

• Refactor to make clean up the rspec tests and make them work with latest version of rpsec

• Switch from built in fqdn_token_string_spec to puppetlabs/stdlib (>= v4.6.0) fqdn_rand_string function instead which is hopefully safer than what was locally created

##2015-01-07 - initial release of 0.1.0