Forge Home

galera

Setup a Galera cluster on MySQL/MariaDB/XtraDB with Arbitrator support

1,202 downloads

109 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

  • 4.0.1 (latest)
  • 4.0.0
  • 3.2.1
  • 3.2.0
  • 3.1.0
  • 3.0.2
released Aug 14th 2024
This version is compatible with:
  • Puppet Enterprise 2023.8.x, 2023.7.x, 2023.6.x, 2023.5.x, 2023.4.x, 2023.3.x, 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
  • Puppet >= 7.0.0 < 9.0.0
  • , , , , ,

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'markt-galera', '4.0.1'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add markt-galera
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install markt-galera --version 4.0.1

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download

Documentation

markt/galera — version 4.0.1 Aug 14th 2024

puppet-galera

Build Status Puppet Forge Puppet Forge - downloads

NOTE: The "main" 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

  • Puppet 7 or higher
  • puppetlabs/mysql
  • A supported version of Codership Galera (MySQL), MariaDB or Percona XtraDB Cluster
  • nmap is required for the cluster bootstrap functionality
  • puppetlabs/xinetd if galera::status_type is set to xinetd (default for FreeBSD)
  • puppet/systemd if galera::status_type is set to systemd (default for newer Linux distributions)
  • puppetlabs/firewall unless galera::configure_firewall is disabled

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':
  # Galera vendor and version
  vendor_type    => 'codership',
  vendor_version => '8.0',
  # Galera cluster config
  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',
}

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':
  # Galera vendor and version
  vendor_type     => 'codership',
  vendor_version  => '8.0',
  #
  # Galera cluster config
  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 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 enable 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/<%= $vendor_version_real %>/%{facts.os.release.major}/%{facts.os.architecture}/"
  ...
# Debian-based systems
galera::repo::codership::apt:
  location: "http://repo.example.com/apt/<%= $vendor_version_real %>/%{facts.os.distro.codename}/"
  ...

FreeBSD support

This module (and all its dependencies) provide support for the FreeBSD operating system. However, from all vendors MariaDB 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        => 'mariadb',
  vendor_version     => '10.11',
}

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 8 / 9 11 / 12 22.04 / 24.04 14.x
8.0 ✔️ / ✔️ ✔️ / ✔️ ✔️ /
Codership Galera (MySQL)
8.0 / 8.4 ✔️ ✔️ / ✔️ ✔️ ✔️ ✔️ / ✔️ ✔️ ✔️ ✔️ / ✔️ ✔️ ❌ ❌
MariaDB Galera Cluster
10.11 / 11.4 ❌ ❌ / ✔️ ✔️ ❌ ❌ / ✔️ ✔️ ❌ ❌ / ✔️ ✔️ ✔️ ✔️

The table only includes the two most recent (LTS) 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 verified with a simple nmap 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.