Update all stable non-major dependencies

README.md

@@ -17,6 +17,25 @@ ansible-galaxy install -r requirements.yml
 ansible-galaxy role install -r requirements.yml
 ```
 
+## Secrets
+
+Generally try to avoid secrets (e.g. use SSH keys instead of passwords).
+
+Because secrets are nonetheless needed sometimes, we use [SOPS](https://github.com/getsops/sops) to securely store secrets in this repository.  
+SOPS encrypts secrets according to "creation rules" which are defined in the `.sops.yaml`.
+Generally all secrets get encrypted for all GPG-keys of all members of the infrastructure team.  
+Ansible then has access to the secrets with the help of the [`community.sops.sops` vars plugin](https://docs.ansible.com/ansible/latest/collections/community/sops/docsite/guide.html#working-with-encrypted-variables), which is configured in this repository.
+A local Ansible run then uses the locally available GPG-key to decrypt the secrets.
+
+For a tutorial on how to set up SOPS for a new host, see [SOPS: New Host](./docs/guides/sops-new-host.md).
+
+### Updating SOPS files after swapping out a GPG key
+
+When a GPG key expires, it is necessary to update the config in `.sops.yaml` and then re-encrypt all files with the updated list of keys. Run this command. The will take a considerable amount of time (minutes).
+```
+find inventories -name "*.sops.*" | xargs sops updatekeys --yes
+```
+
 ## Playbook nur für einzelne Hosts ausführen
 
 Ein paar der Hosts haben den selben Namen, was es etwas schwieriger macht, das Playbook nur für einen der Hosts auszuführen, z. B. `public-reverse-proxy`. Die Kombination aus `--inventory` und `--limit` führt zum Erfolg:

docs/concepts-and-configurations/secrets.md

@@ -1,27 +0,0 @@
----
-title: Secrets
----
-
-# Secrets
-
-Generally one should try to avoid secrets (e.g. using SSH keys instead of passwords).  
-However, since one still needs to work with secrets, we use [SOPS](https://github.com/getsops/sops) to securely store them in our repository. The [`community.sops.sops` vars plugin](https://docs.ansible.com/ansible/latest/collections/community/sops/docsite/guide.html#working-with-encrypted-variables) is then used to access them in Ansible.
-
-All secrets are stored in the inventories in files ending with `.sops.yaml` to provide the secrets contents as variables for hosts and groups.  
-Accompanying creation rules are defined in the [`.sops.yaml`](https://git.hamburg.ccc.de/CCCHH/ansible-infra/src/branch/main/.sops.yaml).
-
-When running Ansible locally, then your GPG key is used for accessing the secrets.  
-Hosts on the other hand, when running Ansible against themselves using ansible-pull, use a configured [age](https://github.com/FiloSottile/age) key to be able to access the secrets relevant to them.
-
-## GPG Keys
-
-The secrets in this repository are encrypted against the GPG public keys of all Infra-Team members as defined in [infra-secrets](https://git.hamburg.ccc.de/CCCHH/infra-secrets).  
-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 the [infra-secrets repo](https://git.hamburg.ccc.de/CCCHH/infra-secrets) as well.
-
-## Guides
-
-See the following pages for guidance on how to use SOPS:
-
-- [SOPS: New Host](../guides/sops-new-host.md)
-- [SOPS: Storing Secrets](../guides/sops-storing-secrets.md)
-- [SOPS: GPG-Key Replacement](../guides/sops-gpg-key-replacement.md)

docs/concepts-and-configurations/sops.md

@@ -0,0 +1,18 @@
+---
+title: SOPS
+---
+
+# SOPS
+
+We're using [SOPS](https://github.com/getsops/sops) for secret management together with the `community.sops.sops` vars plugin for Ansible.
+
+## 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 [infra-secrets](https://git.hamburg.ccc.de/CCCHH/infra-secrets).
+
+## Guides
+
+See the following pages for guidance on how to use SOPS:
+
+- [SOPS: New Host](../guides/sops-new-host.md)
+- [SOPS: Storing Secrets](../guides/sops-storing-secrets.md)

docs/guides/sops-gpg-key-replacement.md

@@ -1,13 +0,0 @@
----
-title: "SOPS: GPG-Key Replacement"
-summary: How to Replace an Expired GPG-Key
----
-
-# SOPS: GPG-Key Replacement
-
-- When a GPG key expires, it is necessary to update the config in the [`.sops.yaml`](https://git.hamburg.ccc.de/CCCHH/ansible-infra/src/branch/main/.sops.yaml) and then re-encrypt all files with the updated list of keys.
-    - If no new key is available, simply remove the key and re-encrypt all files to keep the repository in a working state. Whenever the relevant member provides a new key, add it again and re-encrypt for it again.
-- The re-encryption can be achieved by running the following command (which could take a considerable amount of time):
-  ```bash
-  find inventories -name "*.sops.*" | xargs sops updatekeys --yes
-  ```