pest-bamboo

Puppet module for managing Atlassian Bamboo


Keywords
bamboo, atlassian
License
Apache-2.0
Install
puppet module install pest-bamboo --version 4.0.0

Documentation

puppet-bamboo

Puppet Forge

  1. Overview
  2. Prerequisites
  3. Usage
  4. Reference
  5. Limitations
  6. Development and Contributing
  7. Authors and Contributors

Overview

This is a Puppet module to manage the installation and initial configuration of Atlassian Bamboo, a continuous integration and build server.

  • Manages the download and installation of Bamboo
  • Manages some configuration settings, such as Tomcat ports, proxy configuration, Java options, and JVM tuning.
  • Manages a user, group, and home
  • Manages a service for Bamboo

There's still some post-installation steps that will need to be completed manually, such as entering a license and configuring the database.

This is a fork of maestrodev/bamboo, which appears to be dormant. It includes improvements from other authors as well, notably, Simon Croomes.

This module tries to follow conventions in the Confluence, Jira, and BitBucket modules

Prerequisites

Consult the Atlassian Bamboo documentation for specific system requirements for your platform and version. This module does not manage a Java installation.

NOTE: Since Bamboo 5.10, Atlassian no longer supports JDK < 8

Usage

Defaults

To have Puppet install Bamboo with the default parameters, declare the bamboo class:

class { 'bamboo': }

The bamboo class serves as a single "point of entry" for the module.

Examples

Customizations

class { 'bamboo':
  version      => '6.7.1',
  installdir   => '/opt/bamboo',
  homedir      => '/var/local/bamboo',
  user         => 'bamboo',
  java_home    => '/over/the/rainbow/java',
  download_url => 'https://mirrors.example.com/atlassian/bamboo',
  context_path => 'bamboo',
  umask        => '0022',
  proxy        => {
    scheme    => 'https',
    proxyName => 'bamboo.example.com',
    proxyPort => '443',
  },
}
Using Hiera
contain bamboo
bamboo::version: '6.7.1'
bamboo::checksum: '774ec0917cccc5b90b7be3df4d661620'
bamboo::installdir: '/opt/bamboo'
bamboo::jvm_xms: '512m'
bamboo::jvm_xmx: '1024m'
bamboo::proxy:
  scheme: 'https'
  proxyName: 'bamboo.intranet.org'
  proxyPort: '443'
bamboo::umask: '0022'
bamboo::download_url: 'https://repo.intranet.org/atlassian'
bamboo::java_home: '/etc/alternatives/java_sdk'

Context Path

Specifying a context_path for instances where Bamboo is being served from a path (e.g. example.com/bamboo)

class { 'bamboo':
  context_path => 'bamboo',
}

This configures the embedded Bamboo Tomcat instance with the context path.

Reverse Proxy

For instances where Bamboo is behind a reverse proxy

class { 'bamboo':
  proxy => {
    scheme    => 'https',
    proxyName => 'bamboo.example.com',
    proxyPort => '443',
  },
}

This configures the embedded Bamboo Tomcat instance's connector.

The proxy parameter accepts a hash of Tomcat options for configuring the connector's proxy settings. Refer to Tomcat's documentation for more information.

Installation locations

class { 'bamboo':
  installdir => '/opt/bamboo',
  homedir    => '/opt/local/bamboo',
}

JVM Tuning

class { 'bamboo':
  java_home    => '/usr/lib/java/custom',
  jvm_xms      => '512m',
  jvm_xmx      => '2048m',
  jvm_permgen  => '512m',
  jvm_opts     => '-Dcustomopt',
}

Tomcat Tuning

Bamboo's powered by an embedded Tomcat instance, which can be tweaked.

class { 'bamboo':
  tomcat_port        => '9090',
  max_threads        => '256',
  min_spare_threads  => '50',
  connection_timeout => '30000',
  accept_count       => '200',
}

Reference

Class: bamboo

Parameters

version

Default: '6.7.1'

The version of Bamboo to download and install. Should be in a MAJOR.MINOR.PATH format.

Refer to https://www.atlassian.com/software/bamboo/download

extension

Default: 'tar.gz'

The file extension of the remote archive. This is typically .tar.gz. Accepts .tar.gz or .zip

installdir

Default: '/usr/local/bamboo'

The base directory for extracting/installing Bamboo to. Note that it will decompress inside this directory to a directory such as atlassian-bamboo-6.7.1/ So an installdir of /usr/local/bamboo will ultimately install Bamboo to /usr/local/bamboo/atlassian-bamboo-6.7.1/ by default.

Refer to manage_installdir and appdir

manage_installdir

Default: true

Boolean. Whether this module should be responsible for managing the installdir

appdir

Default: ${installdir}/atlassian-bamboo-${version}

This is the directory that Bamboo gets extracted to within the 'installdir'

By default, this is a subdirectory with the specific version appended to it.

You might want to customize this if you don't want to use the default atlassian-bamboo-${version} convention.

manage_appdir

Default: true

Boolean. Whether this module should be responsible for managing the appdir

homedir

Default: '/var/local/bamboo'

The home directory for the Bamboo user. This path will be managed by this module, even if manage_user is false.

context_path

Default: '' (empty)

For instances where Bamboo is being served from a sub path, such as example.com/bamboo, where the context_path would be bamboo

tomcat_port

Default: '8085'

The HTTP port for serving Bamboo.

max_threads

Default: '150'

Maps to Tomcat's maxThreads HTTP attribute.

Refer to https://tomcat.apache.org/tomcat-7.0-doc/config/http.html for more information.

min_spare_threads

Default: '25'

Maps to Tomcat's minSpareThreads HTTP attribute.

Refer to https://tomcat.apache.org/tomcat-7.0-doc/config/http.html for more information.

connection_timeout

Default: '20000'

Maps to Tomcat's connectionTimeout HTTP attribute.

Refer to https://tomcat.apache.org/tomcat-7.0-doc/config/http.html for more information.

accept_count

Default: '100'

Maps to Tomcat's acceptCount HTTP attribute.

Refer to https://tomcat.apache.org/tomcat-7.0-doc/config/http.html for more information.

proxy

Default: {}

Bamboo's proxy configuration for instances where Bamboo's being served with a reverse proxy in front of it (e.g. Apache or Nginx).

manage_user

Default: true

Specifies whether the module should manage the user or not.

manage_group

Default: true

Specifies whether the module should manage the group or not.

user

Default: 'bamboo'

Bamboo's installation will be owned by this user and the service will run as this user.

group

Default: 'bamboo'

Bamboo's installation will be owned by this group.

uid

Default: undef

Optionally specify a UID for the user.

gid

Default: undef

Optionally specify a GID for the group.

password

Default: '*'

Specify a password for the user.

shell

Default: '/bin/bash'

Specify a shell for the user.

java_home

Default: '/usr/lib/jvm/java'

Absolute path to the Java installation.

jvm_xms

Default: '256m'

Amount of memory the JVM will be started with.

jvm_xmx

Default: '1024m'

Maximum amount of memory the JVM has available.

You may need to increase this if you see java.lang.OutOfMemoryError

jvm_permgen

Default: '256m'

Size of the permanent generation heap. Unlikely that you need to tune this.

jvm_opts

Default: ''

Any custom options to start the JVM with.

jvm_optional

Default: ''

From Bamboo's default setenv.sh:

Occasionally Atlassian Support may recommend that you set some specific JVM
arguments.  You can use this variable below to do that.
download_url

Default: 'https://www.atlassian.com/software/bamboo/downloads/binary'

The base url to download Bamboo from. This should be the URL up to the actual filename. The default downloads from Atlassian's site.

proxy_server

Default: undef

Specify a proxy server to use on the archive resource for downloading Bamboo, with port number if needed. (e.g. https://example.com:8080)

proxy_server_type

Default: undef

Proxy server type (none|http|https|ftp) to use on the archive resource for downloading Bamboo.

manage_service

Default: true

Whether this module should manage the service.

service_ensure

Default: 'running'

The state of the service, if managed.

service_enable

Default: true

Whether the service should start on boot.

service_file

Default: OS-specific (refer to manifests/params.pp)

Path to the init script or service file (systemd).

service_template

Default: $bamboo::params::service_template

Template for the init script/service definition. The module includes an init script and systemd service configuration, but you can use your own if you'd like. This should refer to a Puppet module template. E.g. modulename/bamboo.init.erb

shutdown_wait

Default: 20

Seconds to wait for the Bamboo process to stop. (e.g. service bamboo stop will wait this interval before attempting to kill the process and returning).

facts_ensure

Default: 'present'

Valid values are 'present' or 'absent'

Will provide an external fact called bamboo_version with the installed Bamboo version.

facter_dir

Default: See bamboo::params

Absolute path to the external facts directory. Refer to https://docs.puppet.com/facter/latest/custom_facts.html#external-facts

create_facter_dir

Default: true

Boolean

Whether this module should ensure the "facts.d" directory for external facts is created. This module uses an Exec resource to do that recursively if this is true.

stop_command

Default: service bamboo stop && sleep 15

The command to execute prior to upgrading. This should stop any running Bamboo instance. This is executed after downloading the specified version and before extracting it to install it.

This requires the bamboo_version fact.

initconfig_manage

Default: false

Specifies whether the initconfig file should be managed by this module.

initconfig_path

Default: $::osfamily specific - see bamboo::params

Absolute path to the init config file (sysconfig, defaults). This file is sourced by the init script if it exists. Defaults to /etc/sysconfig/bamboo on Red Hat family systems. Defaults to /etc/default/bamboo on Debian family systems.

initconfig_content

Default: '' (empty)

If initconfig_manage => true, this string should be the content to populate the init config file with.

umask

Default: undef (will use Bamboo's default)

Specifies a UMASK to run Bamboo with.

checksum

Download archive file checksum.

checksum_type

Type of checksum for the archive file download.

Specifies the checksum_type parameter on the puppet/archive resource.

Valid options: (none|md5|sha1|sha2|sha256|sha384|sha512)

Default: md5

Other Classes

The following classes are called from the base class. You shouldn't need to declare these directly.

Limitations

Tested Platforms

  • EL 6
  • EL 7
  • Debian 8
  • Debian 9
  • Ubuntu 14.04
  • Ubuntu 16.04
  • Ubuntu 18.04
  • Puppet 4.x
  • Puppet 5.x
  • Puppet 6.x

Bamboo Configuration

This module does not manage the initial set up of Bamboo - the steps that are done via the web interface once installed and running. This doesn't appear to be easily managed automatically. This includes database configuration and the license. Ultimately, this configuration is placed in ${homedir}/bamboo-cfg.xml. Contributions are welcome to help manage this.

Development and Contributing

Please submit a ticket for any issues, bug fixes, questions, and feature requests.

Pull requests with passing tests and updated tests are appreciated. Please add yourself to the CONTRIBUTORS file and update the README for documentation if appropriate.

Travis CI is used for testing.

How to test the Bamboo module

Install the dependencies:

bundle install

To see what's available:

bundle exec rake -T

Syntax validation, lint, and spec tests:

bundle exec rake validate

Unit tests:

bundle exec rake parallel_spec

Syntax validation:

bundle exec rake validate

Puppet Lint:

bundle exec rake lint

Acceptance tests (beaker):

# By default, this will test against CentOS 7 in a Docker container
bundle exec rake beaker:default

Other Beaker tests:

# Test against centos-6 using Docker
PUPPET_INSTALL_TYPE=agent \
BEAKER_debug=true \
BEAKER_PUPPET_COLLECTION=puppet6 \
BEAKER_TESTMODE=apply \
BEAKER_set=docker/centos-6 \
bundle exec rake beaker

# Test against centos-7 using Docker
PUPPET_INSTALL_TYPE=agent \
BEAKER_debug=true \
BEAKER_PUPPET_COLLECTION=puppet6 \
BEAKER_TESTMODE=apply \
BEAKER_set=docker/centos-7 \
bundle exec rake beaker

# Test against debian-8 using Docker
PUPPET_INSTALL_TYPE=agent \
BEAKER_debug=true \
BEAKER_PUPPET_COLLECTION=puppet6 \
BEAKER_TESTMODE=apply \
BEAKER_set=docker/debian-8 \
bundle exec rake beaker

# Test against debian-9 using Docker
PUPPET_INSTALL_TYPE=agent \
BEAKER_debug=true \
BEAKER_PUPPET_COLLECTION=puppet6 \
BEAKER_TESTMODE=apply \
BEAKER_set=docker/debian-9 \
bundle exec rake beaker

# Test against ubuntu-14.04 using Docker
PUPPET_INSTALL_TYPE=agent \
BEAKER_debug=true \
BEAKER_PUPPET_COLLECTION=puppet6 \
BEAKER_TESTMODE=apply \
BEAKER_set=docker/ubuntu-14.04 \
bundle exec rake beaker

# Test against ubuntu-16.04 using Docker
PUPPET_INSTALL_TYPE=agent \
BEAKER_debug=true \
BEAKER_PUPPET_COLLECTION=puppet6 \
BEAKER_TESTMODE=apply \
BEAKER_set=docker/ubuntu-16.04 \
bundle exec rake beaker

# Test against ubuntu-18.04 using Docker
PUPPET_INSTALL_TYPE=agent \
BEAKER_debug=true \
BEAKER_PUPPET_COLLECTION=puppet6 \
BEAKER_TESTMODE=apply \
BEAKER_set=docker/ubuntu-18.04 \
bundle exec rake beaker

You can set the BAMBOO_DOWNLOAD_URL and BAMBOO_VERSION environment variables for setting the corresponding ::bamboo class parameters for the beaker tests.

Authors and Contributors