doc refactoring

wescale · Jul 3, 2024 · 6b66476 · 6b66476
1 parent 479f758
commit 6b66476
Show file tree

Hide file tree

Showing 59 changed files with 594 additions and 180 deletions.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -60,9 +60,15 @@
 #
 import os, sys, yaml2md
 
-ignore_role_list = ['cloudalchemy.grafana', 'cloudalchemy.node_exporter', 'cloudalchemy.prometheus', 'vault']
+ignore_role_list = [
+    'cloudalchemy.grafana',
+    'cloudalchemy.node_exporter',
+    'cloudalchemy.prometheus',
+    'wescale.hashistack.common_vars',
+    'vault'
+]
 roles_src_path = "../../roles"
-roles_doc_path = "reference/role"
+roles_doc_path = "reference/roles/role"
 
 for element in os.listdir(roles_src_path):
     if not os.path.isdir(roles_src_path + "/" + element + "/defaults") or element in ignore_role_list:

diff --git a/docs/source/reference/_playbooks.md b/docs/source/reference/_playbooks.md
@@ -4,11 +4,7 @@
 :maxdepth: 1
 playbooks/init
 playbooks/observability
-playbooks/vault_pt_manage
-playbooks/vault_dr_secondary
-playbooks/vault_kv_get
-playbooks/vault_kv_put
-playbooks/vault_tf_policies_samples
+playbooks/_ops_vault
 ```
 
 
diff --git a/docs/source/reference/_roles.md b/docs/source/reference/_roles.md
@@ -1,25 +1,25 @@
-# Ansible roles
+# Roles
 
 ```{toctree}
 :maxdepth: 1
-role_infra.md
-role_vault.md
-role_consul.md
-role_nomad.md
-role_envoy.md
-role_alloy.md
-role_loki.md
-role_prometheus.md
-role_grafana.md
-role_prometheus.md
-role_loki.md
-role_custom_ca.md
-role_stage0.md
-role_stage0_offline.md
-role_stage1_bootstrap.md
-role_stage1_dns.md
-role_stage1_rproxy.md
-role_stage1_pip.md
+roles/role_infra.md
+roles/role_vault.md
+roles/role_consul.md
+roles/role_nomad.md
+roles/role_envoy.md
+roles/role_alloy.md
+roles/role_loki.md
+roles/role_prometheus.md
+roles/role_grafana.md
+roles/role_prometheus.md
+roles/role_loki.md
+roles/role_custom_ca.md
+roles/role_stage0.md
+roles/role_stage0_offline.md
+roles/role_stage1_bootstrap.md
+roles/role_stage1_dns.md
+roles/role_stage1_rproxy.md
+roles/role_stage1_pip.md
 
 ```
 
diff --git a/docs/source/reference/playbooks/_ops_vault.md b/docs/source/reference/playbooks/_ops_vault.md
@@ -0,0 +1,12 @@
+# Vault operations
+
+```{toctree}
+:maxdepth: 1
+
+vault_dr_secondary
+vault_kv_get
+vault_kv_put
+vault_pt_manage
+vault_tf_policies_samples
+```
+
diff --git a/docs/source/reference/role_common.md b/docs/source/reference/role_common.md
diff --git a/docs/source/reference/role_envoy.md b/docs/source/reference/role_envoy.md
diff --git a/docs/source/reference/role_vault_sidecar.md b/docs/source/reference/role_vault_sidecar.md
diff --git a/docs/source/reference/role_alloy.md → docs/source/reference/roles/role_alloy.md b/docs/source/reference/role_alloy.md → docs/source/reference/roles/role_alloy.md
@@ -1,16 +1,15 @@
 
-```{include} ../../../roles/alloy/README.md
+```{include} ../../../../roles/alloy/README.md
 ```
 
-## Defaults
+## Role defaults
 
-
-Loki endpoint to forward metrics to.
+* Loki endpoint to forward metrics to.
 ```
 hs_alloy_loki_write_url: "http://grafana.{{ hs_public_domain }}:3100"
 
 ```
