docs: overhaul SOPS documentation for better structure and readability

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.