basicstack/stack.basicstack.de
2
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions
stack.basicstack.de/infrastructure/networking/DNS_REQUIREMENTS.md
CTO Agent 3b000e1ab1 Document k3s cluster network architecture and DNS requirements 
Created comprehensive network documentation for BasicStack k3s cluster:

- NETWORK_ARCHITECTURE.md: Complete network architecture with diagrams,
  node configuration, CNI (Flannel) details, ingress/LoadBalancer setup,
  DNS configuration, TLS certificates, network policies, traffic flows,
  and troubleshooting procedures

- DNS_REQUIREMENTS.md: Complete DNS record requirements for all services
  including A records, MX records, SPF, DKIM, DMARC, and PTR records

- NETWORK_VERIFICATION.md: Verification report documenting current state
  of all network components with findings and recommendations

Updated infrastructure README with links to new network documentation.

Key findings:
- All worker nodes correctly configured with --node-ip set to private IPs
- Flannel VXLAN properly configured with public IP annotations
- Traefik ingress controller operational
- 16/17 TLS certificates valid (registry-tls needs investigation)
- 3 LoadBalancer services properly configured
- Network policies securing database services

Addresses DEV-225: Verify and document k3s cluster network configuration
Related: DEV-224 (node-ip configuration), DEV-223 (DNS issues)

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-07-11 11:06:36 +00:00

6.1 KiB
Raw Blame History

DNS Requirements for BasicStack Services

Last Updated: 2026-07-06

Overview

This document lists all DNS records required for BasicStack services running on the k3s cluster.

Primary Domain: basicstack.de

A Records (HTTP/HTTPS Services)

All HTTP/HTTPS services are accessed via Traefik LoadBalancer. Point DNS records to one or more of the following IPs:

Recommended Target IPs:

  • 178.105.17.239 (k3s-cp-1 control-plane - most stable)
  • 10.42.1.2 (k3s-worker-1 - if using private network routing)
  • 10.42.1.3 (k3s-worker-2 - if using private network routing)
  • 10.42.1.5 (k3s-worker-3 - if using private network routing)

Required DNS A/CNAME Records

Hostname Type Target Service Port(s)
basicstack.org A 178.105.17.239 BasicStack website 443
www.basicstack.org A 178.105.17.239 BasicStack website 443
paperclip.basicstack.de A 178.105.17.239 Paperclip Platform 443
mail.basicstack.de A 178.105.17.239 Stalwart Webmail 443
forgejo.basicstack.de A 178.105.17.239 Git Hosting 443
directus.basicstack.de A 178.105.17.239 CMS 443
books.basicstack.de A 178.105.17.239 BookStack Wiki 443
auth.basicstack.de A 178.105.17.239 Pocket ID (SSO) 443
nextcloud.basicstack.de A 178.105.17.239 File Storage 443
grafana.basicstack.de A 178.105.17.239 Monitoring 443
prometheus.basicstack.de A 178.105.17.239 Metrics 443
alertmanager.basicstack.de A 178.105.17.239 Alerting 443
planka.basicstack.de A 178.105.17.239 Task Board 443
vaultwarden.basicstack.de A 178.105.17.239 Password Manager 443
passbolt.basicstack.de A 178.105.17.239 Password Manager 443
opencloud.basicstack.de A 178.105.17.239 OpenCloud 443
registry.basicstack.de A 178.105.17.239 Container Registry 443

Mail-Specific DNS Records

MX Records

basicstack.de.  3600  IN  MX  10  mail.basicstack.de.

Mail Server A Record

mail.basicstack.de.  3600  IN  A  178.105.17.239

SPF Record (TXT)

basicstack.de.  3600  IN  TXT  "v=spf1 a:mail.basicstack.de ~all"

Explanation:

  • v=spf1: SPF version 1
  • a:mail.basicstack.de: Allow mail from the IP of mail.basicstack.de
  • ~all: Soft fail for all other sources

DKIM Record (TXT)

