From 21e620a12c87b66f7290f2bdee299103abe0fb74 Mon Sep 17 00:00:00 2001
From: teutat3s <teutates@mailbox.org>
Date: Sun, 29 Oct 2023 17:22:15 +0100
Subject: [PATCH] docs: add how to manage DNS records with terraform

---
 docs/dns.md | 41 ++++++++++++++++++++++++++++++++++++++---
 flake.nix   |  1 +
 2 files changed, 39 insertions(+), 3 deletions(-)

diff --git a/docs/dns.md b/docs/dns.md
index 8c1a5731..189ef536 100644
--- a/docs/dns.md
+++ b/docs/dns.md
@@ -1,17 +1,44 @@
 # Changing DNS entries
 
+Our current DNS provider is [namecheap](https://www.namecheap.com/).
+We use [Terraform](https://www.terraform.io) to declaratively manage our pub.solar DNS records.
+
 ### Initial setup
 
-Change into the terraform directory and initialize the terraform providers.
+Skip this step if you already have a `triton` profile setup.
+
+```
+triton profile create
+```
+
+Please follow https://docs.greenbaum.cloud/en/devops/triton-cli.html for the details.
+
+You will need to setup the following [namecheap API credentials](https://www.namecheap.com/support/api/intro),
+look for "namecheap API key" in the pub.solar Keepass database.
+```
+NAMECHEAP_API_KEY
+NAMECHEAP_API_USER
+NAMECHEAP_USER_NAME
+```
+You will probably also need to add your external IP to the [API allow list](https://ap.www.namecheap.com/settings/tools/apiaccess/whitelisted-ips).
+```
+dig -4 ip @dns.toys
+```
+
+Now, change into the terraform directory and initialize the terraform providers.
 
 ```
 cd terraform
-cat ~/.config/triton/profiles.d/lev-1-pub_solar.json | grep keyId
-export TRITON_KEY_ID=
+export TRITON_KEY_ID=$(cat ~/.config/triton/profiles.d/lev-1-pub_solar.json | jq --raw-output .keyId)
 
 terraform init
 ```
 
+Make your changes, e.g. in `dns.tf`.
+```
+$EDITOR dns.tf
+```
+
 Plan your changes using:
 ```
 terraform plan -out pub-solar-infra.plan
@@ -21,3 +48,11 @@ After verification, apply your changes with:
 ```
 terraform apply "pub-solar-infra.plan"
 ```
+
+### Useful links
+
+We use the Manta remote backend to save the terraform state for collaboration.
+- https://www.terraform.io/language/v1.2.x/settings/backends/manta
+
+Namecheap Terraform provider docs:
+- https://registry.terraform.io/providers/namecheap/namecheap/latest/docs
diff --git a/flake.nix b/flake.nix
index 350ce522..7cb4db75 100644
--- a/flake.nix
+++ b/flake.nix
@@ -72,6 +72,7 @@
             treefmt
             nixos-generators
             inputs.nixpkgs-2205.legacyPackages.${system}.terraform
+            jq
           ];
         };
       };