feat(docs): started working on documentation for the collection

This commit is contained in:
Bertrand Lanson 2024-01-05 22:25:50 +01:00
parent bb3513f6fe
commit 59b8002e32
7 changed files with 230 additions and 5 deletions

2
.gitignore vendored
View File

@ -2,4 +2,4 @@
**/__pycache__ **/__pycache__
.vscode .vscode
roles/ednxzu.* roles/ednxzu.*
etc* vault_config

95
docs/quick_start.md Normal file
View File

@ -0,0 +1,95 @@
# 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
Its 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
docs/vault_clusters.md Normal file
View File

@ -0,0 +1,7 @@
# Deploying a Vault cluster
This documentation explains each steps necessary to successfully deploy a Vault cluster using the ednxzu.hashistack ansible collection.
## Prerequisites
You should, before attempting any deployment, have read through the [Quick Start Guide](./quick_start.md). These steps are necessary in order to ensure smooth operations going forward.

View File

@ -0,0 +1,119 @@
---
##########################
# General options ########
##########################
# enable_vault: "yes"
# enable_consul: "yes"
# enable_nomad: "yes"
# deployment_method: "docker"
# api_interface: "eth0"
# api_interface_address: "{{ ansible_facts[api_interface]['ipv4']['address'] }}"
# configuration_directory: "{{ lookup('env', 'PWD') }}/etc/hashistack"
##########################
# Support options ########
##########################
# hashistack_supported_distributions:
# - ubuntu
# - debian
# hashistack_supported_distribution_versions:
# debian:
# - "11"
# - "12"
# ubuntu:
# - "20.04"
# - "22.04"
# preflight_enable_host_ntp_checks: true
# vault_required_ports: [8200,8201]
# consul_required_ports: [8300,8301,8302,8500,8501,8502,8503,8600]
# nomad_required_ports: []
##########################
# Nomad options ##########
##########################
# hashi_nomad_cni_plugins_install: true
# hashi_nomad_start_service: true
# hashi_nomad_cni_plugins_version: latest
# hashi_nomad_cni_plugins_install_path: /opt/cni/bin
# hashi_nomad_version: latest
# hashi_nomad_deploy_method: host # deployment method, either host or docker
# hashi_nomad_env_variables: {}
# hashi_nomad_data_dir: /opt/nomad
# hashi_nomad_extra_files: false
# hashi_nomad_extra_files_src: /tmp/extra_files
# hashi_nomad_extra_files_dst: /etc/nomad.d/extra_files
# #! nomad configuration
# hashi_nomad_configuration: {}
##########################
# Consul options #########
##########################
# hashi_consul_start_service: true
# hashi_consul_version: latest
# hashi_consul_deploy_method: host # deployment method, either host or docker.
# hashi_consul_env_variables: {}
# hashi_consul_data_dir: "/opt/consul"
# hashi_consul_extra_files: false
# hashi_consul_extra_files_src: /tmp/extra_files
# hashi_consul_extra_files_dst: /etc/consul.d/extra_files
# hashi_consul_envoy_install: false
# hashi_consul_envoy_version: latest
# #! consul configuration
# hashi_consul_configuration: {}
##########################
# Vault options ##########
##########################
# vault_cluster_name: vault
# vault_storage_configuration:
# raft:
# path: "{{ hashi_vault_data_dir }}/data"
# node_id: "{{ ansible_hostname }}"
# retry_join: |
# [
# {% for host in groups['vault_servers'] %}
# {
# 'leader_api_addr': 'http://{{ hostvars[host].api_interface_address }}:8200'
# }{% if not loop.last %},{% endif %}
# {% endfor %}
# ]
# extra_vault_container_volumes: []
# default_container_extra_volumes:
# - "/etc/timezone:/etc/timezone"
# - "/etc/localtime:/etc/localtime"
#hashi_vault_start_service: true
hashi_vault_version: "latest"
#hashi_vault_deploy_method: "{{ deployment_method }}" # deployment method, either host or docker
#hashi_vault_env_variables: {}
#hashi_vault_data_dir: "/opt/vault"
#hashi_vault_extra_files: false
#hashi_vault_extra_files_src: /tmp/extra_files
#hashi_vault_extra_files_dst: /etc/vault.d/extra_files
#hashi_vault_extra_container_volumes: "{{ default_container_extra_volumes | union(extra_vault_container_volumes) | unique }}"
##! vault configuration
#hashi_vault_configuration:
# cluster_name: "{{ vault_cluster_name }}"
# cluster_addr: "http://{{ api_interface_address }}:8201"
# api_addr: "http://{{ api_interface_address }}:8200"
# ui: true
# disable_mlock: false
# disable_cache: false
# listener:
# tcp:
# address: "0.0.0.0:8200"
# tls_disable: true
# #tls_disable_client_certs: true
# #tls_cert_file: "{{ hashi_vault_data_dir }}/tls/cert.pem"
# #tls_key_file: "{{ hashi_vault_data_dir }}/tls/key.pem"
# storage: "{{ vault_storage_configuration }}"

View File

@ -101,10 +101,6 @@
when: when:
- enable_consul | bool - enable_consul | bool
- name: "Debug"
ansible.builtin.debug:
msg: "{{ _stat_config_dir_vault_servers }}"
- name: "Make sure directory exists: {{ sub_configuration_directories.vault_servers }}" - name: "Make sure directory exists: {{ sub_configuration_directories.vault_servers }}"
ansible.builtin.assert: ansible.builtin.assert:
that: that:

8
roles/requirements.yml Normal file
View File

@ -0,0 +1,8 @@
---
# requirements file for ednxzu.hashistack
roles:
- name: ednxzu.manage_repositories
- name: ednxzu.manage_apt_packages
- name: ednxzu.manage_pip_packages
- name: ednxzu.install_docker
- name: ednxzu.docker_systemd_service