Important: Replace <public-key> with actual DKIM public key from Stalwart configuration.

default._domainkey.basicstack.de.  3600  IN  TXT  "v=DKIM1; k=rsa; p=<public-key>"

To get the DKIM public key:

kubectl exec -n stalwart deploy/stalwart -- cat /app/dkim/default.public.pem

DMARC Record (TXT)

_dmarc.basicstack.de.  3600  IN  TXT  "v=DMARC1; p=quarantine; rua=mailto:dmarc@basicstack.de"

Explanation:

  • v=DMARC1: DMARC version 1
  • p=quarantine: Policy for failed messages (quarantine them)
  • rua: Email address for aggregate reports

PTR Record (Reverse DNS)

Important: This must be configured at Hetzner for the server's public IP.

239.17.105.178.in-addr.arpa.  IN  PTR  mail.basicstack.de.

Request this from Hetzner Cloud for IP 178.105.17.239.

Wildcard DNS (Alternative)

Instead of individual A records, you can use a wildcard:

*.basicstack.de.  3600  IN  A  178.105.17.239

Pros:

  • Simpler DNS management
  • Automatic coverage for new services

Cons:

  • Less control over individual service routing
  • Potential security implications (all subdomains resolve)

DNS Propagation and TTL

Recommended TTL: 3600 seconds (1 hour)

When changing DNS:

  1. Lower TTL to 300 seconds (5 minutes) at least 24 hours before the change
  2. Make the DNS change
  3. Wait for propagation (typically 5-15 minutes with low TTL)
  4. Verify with: dig <hostname> @8.8.8.8
  5. Raise TTL back to 3600 seconds

DNS Providers

Hetzner DNS

If using Hetzner DNS:

  1. Access via Hetzner Cloud Console or hcloud CLI
  2. Zone: basicstack.de
  3. Can manage via API or web interface

Manual Verification

Check DNS records:

# Check A record
dig basicstack.de @8.8.8.8 +short

# Check MX record
dig basicstack.de MX @8.8.8.8 +short

# Check TXT records (SPF, DKIM, DMARC)
dig basicstack.de TXT @8.8.8.8 +short
dig default._domainkey.basicstack.de TXT @8.8.8.8 +short
dig _dmarc.basicstack.de TXT @8.8.8.8 +short

# Check specific subdomain
dig mail.basicstack.de @8.8.8.8 +short

Troubleshooting DNS Issues

Service Not Accessible

  1. Check DNS resolution:

    dig <hostname> @8.8.8.8

  2. Verify LoadBalancer IPs:

    kubectl get svc -n kube-system traefik

  3. Check Traefik ingress:

    kubectl get ingress -A | grep <hostname>

  4. Test from within cluster:

    kubectl run -it --rm test --image=curlimages/curl --restart=Never -- curl -I https://<hostname>

Mail Delivery Issues

  1. Check MX record:

    dig basicstack.de MX @8.8.8.8

  2. Verify SMTP port accessibility:

    telnet mail.basicstack.de 25

  3. Check SPF/DKIM/DMARC:

    dig basicstack.de TXT @8.8.8.8
dig default._domainkey.basicstack.de TXT @8.8.8.8
dig _dmarc.basicstack.de TXT @8.8.8.8

  4. Verify reverse DNS (PTR):

    dig -x 178.105.17.239 @8.8.8.8

DNS Configuration Checklist

Before deploying a new service:

  • Add A record for service hostname
  • Verify DNS propagation (dig)
  • Create Kubernetes Ingress resource
  • Configure cert-manager Certificate
  • Test HTTPS accessibility
  • Update this document

For mail services, additionally:

  • Configure MX record
  • Configure SPF record
  • Generate and configure DKIM keys
  • Configure DMARC record
  • Request PTR record from Hetzner
  • Test mail delivery with external tool (mail-tester.com)

Related Documentation

Changelog

Date Change Author
2026-07-06 Initial DNS requirements documentation CTO (DEV-225)