From 38cd0f5fa5f14aa7b72a61c11b5e06256b20d5dc Mon Sep 17 00:00:00 2001 From: Bert-Jan Fikse Date: Wed, 17 Sep 2025 15:54:53 +0200 Subject: [PATCH 1/3] chore: add acme decisions to docs --- infrastructure/acme.md | 33 ++++++++++++++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/infrastructure/acme.md b/infrastructure/acme.md index dc590a7..057d328 100644 --- a/infrastructure/acme.md +++ b/infrastructure/acme.md @@ -1 +1,32 @@ -#ACME \ No newline at end of file +# ACME DNS Challenges +## Summary +We agreed to use **ACME DNS-01 challenges** for issuing certificates for **both public-facing and internal services**. A key benefit is that DNS-01 **enables internal certificate issuance** in the first place, since the CA only needs to verify TXT records in DNS (no inbound HTTP/ALPN access to the service). To keep our primary DNS zones clean, we will create a **separate, dedicated zone** for ACME challenges and **delegate** challenge records to it via **CNAME**. + +## Decisions +- Use **ACME DNS-01** as the challenge type for **both external/public and internal** certificate issuance. +- Create a **dedicated DNS zone** for ACME challenges (e.g., `_acme.example.com`). +- For each certificate FQDN, publish a **CNAME** at `_acme-challenge.` that points into the dedicated challenge zone. +- Store the **TXT token(s)** only in the dedicated challenge zone to avoid cluttering primary zones. +- Keep **low TTLs** (e.g., 60-120s) on both CNAME and TXT records to speed up renewals. +- Restrict write access to the challenge zone to the ACME automation only. + +## Reference Design +**Dedicated zone:** +`_acme.example.com` + +**For a service FQDN:** +Target certificate: `app1.example.com` + +**Publish in the primary zone:** +```dns +; Delegate the challenge to the dedicated zone +_acme-challenge.app1.example.com. CNAME app1._acme-challenge._acme.example.com. +``` + +**Publish in the dedicated zone (managed by the ACME client/automation):** +```dns +; ACME client writes the TXT token here +app1._acme-challenge._acme.example.com. TXT "ACME_VALIDATION_TOKEN" +``` + +> During validation, the CA will follow the CNAME from the primary zone to the dedicated zone and read the TXT record there. \ No newline at end of file From 81fc47a9f5f2bdac95eff9aeab514b6afd294285 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tobias=20W=C3=BCst?= Date: Wed, 17 Sep 2025 16:09:15 +0200 Subject: [PATCH 2/3] chore(docs): initial compit of the IPv6 docu --- infrastructure/ipv6.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/infrastructure/ipv6.md b/infrastructure/ipv6.md index e69de29..2271b21 100644 --- a/infrastructure/ipv6.md +++ b/infrastructure/ipv6.md @@ -0,0 +1,33 @@ +# IPv6 – Overview and Best Practices + +## Why IPv6? +IPv6 was introduced to address the limitations of IPv4, most notably the shortage of available addresses. It provides an almost unlimited address space, improved support for modern networking, and forms the foundation for future-proof infrastructures. + +## DNS instead of IP addresses +- IPv6 addresses are long and difficult to memorize (e.g. `2001:db8:85a3::8a2e:370:7334`). +- It is therefore recommended to use **DNS names for virtual machines (VMs)** and other systems. + → This improves administration, readability, and reduces error potential. + +## Own IPv6 Stack +- The **RFC4193 range** (`fd00::/8`) is reserved for **local, private use**, similar to private IPv4 networks (e.g. `192.168.x.x`). +- For production environments, it is preferable to use **public, globally routable IPv6 prefixes** obtained from an ISP or an own IPv6 allocation. + → Advantages: + - Unique addressing without overlaps + - Direct reachability and routability on the Internet + - Sustainable, future-oriented network design + +## Dual Stack as a Transition Strategy +- In many environments, IPv4 cannot be replaced immediately. +- **Dual Stack** allows IPv4 and IPv6 to operate in parallel. +- This enables a gradual transition to IPv6 without requiring a complete redesign of the network infrastructure at once. +- Dual Stack can be maintained as long as necessary, until IPv6 adoption is complete. + +## Jump Host for IPv6-only Zones +- When migrating to **IPv6-only environments**, not all clients or tools may yet support IPv6. +- A **Jump Host** with both IPv4 and IPv6 connectivity can serve as an entry point. +- It enables access from IPv4-based networks into IPv6-only segments, acting as a controlled and secure bridge during the transition phase. +- This approach ensures operability while gradually phasing out IPv4. + +## Conclusion +IPv6 is essential for modern IT infrastructures and significantly simplifies network management in the long term. +By relying on **DNS names instead of raw IP addresses**, operating an **own, globally valid IPv6 stack**, using **Dual Stack during the migration phase**, and providing a **Jump Host for IPv6-only zones**, networks become more robust, scalable, and future-proof. From 0e0382635bf4c1f2e57cd6a2dccedf92a307f758 Mon Sep 17 00:00:00 2001 From: Bert-Jan Fikse Date: Wed, 17 Sep 2025 15:54:53 +0200 Subject: [PATCH 3/3] chore: add acme decisions to docs --- infrastructure/acme.md | 33 ++++++++++++++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/infrastructure/acme.md b/infrastructure/acme.md index dc590a7..057d328 100644 --- a/infrastructure/acme.md +++ b/infrastructure/acme.md @@ -1 +1,32 @@ -#ACME \ No newline at end of file +# ACME DNS Challenges +## Summary +We agreed to use **ACME DNS-01 challenges** for issuing certificates for **both public-facing and internal services**. A key benefit is that DNS-01 **enables internal certificate issuance** in the first place, since the CA only needs to verify TXT records in DNS (no inbound HTTP/ALPN access to the service). To keep our primary DNS zones clean, we will create a **separate, dedicated zone** for ACME challenges and **delegate** challenge records to it via **CNAME**. + +## Decisions +- Use **ACME DNS-01** as the challenge type for **both external/public and internal** certificate issuance. +- Create a **dedicated DNS zone** for ACME challenges (e.g., `_acme.example.com`). +- For each certificate FQDN, publish a **CNAME** at `_acme-challenge.` that points into the dedicated challenge zone. +- Store the **TXT token(s)** only in the dedicated challenge zone to avoid cluttering primary zones. +- Keep **low TTLs** (e.g., 60-120s) on both CNAME and TXT records to speed up renewals. +- Restrict write access to the challenge zone to the ACME automation only. + +## Reference Design +**Dedicated zone:** +`_acme.example.com` + +**For a service FQDN:** +Target certificate: `app1.example.com` + +**Publish in the primary zone:** +```dns +; Delegate the challenge to the dedicated zone +_acme-challenge.app1.example.com. CNAME app1._acme-challenge._acme.example.com. +``` + +**Publish in the dedicated zone (managed by the ACME client/automation):** +```dns +; ACME client writes the TXT token here +app1._acme-challenge._acme.example.com. TXT "ACME_VALIDATION_TOKEN" +``` + +> During validation, the CA will follow the CNAME from the primary zone to the dedicated zone and read the TXT record there. \ No newline at end of file