Manage MariaDB or a Galera cluster of MariaDB nodes with Salt.
Table of Contents
See the full SaltStack Formulas installation and usage instructions.
If you are interested in writing or contributing to formulas, please pay attention to the Writing Formula Section.
If you want to use this formula, please pay attention to the FORMULA
file and/or git tag
,
which contains the currently released version. This formula is versioned according to Semantic Versioning.
See Formula Versioning Section for more details.
If you need (non-default) configuration, please refer to:
- how to configure the formula with map.jinja
- the
pillar.example
file - the Special notes section
- Certificates are automatically generated if configured.
- Optionally, there is also support for initializing a connection to HashiCorp Vault.
- The MariaDB root user has no password by default and running
mysql_secure_installation
is discouraged. There is no option to set the root password.
An example pillar is provided, please see pillar.example. Note that you do not need to specify everything by pillar. Often, it's much easier and less resource-heavy to use the parameters/<grain>/<value>.yaml
files for non-sensitive settings. The underlying logic is explained in map.jinja.
The following states are found in this formula:
mariadb
mariadb.package
mariadb.package.repo
mariadb.config
mariadb.cert
mariadb.service
mariadb.vault
mariadb.databases
mariadb.users
mariadb.clean
mariadb.package.clean
mariadb.package.repo.clean
mariadb.config.clean
mariadb.cert.clean
mariadb.service.clean
mariadb.vault.clean
mariadb.databases.clean
mariadb.users.clean
Meta-state.
This installs the mariadb package, manages the mariadb configuration, creates TLS certificates if they have been configured, starts the MariaDB service, initializes a Vault connection if configured and then manages configured databases and user accounts.
Installs the mariadb package only.
This state will install the configured mariadb repository. This works for apt/dnf/yum/zypper-based distributions only by default.
Manages the mariadb service configuration. Has a dependency on mariadb.package.
Manages MariaDB server/client certificates as well as the trusted root CA certificate.
Pulls the certificate paths directly from the configuration.
All three values ssl_key
, ssl_cert
and ssl_ca
must be specified
in mysqld
/mariadb
(server) or mysql
(client) for this
state to apply.
Starts the mariadb service and enables it at boot time.
If manage_firewall
is true, will also ensure the service
ports are exposed.
Has a dependency on mariadb.config.
Notes for Galera (install:galera
is true):
- If
config:mariadb:wsrep_cluster_address
is unspecified, will initialize a new cluster. - If you need to bootstrap a cluster after shutting down all nodes,
you will need to pass
pillar='{"galera_bootstrap": false}'
tostate.apply
. - Ensure that all service ports are exposed to other nodes in the cluster, otherwise starting the service will fail.
Connects the local database to a Vault database secret plugin and manages associated roles.
Requires vault:init
set to true to be included in the
meta state by default.
Manages databases. Has a dependency on mariadb.service.
Manages user accounts and their database grants. Has a dependency on mariadb.databases.
Meta-state.
Undoes everything performed in the mariadb
meta-state
in reverse order, i.e.
removes managed databases if clean_databases
is true,
removes managed user accounts,
removes the Vault connection if configured,
stops the service,
removes the configuration file and then
uninstalls the package.
Removes the mariadb package. Has a dependency on mariadb.config.clean.
This state will remove the configured mariadb repository. This works for apt/dnf/yum/zypper-based distributions only by default.
Removes the configuration of the mariadb service and has a dependency on mariadb.service.clean.
Removes the managed MariaDB server/client certificates as well as the trusted root CA certificate.
Stops the mariadb service and disables it at boot time.
Removes the Vault connection, associated roles and the vault
user account.
Removes all managed databases if mariadb:clean_databases
is True.
Removes all managed user accounts and grants.
Commit message formatting is significant!
Please see How to contribute for more details.
pre-commit is configured for this formula, which you may optionally use to ease the steps involved in submitting your changes.
First install the pre-commit
package manager using the appropriate method, then run bin/install-hooks
and
now pre-commit
will run automatically on each git commit
.
$ bin/install-hooks pre-commit installed at .git/hooks/pre-commit pre-commit installed at .git/hooks/commit-msg
There is a script that semi-autodocuments available states: bin/slsdoc
.
If a .sls
file begins with a Jinja comment, it will dump that into the docs. It can be configured differently depending on the formula. See the script source code for details currently.
This means if you feel a state should be documented, make sure to write a comment explaining it.
Linux testing is done with kitchen-salt
.
- Ruby
- Docker
$ gem install bundler
$ bundle install
$ bin/kitchen test [platform]
Where [platform]
is the platform name defined in kitchen.yml
,
e.g. debian-9-2019-2-py3
.
Creates the docker instance and runs the mariadb
main state, ready for testing.
Runs the inspec
tests on the actual instance.
Removes the docker instance.
Runs all of the stages above in one go: i.e. destroy
+ converge
+ verify
+ destroy
.
Gives you SSH access to the instance for manual testing.