Ansible Playbooks for Rancher Hosts
This is a series of playbooks designed to quickly bring up a Rancher environment.
This is an overview of how the project behaves. For specific instructions on installing and using these playbooks with static and dynamic inventories, please see INSTALL.md.
NOTE: This is a work in progress. As of this writing it will provision an Ubuntu 16.04 environment with static hosts or dynamic hosts in EC2.
In the future it will adapt to RHEL/CentOS/Ubuntu/Debian according to the system where the playbooks run. It will also grow to support other providers with dynamic inventory support.
Prerequisites
Install Python
Ubuntu 16.04 doesn't come with Python installed by default. You can either
install it manually after booting the instances, or you can add the following
to cloud-config:
#!/bin/bash
apt-get -qq update
apt-get -qq -y install python-pip
Alternatively, add the following:
#cloud-config
package_upgrade: true
package_update: true
packages:
- curl
- python
- python-pip
Ansible Vault
This project uses the Ansible Vault
for storing private information. There is a sample vault provided with this
repository. The password is ansible and can be changed by following the
instructions on rekeying located here.
If you wish to skip using the Vault and instead store passwords in plaintext
in the various configuration files, you can do so by removing all references to
private.yml from the vars_files key in any YAML file in the root of the
project (e.g. rancher.yml, haproxy.yml, etc.)
Prior to removing this file, copy its variables out to another variable file,
such as group_vars/all.yml.
Inventory
The project uses a mixture of static and dynamic inventory. Static entries
go into static_server and static_node in inventory/hosts. Dynamic
hosts will be brought in and added to their corresponding groups. All hosts
and groups will then be collected into server:children,
loadbalancer:children, and node:children for processing by the playbooks
themselves.
Supported Inventory Systems
- Static
- EC2
Enabling Dynamic Inventory Systems
Dynamic inventory provider scripts and their configuration files are stored in inventory_providers. To activate one or more of them, symlink them to the inventory directory:
$ cd inventory
$ ln -s ../inventory_providers/ec2.py ec2.py
EC2
See INSTALL_EC2.md
Playbooks
All playbooks are included in site.yml. To execute a full run:
$ ansible-playbook site.yml
Note: you won't be able to run a server and node install in the first run. You will need to install the server and then configure API keys in the Vault.
Optionally, you can filter by one or more roles:
$ ansible-playbook --limit node site.yml
Individual playbooks can be run as outlined below.
Rancher
This playbook installs the version of Docker indicated in group_vars/all.yml
on hosts with a role tag of server or node. It goes on to install
Rancher Server on all hosts with role set to server. If the role is set to node, and if there are API keys for the environment located in the
Vault, it will register nodes with the Rancher server.
The Rancher configuration in group_vars/server.yml designates the
architecture:
- single node, internal database
- single node, external database
- single node, bind-mount database
- single node, force HA
- sets external database
- use this if you want HA and will add additional servers later
Ansible will automatically configure Rancher to use an external database if any of the following are true:
use_external_dbistrueforce_haistrue- more than one instance has a tag of
role=server
If Rancher Server will use an external database, set the database parameters
in group_vars/server.yml and set the db_pass in the Vault.
Ansible will perform sanity checks and fail if the database parameters are missing, but it will not test that the parameters are actually correct.
Ansible will create the database and its user if needed.
See INSTALL.md for more information about automatic host registration.
To run the Rancher playbook on its own, execute:
$ ansible-playbook rancher.yml
HAProxy
This playbook installs HAProxy on hosts with role set to loadbalancer, or
if no hosts exist with this tag, it will install HAProxy on hosts with role
set to server. The latter is only appropriate for single-server
environments. If you are running Rancher in an HA configuration, create
additional instances tagged with role=loadbalancer and change haproxy.yml
to run on nodes with this tag.
NOTE: If you wish to disable HAProxy entirely, set haproxy_enabled to false in
vars/default.yml.
After installing HAProxy this playbook then configures it for SSL termination using the certificate stored in the Vault. The certificate provided in the vault is a self-signed certificate for a fake domain - please replace it with your own certificate.
HAProxy performs pass-through TCP proxying to Rancher Server using the Proxy protocol. This absolves us of the need to have HAProxy perform additional analysis of the content to enable Websockets or GRPC communication between the server and the nodes.
Ansible will automatically populate haproxy.cfg with the internal IPs of
all Rancher servers (members of the server group). Should these IPs change
(e.g. if servers are added or removed), or if you need to rebuild the
configuration (such as if you change the certificate), simply re-run this
playbook:
$ ansible-playbook --tags config haproxy.yml
Alternative Post-Install Node Setup (optional)
This section applies if you do not use these playbooks to register your nodes with Rancher automatically.
Since you already have an Ansible environment that knows your hosts by their EC2 tag, you can use this to install the Rancher Agent onto your nodes.
After logging into the server and configuring access control, select your environment and add a node. Copy the command that Rancher gives you and use it from your Ansible control station:
$ ansible node -a "<command>"
This will reach out to all of your nodes in parallel and instruct them to install the agent. Within a few moments you'll see them appear in the UI.