Table of Contents
- 🚀 Quick Start Guide
- 📚 Prerequisites
- 🛠️ Preparing the Deployment Host
- 1. Install Dependencies
- 2. Set Up a Python Virtual Environment
- 3. Ensure Latest Version of pip
- 4. Install Ansible
- 5. Create Directory Structure
- 6. Configure Ansible
- 7. Install the Hashistack-Ansible Collection
- 8. Install Additional Dependencies
- 9. Set Up Inventory and Configuration Files
- 🔐 Generate Credentials
- ✅ Running Preflight Checks and Bootstrap Playbooks
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
🚀 Quick Start Guide
Welcome to the Hashistack-Ansible Quick Start Guide! This guide will help you get your environment ready to deploy HashiCorp product clusters (Nomad, Consul, Vault) with ease.
📚 Prerequisites
📖 Recommended Readings
Before diving in, it’s helpful to familiarize yourself with the basics of:
🖥️ Supported Operating Systems
We officially support the following operating systems:
- Debian
- 11 (Bullseye)
- 12 (Bookworm)
- Ubuntu
- 20.04 (Focal)
- 22.04 (Jammy)
- 24.04 (Noble)
Other Debian-based distributions might work, but they are not tested and may break with updates.
🌐 Target Hosts
Target hosts are the machines where you’ll be deploying your clusters. They should meet the following minimum requirements:
🚨 Must-Haves:
- SSH Access: Ensure target hosts are reachable via SSH by the deployment node (the machine running the Ansible playbooks). The user must have privilege escalation (e.g., sudo).
- Network Communication: Hosts must communicate with each other based on your cluster topology (e.g., Vault hosts must all reach each other).
- Time Sync: Hosts should be synced to a common time source.
- Low Latency: Ensure less than 10ms of latency between hosts (crucial for the Raft consensus algorithm).
- Systemd: Hosts must use systemd as their init system.
⭐ Recommendations:
- Two Network Interfaces:
- One public-facing for client-to-server traffic.
- One private for server-to-server and deployment-to-server communications.
- Memory: At least 8GB of RAM (more for larger scale setups).
- Disk Space: Minimum of 40GB of free disk space.
🛠️ Preparing the Deployment Host
Follow these steps to prepare your deployment host:
1. Install Dependencies
Start by installing the necessary packages:
sudo apt update
sudo apt install git python3-dev libffi-dev gcc libssl-dev python3-venv
2. Set Up a Python Virtual Environment
Create and activate a Python virtual environment to isolate your setup:
python3 -m venv /path/to/venv
source /path/to/venv/bin/activate
3. Ensure Latest Version of pip
Update pip to the latest version:
pip install -U pip
4. Install Ansible
Hashistack-Ansible requires at least Ansible 7 (or ansible-core 2.15):
pip install 'ansible>=7'
5. Create Directory Structure
Organize your project with the following structure (optional but recommended):
mkdir -p etc/hashistack collections inventory roles
touch ansible.cfg
Your directory should look like this:
.
├── ansible.cfg
├── collections
├── etc
│ └── hashistack
├── inventory
└── roles
6. Configure Ansible
Edit your ansible.cfg file to include the minimum required settings:
[defaults]
roles_path = ./roles/
collections_path = ./collections/
inventory = ./inventory/
7. Install the Hashistack-Ansible Collection
Install the ednz_cloud.hashistack collection:
ansible-galaxy collection install git+https://github.com/ednxzu/hashistack.git,tags/<version>
This will create a directory under ./collections/ansible_collections/ednz_cloud/hashistack.
8. Install Additional Dependencies
Some roles aren’t packaged with the collection, so you’ll need to install them:
ansible-galaxy install -r ./collections/ansible_collections/ednz_cloud/hashistack/roles/requirements.yml
These roles will be installed inside ./roles/.
9. Set Up Inventory and Configuration Files
Copy the sample inventory and global configuration files to your local environment:
cp collections/ansible_collections/ednz_cloud/hashistack/playbooks/inventory/multinode.ini inventory/
cp collections/ansible_collections/ednz_cloud/hashistack/playbooks/group_vars/all/globals.yml etc/hashistack/globals.yml
🔐 Generate Credentials
Before deploying your infrastructure, you need to generate credentials for cluster bootstrapping:
ansible-playbook -i inventory/inventory.ini ednz_cloud.hashistack.credentials.yml
This will create and populate etc/hashistack/secrets/credentials.yml.
Warning
This file contains root tokens and other sensitive credentials for Consul and Nomad clusters. Handle it with care!
Vault credentials will be generated during the Vault cluster bootstrap process and stored in etc/hashistack/secrets/vault.yml.
Note
Encrypt these sensitive files before committing them to source control using ansible-vault or sops.
✅ Running Preflight Checks and Bootstrap Playbooks
To ensure everything is correctly set up, run the bootstrap and preflight playbooks:
ansible-playbook -i inventory/inventory.ini ednz_cloud.hashistack.bootstrap.yml
ansible-playbook -i inventory/inventory.ini ednz_cloud.hashistack.preflight.yml
These playbooks will perform checks and installations to prepare your target hosts and deployment environment.
You're now all set to deploy your HashiStack clusters! 🎉