feat: reorganize docs, enahance quick-start
parent
134d9e4ca7
commit
9f036fb357
SSH Key Fingerprint:
SHA256:/nqc6HGqld/PS208F6FUOvZlUzTS0rGpNNwR5O2bQBw
@ -14,11 +14,12 @@ Hashistack-Ansible's project aims at providing a production-ready, repeatable, a
|
||||
# Index
|
||||
|
||||
1. [Introduction](01-introduction)
|
||||
2. [General informations](02-general-informations)
|
||||
3. [Architecture Guide](03-architecture-guide)
|
||||
4. Service Configuration
|
||||
- [Consul](04-consul-configuration)
|
||||
- [Nomad](04-nomad-configuration)
|
||||
- [Vault](04-vault-configuration)
|
||||
- [Extras](04-extra-configuration)
|
||||
5. [TLS]()
|
||||
2. [Quick-Start Guide](02-quick-start)
|
||||
3. [General informations](10-general-informations)
|
||||
4. [Architecture Guide](11-architecture-guide)
|
||||
5. Service Configuration
|
||||
- [Consul](21-consul-configuration)
|
||||
- [Nomad](22-nomad-configuration)
|
||||
- [Vault](23-vault-configuration)
|
||||
- [Extras](24-extra-configuration)
|
||||
6. [TLS]()
|
||||
|
||||
163
02-quick-start.md
Normal file
163
02-quick-start.md
Normal file
@ -0,0 +1,163 @@
|
||||
# 🚀 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:
|
||||
- [Ansible](https://docs.ansible.com/)
|
||||
- [Nomad](https://developer.hashicorp.com/nomad/docs)
|
||||
- [Consul](https://developer.hashicorp.com/consul/docs)
|
||||
- [Vault](https://developer.hashicorp.com/vault/docs)
|
||||
|
||||
### 🖥️ 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:
|
||||
|
||||
```shell
|
||||
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:
|
||||
|
||||
```shell
|
||||
python3 -m venv /path/to/venv
|
||||
source /path/to/venv/bin/activate
|
||||
```
|
||||
|
||||
### 3. Ensure Latest Version of pip
|
||||
Update pip to the latest version:
|
||||
|
||||
```shell
|
||||
pip install -U pip
|
||||
```
|
||||
|
||||
### 4. Install Ansible
|
||||
Hashistack-Ansible requires at least Ansible **7** (or ansible-core **2.15**):
|
||||
|
||||
```shell
|
||||
pip install 'ansible-core>=2.15'
|
||||
```
|
||||
|
||||
### 5. Create Directory Structure
|
||||
Organize your project with the following structure (optional but recommended):
|
||||
|
||||
```shell
|
||||
mkdir -p etc/hashistack collections inventory roles
|
||||
touch ansible.cfg
|
||||
```
|
||||
|
||||
Your directory should look like this:
|
||||
|
||||
```shell
|
||||
.
|
||||
├── ansible.cfg
|
||||
├── collections
|
||||
├── etc
|
||||
│ └── hashistack
|
||||
├── inventory
|
||||
└── roles
|
||||
```
|
||||
|
||||
### 6. Configure Ansible
|
||||
Edit your `ansible.cfg` file to include the minimum required settings:
|
||||
|
||||
```ini
|
||||
[defaults]
|
||||
roles_path = ./roles/
|
||||
collections_path = ./collections/
|
||||
inventory = ./inventory/
|
||||
```
|
||||
|
||||
### 7. Install the Hashistack-Ansible Collection
|
||||
Install the `ednz_cloud.hashistack` collection:
|
||||
|
||||
```shell
|
||||
ansible-galaxy collection install git+https://github.com/ednz-cloud/hashistack.git,<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:
|
||||
|
||||
```shell
|
||||
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:
|
||||
|
||||
```shell
|
||||
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:
|
||||
|
||||
```shell
|
||||
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](https://docs.ansible.com/ansible/latest/cli/ansible-vault.html) or [sops](https://github.com/getsops/sops).
|
||||
|
||||
## ✅ Running Preflight Checks and Bootstrap Playbooks
|
||||
|
||||
To ensure everything is correctly set up, run the `bootstrap` and `preflight` playbooks:
|
||||
|
||||
```shell
|
||||
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! 🎉
|
||||
154
quick_start.md
154
quick_start.md
@ -1,154 +0,0 @@
|
||||
# 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](https://docs.ansible.com/) and [Docker](https://docs.docker.com/)(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.
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
```bash
|
||||
python3 -m venv /path/to/venv
|
||||
source /path/to/venv/bin/activate
|
||||
```
|
||||
|
||||
3. Ensure the latest version of pip is installed
|
||||
|
||||
```bash
|
||||
pip install -U pip
|
||||
```
|
||||
|
||||
4. Install [Ansible](http://www.ansible.com/). Hashistack-Ansible requires at least Ansible **7**(or ansible-core **2.15**)
|
||||
|
||||
```bash
|
||||
pip install 'ansible-core>=2.15'
|
||||
```
|
||||
|
||||
5. Create the directory structure. This is not required but **heavily** recommended.
|
||||
|
||||
```bash
|
||||
mkdir -p etc/hashistack collections inventory roles
|
||||
touch ansible.cfg
|
||||
```
|
||||
|
||||
Your directory structure should look like this
|
||||
|
||||
```bash
|
||||
.
|
||||
├── ansible.cfg
|
||||
├── collections
|
||||
├── etc
|
||||
│ └── hashistack
|
||||
├── inventory
|
||||
└── roles
|
||||
```
|
||||
|
||||
6. Edit the `ansible.cfg` file with the minimum requirements.
|
||||
|
||||
```bash
|
||||
[defaults]
|
||||
roles_path = ./roles/
|
||||
collections_path = ./collections/
|
||||
inventory = ./inventory/
|
||||
```
|
||||
|
||||
7. Install the `ednz_cloud.hashistack` ansible collection
|
||||
|
||||
```bash
|
||||
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`
|
||||
|
||||
```bash
|
||||
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/`.
|
||||
|
||||
9. Copy `inventory` file and `globals.yml `file locally
|
||||
|
||||
```bash
|
||||
cp collections/ansible_collections/ednz_cloud/hashistack/playbooks/inventory/multinode.ini inventory/
|
||||
```
|
||||
|
||||
```bash
|
||||
cp collections/ansible_collections/ednz_cloud/hashistack/playbooks/group_vars/all/globals.yml etc/hashistack/globals.yml
|
||||
```
|
||||
|
||||
## Generate Credentials
|
||||
|
||||
Before deploying your infrastructure with Hashistack-Ansible, you need to generate credentials that will be used to bootstrap the various clusters.
|
||||
|
||||
This can be done by running the `generate_credentials.yml` playbook.
|
||||
|
||||
```bash
|
||||
ansible-playbook -i inventory/inventory.ini ednz_cloud.hashistack.generate_credentials.yml
|
||||
```
|
||||
|
||||
This will create and populate `etc/hashistack/secrets/credentials.yml`
|
||||
|
||||
> [!WARNING]
|
||||
> This file is VERY SENSITIVE, as it holds the root tokens and other credentials for consul and nomad clusters.
|
||||
|
||||
This does not generate vault credentials, as it is not possible to generate those in advance. These credentials will be generated, if you enable the vault deployment, during the bootstrap process of the vault cluster, and stored in `etc/hashistack/secrets/vault.yml`
|
||||
|
||||
> [!WARNING]
|
||||
> It is HIGHLY recommended to encrypt these two files before enventually commiting them to source control. You can do so using tools like [ansible-vault](https://docs.ansible.com/ansible/latest/cli/ansible-vault.html) or [sops](https://github.com/getsops/sops).
|
||||
|
||||
## Running preflight checks and bootstrap playbooks
|
||||
|
||||
Before running the main deployment playbook, you might want to run the `bootstrap` and `preflight` playbooks, which do a number of checks to ensure all hosts are setup correctly for deployment.
|
||||
|
||||
```bash
|
||||
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 run a number of checks, and installations, in order to ensure the target hosts, as well as your deployment environment are correctly setup in order to install all the components.
|
||||
Loading…
Reference in New Issue
Block a user