aboutsummaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md67
1 files changed, 67 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..dcf6ed9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,67 @@
+D53
+===
+
+[![Build Status](https://drone.deuxfleurs.fr/api/badges/lx/D53/status.svg)](https://drone.deuxfleurs.fr/lx/D53)
+
+D53 is a dynamic DNS updater that sources information from Consul to route services to the correct place
+
+### Tag syntax
+
+D53 reads tags affected to services in Consul. Tags can be formatted as follows:
+
+- `d53-a <domain> <subdomain>`, will set the node running this service as an IPv4 target in an A record for `<subdomain>.<domain>`
+- `d53-aaaa <domain> <subdomain>`, same but as an IPv6 target in a AAAA record
+- `d53-cname <domain> <subdomain>`, same but as an alias using a CNAME record
+
+Example Nomad service configurations:
+
+```hcl
+# The following can be used in the Tricot service definition
+# to redirect the current deuxfleurs.fr and <site_name>.site.deuxfleurs.fr
+# to this node through A and AAAA records
+ tags = [
+ "(diplonat (tcp_port 80))"
+ "d53-a deuxfleurs.fr ${meta.site}.site",
+ "d53-a deuxfleurs.fr global.site",
+ "d53-aaaa deuxfleurs.fr ${meta.site}.site",
+ "d53-aaaa deuxfleurs.fr global.site",
+ ]
+```
+
+```hcl
+# The following can be used in the Guichet service definition
+# to configure a Tricot reverse proxy entry, and to redirect using
+# a CNAME the guichet.deuxfleurs.fr to the correct target,
+# which is usually defined in the form of <site_name>.site.deuxfleurs.fr
+ tags = [
+ "tricot guichet.deuxfleurs.fr",
+ "d53-cname deuxfleurs.fr guichet",
+ ]
+```
+
+### Finding targets
+
+The IPv4, IPv6 and CNAME targets to set in the record are extracted from the metadata values affected to each node in the Consul configuration.
+In particular, the following values are used:
+
+- `public_ipv4`: a public IPv4 through which the current node is possibly reachable (see DiploNAT to automatically open ports in a NAT)
+- `public_ipv6`: a public IPv6 through which the current node is reachable
+- `cname_target`: a CNAME target that resolves to a domain name whose A and/or AAAA entries point to this node (possibly among others)
+
+Here is the relevant Nix configuration snippet that sets up these metadata values:
+
+```nix
+ let node_meta = {
+ "site" = cfg.site_name;
+ "public_ipv6" = cfg.ipv6;
+ } //
+ (if cfg.public_ipv4 != null
+ then { "public_ipv4" = cfg.public_ipv4; }
+ else {}) //
+ (if cfg.cname_target != null
+ then { "cname_target" = cfg.cname_target; }
+ else {});
+
+ ### ... later ...
+ services.consul.extraConfig.node_meta = node_meta;
+```