diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..8f5508e --- /dev/null +++ b/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). diff --git a/docs/introduction.md b/docs/introduction.md new file mode 100644 index 0000000..61026ec --- /dev/null +++ b/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!"#$%&'\''()*+,-./:;<=>?@[\]^_`{|}~' +vault_maintainer_user: +vault_maintainer_password: +``` + +``` +# vault/secrets +ansible_become_password: +token: +``` + + +## More configuration +Read more in the [configuration](./configuration.md) section. + diff --git a/docs/inventory.md b/docs/inventory.md new file mode 100644 index 0000000..75ff1d0 --- /dev/null +++ b/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. diff --git a/docs/k3s.md b/docs/k3s.md new file mode 100644 index 0000000..094753d --- /dev/null +++ b/docs/k3s.md @@ -0,0 +1,3 @@ +# K3s + +Coming soon ! diff --git a/docs/nas.md b/docs/nas.md new file mode 100644 index 0000000..7a7544b --- /dev/null +++ b/docs/nas.md @@ -0,0 +1,3 @@ +# NAS + +Coming soon ! diff --git a/docs/network.md b/docs/network.md new file mode 100644 index 0000000..d365b61 --- /dev/null +++ b/docs/network.md @@ -0,0 +1,3 @@ +# Network + +Coming soon ! diff --git a/docs/node.md b/docs/node.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/vault.md b/docs/vault.md new file mode 100644 index 0000000..c1aa4a3 --- /dev/null +++ b/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!"#$%&'\''()*+,-./:;<=>?@[\]^_`{|}~' +vault_maintainer_user: +vault_maintainer_password: +``` + +``` +# vault/secrets +ansible_become_password: +token: +``` + +## Note +To avoid pasting your vault password everytime, you can create a `.vault_pass` file in the root directory with the vault password.