-Prometheus endpoint to forward metrics to.
+* Prometheus endpoint to forward metrics to.
 ```
 hs_alloy_prometheus_write_url: "http://grafana.{{ hs_public_domain }}:9090"
 
diff --git a/docs/source/reference/roles/role_common.md b/docs/source/reference/roles/role_common.md
@@ -0,0 +1,57 @@
+
+```{include} ../../../../roles/common_vars/README.md
+```
+
+## Role defaults
+
+```
+tf_action: apply
+
+hs_public_domain: >-
+  {{ hs_workspace | regex_replace('_', '-') }}.{{ hs_parent_domain }}
+
+```
+* ID of the vault node. MUST be different for every node in the cluster.
+```
+hs_node_id: >-
+  {{ inventory_hostname | regex_replace('_', '-') }}
+
+```
+* FQDN of the node on the network. MUST be different for every node in the cluster. MUST
+be solvable by any of the other nodes in the cluster.
+
+```
+hs_node_fqdn: >-
+  {{ hs_node_id }}.{{ hs_public_domain }}
+
+collection_root: "{{ (playbook_dir + '/../') | realpath }}"
+collection_tf_modules_dir: "{{ collection_root }}/terraform"
+
+hs_workspace_root: "{{ lookup('env', 'PWD') }}"
+hs_workspace_group_vars_root_dir: "{{ hs_workspace_root }}/group_vars"
+hs_workspace_host_vars_dir: "{{ hs_workspace_root }}/host_vars"
+hs_workspace_group_vars_dir: "{{ hs_workspace_root }}/group_vars/hashistack"
+hs_workspace_group_vars_dir_relative_dir: "./group_vars/hashistack"
+hs_workspace_sre_group_vars_dir: "{{ hs_workspace_root }}/group_vars/hashistack_sre"
+hs_workspace_tf_modules_dir: "{{ hs_workspace_root }}/terraform"
+hs_workspace_secrets_dir: "{{ hs_workspace_group_vars_dir }}/secrets"
+hs_workspace_secrets_dir_relative_dir: "{{ hs_workspace_group_vars_dir_relative_dir }}/secrets"
+hs_workspace_ssh_private_key_file: "{{ hs_workspace_secrets_dir }}/default.key"
+hs_workspace_ssh_private_key_file_relative_path: "{{ hs_workspace_secrets_dir_relative_dir }}/default.key"
+hs_workspace_ssh_public_key_file: "{{ hs_workspace_ssh_private_key_file }}.pub"
+hs_workspace_ssh_public_key_file_relative_path: "{{ hs_workspace_ssh_private_key_file_relative_path }}.pub"
+
+hs_workspace_group: "hashistack"
+hs_workspace_cluster_group: "hashistack_cluster"
+hs_workspace_masters_group: "hashistack_masters"
+hs_workspace_minions_group: "hashistack_minions"
+
+host_vars_dir: "{{ hs_workspace_host_vars_dir }}/{{ inventory_hostname }}"
+host_secrets_dir: "{{ host_vars_dir }}/secrets"
+
+tf_module_src: "{{ collection_tf_modules_dir }}/{{ tf_module_name }}/"
+tf_module_dest: "{{ hs_workspace_tf_modules_dir }}/{{ tf_module_name }}"
+
+glxclans_host_service_user_name: "caretaker"
+
+hs_install_vault_sidecar: true
diff --git a/docs/source/reference/role_consul.md → docs/source/reference/roles/role_consul.md b/docs/source/reference/role_consul.md → docs/source/reference/roles/role_consul.md
@@ -1,18 +1,16 @@
 
-```{include} ../../../roles/consul/README.md
+```{include} ../../../../roles/consul/README.md
 ```
 
-## Defaults
+## Role defaults
 
-* Version of the consul package to install.
-* Used to determine which archive to install according to the suffix like
-[in the official release repository](https://releases.hashicorp.com/consul/). For example,
+* Version of the consul package to install. Used to determine which archive to
+install according to the suffix like [in the official release repository](https://releases.hashicorp.com/consul/). For example,
 valid values are: '1.16.4', '1.17.0+ent', '1.17.2+ent.fips1402', etc.
-
 ```
 hs_consul_version: "1.17.2"
-```
 
+```
 ### Local paths
 
 * Path to local directory containing secrets to be uploaded to nodes.

diff --git a/docs/source/reference/role_custom_ca.md → .../source/reference/roles/role_custom_ca.md b/docs/source/reference/role_custom_ca.md → .../source/reference/roles/role_custom_ca.md
@@ -1,29 +1,25 @@
 
-```{include} ../../../roles/custom_ca/README.md
+```{include} ../../../../roles/custom_ca/README.md
 ```
 
 ## Role defaults
 
 * Local path where the ca certificate should be generated.
-
 ```
 hs_custom_ca_certificate: "{{ hs_workspace_secrets_dir }}/ca.cert.pem"
-```
 
+```
 * Local path where each node private key should be generated.
-
 ```
 hs_custom_ca_host_private_key: "{{ hs_workspace_secrets_dir }}/self.cert.key"
-```
 
+```
 * Local path where each node certificate should be generated.
-
 ```
 hs_custom_ca_host_certificate: "{{ hs_workspace_secrets_dir }}/self.cert.pem"
-```
 
+```
 * Local path where each node fullchain certificate should be generated.
-
 ```
 hs_custom_ca_host_fullchain_certificate: "{{ hs_workspace_secrets_dir }}/self.fullchain.cert.pem"
 
diff --git a/docs/source/reference/roles/role_envoy.md b/docs/source/reference/roles/role_envoy.md
@@ -0,0 +1,8 @@
+
+```{include} ../../../../roles/envoy/README.md
+```
+
+## Role defaults
+
+```
+envoy_version: "1.27.2"
diff --git a/docs/source/reference/role_grafana.md → docs/source/reference/roles/role_grafana.md b/docs/source/reference/role_grafana.md → docs/source/reference/roles/role_grafana.md
@@ -1,31 +1,31 @@
 
