Note
This document assumes you have a working Ansible installation. If you don’t, install Ansible before continuing. This can be done simply by running pip install -r requirements.txt from the root of the project.
It also assumes you have a working Terraform installation. You can download Terraform from Terraform downloads.
The Mantl project uses Ansible to bring up nodes and clusters. This generally means that you need three things:
The playbooks and roles in this project will work on whatever provider (or bare metal) you care to spin up, as long as it can run CentOS 7 or equivalent.
Your hosts will have to be accessible with your SSH key. If you’re unfamiliar with SSH keys, please read DigitalOcean’s guide to setting up SSH keys.
Here are some guides specific to each of the platforms that Mantl supports:
Community-supported platform: .. toctree:
:maxdepth:1
vsphere.rst
softplayer.rst
bare-metal.rst
There are several preparatory steps to provisioning the cloud hosts that are common to all providers:
You will need to copy the .tf file of the platform you are using from mantl/terraform/ to the root of the project. For example, mantl/terraform/openstack-modules.sample.tf will need to be copied to mantl/openstack-module-sample.tf. The variables in the copied .tf file will need to be changed to your configuration.
Note
More than one .tf file in the mantl directory will lead to errors upon deployment. Since Mantl initially does not support multiple datacenters, extra .tf files will need to be renamed or moved. If you would like to add multiple datacenters see the Consul docs for more information.
Running the security-setup script in the root directory will set up passwords, authentication, and certificates. For more information, see the security-setup script documentation.
Note
Ansible requres a Python 2 binary. If yours is not at /usr/bin/python, please view the Ansible FAQ. You can add an extra variable to the following commands, e.g. ansible -e ansible_python_interpreter=/path/to/python2.
The following steps assume that you have provisioned your cloud host by taking the steps listed in one of the guides above.
This project ships with a dynamic inventory file to read Terraform .tfstate files, terraform.py. If you are not running Ansible from the root directory or would like to use a custom inventory file, you can use the -i argument of ansible or ansible-playbook to specify the inventory file path.
ansible-playbook -i path/to/inventory -e @security.yml mantl.yml
For the next steps, you may want to add your password to the ssh-agent avoid re-entering your password.
ansible all -m ping
It may take a few minutes after running terraform for the servers to be reachable. If any servers fail to connect, you can check your connection by adding -vvvv for verbose SSH debugging to view the errors in more detail.
Warning
Due to updated packages in the recent CentOS 7 (1511) release, it is critical that you upgrade operating system packages on all servers before proceeding with the deployment:
ansible-playbook playbooks/upgrade-packages.yml
If you neglect to upgrade packages, you will likely experience multiple failures, particularly around Consul. See issues 907 and 927 for more details.
First, you will need to customize a playbook. A sample can be found at sample.yml in the root directory which you can copy to mantl.yml. You can find more about customizing this at playbooks. You’ll want to change consul_acl_datacenter to your preferred ACL datacenter. If you only have one datacenter, you can remove this variable.
Next, assuming you’ve placed the filled-out template at mantl.yml:
ansible-playbook -e @security.yml mantl.yml
The deployment will probably take a while as all tasks are completed.
Once your deployment has completed, you will be able to access the Mantl UI in your browser by connecting to one of the control nodes.
If you need the IP address of your nodes, you can use terraform.py:
$ python2 plugins/inventory/terraform.py --hostfile
## begin hosts generated by terraform.py ##
xxx.xxx.xxx.xxx mantl-control-01
xxx.xxx.xxx.xxx mantl-control-02
xxx.xxx.xxx.xxx mantl-control-03
xxx.xxx.xxx.xxx mantl-edge-01
xxx.xxx.xxx.xxx mantl-edge-02
xxx.xxx.xxx.xxx mantl-kubeworker-001
xxx.xxx.xxx.xxx mantl-kubeworker-002
xxx.xxx.xxx.xxx mantl-kubeworker-003
xxx.xxx.xxx.xxx mantl-worker-001
xxx.xxx.xxx.xxx mantl-worker-002
xxx.xxx.xxx.xxx mantl-worker-003
xxx.xxx.xxx.xxx mantl-worker-004
xxx.xxx.xxx.xxx mantl-worker-005
## end hosts generated by terraform.py ##
When you enter a control node’s IP address into your browser, you’ll likely get prompted about invalid security certificates (if you have SSL/TLS turned on). Follow your browser’s instructions on how to access a site without valid certs. Then, you will be presented with a basic access authentication prompt. The username and password for this are the ones generated by security-setup, and are stored in security.yml if you forgot them.
Here is what you should be looking at after you connect and authenticate:
Click the image to go to the GitHub project
Below are guides customizing your deployment:
To restart your deployment and make sure all components are restarted and working correctly, use the playbooks/reboot-hosts.yml playbook.
ansible-playbook playbooks/reboot-hosts.yml
You can also provision your cluster by running a docker container. See Using the Dockerfile for more information.