Skip to content

Unified Hostname Architecture

This document describes the unified hostname approach for accessing homelab services both internally and externally using a single domain (*.bogocat.com).

Overview

Problem: Using separate domains for internal (*.internal) vs external (*.bogocat.com) access causes Authentik OIDC issuer mismatches and requires duplicate provider configurations.

Solution: Use *.bogocat.com for everything. DNS resolution determines the path: - Internal DNS (OPNsense) → direct to K8s Ingress - External DNS (Cloudflare) → VPS → WireGuard → K8s Ingress

Architecture Diagram

                    INTERNAL (home network or WireGuard VPN)
               ┌──────────────────────────────────────────────────┐
               │                                                  │
  Device ───► OPNsense DNS                                        │
  "radarr.bogocat.com"  │                                         │
                        │ override: 10.89.97.220                  │
                        ▼                                         │
                  K8s Ingress ──► Authentik ──► Service           │
                  (10.89.97.220)   (auth.bogocat.com)             │
               └──────────────────────────────────────────────────┘


                    EXTERNAL (public internet)
               ┌──────────────────────────────────────────────────┐
               │                                                  │
  Device ───► Cloudflare DNS ───► Hetzner VPS (Caddy)             │
  "radarr.bogocat.com"          5.161.45.147:443                  │
                                     │                            │
                                     │ WireGuard (10.22.95.0/24)  │
                                     ▼                            │
                               OPNsense (10.22.95.1)              │
                                     │                            │
                                     ▼                            │
                               K8s Ingress ──► Authentik ──► Service
                               (10.89.97.220)                     │
               └──────────────────────────────────────────────────┘


                    WIREGUARD VPN (from anywhere)
               ┌──────────────────────────────────────────────────┐
               │                                                  │
  Device ═══════════► WireGuard Tunnel ───► OPNsense              │
  (coffee shop)       (encrypted)               │                 │
                                                │ DNS override    │
                                                ▼                 │
                                          10.89.97.220            │
                                                │                 │
                                                ▼                 │
                                          K8s Ingress ──► Service │
               └──────────────────────────────────────────────────┘

Benefits

Benefit Description
Single Authentik provider per app No duplicate internal/external providers
No OIDC issuer mismatch Same hostname = same issuer URL
Internal resilience Works when internet is down (OPNsense resolves locally)
WireGuard bypasses VPS Direct access when connected to VPN
Simpler configuration One hostname to remember per service

Components

DNS Resolution

Location DNS Server radarr.bogocat.com resolves to
Home LAN OPNsense (override) 10.89.97.220 (direct)
WireGuard VPN OPNsense (override) 10.89.97.220 (direct)
Public Internet Cloudflare 5.161.45.147 (VPS)

Traffic Flow

Access Method Path Latency
Home LAN Device → K8s Ingress ~1ms
WireGuard VPN Device → Tunnel → K8s Ingress ~20-50ms
Public Internet Device → VPS → WireGuard → K8s Ingress ~50-100ms

TLS Termination

Path TLS Terminated At
Internal K8s Ingress (cert-manager)
External VPS Caddy (Let's Encrypt) → re-encrypted to K8s

Configuration

OPNsense DNS Overrides

Services → Unbound DNS → Host Overrides:

Host Domain IP
auth bogocat.com 10.89.97.220
radarr bogocat.com 10.89.97.220
sonarr bogocat.com 10.89.97.220
... bogocat.com 10.89.97.220

Or use a wildcard (if supported): | Host | Domain | IP | |------|--------|-----| | * | bogocat.com | 10.89.97.220 |

Authentik Provider Configuration

Each proxy provider uses the public hostname:

Field Value
External host https://radarr.bogocat.com
Mode Forward auth (single application)

K8s Ingress

spec:
  rules:
  - host: radarr.bogocat.com  # NOT radarr.internal
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: radarr-external
            port:
              number: 7878

VPS Caddy

radarr.bogocat.com {
    reverse_proxy 10.89.97.220:80 {
        header_up Host radarr.bogocat.com
        header_up X-Forwarded-Host radarr.bogocat.com
        header_up X-Forwarded-Proto https
    }
}

Migration from *.internal

  1. Add OPNsense DNS overrides for *.bogocat.com
  2. Update Authentik providers: external_host → https://*.bogocat.com
  3. Update K8s Ingresses: host → *.bogocat.com
  4. Add VPS Caddy entries for each service
  5. Test internal and external access
  6. Remove old *.internal Ingresses (optional - can keep as fallback)

Fallback

The *.internal hostnames can remain as a fallback: - If *.bogocat.com cert expires or has issues - For debugging (bypass Authentik by hitting internal directly) - Gradual migration