From 31d025ed7588374aa9d60269e142a47b86d35ba6 Mon Sep 17 00:00:00 2001
From: transcaffeine <transcaffeine@finally.coffee>
Date: Sat, 21 Sep 2024 10:57:46 +0200
Subject: [PATCH] docs: add READMEs to roles powerdns_tsig_key and dns

---
 README.md                         |  6 ++++++
 roles/dns/README.md               | 33 +++++++++++++++++++++++++++++++
 roles/powerdns_tsig_key/README.md | 25 +++++++++++++++++++++++
 3 files changed, 64 insertions(+)
 create mode 100644 roles/dns/README.md
 create mode 100644 roles/powerdns_tsig_key/README.md

diff --git a/README.md b/README.md
index a22b994..fee88ad 100644
--- a/README.md
+++ b/README.md
@@ -13,6 +13,9 @@ and configuring basic system utilities like gnupg, ssh etc
 
 - [`gnupg`](roles/gnupg/README.md): configures gnupg on the target system
 
+- [`lego`](roles/lego/README.md): runs [lego (LetsEncrypt Go]](https://github.com/go-acme/lego),
+  a ACME client written in go, using systemd (timers). Multi-instance capable.
+
 - [`mariadb`](roles/mariadb/README.md): runs [MariaDB Server](https://mariadb.org/), one of the world's most popular open source relational database
 
 - [`minio`](roles/minio/README.md): Deploy [min.io](https://min.io), an
@@ -24,6 +27,9 @@ and configuring basic system utilities like gnupg, ssh etc
 - [`restic`](roles/restic/README.md): Manage backups using restic
   and persist them to a configurable backend.
 
+- [`powerdns_tsig_key`](roles/powerdns_tsig_key/README.md): Simple ansible role
+  for generating TSIG keys in PowerDNS.
+
 ## License
 
 [CNPLv7+](LICENSE.md): Cooperative Nonviolent Public License
diff --git a/roles/dns/README.md b/roles/dns/README.md
new file mode 100644
index 0000000..4dd2fd2
--- /dev/null
+++ b/roles/dns/README.md
@@ -0,0 +1,33 @@
+# `finallycoffee.base.dns` ansible role
+
+Simple role for wrapping around the
+[`famedly.dns.update`](https://github.com/famedly/ansible-collection-dns/blob/main/plugins/modules/update.py)
+ansible module.
+
+## Usage
+
+### Example playbook
+```yaml
+- target: "{{ target_hosts }}"
+  roles:
+    - role: finallycoffee.base.dns
+      vars:
+        dns_server: "dns.example.org"
+        dns_zone: "zone.example.org"
+        dns_records: "{{ dns_records }}"
+        dns_record_state: exact
+        dns_tsig_name: "mykeyname"
+        dns_tsig_algo: "hmac-sha256"
+        dns_tsig_key: "mykeycontent"
+  vars:
+    dns_records:
+      - type: A
+        name: gitea
+        content: "127.0.0.1"
+      - type: AAAA
+        name: gitea
+        content: "fe80::1"
+      - type: CNAME
+        name: "_acme_challenge.gitea"
+        content: "delegated-cname.challenge.example.org"
+```
diff --git a/roles/powerdns_tsig_key/README.md b/roles/powerdns_tsig_key/README.md
new file mode 100644
index 0000000..099100e
--- /dev/null
+++ b/roles/powerdns_tsig_key/README.md
@@ -0,0 +1,25 @@
+# `finallycoffee.base.powerdns_tsig_key`
+
+Simple ansible role for ensuring a TSIG key is present in a given PowerDNS-
+instance.
+
+## Usage
+
+The usage example below assumes `powerdns` is running in a container named `powerdns` (as supplied to `powerdns_tsig_key_container_name`.
+
+```yaml
+- hosts: "{{ target_hosts }}"
+  become: true
+  roles:
+    - role: finallycoffee.base.powerdns_tsig_key
+      vars:
+        powerdns_tsig_key_name: "nameofmykey"
+        powerdns_tsig_key_path: "/var/lib/myapp/tsig.key"
+        powernds_tsig_key_algo: "hmac-sha512"
+        powerdns_tsig_key_path_owner: "myappuser"
+        powerdns_tsig_key_path_group: "myappgroup"
+        powerdns_tsig_key_container_name: 'powerdns'
+```
+
+> [!INFO]
+> Support for non-docker deployments is pending.