Forge Home

Modules

Resources

PuppetEcosystemPuppet CommunityUpdates

galera

Setup a Galera cluster on MySQL/MariaDB/XtraDB with Arbitrator support
Project URLRSS FeedReport issues

818,834 downloads

1,254 latest version

5.0 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 3.0.1 (latest)
  • 3.0.0
  • 2.2.0
  • 2.1.0
  • 2.0.0
  • 1.0.6
  • 1.0.5
  • 1.0.4
  • 1.0.3
  • 1.0.2
  • 1.0.1
  • 1.0.0
  • 0.7.2
  • 0.7.1
  • 0.7.0
  • 0.6.0
released Aug 17th 2022
This version is compatible with:
  • Puppet Enterprise 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x, 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x
  • Puppet >= 6.0.0 < 8.0.0
  • , , , , ,
This module has been deprecated by its author since Jul 11th 2023.

The reason given was: new maintainer

The author has suggested markt-galera as its replacement.

Start using this module

Tags: mysql, database, cluster, percona, mariadb, galera, xtradb, garbd, codership, wsrep, arbitrator

Documentation

fraenki/galera — version 3.0.1 Aug 17th 2022

puppet-galera

Build Status Puppet Forge Puppet Forge - downloads

NOTE: The "master" branch on GitHub contains the development version, which may break anything at any time. Consider using one of the official releases instead.

Table of Contents

  1. Overview
  2. Requirements
  3. Usage
  4. OS and Cluster Compatibility
  5. Reference
  6. Limitations
  7. Development

Overview

This module will massage puppetlabs-mysql into creating a Galera cluster on MySQL, MariaDB or XtraDB. It also supports setting up an Arbitrator node.

It will try to recover from failures by bootstrapping on a node designated as the master if no other nodes appear to be running mysql, but if the cluster goes down and the master is permanently taken out, another node will need to be specified as the 'master' that can bootstrap the cluster.

Requirements

Usage

Basic usage

Basic usage requires only the FQDN of the master node, a list of IP addresses of other nodes and two passwords:

class { 'galera':
  cluster_name    => 'mycluster',
  galera_servers  => ['10.0.99.101', '10.0.99.102', '10.0.99.103'],
  galera_master   => 'node1.example.com',
  root_password   => 'pa$$w0rd',
  status_password => 'pa$$w0rd',
}

This will install the default packages and version. However, in a production environment you should definitely set the vendor and version variables to the desired value, because the default values might change:

class { 'galera':
  vendor_type    => 'percona',
  vendor_version => '8.0',
  ...

On Debian/Ubuntu systems the user debian-sys-maint@localhost is required for updates and will be created automatically, but you should set a proper password when using these platforms:

class { 'galera':
  deb_sysmaint_password => 'secretpassword',
  ...

WSREP provider options

Note that the module will automatically add the required Galera/WSREP provider options to the server configuration. Currently the following parameters are automatically added: wsrep_cluster_address, wsrep_cluster_name, wsrep_node_address, wsrep_node_incoming_address, wsrep_on, wsrep_provider, wsrep_slave_threads, wsrep_sst_method, wsrep_sst_auth, wsrep_sst_receive_address.

Some of these values are used directly from their respective class parameter. For example, to change the SST method:

class { 'galera':
  wsrep_sst_method => 'xtrabackup',
  ...

Other values like wsrep_cluster_address and wsrep_sst_auth are generated from several class parameters. Please have a look at the parameter reference and the module's data directory for further details.

Of course, all Galera/WSREP provider options can be overridden by using the $override_options parameter (see below for an example).

More complex example

Furthermore, a number of simple options are available to customize the cluster configuration according to your needs:

class { 'galera':
  cluster_name    => 'mycluster',
  galera_servers  => ['10.0.99.101', '10.0.99.102', '10.0.99.103'],
  galera_master   => 'node1.example.com',
  root_password   => 'pa$$w0rd',
  status_password => 'pa$$w0rd',

  # Default is 'percona'
  vendor_type     => 'codership',
  vendor_version  => '8.0',

  # This will be used to populate my.cnf values that
  # control where wsrep binds, advertises, and listens
  local_ip => $facts['networking']['ip'],

  # This will be set when the cluster is bootstrapped
  root_password => 'myrootpassword',

  # Disable this if you don't want firewall rules to be set
  configure_firewall => true,

  # Configure the SST method
  wsrep_sst_method => 'xtrabackup-v2',

  # These options are only used for the firewall -
  # to change the my.cnf settings, use the override options
  # described below
  mysql_port => 3306,
  wsrep_state_transfer_port => 4444,
  wsrep_inc_state_transfer_port => 4568,

