Mercurial > repos > other > Puppet
annotate modules/mysql/README.md @ 245:b0f8b88fea5c
Add "translate" module used by MySQL module
author | IBBoard <dev@ibboard.co.uk> |
---|---|
date | Sat, 21 Dec 2019 14:12:10 -0500 |
parents | 48d3a1948e4d |
children | 668df4711671 |
rev | line source |
---|---|
244 | 1 # mysql |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
2 |
244 | 3 #### Table of Contents |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
4 |
244 | 5 1. [Module Description - What the module does and why it is useful](#module-description) |
6 2. [Setup - The basics of getting started with mysql](#setup) | |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
7 * [Beginning with mysql](#beginning-with-mysql) |
244 | 8 3. [Usage - Configuration options and additional functionality](#usage) |
9 * [Customize server options](#customize-server-options) | |
10 * [Create a database](#create-a-database) | |
11 * [Customize configuration](#customize-configuration) | |
12 * [Work with an existing server](#work-with-an-existing-server) | |
13 * [Specify passwords](#specify-passwords) | |
14 * [Install Percona server on CentOS](#install-percona-server-on-centos) | |
15 * [Install MariaDB on Ubuntu](#install-mariadb-on-ubuntu) | |
16 * [Install Plugins](#install-plugins) | |
17 4. [Reference - An under-the-hood peek at what the module is doing and how](REFERENCE.md) | |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
18 5. [Limitations - OS compatibility, etc.](#limitations) |
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
19 6. [Development - Guide for contributing to the module](#development) |
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
20 |
244 | 21 ## Module Description |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
22 |
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
23 The mysql module installs, configures, and manages the MySQL service. |
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
24 |
244 | 25 This module manages both the installation and configuration of MySQL, as well as extending Puppet to allow management of MySQL resources, such as databases, users, and grants. |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
26 |
244 | 27 ## Setup |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
28 |
244 | 29 ### Beginning with mysql |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
30 |
244 | 31 To install a server with the default options: |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
32 |
244 | 33 `include '::mysql::server'`. |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
34 |
244 | 35 To customize options, such as the root password or `/etc/my.cnf` settings, you must also pass in an override hash: |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
36 |
244 | 37 ```puppet |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
38 class { '::mysql::server': |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
39 root_password => 'strongpassword', |
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
40 remove_default_accounts => true, |
244 | 41 restart => true, |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
42 override_options => $override_options |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
43 } |
244 | 44 ``` |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
45 |
244 | 46 Nota bene: Configuration changes will only be applied to the running |
47 MySQL server if you pass true as restart to mysql::server. | |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
48 |
244 | 49 See [**Customize Server Options**](#customize-server-options) below for examples of the hash structure for $override_options. |
50 | |
51 ## Usage | |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
52 |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
53 All interaction for the server is done via `mysql::server`. To install the client, use `mysql::client`. To install bindings, use `mysql::bindings`. |
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
54 |
244 | 55 ### Customize server options |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
56 |
244 | 57 To define server options, structure a hash structure of overrides in `mysql::server`. This hash resembles a hash in the my.cnf file: |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
58 |
244 | 59 ```puppet |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
60 $override_options = { |
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
61 'section' => { |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
62 'item' => 'thing', |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
63 } |
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
64 } |
244 | 65 ``` |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
66 |
244 | 67 For options that you would traditionally represent in this format: |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
68 |
244 | 69 ``` |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
70 [section] |
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
71 thing = X |
244 | 72 ``` |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
73 |
244 | 74 Entries can be created as `thing => true`, `thing => value`, or `thing => ""` in the hash. Alternatively, you can pass an array as `thing => ['value', 'value2']` or list each `thing => value` separately on individual lines. |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
75 |
244 | 76 You can pass a variable in the hash without setting a value for it; the variable would then use MySQL's default settings. To exclude an option from the `my.cnf` file --- for example, when using `override_options` to revert to a default value --- pass `thing => undef`. |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
77 |
244 | 78 If an option needs multiple instances, pass an array. For example, |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
79 |
244 | 80 ```puppet |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
81 $override_options = { |
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
82 'mysqld' => { |
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
83 'replicate-do-db' => ['base1', 'base2'], |
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
84 } |
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
85 } |
244 | 86 ``` |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
87 |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
88 produces |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
89 |
244 | 90 ```puppet |
91 [mysqld] | |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
92 replicate-do-db = base1 |
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
93 replicate-do-db = base2 |
244 | 94 ``` |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
95 |
244 | 96 To implement version specific parameters, specify the version, such as [mysqld-5.5]. This allows one config for different versions of MySQL. |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
97 |
244 | 98 ### Create a database |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
99 |
244 | 100 To create a database with a user and some assigned privileges: |
101 | |
102 ```puppet | |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
103 mysql::db { 'mydb': |
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
104 user => 'myuser', |
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
105 password => 'mypass', |
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
106 host => 'localhost', |
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
107 grant => ['SELECT', 'UPDATE'], |
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
108 } |
244 | 109 ``` |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
110 |
244 | 111 To use a different resource name with exported resources: |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
112 |
244 | 113 ```puppet |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
114 @@mysql::db { "mydb_${fqdn}": |
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
115 user => 'myuser', |
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
116 password => 'mypass', |
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
117 dbname => 'mydb', |
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
118 host => ${fqdn}, |
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
119 grant => ['SELECT', 'UPDATE'], |
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
120 tag => $domain, |
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
121 } |
244 | 122 ``` |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
123 |
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
124 Then you can collect it on the remote DB server: |
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
125 |
244 | 126 ```puppet |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
127 Mysql::Db <<| tag == $domain |>> |
244 | 128 ``` |
129 | |
130 If you set the sql parameter to a file when creating a database, the file is imported into the new database. | |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
131 |
244 | 132 For large sql files, increase the `import_timeout` parameter, which defaults to 300 seconds. |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
133 |
244 | 134 If you have installed the mysql client in a non standard bin/sbin path you can set this with `mysql_exec_path` . |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
135 |
244 | 136 ```puppet |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
137 mysql::db { 'mydb': |
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
138 user => 'myuser', |
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
139 password => 'mypass', |
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
140 host => 'localhost', |
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
141 grant => ['SELECT', 'UPDATE'], |
244 | 142 sql => '/path/to/sqlfile.gz', |
143 import_cat_cmd => 'zcat', | |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
144 import_timeout => 900, |
244 | 145 mysql_exec_path => '/opt/rh/rh-myql57/root/bin' |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
146 } |
244 | 147 ``` |
148 | |
149 ### Customize configuration | |
150 | |
151 To add custom MySQL configuration, place additional files into `includedir`. This allows you to override settings or add additional ones, which is helpful if you don't use `override_options` in `mysql::server`. The `includedir` location is by default set to `/etc/mysql/conf.d`. | |
152 | |
153 ### Work with an existing server | |
154 | |
155 To instantiate databases and users on an existing MySQL server, you need a `.my.cnf` file in `root`'s home directory. This file must specify the remote server address and credentials. For example: | |
156 | |
157 ```puppet | |
158 [client] | |
159 user=root | |
160 host=localhost | |
161 password=secret | |
162 ``` | |
163 | |
164 This module uses the `mysqld_version` fact to discover the server version being used. By default, this is set to the output of `mysqld -V`. If you're working with a remote MySQL server, you may need to set a custom fact for `mysqld_version` to ensure correct behaviour. | |
165 | |
166 When working with a remote server, do *not* use the `mysql::server` class in your Puppet manifests. | |
167 | |
168 ### Specify passwords | |
169 | |
170 In addition to passing passwords as plain text, you can input them as hashes. For example: | |
171 | |
172 ```puppet | |
173 mysql::db { 'mydb': | |
174 user => 'myuser', | |
175 password => '*6C8989366EAF75BB670AD8EA7A7FC1176A95CEF4', | |
176 host => 'localhost', | |
177 grant => ['SELECT', 'UPDATE'], | |
178 } | |
179 ``` | |
180 | |
181 If required, the password can also be an empty string to allow connections without an password. | |
182 | |
183 ### Install Percona server on CentOS | |
184 | |
185 This example shows how to do a minimal installation of a Percona server on a | |
186 CentOS system. This sets up the Percona server, client, and bindings (including Perl and Python bindings). You can customize this usage and update the version as needed. | |
187 | |
188 This usage has been tested on Puppet 4.4, 5.5 and 6.3.0 / CentOS 7 / Percona Server 5.7. | |
189 | |
190 **Note:** The installation of the yum repository is not part of this package | |
191 and is here only to show a full example of how you can install. | |
192 | |
193 ```puppet | |
194 yumrepo { 'percona': | |
195 descr => 'CentOS $releasever - Percona', | |
196 baseurl => 'http://repo.percona.com/percona/yum/release/$releasever/RPMS/$basearch', | |
197 gpgkey => 'https://repo.percona.com/yum/PERCONA-PACKAGING-KEY', | |
198 enabled => 1, | |
199 gpgcheck => 1, | |
200 } | |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
201 |
244 | 202 class {'mysql::server': |
203 package_name => 'Percona-Server-server-57', | |
204 service_name => 'mysql', | |
205 config_file => '/etc/my.cnf', | |
206 includedir => '/etc/my.cnf.d', | |
207 root_password => 'PutYourOwnPwdHere', | |
208 override_options => { | |
209 mysqld => { | |
210 log-error => '/var/log/mysqld.log', | |
211 pid-file => '/var/run/mysqld/mysqld.pid', | |
212 }, | |
213 mysqld_safe => { | |
214 log-error => '/var/log/mysqld.log', | |
215 }, | |
216 } | |
217 } | |
218 | |
219 # Note: Installing Percona-Server-server-57 also installs Percona-Server-client-57. | |
220 # This shows how to install the Percona MySQL client on its own | |
221 class {'mysql::client': | |
222 package_name => 'Percona-Server-client-57' | |
223 } | |
224 | |
225 # These packages are normally installed along with Percona-Server-server-57 | |
226 # If you needed to install the bindings, however, you could do so with this code | |
227 class { 'mysql::bindings': | |
228 client_dev_package_name => 'Percona-Server-shared-57', | |
229 client_dev => true, | |
230 daemon_dev_package_name => 'Percona-Server-devel-57', | |
231 daemon_dev => true, | |
232 perl_enable => true, | |
233 perl_package_name => 'perl-DBD-MySQL', | |
234 python_enable => true, | |
235 python_package_name => 'MySQL-python', | |
236 } | |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
237 |
244 | 238 # Dependencies definition |
239 Yumrepo['percona']-> | |
240 Class['mysql::server'] | |
241 | |
242 Yumrepo['percona']-> | |
243 Class['mysql::client'] | |
244 | |
245 Yumrepo['percona']-> | |
246 Class['mysql::bindings'] | |
247 ``` | |
248 | |
249 ### Install MariaDB on Ubuntu | |
250 | |
251 #### Optional: Install the MariaDB official repo | |
252 | |
253 In this example, we'll use the latest stable (currently 10.1) from the official MariaDB repository, not the one from the distro repository. You could instead use the package from the Ubuntu repository. Make sure you use the repository corresponding to the version you want. | |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
254 |
244 | 255 **Note:** `sfo1.mirrors.digitalocean.com` is one of many mirrors available. You can use any official mirror. |
256 | |
257 ```puppet | |
258 include apt | |
259 | |
260 apt::source { 'mariadb': | |
261 location => 'http://sfo1.mirrors.digitalocean.com/mariadb/repo/10.1/ubuntu', | |
262 release => $::lsbdistcodename, | |
263 repos => 'main', | |
264 key => { | |
265 id => '199369E5404BD5FC7D2FE43BCBCB082A1BB943DB', | |
266 server => 'hkp://keyserver.ubuntu.com:80', | |
267 }, | |
268 include => { | |
269 src => false, | |
270 deb => true, | |
271 }, | |
272 } | |
273 ``` | |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
274 |
244 | 275 #### Install the MariaDB server |
276 | |
277 This example shows MariaDB server installation on Ubuntu Trusty. Adjust the version and the parameters of `my.cnf` as needed. All parameters of the `my.cnf` can be defined using the `override_options` parameter. | |
278 | |
279 The folders `/var/log/mysql` and `/var/run/mysqld` are created automatically, but if you are using other custom folders, they should exist as prerequisites for this code. | |
280 | |
281 All the values set here are an example of a working minimal configuration. | |
282 | |
283 Specify the version of the package you want with the `package_ensure` parameter. | |
284 | |
285 ```puppet | |
286 class {'::mysql::server': | |
287 package_name => 'mariadb-server', | |
288 package_ensure => '10.1.14+maria-1~trusty', | |
289 service_name => 'mysql', | |
290 root_password => 'AVeryStrongPasswordUShouldEncrypt!', | |
291 override_options => { | |
292 mysqld => { | |
293 'log-error' => '/var/log/mysql/mariadb.log', | |
294 'pid-file' => '/var/run/mysqld/mysqld.pid', | |
295 }, | |
296 mysqld_safe => { | |
297 'log-error' => '/var/log/mysql/mariadb.log', | |
298 }, | |
299 } | |
300 } | |
301 | |
302 # Dependency management. Only use that part if you are installing the repository | |
303 # as shown in the Preliminary step of this example. | |
304 Apt::Source['mariadb'] ~> | |
305 Class['apt::update'] -> | |
306 Class['::mysql::server'] | |
307 | |
308 ``` | |
309 | |
310 #### Install the MariaDB client | |
311 | |
312 This example shows how to install the MariaDB client and all of the bindings at once. You can do this installation separately from the server installation. | |
313 | |
314 Specify the version of the package you want with the `package_ensure` parameter. | |
315 | |
316 ```puppet | |
317 class {'::mysql::client': | |
318 package_name => 'mariadb-client', | |
319 package_ensure => '10.1.14+maria-1~trusty', | |
320 bindings_enable => true, | |
321 } | |
322 | |
323 # Dependency management. Only use that part if you are installing the repository as shown in the Preliminary step of this example. | |
324 Apt::Source['mariadb'] ~> | |
325 Class['apt::update'] -> | |
326 Class['::mysql::client'] | |
327 ``` | |
328 | |
329 ### Install MySQL Community server on CentOS | |
330 | |
331 You can install MySQL Community Server on CentOS using the mysql module and Hiera. This example was tested with the following versions: | |
332 | |
333 * MySQL Community Server 5.6 | |
334 * Centos 7.3 | |
335 * Puppet 3.8.7 using Hiera | |
336 * puppetlabs-mysql module v3.9.0 | |
337 | |
338 In Puppet: | |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
339 |
244 | 340 ```puppet |
341 include ::mysql::server | |
342 | |
343 create_resources(yumrepo, hiera('yumrepo', {})) | |
344 | |
345 Yumrepo['repo.mysql.com'] -> Anchor['mysql::server::start'] | |
346 Yumrepo['repo.mysql.com'] -> Package['mysql_client'] | |
347 | |
348 create_resources(mysql::db, hiera('mysql::server::db', {})) | |
349 ``` | |
350 | |
351 In Hiera: | |
352 | |
353 ```yaml | |
354 --- | |
355 | |
356 # Centos 7.3 | |
357 yumrepo: | |
358 'repo.mysql.com': | |
359 baseurl: "http://repo.mysql.com/yum/mysql-5.6-community/el/%{::operatingsystemmajrelease}/$basearch/" | |
360 descr: 'repo.mysql.com' | |
361 enabled: 1 | |
362 gpgcheck: true | |
363 gpgkey: 'http://repo.mysql.com/RPM-GPG-KEY-mysql' | |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
364 |
244 | 365 mysql::client::package_name: "mysql-community-client" # required for proper MySQL installation |
366 mysql::server::package_name: "mysql-community-server" # required for proper MySQL installation | |
367 mysql::server::package_ensure: 'installed' # do not specify version here, unfortunately yum fails with error that package is already installed | |
368 mysql::server::root_password: "change_me_i_am_insecure" | |
369 mysql::server::manage_config_file: true | |
370 mysql::server::service_name: 'mysqld' # required for puppet module | |
371 mysql::server::override_options: | |
372 'mysqld': | |
373 'bind-address': '127.0.0.1' | |
374 'log-error': '/var/log/mysqld.log' # required for proper MySQL installation | |
375 'mysqld_safe': | |
376 'log-error': '/var/log/mysqld.log' # required for proper MySQL installation | |
377 | |
378 # create database + account with access, passwords are not encrypted | |
379 mysql::server::db: | |
380 "dev": | |
381 user: "dev" | |
382 password: "devpass" | |
383 host: "127.0.0.1" | |
384 grant: | |
385 - "ALL" | |
386 | |
387 ``` | |
388 | |
389 ### Install Plugins | |
390 | |
391 Plugins can be installed by using the `mysql_plugin` defined type. See `examples/mysql_plugin.pp` for futher examples. | |
392 ## Reference | |
393 | |
394 ### Classes | |
395 | |
396 #### Public classes | |
397 | |
398 * [`mysql::server`](#mysqlserver): Installs and configures MySQL. | |
399 * [`mysql::server::monitor`](#mysqlservermonitor): Sets up a monitoring user. | |
400 * [`mysql::server::mysqltuner`](#mysqlservermysqltuner): Installs MySQL tuner script. | |
401 * [`mysql::server::backup`](#mysqlserverbackup): Sets up MySQL backups via cron. | |
402 * [`mysql::bindings`](#mysqlbindings): Installs various MySQL language bindings. | |
403 * [`mysql::client`](#mysqlclient): Installs MySQL client (for non-servers). | |
404 | |
405 #### Private classes | |
406 | |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
407 * `mysql::server::install`: Installs packages. |
244 | 408 * `mysql::server::installdb`: Implements setup of mysqld data directory (e.g. /var/lib/mysql) |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
409 * `mysql::server::config`: Configures MYSQL. |
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
410 * `mysql::server::service`: Manages service. |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
411 * `mysql::server::account_security`: Deletes default MySQL accounts. |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
412 * `mysql::server::root_password`: Sets MySQL root password. |
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
413 * `mysql::server::providers`: Creates users, grants, and databases. |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
414 * `mysql::bindings::client_dev`: Installs MySQL client development package. |
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
415 * `mysql::bindings::daemon_dev`: Installs MySQL daemon development package. |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
416 * `mysql::bindings::java`: Installs Java bindings. |
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
417 * `mysql::bindings::perl`: Installs Perl bindings. |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
418 * `mysql::bindings::php`: Installs PHP bindings. |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
419 * `mysql::bindings::python`: Installs Python bindings. |
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
420 * `mysql::bindings::ruby`: Installs Ruby bindings. |
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
421 * `mysql::client::install`: Installs MySQL client. |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
422 * `mysql::backup::mysqldump`: Implements mysqldump backups. |
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
423 * `mysql::backup::mysqlbackup`: Implements backups with Oracle MySQL Enterprise Backup. |
244 | 424 * `mysql::backup::xtrabackup`: Implements backups with XtraBackup from Percona or Mariabackup. |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
425 |
244 | 426 ### Parameters |
427 | |
428 #### mysql::server | |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
429 |
244 | 430 ##### `create_root_user` |
431 | |
432 Whether root user should be created. | |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
433 |
244 | 434 Valid values are `true`, `false`. |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
435 |
244 | 436 Defaults to `true`. |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
437 |
244 | 438 This is useful for a cluster setup with Galera. The root user has to be created only once. You can set this parameter true on one node and set it to false on the remaining nodes. |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
439 |
244 | 440 ##### `create_root_my_cnf` |
441 | |
442 Whether to create `/root/.my.cnf`. | |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
443 |
244 | 444 Valid values are `true`, `false`. |
445 | |
446 Defaults to `true`. | |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
447 |
244 | 448 `create_root_my_cnf` allows creation of `/root/.my.cnf` independently of `create_root_user`. You can use this for a cluster setup with Galera where you want `/root/.my.cnf` to exist on all nodes. |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
449 |
244 | 450 ##### `root_password` |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
451 |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
452 The MySQL root password. Puppet attempts to set the root password and update `/root/.my.cnf` with it. |
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
453 |
244 | 454 This is required if `create_root_user` or `create_root_my_cnf` are true. If `root_password` is 'UNSET', then `create_root_user` and `create_root_my_cnf` are assumed to be false --- that is, the MySQL root user and `/root/.my.cnf` are not created. |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
455 |
244 | 456 Password changes are supported; however, the old password must be set in `/root/.my.cnf`. Effectively, Puppet uses the old password, configured in `/root/my.cnf`, to set the new password in MySQL, and then updates `/root/.my.cnf` with the new password. |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
457 |
244 | 458 ##### `old_root_password` |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
459 |
244 | 460 This parameter no longer does anything. It exists only for backwards compatibility. See the `root_password` parameter above for details on changing the root password. |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
461 |
244 | 462 ##### `create_root_login_file` |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
463 |
244 | 464 Whether to create `/root/.mylogin.cnf` when using mysql 5.6.6+. |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
465 |
244 | 466 Valid values are `true`, `false`. |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
467 |
244 | 468 Defaults to `false`. |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
469 |
244 | 470 `create_root_login_file` will put a copy of your existing `.mylogin.cnf` in the `/root/.mylogin.cnf` location. |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
471 |
244 | 472 When set to 'true', this option also requires the `login_file` option. |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
473 |
244 | 474 The `login_file` option is required when set to true. |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
475 |
244 | 476 #### `login_file` |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
477 |
244 | 478 Whether to put the `/root/.mylogin.cnf` in place. |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
479 |
244 | 480 You need to create the `.mylogin.cnf` file with `mysql_config_editor`, this tool comes with mysql 5.6.6+. |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
481 |
244 | 482 The created .mylogin.cnf needs to be put under files in your module, see example below on how to use this. |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
483 |
244 | 484 When the `/root/.mylogin.cnf` exists the environment variable `MYSQL_TEST_LOGIN_FILE` will be set. |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
485 |
244 | 486 This is required if `create_root_user` and `create_root_login_file` are true. If `root_password` is 'UNSET', then `create_root_user` and `create_root_login_file` are assumed to be false --- that is, the MySQL root user and `/root/.mylogin.cnf` are not created. |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
487 |
244 | 488 ```puppet |
489 class { '::mysql::server': | |
490 root_password => 'password', | |
491 create_root_my_cnf => false, | |
492 create_root_login_file => true, | |
493 login_file => "puppet:///modules/${module_name}/mylogin.cnf", | |
494 } | |
495 ``` | |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
496 |
244 | 497 ##### `override_options` |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
498 |
244 | 499 Specifies override options to pass into MySQL. Structured like a hash in the my.cnf file: |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
500 |
244 | 501 ```puppet |
502 class { 'mysql::server': | |
503 root_password => 'password' | |
504 } | |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
505 |
244 | 506 mysql_plugin { 'auth_pam': |
507 ensure => present, | |
508 soname => 'auth_pam.so', | |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
509 } |
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
510 |
244 | 511 ``` |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
512 |
244 | 513 ### Tasks |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
514 |
244 | 515 The MySQL module has an example task that allows a user to execute arbitary SQL against a database. Please refer to to the [PE documentation](https://puppet.com/docs/pe/2017.3/orchestrator/running_tasks.html) or [Bolt documentation](https://puppet.com/docs/bolt/latest/bolt.html) on how to execute a task. |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
516 |
244 | 517 ## Limitations |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
518 |
244 | 519 For an extensive list of supported operating systems, see [metadata.json](https://github.com/puppetlabs/puppetlabs-mysql/blob/master/metadata.json) |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
520 |
244 | 521 **Note:** The mysqlbackup.sh does not work and is not supported on MySQL 5.7 and greater. |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
522 |
244 | 523 ## Development |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
524 |
244 | 525 We are experimenting with a new tool for running acceptance tests. Its name is [puppet_litmus](https://github.com/puppetlabs/puppet_litmus) this replaces beaker as the test runner. To run the acceptance tests follow the instructions from this point [here](https://github.com/puppetlabs/puppet_litmus/wiki/Tutorial:-use-Litmus-to-execute-acceptance-tests-with-a-sample-module-(MoTD)#install-the-necessary-gems-for-the-module). |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
526 |
244 | 527 Puppet modules on the Puppet Forge are open projects, and community contributions are essential for keeping them great. We can't access the huge number of platforms and myriad of hardware, software, and deployment configurations that Puppet is intended to serve. |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
528 |
244 | 529 We want to keep it as easy as possible to contribute changes so that our modules work in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things. |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
530 |
244 | 531 Check out our the complete [module contribution guide](https://puppet.com/docs/puppet/latest/contributing.html). |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
532 |
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
533 ### Authors |
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
534 |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
535 This module is based on work by David Schmitt. The following contributors have contributed to this module (beyond Puppet Labs): |
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
536 |
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
537 * Larry Ludwig |
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
538 * Christian G. Warden |
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
539 * Daniel Black |
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
540 * Justin Ellison |
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
541 * Lowe Schmidt |
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
542 * Matthias Pigulla |
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
543 * William Van Hevelingen |
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
544 * Michael Arnold |
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
545 * Chris Weyl |
26
58d1818c2ded
Update MySQL module (which adds "staging" module)
IBBoard <dev@ibboard.co.uk>
parents:
0
diff
changeset
|
546 * Daniël van Eeden |
244 | 547 * Jan-Otto Kröpke |
548 * Timothy Sven Nelson |