Update 02 quick start
parent
9f036fb357
commit
497bb3c9c0
@ -1,163 +1,163 @@
|
|||||||
# 🚀 Quick Start Guide
|
# 🚀 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.
|
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
|
## 📚 Prerequisites
|
||||||
|
|
||||||
### 📖 Recommended Readings
|
### 📖 Recommended Readings
|
||||||
Before diving in, it’s helpful to familiarize yourself with the basics of:
|
Before diving in, it’s helpful to familiarize yourself with the basics of:
|
||||||
- [Ansible](https://docs.ansible.com/)
|
- [Ansible](https://docs.ansible.com/)
|
||||||
- [Nomad](https://developer.hashicorp.com/nomad/docs)
|
- [Nomad](https://developer.hashicorp.com/nomad/docs)
|
||||||
- [Consul](https://developer.hashicorp.com/consul/docs)
|
- [Consul](https://developer.hashicorp.com/consul/docs)
|
||||||
- [Vault](https://developer.hashicorp.com/vault/docs)
|
- [Vault](https://developer.hashicorp.com/vault/docs)
|
||||||
|
|
||||||
### 🖥️ Supported Operating Systems
|
### 🖥️ Supported Operating Systems
|
||||||
We officially support the following operating systems:
|
We officially support the following operating systems:
|
||||||
- **Debian**
|
- **Debian**
|
||||||
- 11 (Bullseye)
|
- 11 (Bullseye)
|
||||||
- 12 (Bookworm)
|
- 12 (Bookworm)
|
||||||
- **Ubuntu**
|
- **Ubuntu**
|
||||||
- 20.04 (Focal)
|
- 20.04 (Focal)
|
||||||
- 22.04 (Jammy)
|
- 22.04 (Jammy)
|
||||||
- 24.04 (Noble)
|
- 24.04 (Noble)
|
||||||
|
|
||||||
> Other Debian-based distributions might work, but they are **not tested** and may break with updates.
|
> Other Debian-based distributions might work, but they are **not tested** and may break with updates.
|
||||||
|
|
||||||
### 🌐 Target Hosts
|
### 🌐 Target Hosts
|
||||||
|
|
||||||
Target hosts are the machines where you’ll be deploying your clusters. They should meet the following minimum requirements:
|
Target hosts are the machines where you’ll be deploying your clusters. They should meet the following minimum requirements:
|
||||||
|
|
||||||
#### 🚨 Must-Haves:
|
#### 🚨 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).
|
- **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).
|
- **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.
|
- **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).
|
- **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.
|
- **Systemd:** Hosts must use systemd as their init system.
|
||||||
|
|
||||||
#### ⭐ Recommendations:
|
#### ⭐ Recommendations:
|
||||||
- **Two Network Interfaces:**
|
- **Two Network Interfaces:**
|
||||||
- One public-facing for client-to-server traffic.
|
- One public-facing for client-to-server traffic.
|
||||||
- One private for server-to-server and deployment-to-server communications.
|
- One private for server-to-server and deployment-to-server communications.
|
||||||
- **Memory:** At least 8GB of RAM (more for larger scale setups).
|
- **Memory:** At least 8GB of RAM (more for larger scale setups).
|
||||||
- **Disk Space:** Minimum of 40GB of free disk space.
|
- **Disk Space:** Minimum of 40GB of free disk space.
|
||||||
|
|
||||||
## 🛠️ Preparing the Deployment Host
|
## 🛠️ Preparing the Deployment Host
|
||||||
|
|
||||||
Follow these steps to prepare your deployment host:
|
Follow these steps to prepare your deployment host:
|
||||||
|
|
||||||
### 1. Install Dependencies
|
### 1. Install Dependencies
|
||||||
Start by installing the necessary packages:
|
Start by installing the necessary packages:
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
sudo apt update
|
sudo apt update
|
||||||
sudo apt install git python3-dev libffi-dev gcc libssl-dev python3-venv
|
sudo apt install git python3-dev libffi-dev gcc libssl-dev python3-venv
|
||||||
```
|
```
|
||||||
|
|
||||||
### 2. Set Up a Python Virtual Environment
|
### 2. Set Up a Python Virtual Environment
|
||||||
Create and activate a Python virtual environment to isolate your setup:
|
Create and activate a Python virtual environment to isolate your setup:
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
python3 -m venv /path/to/venv
|
python3 -m venv /path/to/venv
|
||||||
source /path/to/venv/bin/activate
|
source /path/to/venv/bin/activate
|
||||||
```
|
```
|
||||||
|
|
||||||
### 3. Ensure Latest Version of pip
|
### 3. Ensure Latest Version of pip
|
||||||
Update pip to the latest version:
|
Update pip to the latest version:
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
pip install -U pip
|
pip install -U pip
|
||||||
```
|
```
|
||||||
|
|
||||||
### 4. Install Ansible
|
### 4. Install Ansible
|
||||||
Hashistack-Ansible requires at least Ansible **7** (or ansible-core **2.15**):
|
Hashistack-Ansible requires at least Ansible **7** (or ansible-core **2.15**):
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
pip install 'ansible-core>=2.15'
|
pip install 'ansible-core>=2.15'
|
||||||
```
|
```
|
||||||
|
|
||||||
### 5. Create Directory Structure
|
### 5. Create Directory Structure
|
||||||
Organize your project with the following structure (optional but recommended):
|
Organize your project with the following structure (optional but recommended):
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
mkdir -p etc/hashistack collections inventory roles
|
mkdir -p etc/hashistack collections inventory roles
|
||||||
touch ansible.cfg
|
touch ansible.cfg
|
||||||
```
|
```
|
||||||
|
|
||||||
Your directory should look like this:
|
Your directory should look like this:
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
.
|
.
|
||||||
├── ansible.cfg
|
├── ansible.cfg
|
||||||
├── collections
|
├── collections
|
||||||
├── etc
|
├── etc
|
||||||
│ └── hashistack
|
│ └── hashistack
|
||||||
├── inventory
|
├── inventory
|
||||||
└── roles
|
└── roles
|
||||||
```
|
```
|
||||||
|
|
||||||
### 6. Configure Ansible
|
### 6. Configure Ansible
|
||||||
Edit your `ansible.cfg` file to include the minimum required settings:
|
Edit your `ansible.cfg` file to include the minimum required settings:
|
||||||
|
|
||||||
```ini
|
```ini
|
||||||
[defaults]
|
[defaults]
|
||||||
roles_path = ./roles/
|
roles_path = ./roles/
|
||||||
collections_path = ./collections/
|
collections_path = ./collections/
|
||||||
inventory = ./inventory/
|
inventory = ./inventory/
|
||||||
```
|
```
|
||||||
|
|
||||||
### 7. Install the Hashistack-Ansible Collection
|
### 7. Install the Hashistack-Ansible Collection
|
||||||
Install the `ednz_cloud.hashistack` collection:
|
Install the `ednz_cloud.hashistack` collection:
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
ansible-galaxy collection install git+https://github.com/ednz-cloud/hashistack.git,<version>
|
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`.
|
This will create a directory under `./collections/ansible_collections/ednz_cloud/hashistack`.
|
||||||
|
|
||||||
### 8. Install Additional Dependencies
|
### 8. Install Additional Dependencies
|
||||||
Some roles aren’t packaged with the collection, so you’ll need to install them:
|
Some roles aren’t packaged with the collection, so you’ll need to install them:
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
ansible-galaxy install -r ./collections/ansible_collections/ednz_cloud/hashistack/roles/requirements.yml
|
ansible-galaxy install -r ./collections/ansible_collections/ednz_cloud/hashistack/roles/requirements.yml
|
||||||
```
|
```
|
||||||
|
|
||||||
These roles will be installed inside `./roles/`.
|
These roles will be installed inside `./roles/`.
|
||||||
|
|
||||||
### 9. Set Up Inventory and Configuration Files
|
### 9. Set Up Inventory and Configuration Files
|
||||||
Copy the sample inventory and global configuration files to your local environment:
|
Copy the sample inventory and global configuration files to your local environment:
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
cp collections/ansible_collections/ednz_cloud/hashistack/playbooks/inventory/multinode.ini inventory/
|
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
|
cp collections/ansible_collections/ednz_cloud/hashistack/playbooks/group_vars/all/globals.yml etc/hashistack/globals.yml
|
||||||
```
|
```
|
||||||
|
|
||||||
## 🔐 Generate Credentials
|
## 🔐 Generate Credentials
|
||||||
|
|
||||||
Before deploying your infrastructure, you need to generate credentials for cluster bootstrapping:
|
Before deploying your infrastructure, you need to generate credentials for cluster bootstrapping:
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
ansible-playbook -i inventory/inventory.ini ednz_cloud.hashistack.credentials.yml
|
ansible-playbook -i inventory/inventory.ini ednz_cloud.hashistack.credentials.yml
|
||||||
```
|
```
|
||||||
|
|
||||||
This will create and populate `etc/hashistack/secrets/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!
|
> [!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`.
|
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).
|
> [!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
|
## ✅ Running Preflight Checks and Bootstrap Playbooks
|
||||||
|
|
||||||
To ensure everything is correctly set up, run the `bootstrap` and `preflight` playbooks:
|
To ensure everything is correctly set up, run the `bootstrap` and `preflight` playbooks:
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
ansible-playbook -i inventory/inventory.ini ednz_cloud.hashistack.bootstrap.yml
|
ansible-playbook -i inventory/inventory.ini ednz_cloud.hashistack.bootstrap.yml
|
||||||
ansible-playbook -i inventory/inventory.ini ednz_cloud.hashistack.preflight.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.
|
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! 🎉
|
You're now all set to deploy your HashiStack clusters! 🎉
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user