-```{include} ../../../roles/grafana/README.md
+```{include} ../../../../roles/grafana/README.md
 ```
 
-## defaults/main.yml
+## Role defaults
 
-Grafana API endpoint exposure. Will be used from ansible controller to configure
+* Grafana API endpoint exposure. Will be used from ansible controller to configure
 via API.
 ```
 hs_grafana_url: "https://{{ grafana_public_cluster_address }}"
 
 ```
-Enable/disable usage of custom CA file for Grafana API certificate validation.
+* Enable/disable usage of custom CA file for Grafana API certificate validation.
 ```
 hs_grafana_use_custom_ca: false
 
 ```
-Ansible controler path to custom CA file for API certificate validation.
+* Ansible controler path to custom CA file for API certificate validation.
 ```
 hs_grafana_custom_ca_cert: "{{ hs_workspace_secrets_dir }}/ca.cert.pem"
 
 ```
-Expected Grafana version to install.
+* Expected Grafana version to install.
 ```
 hs_grafana_version: "10.2.1"
 
 ```
-Ansible controler directory path where the role should
+* Ansible controler directory path where the role should
 copy terraform modules for configuration.
 ```
 hs_grafana_tf_work_dir: >-

diff --git a/docs/source/reference/role_infra.md → docs/source/reference/roles/role_infra.md b/docs/source/reference/role_infra.md → docs/source/reference/roles/role_infra.md
@@ -1,29 +1,32 @@
-```{include} ../../../roles/infra/README.md
+```{include} ../../../../roles/infra/README.md
 ```
 
 ## Role defaults
 
-Name of the hashistack instance.
+* Name of the hashistack instance.
 ```
 hs_infra_workspace: "{{ hs_workspace }}"
 
 ```
-The only provider supported so far is the default.
+* The only provider supported so far is the default.
 ```
 hs_infra_flavor: "scw_one"
 
 ```
-Directory in which the role will copy its terraform module sources.
+* Directory in which the role will copy its terraform module sources.
 ```
 hs_infra_tf_modules_dir: "{{ hs_workspace_tf_modules_dir }}"
 
+```
+* Local directory for secrets storage
+```
+hs_infra_local_secrets_dir: "{{ hs_workspace_secrets_dir }}"
+
 ```
 ## Terraform variables
 
-Atomic configuration variables for all flavors.
 ```
 hs_infra_private_key_file: "{{ hs_workspace_ssh_private_key_file }}"
-hs_infra_local_secrets_dir: "{{ hs_workspace_secrets_dir }}"
 hs_infra_local_hs_group_vars_dir: "{{ hs_workspace_group_vars_dir }}"
 hs_infra_local_hs_sre_group_vars_dir: "{{ hs_workspace_sre_group_vars_dir }}"
 hs_infra_local_expected_dirs:

diff --git a/docs/source/reference/role_loki.md → docs/source/reference/roles/role_loki.md b/docs/source/reference/role_loki.md → docs/source/reference/roles/role_loki.md
@@ -1,8 +1,8 @@
 
-```{include} ../../../roles/loki/README.md
+```{include} ../../../../roles/loki/README.md
 ```
 
-## Defaults
+## Role defaults
 
 ```
 loki_cluster_address: localhost

diff --git a/docs/source/reference/role_nomad.md → docs/source/reference/roles/role_nomad.md b/docs/source/reference/role_nomad.md → docs/source/reference/roles/role_nomad.md
@@ -1,8 +1,8 @@
 
-```{include} ../../../roles/nomad/README.md
+```{include} ../../../../roles/nomad/README.md
 ```
 
-## Defaults
+## Role defaults
 
 ```
 hs_nomad_datacenter_name: "{{ hs_workspace }}"

diff --git a/docs/source/reference/role_prometheus.md → ...source/reference/roles/role_prometheus.md b/docs/source/reference/role_prometheus.md → ...source/reference/roles/role_prometheus.md
@@ -1,8 +1,8 @@
 
-```{include} ../../../roles/prometheus/README.md
+```{include} ../../../../roles/prometheus/README.md
 ```
 
-## Defaults
+## Role defaults
 
 ```
 hs_prometheus_scrape_configs: []

diff --git a/docs/source/reference/role_stage0.md → docs/source/reference/roles/role_stage0.md b/docs/source/reference/role_stage0.md → docs/source/reference/roles/role_stage0.md
@@ -1,12 +1,7 @@
 
-```{include} ../../../roles/stage0/README.md
+```{include} ../../../../roles/stage0/README.md
 ```
 
-## External variables dependencies
-
-* `hs_workspace_root` defined in `{{ playbook_dir }}/group_vars/all.yml`
-* `tf_action` defined in `{{ playbook_dir }}/group_vars/all.yml`
-
 ## Role defaults
 
 Name of the hashistack instance. Defaults to a variable: