diff --git a/README.md b/README.md index a2f2214..741eeb3 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ Generally all secrets get encrypted for all GPG-keys of all members of the infra 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). +For a tutorial on how to set up secrets using SOPS for a new host, see [Setting Up Secrets Using SOPS for a New Host](./docs/setting_up_secrets_using_sops_for_a_new_host.md). ### Updating SOPS files after swapping out a GPG key diff --git a/docs/concepts-and-configurations/sops.md b/docs/concepts-and-configurations/sops.md deleted file mode 100644 index e4519e5..0000000 --- a/docs/concepts-and-configurations/sops.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -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/create-new-web-service-vm.md b/docs/guides/create-new-web-service-vm.md index ed0974b..bf7d65b 100644 --- a/docs/guides/create-new-web-service-vm.md +++ b/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 [SOPS: New Host](./sops-new-host.md) before continuing. +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. ## Service-specific config diff --git a/docs/guides/setting_up_secrets_using_sops_for_a_new_host.md b/docs/guides/setting_up_secrets_using_sops_for_a_new_host.md new file mode 100644 index 0000000..a0e8935 --- /dev/null +++ b/docs/guides/setting_up_secrets_using_sops_for_a_new_host.md @@ -0,0 +1,33 @@ +# 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. diff --git a/docs/guides/sops-new-host.md b/docs/guides/sops-new-host.md deleted file mode 100644 index c786e96..0000000 --- a/docs/guides/sops-new-host.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -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 - ``` - 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 `.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: - ``` - Note that SOPS only encrypts the values, not the keys. diff --git a/docs/guides/sops-storing-secrets.md b/docs/guides/sops-storing-secrets.md deleted file mode 100644 index 2020837..0000000 --- a/docs/guides/sops-storing-secrets.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -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//host_vars/.sops.yaml - ``` - For inventory-wide secrets, open the inventories `all` group SOPS file: - ``` - sops inventories//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.