docs: overhaul SOPS documentation for better structure and readability

docs/guides/create-new-web-service-vm.md

@@ -57,7 +57,7 @@ As the first step, we need to make the host known to Ansible.
 
 ## Ansible-Pull Configuration
 
-Since you added your host to the `ansible_pull_hosts`, you also need to follow [Setting Up Secrets Using SOPS for a New Host](/docs/setting_up_secrets_using_sops_for_a_new_host.md) before continuing.
+Since you added your host to the `ansible_pull_hosts`, you also need to follow [SOPS: New Host](./sops-new-host.md) before continuing.
 
 ## Service-specific config
 

docs/guides/setting_up_secrets_using_sops_for_a_new_host.md

@@ -1,33 +0,0 @@
-# Setting Up Secrets Using SOPS for a New Host
-
-Because we're using the `community.sops.sops` vars plugin, the SOPS-encrypted secrets get stored in the inventory.
-
-1. Create a new age key for Ansible pull on the host.
-   ```
-   age-keygen
-   ```
-   Then add the public key part under `keys.hosts.chaosknoten.age` in [.sops.yaml](../.sops.yaml).
-2. Add a new creation rule for the hosts `host_vars` file in the sops config at `.sops.yaml`.
-   It should probably hold all admin keys plus the host entry you just added.
-   You can use existing creation rules as a reference.
-3. Re-encrypt existing files with the new key (manly `group_var/all.sops.yaml`): `find inventories -name "*.sops.*" | xargs sops updatekeys --yes`.
-
-   If GPG yells at you, follow the instructions in our [password-store](https://git.hamburg.ccc.de/CCCHH/password-store).
-4. Create a SOPS secrets file in the `host_vars` subdirectory of the relevant inventory.
-   The name of the file should be in the format `[HOSTNAME].sops.yaml` to get picked up by the vars plugin and to match the previously created creation rule.  
-   This can be accomplished with a command similar to this:
-   ```
-   sops inventories/[chaosknoten|z9]/host_vars/[HOSTNAME].sops.yaml
-   ```
-5. With the editor now open, add the secrets you want to store.
-   Because we're using the `community.sops.sops` vars plugin, the stored secrets will be exposed as Ansible variables.  
-   Also note that SOPS only encrypts the values, not the keys.  
-   When now creating entries, try to adhere to the following variable naming convention:
-   - Make sure to put the prive age key in here under `ansible_pull__age_private_key`.
-   - Prefix variable names with `secret__`, if they are intended to be used in a template file or similar. (e.g. `secret__netbox_secret_key: secret_value`)
-   - Otherwise, if the variable is directly consumed by a role or similar, directly set the variable. (e.g. `netbox__db_password: secret_value`)
-6. Now that the secrets are stored, they are exposed as variables and can simply be used like any other variable.
-
-## GPG Keys
-
-In order to edit encrypted files, you need all the GPG public keys imported into your GPG Keychain. You should be able to find the necessary public keys in https://git.hamburg.ccc.de/CCCHH/password-store.

docs/guides/sops-new-host.md

@@ -0,0 +1,58 @@
+---
+title: "SOPS: New Host"
+summary: How to Setup SOPS for a New Host
+---
+
+# SOPS: New Host
+
+The following outlines the steps to take for setting up [SOPS](../concepts-and-configurations/sops.md) for a new host (`myservice`).  
+Every host needs a SOPS configuration as every host should be set up to run ansible-pull.
+
+1. Create a new age key for ansible-pull for the host:
+   ```
+   age-keygen
+   ```
+2. Add the public key part to the [`.sops.yaml`](https://git.hamburg.ccc.de/CCCHH/ansible-infra/src/branch/main/.sops.yaml) under:
+   ```yaml
+   keys:
+    # ...
+    hosts:
+      chaosknoten:
+        age: &host_chaosknoten_age_keys
+          # ...
+          - &host_myservice_ansible_pull_age_key <age public key here>
+   ```
+   You can use the existing configuration as guidance.  
+   For VMs not on Chaosknoten, choose the appropriate section.
+3. Add a new creation rule for the hosts `host_vars` file to the [`.sops.yaml`](https://git.hamburg.ccc.de/CCCHH/ansible-infra/src/branch/main/.sops.yaml).  
+   It should most likely hold all admin keys plus the host entry you just added and look something like this:
+   ```yaml
+   creation_rules:
+    # ...
+    ## host vars
+    # chaosknoten hosts
+    # ...
+    - path_regex: "inventories/chaosknoten/host_vars/myservice\\.sops\\..+"
+      key_groups:
+        - pgp:
+            *admin_gpg_keys
+          age:
+            - *host_myservice_ansible_pull_age_key
+   ```  
+   You can use existing creation rules as a reference.  
+   For VMs not on Chaosknoten, choose the appropriate section.
+4. Re-encrypt for the newly added key (mainly `group_vars/all.sops.yaml`):
+   ```bash
+   find inventories -name "*.sops.*" | xargs sops updatekeys --yes
+   ```
+   If GPG yells at you, follow the instructions in [infra-secrets](https://git.hamburg.ccc.de/CCCHH/infra-secrets).
+5. Create a SOPS secrets file in the `host_vars` subdirectory of the relevant inventory. The name of the file should be of the format `<hostname>.sops.yaml` to get picked up by the vars plugin and to match the previously created creation rule.  
+   For this example the following command accomplishes this:
+   ```
+   sops inventories/chaosknoten/host_vars/myservice.sops.yaml
+   ```
+    - With the editor now open, delete the example content and add the previously generated age private key like this:
+      ```yaml
+      ansible_pull__age_private_key: <age private key here>
+      ```
+      Note that SOPS only encrypts the values, not the keys.  

docs/guides/sops-storing-secrets.md

@@ -0,0 +1,29 @@
+---
+title: "SOPS: Storing Secrets"
+summary: How to Store Secrets Using SOPS
+---
+
+# SOPS: Storing Secrets
+
+Some guidance on how to store secrets using [SOPS](../concepts-and-configurations/sops.md). For a guide on how to setup SOPS for a new host, see [SOPS: New Host](./sops-new-host.md).
+
+1. For storing host-specific secrets, open the host-specific SOPS file:
+   ```
+   sops inventories/<chaosknoten/z9/...>/host_vars/<hostname>.sops.yaml
+   ```
+   For inventory-wide secrets, open the inventories `all` group SOPS file:
+   ```
+   sops inventories/<chaosknoten/z9/...>/group_vars/all.sops.yaml
+   ```
+2. Now the secrets can be added to the opened file. Because we're using the `community.sops.sops` vars plugin, the stored secrets will then be exposed as Ansible variables.  
+   Note that SOPS only encrypts the values, not the keys.  
+   When creating entries, try to adhere to the following variable naming conventions:
+    - Prefix variable names with `secret__`, if they are intended to be used in a template file or similar, e.g.:
+      ```yaml
+      secret__netbox_secret_key: secret_value
+      ```
+    - Otherwise, if the variable is directly consumed by a role or similar, directly set the variable, e.g.:
+      ```yaml
+      netbox__db_password: secret_value
+      ```
+3. After closing the editor, the secrets are stored. In Ansible they are exposed as variables and can simply be used like any other variable.