diff --git a/02-quick-start.md b/02-quick-start.md index 796642d..b00e43b 100644 --- a/02-quick-start.md +++ b/02-quick-start.md @@ -1,163 +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, -``` - -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! πŸŽ‰ +# πŸš€ 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, +``` + +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! πŸŽ‰