RanchHand

Deploy Rancher in HA mode onto existing hardware.

Design

This tool aims to automate the steps listed in Rancher's official HA Install documentation in a reproducable manner. It also enforces many of the recommendations given inside Rancher's hardening guide.

Usage

1. Ensure that the Rancher version is >= 2.6.
2. Download the latest release from GitHub.
3. Install Ansible (version >=2.8) locally
4. (optional) To update the Rancher default password, set the RANCHER_PASSWORD environment variable: export RANCHER_PASSWORD=<new password>
   1. (required) Configure ansible for proper output: export ANSIBLE_COW_SELECTION=random
5. Execute ansible-galaxy install -r ansible/requirements.yml to install dependencies
6. Execute ansible-playbook -i '1.2.4.5,...,10.20.30.40,' --private-key=~/.ssh/id_rsa --user=ubuntu ansible/prod.yml --diff --check to perform a dry run of all the changes.

Example

This example shows a manual run of the production playbook (prod.yml) from a local machine imaging a cluster behind a bastion/proxy server.

ansible-playbook -i '10.0.1.6,10.0.1.51,10.0.1.94,' --private-key=/Users/myhost/.ssh/id_rsa --user=ubuntu --ssh-common-args='-o StrictHostKeyChecking=no -o StrictHostKeyChecking=no -o ProxyCommand="ssh -o StrictHostKeyChecking=no -W %h:%p -q ubuntu@54.190.1.95"' ansible/prod.yml --diff

In the example above, only the bastion server, 54.190.1.95, is publicly accessible. However, including the Terraform module should be sufficient for most users.

Terraform

Using the Terraform module, you can leverage Ranchhand to create a Rancher cluster on a specific set of nodes.

module "ranchhand" {
  source = "github.com/dominodatalab/ranchhand"

  node_ips         = ["..."]
  working_dir      = "..."
  cert_dnsnames    = ["..."]
  cert_ipaddresses = ["..."]

  ssh_username   = "..."
  ssh_key_path   = "..."
  ssh_proxy_user = "..."
  ssh_proxy_host = "..."
}

Development

Please submit any feature enhancements, bug fixes, or ideas via pull requests or issues. If you need to test local changes e2e, you can do so using Vagrant and Virtualbox. Here are the recommended steps:

1. Make sure you have Vagrant and VirtualBox installed.

   brew cask install vagrant virtualbox

2. Create one or more VMs. For convenience, a pre-configured Vagrantfile is available.

   cd test/
   NODE_COUNT=N NODE_DISTRO="ubuntu_xenial|ubuntu_bionic|centos|rhel" vagrant up
   

3. Use ansible to launch a Ranchhand run against your VM(s) and verify your changes.

   ansible-galaxy install -r ansible/requirements.yml
   ansible-playbook -i '192.168.50.10,' \
     --private-key=~/.ssh/id_rsa \
     --ssh-common-args='-o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null' \
     --user=vagrant \
     -e "cert_names=DNS:localhost" \
     -e "node_count=1" \
     ansible/prod.yml \
     --diff
   

   Note the trailing comma (",") in the host/ip list.

Ansible References

Here are some helpful Ansible references for getting started with Ansible.

1. Ansible Overview
2. Installation Guide
3. Project Directory Layout
4. Roles
5. Best Practices

Contribute

Contributions are always welcome! Please submit any questions, bugs or changes via an issue or PR. Thank you.