From 59b8002e329d4b0b2c89c7a8e6529d984be98e98 Mon Sep 17 00:00:00 2001 From: Bertrand Lanson Date: Fri, 5 Jan 2024 22:25:50 +0100 Subject: [PATCH] feat(docs): started working on documentation for the collection --- .gitignore | 2 +- docs/quick_start.md | 95 ++++++++++++++ docs/vault_clusters.md | 7 ++ .../etc/hashistack/globals.yml | 119 ++++++++++++++++++ .../etc/hashistack/vault_servers/.gitkeep | 0 playbooks/preflight.yml | 4 - roles/requirements.yml | 8 ++ 7 files changed, 230 insertions(+), 5 deletions(-) create mode 100644 docs/quick_start.md create mode 100644 docs/vault_clusters.md create mode 100644 molecule/no_tls_multi_node/etc/hashistack/globals.yml create mode 100644 molecule/no_tls_multi_node/etc/hashistack/vault_servers/.gitkeep create mode 100644 roles/requirements.yml diff --git a/.gitignore b/.gitignore index d3ac8ef..dbdf997 100644 --- a/.gitignore +++ b/.gitignore @@ -2,4 +2,4 @@ **/__pycache__ .vscode roles/ednxzu.* -etc* \ No newline at end of file +vault_config \ No newline at end of file diff --git a/docs/quick_start.md b/docs/quick_start.md new file mode 100644 index 0000000..3c03ab7 --- /dev/null +++ b/docs/quick_start.md @@ -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 + +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/ +``` \ No newline at end of file diff --git a/docs/vault_clusters.md b/docs/vault_clusters.md new file mode 100644 index 0000000..57799e5 --- /dev/null +++ b/docs/vault_clusters.md @@ -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. diff --git a/molecule/no_tls_multi_node/etc/hashistack/globals.yml b/molecule/no_tls_multi_node/etc/hashistack/globals.yml new file mode 100644 index 0000000..c1e93ae --- /dev/null +++ b/molecule/no_tls_multi_node/etc/hashistack/globals.yml @@ -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 }}" diff --git a/molecule/no_tls_multi_node/etc/hashistack/vault_servers/.gitkeep b/molecule/no_tls_multi_node/etc/hashistack/vault_servers/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/playbooks/preflight.yml b/playbooks/preflight.yml index 35c57b4..3d7013f 100644 --- a/playbooks/preflight.yml +++ b/playbooks/preflight.yml @@ -101,10 +101,6 @@ when: - enable_consul | bool - - name: "Debug" - ansible.builtin.debug: - msg: "{{ _stat_config_dir_vault_servers }}" - - name: "Make sure directory exists: {{ sub_configuration_directories.vault_servers }}" ansible.builtin.assert: that: diff --git a/roles/requirements.yml b/roles/requirements.yml new file mode 100644 index 0000000..25bb7bb --- /dev/null +++ b/roles/requirements.yml @@ -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