document "roles"

TODO: rename to "groups"

README.md

@@ -5,7 +5,7 @@ Purpose: Manage gpg keys for:
 
 # Key Management
 
-## howto create and add a gpg key
+## 1. Onboarding: howto create and add a gpg key
 - please follow instruction on following link: https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key
 - add ONLY the _PUBLIC_ part of your gpg key!!!
 - checkin via MergeRequest/PullRequest
@@ -16,7 +16,17 @@ gpg --import /path/to/keys/*.gpg.pub
 ### list imported gpg keys
 gpg --list-keys --keyid-format=long
 
-# EOL: Archive Expired Keys
+
+### roles
+
+Access for each repo is tracked using the `./roles/` directory; each sub-directory represents a "role" or "group". (Naming: choosing "role" as the name and deciding to just have "one group per role"
+
+```bash
+cd roles/<project_name>
+ln -s ../../<path_to_key.gpg.pub>
+```
+
+## 2. Offboarding: Archive Expired Keys (EOL)
 
 To mark a key as expired, move it to the `archive/` dir as follows:
 
@@ -24,6 +34,30 @@ To mark a key as expired, move it to the `archive/` dir as follows:
 mv ${keyname} "archive/${keyname}_$(date '+%Y-%m-%d').archive"
 ```
 
+## 3. Configure sops config
+
+Context: This repo stores the keys used to encrypt secrets in other repos; these "consumer" repos each contain a sops config `.sops.yaml` which manages access to the encrypted files (e.g. `secrets.yaml`)
+
+
+The following commands explain how to update the `.sops.yaml` for a repository:
+
+```bash
+# E.g. update sops config for DevNSO
+% git clone git@git.dev-at.de:cloud-solutions/nso/devnso-adp-argocd.git
+% cd devnso-adp-argocd/
+
+# List available roles
+% ${PATH_TO_THIS_REPO}/bin/update_sops.sh --list_roles
+# INFO: listing roles
+admin
+automation
+devnso-adp-argocd
+
+# For a given role, update sops config and specified secrets file
+% ${PATH_TO_THIS_REPO}/bin/update_sops.sh -r devnso-adp-argocd -s ./adp-api-devs/adp-api-devs/secrets.yaml
+% git diff
+```
+
 # Configure SOPS
 
 SOPS is used for encrypting secrets, e.g. credentials for various systems
@@ -75,24 +109,3 @@ sops -d secrets.yaml
 cd example/
 ./cmd_sops.sh
 ```
-
-
-# Automation
-
-```bash
-# E.g. update sops config for DevNSO
-% git clone git@git.dev-at.de:cloud-solutions/nso/devnso-adp-argocd.git
-% cd devnso-adp-argocd/
-% ${PATH_TO_THIS_REPO}/bin/update_sops.sh
-
-# List available roles
-% ${PATH_TO_THIS_REPO}/bin/update_sops.sh --list_roles
-# INFO: listing roles
-admin
-automation
-devnso-adp-argocd
-
-# For a given role, update sops config and specified secrets file
-% ${PATH_TO_THIS_REPO}/bin/update_sops.sh -r devnso-adp-argocd -s ./adp-api-devs/adp-api-devs/secrets.yaml
-% git diff
-```