diff --git a/README.md b/README.md index bd980d8..08e60f5 100644 --- a/README.md +++ b/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: diff --git a/docs/concepts-and-configurations/secrets.md b/docs/concepts-and-configurations/secrets.md deleted file mode 100644 index 5734384..0000000 --- a/docs/concepts-and-configurations/secrets.md +++ /dev/null @@ -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) diff --git a/docs/concepts-and-configurations/sops.md b/docs/concepts-and-configurations/sops.md new file mode 100644 index 0000000..e4519e5 --- /dev/null +++ b/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) diff --git a/docs/guides/sops-gpg-key-replacement.md b/docs/guides/sops-gpg-key-replacement.md deleted file mode 100644 index 8edb5f4..0000000 --- a/docs/guides/sops-gpg-key-replacement.md +++ /dev/null @@ -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 - ```