docs: Add initial documentation

docs/configuration.md

@@ -0,0 +1,27 @@
+# Configuration
+
+This set of playbooks can be configured through the following files:
+- `inventory/group_vars/all.yml`
+- `inventory/vars/main.yaml`
+- `inventory/vars/unprovisioned.yml`
+
+## Base user
+If you did not install your machines using processes from the [ISO repository](https://git.halis.io/athens-school/iso-repository), you will need to adapt the user configuration in `inventory/vars/unprovisioned.yml` to your initial user.
+
+## SSH Ports
+It is recommended to change the default SSH port for security reasons. 
+The ssh port can be configured in 2 steps:
+1. Change the `ansible_ssh_port` variable in `inventory/group_vars/all.yml`
+2. Change the `sshd_port` variable in `inventory/vars/unprovisioned.yml`
+
+`sshd_port` is used to configure the SSH port on the target machine, while `ansible_ssh_port` is used to configure the SSH port Ansible will use to connect to each host when running the unprovisioned playbook.
+
+## Wireguard port
+The default port for Wireguard is 51820. If you need to change it, you can do so by changing the `wireguard_port` variable in `inventory/group_vars/all.yml`.
+
+## K3s configuration
+All of the k3s configuration is done through the `inventory/group_vars/all/yml` file.
+
+You can update the `k3s_version` variable to install a specific version of k3s before running the playbooks.
+Other k3s configuration flags can be found under the `extra_server_args` and `extra_agent_args` variables.
+To learn more about the available flags, refer to the [k3s documentation](https://docs.k3s.io/cli/server).

docs/introduction.md

@@ -0,0 +1,43 @@
+# Halis Ansible
+
+This repository contains a collection of Ansible playbooks and roles to manage a k3s cluster, and its associated infrastructure.
+You will find a `Makefile` to help you run the playbooks, alongside some inventory templates for each use case.
+
+## Requirements
+Before you start, make sure you have the following packages installed:
+- `ansible-core`
+
+## Before you start
+### SSH connection
+Document the installation of the maintainer user through ssh keys (./inventory/vars/unprovisioned.yml), same for atmen user.
+### Secrets
+Before you get started, you will need to create one master secret:
+```bash
+tr -dc 'A-Za-z0-9!"#$%&'\''()*+,-./:;<=>?@[\]^_`{|}~' </dev/urandom | head -c 13; echo
+```
+or use any password generator from your favorite password manager.
+
+Keep this secret in a safe place, as it will be used to encrypt and decrypt your vault.
+
+Two files in `./vault` are used to store sensitive data:
+- `user_provisioning` contains default and maintainer user credentials
+- `secrets` ansible root password and k3s secret token
+
+They are formatted as follows:
+```
+# vault/user_provisioning
+vault_atmen_password: <atmen_password>
+vault_maintainer_user: <maintainer_user>
+vault_maintainer_password: <maintainer_password>
+```
+
+```
+# vault/secrets
+ansible_become_password: <atmen_password>
+token: <k3s_token>
+```
+
+
+## More configuration
+Read more in the [configuration](./configuration.md) section.
+

docs/inventory.md

@@ -0,0 +1,15 @@
+# Inventory
+
+The inventory is a list of hosts Ansible will manage, and how each of those hosts will be configured in term of networking, software and labeling.
+
+## Inventory templates
+
+This repository contains multiple inventory templates, each one adapted to its respective playbook.
+
+`./inventory/hosts.template.yml`
+
+This is the default inventory template, used for most playbooks to manage the k3s setup. It contains the following groups:
+ - server
+ - agent
+
+The `server` group contains the list of control plane nodes, while the `agent` group contains the list of worker nodes.

docs/k3s.md

@@ -0,0 +1,3 @@
+# K3s
+
+Coming soon !

docs/nas.md

@@ -0,0 +1,3 @@
+# NAS
+
+Coming soon !

docs/network.md

@@ -0,0 +1,3 @@
+# Network
+
+Coming soon !

docs/vault.md

@@ -0,0 +1,30 @@
+# Vault
+
+Before you get started, you will need to create one master secret:
+```bash
+tr -dc 'A-Za-z0-9!"#$%&'\''()*+,-./:;<=>?@[\]^_`{|}~' </dev/urandom | head -c 13; echo
+```
+or use any password generator from your favorite password manager.
+
+Keep this secret in a safe place, as it will be used to encrypt and decrypt your vault.
+
+Two files in `./vault` are used to store sensitive data:
+- `user_provisioning` contains default and maintainer user credentials
+- `secrets` ansible root password and k3s secret token
+
+They are formatted as follows:
+```
+# vault/user_provisioning
+vault_atmen_password: <atmen_password>
+vault_maintainer_user: <maintainer_user>
+vault_maintainer_password: <maintainer_password>
+```
+
+```
+# vault/secrets
+ansible_become_password: <atmen_password>
+token: <k3s_token>
+```
+
+## Note
+To avoid pasting your vault password everytime, you can create a `.vault_pass` file in the root directory with the vault password.