hcp-ansible/docs/quick_start.md

Quick Start Guide

This documentation will show you the preparation steps necessary to ensure that you environment is ready to deploy cluster(s).

Prerequisites

Recommended readings

It’s beneficial to learn basics of both Ansible and Docker(for docker deployments) before running Hashistack Ansible.

Operating

The only supported operating systems currently are:

• Debian
  • 11, Bullseye
  • 12, Bookworm
• Ubuntu
  • 20.04, Focal
  • 22.04, Jammy

Other Debian-based distributions might work, but are not tested, and may break at any given update.

Target Hosts

Target hosts are the hosts you are planning on deploying cluster(s) to.

These hosts must satisfy the following minimum requirements:

• Be reachable via ssh by the deployment node (the machine running the ansible playbooks), with a user that has the ability to escalate privileges.
• Be able to comunicate with each other, according to your cluster topology (vault hosts must all be able to reach each other, etc...)
• Be synced to a common time
• Have less than 10ms of latency to reach each other (raft consensus algorithm requirement)
• Be using systemd as their init system.

Ideally, hosts are recommended to satisfy the following recommendations:

• Have 2 network interfaces:
  • One that is public facing for client-to-server traffic
  • One that is not public facing for server-to-server and deployment-to-server communications
• Have a minimum of 8GB of memory (less will work, but the larger the scale, the higher the RAM requirements will be)
• Have a minimum of 40GB of free disk space

Prepare the deployment host

1. Install the virtual environment dependencies.

sudo apt update
sudo apt install git python3-dev libffi-dev gcc libssl-dev python3-venv

2. Create a python virtual environment and activate it.

python3 -m venv /path/to/venv
source /path/to/venv/bin/activate

3. Ensure the latest version of pip is installed

pip install -U pip

4. Install Ansible. Hashistack Ansible requires at least Ansible 7(or ansible-core 2.15)

pip install 'ansible-core>=2.15'

5. Create the directory structure. This is not required but heavily recommended.

mkdir -p etc/hashistack collections inventory roles
touch ansible.cfg

Your directory structure should look like this

.
├── ansible.cfg
├── collections
├── etc
│   └── hashistack
├── inventory
└── roles

6. Edit the ansible.cfg file with the minimum requirements.

[defaults]
roles_path = ./roles/
collections_path = ./collections/
inventory  = ./inventory/

7. Install the ednz_cloud.hashistack ansible collection

ansible-galaxy collection install ednz_cloud.hashistack:==<version>

You should now have a directory under ./collections/ansible_collections/ednz_cloud/hashistack

8. Install the other dependencies required by ednz_cloud.hashistack

ansible-galaxy install -r ./collections/ansible_collections/ednz_cloud/hashistack/roles/requirements.yml

This will install roles that are not packaged with the collection, but are still required in order to run the playbooks.

You should now have some roles inside ./roles/.