3b000e1ab1
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>
232 lines
6.1 KiB
Markdown
232 lines
6.1 KiB
Markdown
# 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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
dig <hostname> @8.8.8.8
|
|
```
|
|
|
|
2. **Verify LoadBalancer IPs:**
|
|
```bash
|
|
kubectl get svc -n kube-system traefik
|
|
```
|
|
|
|
3. **Check Traefik ingress:**
|
|
```bash
|
|
kubectl get ingress -A | grep <hostname>
|
|
```
|
|
|
|
4. **Test from within cluster:**
|
|
```bash
|
|
kubectl run -it --rm test --image=curlimages/curl --restart=Never -- curl -I https://<hostname>
|
|
```
|
|
|
|
### Mail Delivery Issues
|
|
|
|
1. **Check MX record:**
|
|
```bash
|
|
dig basicstack.de MX @8.8.8.8
|
|
```
|
|
|
|
2. **Verify SMTP port accessibility:**
|
|
```bash
|
|
telnet mail.basicstack.de 25
|
|
```
|
|
|
|
3. **Check SPF/DKIM/DMARC:**
|
|
```bash
|
|
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):**
|
|
```bash
|
|
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
|
|
|
|
- [Network Architecture](NETWORK_ARCHITECTURE.md)
|
|
- [Stalwart Mail Setup](../../apps/stalwart/README.md)
|
|
- [K3S Operations Guide](../K3S_OPERATIONS.md)
|
|
|
|
## Changelog
|
|
|
|
| Date | Change | Author |
|
|
|------|--------|--------|
|
|
| 2026-07-06 | Initial DNS requirements documentation | CTO (DEV-225) |
|