  # This is used for the firewall + for status checks
  # when deciding whether to bootstrap
  wsrep_group_comm_port => 4567,
}

A catch-all parameter $override_options can be used to populate my.cnf and overwrite default values in the same way as the puppetlabs-mysql module:

class { 'galera':
  override_options => {
    'mysqld' => {
      'bind_address' => '0.0.0.0',
    }
  }
  ...
}

Configuring an Arbitrator

Configuring an Arbitrator service is straight-forward:

class { 'galera':
  arbitrator      => true,
  cluster_name    => 'mycluster',
  galera_servers  => ['10.0.99.101', '10.0.99.102', '10.0.99.103'],
  ...
}

You may even use the same parameters that you would normally use for database nodes, when $arbitrator is set to true they will be ignored. This makes it easy to share the same parameters across all cluster nodes, no matter if they are real database nodes or just an arbitrator service.

Custom repository configuration

This module automatically determines which APT/YUM repositories need to be configured. This depends on your choices for $vendor_type, $vendor_version and $wsrep_sst_method. Each of these choices may enabled additional repositories.

For example, if setting $vendor_type=codership and $wsrep_sst_method=xtrabackup, the module will enable the Codership repository to install the Galera server and the Percona repository to install the XtraBackup tool. This works because every vendor/version and SST method may specify the internal $want_repos parameter, which is essentially a list of repositories.

Disable repo management if you are managing your own repos and mirrors:

class { 'galera':
  configure_repo => false,
  ...
}

Or if you just want to switch to using a local mirror, simply change the repo URL for the chosen $vendor_type. For Codership you would add something like this to Hiera:

# RHEL-based systems
galera::repo::codership::yum:
  baseurl: "http://repo.example.com/RPMS/%{facts.os.release.major}/RPMS/%{facts.os.architecture}/"
  baseurl: "http://repo.example.com/RPMS/<%= $vendor_version_real %>/%{facts.os.release.major}/%{facts.os.architecture}/"

# Debian-based systems
galera::repo::codership::apt:
  apt_location: "http://repo.example.com/apt/%{facts.os.distro.codename}/"
  ...

FreeBSD support

This module (and all its dependencies) provide support for the FreeBSD operating system. However, from all vendors Codership seems to provide the best support for Galera clusters on FreeBSD. The following configuration is known to work:

class { 'galera':
  configure_firewall => false,
  configure_repo     => false,
  galera_servers     => ['10.0.99.101', '10.0.99.102'],
  galera_master      => 'node1.example.com',
  root_password      => 'pa$$w0rd',
  status_password    => 'pa$$w0rd',
  vendor_type        => 'codership',
  vendor_version     => '5.7',
}

EPP supported for many options

This module supports inline EPP for many of its options and parameters. This way class parameters and internal variables can be used when specifying options. Currently this is enabled for $override_options, $wsrep_sst_auth and all repository options.

# server/wsrep options

galera::override_options:
  mysqld:
    wsrep_sst_method: "<%= $wsrep_sst_method %>"
    wsrep_provider: "<%= $params['libgalera_location'] %>"

galera::wsrep_sst_auth: "root:<%= $root_password %>"

# repo configuration

galera::repo::codership::yum:
  baseurl: "http://releases.galeracluster.com/mysql-wsrep-<%= $vendor_version_real %>/%{os_name_lc}/%{os.release.major}/%{os.architecture}/"
  ...

OS and Cluster Compatibility

Note that not all versions of Percona XtraDB, Codership Galera and MariaDB are supported on all operating systems. Please consult the official documentation to find out if your operating system is supported.

Below you will find an incomplete and possibly outdated list of known (in)compatiblities. Take it with a grain of salt.

RedHat Debian Ubuntu FreeBSD
Percona XtraDB Cluster 7 / 8 10 / 11 20.04 / 22.04 13.x
5.7 / 8.0 :green_circle: :green_circle: / :green_circle: :green_circle: :green_circle: :green_circle: / :green_circle: :green_circle: :green_circle: :green_circle: / :no_entry_sign: :no_entry_sign: :no_entry_sign: :no_entry_sign:
Codership Galera (MySQL)
5.7 / 8.0 :green_circle: :green_circle: / :green_circle: :green_circle: :no_entry_sign: :no_entry_sign: / :green_circle: :green_circle: :no_entry_sign: :green_circle: / :no_entry_sign: :no_entry_sign: :green_circle: :no_entry_sign:
MariaDB Galera Cluster
10.5 / 10.6 :green_circle: :green_circle: / :green_circle: :green_circle: :green_circle: :green_circle: / :green_circle: :green_circle: :green_circle: :green_circle: / :green_circle: :green_circle: :green_circle: :green_circle:

The table only includes the two most recent versions. Older and possibly outdated releases are not listed, although they may still be supported by their vendors.

Reference

Classes and parameters are documented in REFERENCE.md.

Limitations

This module was created to work in tandem with the puppetlabs-mysql module, rather than replacing it. As the stages in the mysql module are quite strictly laid out in the mysql::server class, this module places its own resources in the gaps between them.

Of note is an exec that will start the mysql service with parameters which will bootstrap/start a new cluster, but only if it cannot open the comms port to any other node in the provided list. This is done with a simple nc command and should not be considered terribly reliable.

Furthermore the bootstrap functionality may be considered harmful for existing clusters. For extra safety, the bootstrap command may be set to something like /bin/false (see GH-116 for more information).

It should also be noted that it is not possible to unset default configuration variables (see GH-174). This is true for this modules' own variables, but also for pre-defined variables that are set by the puppetlabs/mysql module.

Development

Contributing

Please use the GitHub issues functionality to report any bugs or requests for new features. Feel free to fork and submit pull requests for potential contributions.

All contributions must pass all existing tests, new features should provide additional unit/acceptance tests.