├── .gitignore
├── .vscode
└── settings.json
├── Gruntfile.js
├── LICENSE
├── README.md
├── azure-architecture.png
├── generator.html
├── metadata.json
├── package-lock.json
├── package.json
└── sources
├── app.source.js
├── arm.source.js
├── azure-vm-sizes.json
├── cloud-config.source.js
├── cloud-config
├── create-raid-array.service
├── create-raid-array.sh
├── docker-mariadb-galera.service
├── docker-mariadb-galera.sh
├── docker-mariadb-waiter.service
├── docker-mariadb-waiter.sh
├── etcd-waiter.service
├── etcd-waiter.sh
├── mnt-data.mount
└── mysql_server.cnf
├── forms.source.js
├── generator.source.html
├── templates
├── base.template.json
├── storage-account.template.json
└── unmanaged-disk.template.json
├── yaml-arm.source.js
└── yaml.source.js
/.gitignore:
--------------------------------------------------------------------------------
1 | # Intermediary build files
2 | sources/app.build.js
3 | sources/cloud-config.pack.json
4 |
5 |
6 | # Created by https://www.gitignore.io/api/node,osx,windows,linux
7 |
8 | ### Node ###
9 | # Logs
10 | logs
11 | *.log
12 | npm-debug.log*
13 |
14 | # Runtime data
15 | pids
16 | *.pid
17 | *.seed
18 |
19 | # Directory for instrumented libs generated by jscoverage/JSCover
20 | lib-cov
21 |
22 | # Coverage directory used by tools like istanbul
23 | coverage
24 |
25 | # Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
26 | .grunt
27 |
28 | # node-waf configuration
29 | .lock-wscript
30 |
31 | # Compiled binary addons (http://nodejs.org/api/addons.html)
32 | build/Release
33 |
34 | # Dependency directories
35 | node_modules
36 | jspm_packages
37 |
38 | # Optional npm cache directory
39 | .npm
40 |
41 | # Optional REPL history
42 | .node_repl_history
43 |
44 |
45 | ### OSX ###
46 | .DS_Store
47 | .AppleDouble
48 | .LSOverride
49 |
50 | # Icon must end with two \r
51 | Icon
52 |
53 |
54 | # Thumbnails
55 | ._*
56 |
57 | # Files that might appear in the root of a volume
58 | .DocumentRevisions-V100
59 | .fseventsd
60 | .Spotlight-V100
61 | .TemporaryItems
62 | .Trashes
63 | .VolumeIcon.icns
64 |
65 | # Directories potentially created on remote AFP share
66 | .AppleDB
67 | .AppleDesktop
68 | Network Trash Folder
69 | Temporary Items
70 | .apdisk
71 |
72 |
73 | ### Windows ###
74 | # Windows image file caches
75 | Thumbs.db
76 | ehthumbs.db
77 |
78 | # Folder config file
79 | Desktop.ini
80 |
81 | # Recycle Bin used on file shares
82 | $RECYCLE.BIN/
83 |
84 | # Windows Installer files
85 | *.cab
86 | *.msi
87 | *.msm
88 | *.msp
89 |
90 | # Windows shortcuts
91 | *.lnk
92 |
93 |
94 | ### Linux ###
95 | *~
96 |
97 | # temporary files which can be created if a process still has a handle open of a deleted file
98 | .fuse_hidden*
99 |
100 | # KDE directory preferences
101 | .directory
102 |
103 | # Linux trash folder which might appear on any partition or disk
104 | .Trash-*
105 |
--------------------------------------------------------------------------------
/.vscode/settings.json:
--------------------------------------------------------------------------------
1 | {
2 | "files.exclude": {
3 | "node_modules/": true,
4 | "sources/app.build.js": true,
5 | "sources/cloud-config.pack.json": true
6 | },
7 | "files.trimTrailingWhitespace": true,
8 | "editor.tabSize": 4,
9 | "files.insertFinalNewline": true
10 | }
11 |
--------------------------------------------------------------------------------
/Gruntfile.js:
--------------------------------------------------------------------------------
1 | 'use strict'
2 |
3 | let co = require('co')
4 | let fs = require('mz/fs')
5 |
6 | module.exports = function(grunt) {
7 | grunt.initConfig({
8 | pack: {
9 | dist: {
10 | src: ['sources/cloud-config/*'],
11 | dest: 'sources/cloud-config.pack.json'
12 | }
13 | },
14 | browserify: {
15 | dist: {
16 | files: {
17 | 'sources/app.build.js': ['sources/app.source.js']
18 | },
19 | options: {
20 | }
21 | }
22 | },
23 | htmlbuild: {
24 | dist: {
25 | src: 'sources/generator.source.html',
26 | dest: 'generator.html',
27 | options: {
28 | scripts: {
29 | app: 'sources/app.build.js',
30 | yaml: 'node_modules/js-yaml/dist/js-yaml.min.js'
31 | }
32 | }
33 | }
34 | },
35 | watch: {
36 | scripts: {
37 | files: ['sources/*.source.*', 'sources/cloud-config/*', 'sources/templates/*'],
38 | tasks: ['default']
39 | }
40 | }
41 | })
42 |
43 | grunt.loadNpmTasks('grunt-browserify')
44 | grunt.loadNpmTasks('grunt-html-build')
45 | grunt.loadNpmTasks('grunt-contrib-watch')
46 |
47 | grunt.registerMultiTask('pack', function() {
48 | let task = this
49 | let taskDone = task.async()
50 | let files = this.files
51 | let options = this.options()
52 |
53 | co(function*() {
54 | let readPromisesList = {}
55 | for(let i = 0; i < files.length; i++) {
56 | let f = files[i]
57 |
58 | if(f.src.length) {
59 | let dest = f.dest
60 | let done = 0
61 |
62 | for(let j = 0; j < f.src.length; j++) {
63 | let filename = f.src[j].split('/').pop()
64 | let promise = Promise.resolve(true).then(res => {
65 | return fs.readFile(f.src[j], 'utf8')
66 | })
67 | readPromisesList[filename] = promise
68 | }
69 |
70 | let pack = yield readPromisesList
71 |
72 | let packStr = JSON.stringify(pack)
73 | yield fs.writeFile(dest, packStr)
74 | }
75 | }
76 |
77 | taskDone()
78 | })
79 | })
80 |
81 | grunt.registerTask('default', ['pack', 'browserify', 'htmlbuild'])
82 | }
83 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | Copyright (c) 2017 Alessandro Segala
2 |
3 | Permission is hereby granted, free of charge, to any person obtaining a copy
4 | of this software and associated documentation files (the "Software"), to deal
5 | in the Software without restriction, including without limitation the rights
6 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
7 | copies of the Software, and to permit persons to whom the Software is
8 | furnished to do so, subject to the following conditions:
9 |
10 | The above copyright notice and this permission notice shall be included in all
11 | copies or substantial portions of the Software.
12 |
13 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
18 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
19 | SOFTWARE.
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # MariaDB + Galera Cluster on CoreOS with Docker
2 |
3 | > **The generator web app is now hosted on GitHub pages at the URL: [http://egoalesum.github.io/mariadb-cluster/generator.html](http://egoalesum.github.io/mariadb-cluster/generator.html)**
4 |
5 | This repository contains a generator app for the Cloud Config and the Azure Resource Manager (ARM) template files, to create a MariaDB database with Galera Cluster, running inside Docker containers on CoreOS. You can read more about the architecture, and the choices behind it, on [this blog post](http://withblue.ink/2016/03/09/galera-cluster-mariadb-coreos-and-docker-part-1.html). The ARM template is a JSON file that can be deployed automatically with just a few clicks on Azure and it includes a tailored Cloud Config file.
6 |
7 | The starting point is the generator app, which is a static HTML file that runs inside any modern web browser to create ad-hoc Cloud Config and Azure ARM template files. You can use the [hosted generator app](http://egoalesum.github.io/mariadb-cluster/generator.html), or you can clone the repository locally and open `generator.html` with any web browser.
8 |
9 |
10 | ## Getting started
11 |
12 | You can use the generator app hosted on GitHub pages or clone the repository and run it locally:
13 |
14 | - **Recommended:** Use the [hosted generator app](http://egoalesum.github.io/mariadb-cluster/generator.html)
15 | - If you prefer to run the app locally, clone this repository in your local machine, then open the `generator.html` file with a web browser. Using one of the "evergreen browsers" (Edge, Chrome, Safari, Firefox) is recommended. You will need to be connected to the Internet for the web application to work properly. Please note that if you're having issues with the page not working while opening it from your local disk, you might need to manually set the "etcd2 Discovery URL" parameter, or put the page on a web server.
16 |
17 | The web application offers two modes:
18 | - **Azure Resource Manager**: in this mode, an ARM template (a JSON document) is generated, ready to be deployed to Azure. The resulting ARM template includes the Cloud Config file too.
19 | - **Only cloud-config.yaml**: generates only the Cloud Config file, in plaintext and base64-encoded. This file can be used to startup the Galera Cluster on any public/private cloud.
20 |
21 | ## Deploying to Azure
22 |
23 | The ARM template allows you to deploy a MariaDB + Galera Cluster (based on CoreOS) with a few clicks, running on the Microsoft Azure cloud.
24 |
25 | ### How to deploy the template
26 |
27 | 1. Ensure you have an active Azure subscription. You can also get a [free trial](http://azure.com/free).
28 | 2. Using the [hosted generator app](http://egoalesum.github.io/mariadb-cluster/generator.html) or the `generator.html` page on your machine, create the Azure Resource Manager template, properly configured.
29 | 3. Open the [Azure Portal](https://portal.azure.com), then press "+ New" on the top left corner, search for "Template deployment" and select the result with the same name. Then click on the "Create" button.
30 | 4. In the "Template" blade, paste the "Azure Resource Manager template" JSON document generated with the HTML app.
31 | 5. In the "Parameters" blade, leave all values to their default (the JSON you pasted has all your parameters already hardcoded as default values).
32 | 6. Select the subscription you want to deploy the cluster into, then create a new Resource Group (or choose an existing one) and pick in what Azure region you want the deployment to happen. Lastly, accept the mandatory legal terms and press Create.
33 | 7. Azure will deploy your VMs and linked resources, and then MariaDB and Galera Cluster will be started in all the VMs automatically. The duration of the setup depends a lot on the size of the attached disks; with small disks (2-4), it should last around 5 minutes.
34 |
35 | ### Architecture of deployment on Azure
36 |
37 | On the Microsoft Azure platform, the JSON template is deploying the following:
38 |
39 | 
40 |
41 | 1. A Virtual Network named after the Resource Group (not in the diagram) with address space `10.0.0.0/16`.
42 | 2. A subnet `10.0.1.0/24` named `mariadb-subnet`.
43 | 3. An Azure Internal Load Balancer for the MySQL endpoints (port `3306`). The Internal Load Balancer has always the address `10.0.1.4` and no public IP.
44 | 4. The 3 or 5 nodes running the application. All VMs are named `mariadb-node-N` (where N is a number between 0 and 4), with addresses automatically assigned by DHCP (generally, the first one to deploy obtains `10.0.1.5`, and the others follow in sequence). Nodes do not have a public IP, and Network Security Group rules allow traffic to only port `3306` (MySQL) and `22` (SSH), and only from within the Virtual Network. All VMs are also deployed in an Availability Set, in order to achieve high availability.
45 |
46 | Your application can connect to the MariaDB Galera Cluster on the IP `10.0.1.4` (Internal Load Balancer) on port `3306`. Using Network Security Group rules, connections to the database are allowed only from within the Virtual Network. Connecting to the cluster using the IP of the Internal Load Balancer is recommended because it handles failover automatically; however, it's still possible to connect to individual nodes directly, for example for debug purposes. In case you need to administer the VMs using SSH, you can do so by connecting to each instance on port `22`, from another machine inside the Virtual Network, and authenticating using the public key method.
47 |
48 | The default password for the `root` user in the database is **`my-secret-pw`**; it's recommended to change it as soon as possible, using the following SQL statement:
49 |
50 | ````sql
51 | SET PASSWORD FOR 'root'@'%' = PASSWORD('newpass');
52 | ````
53 |
54 | Note: when using Galera Cluster, it's important not to edit the `mysql` system database, because those changes won't be replicated across the nodes. To edit users, leverage SQL statements such as `CREATE USER`, `SET PASSWORD`, etc; do not alter the `mysql.user` table directly.
55 |
56 |
57 | ## Using the Cloud Config mode
58 |
59 | If you use the "Cloud Config mode", the generator app will create only a `cloud-config.yaml` file (in plaintext and base64-encoded). You can use that file to spin up your own cluster, in any public or private cloud.
60 |
61 | There are only a few restrictions to keep in mind when designing your architecture:
62 |
63 | 1. The `cloud-config.yaml` file generated is meant to be used with CoreOS 899+ (latest Stable release as of writing); it has not been tested with any other Linux distribution, and it's likely not to work.
64 | 2. With these scripts, you can deploy up to 5 nodes in the cluster, and your nodes must be named `mariadb-node-0`, `mariadb-node-1`, etc, until `mariadb-node-4`. All VMs in the cluster must be able to connect to each other using those names, so you need to ensure that a naming resolution service exists in your infrastructure. Indeed, in the current version, the MariaDB configuration file has hardcoded the hostnames of the VMs; this design choice may change in the future, however.
65 | 3. It's strongly advised to use an odd number of nodes to avoid the risk of "split-brain conditions" (please see the [official Galera documentation](http://galeracluster.com/documentation-webpages/weightedquorum.html)).
66 | 4. The default password for the `root` user in the database is **`my-secret-pw`**; it's recommended to change it as soon as possible.
67 |
68 | > **Note:** when in "Cloud Config mode", the generated YAML file is slightly different than the one generated in "Azure Resource Manager template" mode. In the latter case, a few more units and scripts are added to attach and format data disks attached to the Azure Virtual Machines.
69 |
70 |
71 | ## Notes on parameters for the generator
72 |
73 | ### etcd2 Discovery URL
74 |
75 | An optional parameter in the generator app is the Discovery URL for etcd2. etcd2 is a distributed key/value storage that is shipped with CoreOS and on which the deployment scripts in this repository rely on.
76 |
77 | **Most users should leave the Discovery URL field empty**. When the field is not set, the generator app will request a new Discovery URL automatically on your behalf, using `http://discovery.etcd.io/`. You will need to manually set a value for this field if you are re-deploying the template in an existing, running cluster.
78 |
79 | ### SSH key
80 |
81 | The generator app requires you to specify a **SSH RSA public key**.
82 |
83 | **Linux and Mac** users can use the built-in `ssh-keygen` command line utility, which is pre-installed in OSX and most Linux distributions. Execute the following command, and when prompted save to the default location (`~/.ssh/id_rsa`):
84 |
85 | $ ssh-keygen -t rsa -b 4096
86 |
87 | Your **public** key will be located in `~/.ssh/id_rsa.pub`.
88 |
89 | **Windows** users can generate compatible keys using PuTTYgen, as shown in [this article](https://winscp.net/eng/docs/ui_puttygen). Please make sure you select "SSH-2 RSA" as type, and use 4096 bits as size for best security.
90 |
91 |
92 | ## For developers
93 |
94 | If you want to modify the generator app (for example because you want to alter the deployment scripts, systemd units, etc), you can re-compile it using Grunt.
95 |
96 | 1. Ensure Node.js 5.0 or higher is installed (it will probably work with Node.js 4.x too, but it's not tested). You can download the latest version from the [Node.js website](https://nodejs.org/).
97 | 2. Clone this git repository on your machine: `$ git clone https://github.com/EgoAleSum/mariadb-cluster.git`
98 | 3. Inside the directory where you cloned the repository, install the required npm modules: `$ npm install`
99 | 4. Rebuild the generator app with: `$ grunt`.
100 | 5. To watch for changes to source files and re-compile automatically, you can use `$ grunt watch`.
101 |
102 | Structure of the repository:
103 |
104 | - The `generator.html` app is built from files in the `sources` folder.
105 | - Inside the source folder, the `cloud-config` directory contains the raw deployment scripts, systemd units and configuration files to be copied on the VMs. Those files are then merged in a single JSON document by Grunt at "compile time".
106 | - The entry-point for the JavaScript code is the `app.source.js` file. Using Browserify, Grunt merges all JavaScript code into `app.build.js`.
107 | - Lastly, Grunt inlines all JavaScript code inside the `generator.html` file using html-build. Please note that certain third-party dependencies, such as jQuery, Bootstrap and highlight.js, are linked externally (over the Internet).
108 | - Because the `discovery.etcd.io` service doesn't support CORS (see [this issue on GitHub](https://github.com/coreos/discovery.etcd.io/issues/12)), in order for the automatic generation of Discovery URLs to work we need to proxy the request. Without a backend server for the generator app, the best solution is to use a third-party service like [CrossOrigin.me](https://crossorigin.me/). etcd2 Discovery URLs aren't particularly sensitive information, so risks associated with using an external service are minimal. If you're concerned about security, you can deploy your own CORS proxy using the open source CrossOrigin.me code on your own machines, and change the url in the `cloud-config.source.js` file.
109 |
110 |
111 | ## TODO
112 |
113 | - [ ] Support Azure Premium Storage and Managed Disks
114 | - [ ] Switch WSREP engine from rsync to xtrabackup (see https://github.com/docker-library/mariadb/pull/47)
115 |
--------------------------------------------------------------------------------
/azure-architecture.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/ItalyPaleAle/mariadb-cluster/d63c6c50edb80e5385869fab12ab77718164d499/azure-architecture.png
--------------------------------------------------------------------------------
/generator.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 | Template generator
8 |
9 |
10 |
11 |
12 |
13 |
14 |
15 |
16 |
17 |