Architecture Overview

Charon is a production-ready Kubernetes infrastructure platform designed around category-based namespace isolation, secure VPN mesh networking, and centralized identity management.

System Architecture

┌────────────────────────────────────────────────────────────────────┐
│                     External Access Layer                           │
├────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  Internet ──▶ LoadBalancer ──▶ nginx-ingress ──▶ cert-manager      │
│               (Linode LKE)      (external)        (Let's Encrypt)   │
│                                                                      │
└──────────────────────────┬─────────────────────────────────────────┘
                           │
                           ▼
┌────────────────────────────────────────────────────────────────────┐
│                    VPN Coordination Layer                           │
├────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  Headscale (core namespace)                                         │
│  ├─ Control server for Tailscale mesh VPN                          │
│  ├─ User and pre-auth key management                               │
│  ├─ 100.64.0.0/10 address allocation                               │
│  └─ External HTTPS endpoint for enrollment                         │
│                                                                      │
└──────────────────────────┬─────────────────────────────────────────┘
                           │
                           ▼
┌────────────────────────────────────────────────────────────────────┐
│                   Kubernetes Cluster (LKE)                          │
├────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  core Namespace                                             │   │
│  ├─────────────────────────────────────────────────────────────┤   │
│  │  ▪ Headscale (VPN coordination)                             │   │
│  │  ▪ FreeIPA (LDAP/Kerberos identity management)             │   │
│  │  ▪ Container Registry (future)                              │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                      │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  monitoring Namespace                                       │   │
│  ├─────────────────────────────────────────────────────────────┤   │
│  │  ▪ Prometheus (metrics, 35+ targets, 15d retention)         │   │
│  │  ▪ Thanos (long-term storage, optional)                     │   │
│  │  ▪ Grafana (dashboards, git-sync, Tempo correlations)      │   │
│  │  ▪ Loki (log aggregation, emptyDir)                        │   │
  │  ▪ Tempo (distributed tracing, OTLP/gRPC)                  │   │
│  │  ▪ Promtail (log collection, DaemonSet)                    │   │
│  │  ▪ AlertManager (alert routing)                            │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                      │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  gitops Namespace                                           │   │
│  ├─────────────────────────────────────────────────────────────┤   │
│  │  ▪ Redmine (project management, PostgreSQL external)       │   │
│  │  ▪ GitLab (future)                                          │   │
│  │  ▪ ArgoCD (future)                                          │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                      │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  inference Namespace                                        │   │
│  ├─────────────────────────────────────────────────────────────┤   │
│  │  ▪ Open-WebUI (AI chat interface)                          │   │
│  │  ▪ Ollama (LLM inference)                                   │   │
│  │  ▪ vLLM (future, GPU workloads)                            │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                      │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  infra Namespace                                            │   │
│  ├─────────────────────────────────────────────────────────────┤   │
│  │  ▪ NetBox (future, IPAM)                                    │   │
│  │  ▪ Vault (future, secret management)                        │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                      │
└────────────────────────────────────────────────────────────────────┘

Core Components

Category-Based Namespaces

Services are organized into functional categories with strict RBAC boundaries:

Namespace	Purpose	Services
core	Infrastructure dependencies	Headscale, FreeIPA
monitoring	Observability stack	Prometheus, Grafana, Loki, Thanos
gitops	Development tooling	Redmine, GitLab (future), ArgoCD (future)
inference	AI/ML workloads	Open-WebUI, Ollama, vLLM (future)
infra	Operations tools	NetBox (future), Vault (future)

Benefits:

Clear security and trust boundaries
Independent resource quotas and limits
Simplified RBAC management
Logical grouping of related services
Easy to add new categories

See Namespaces Configuration for Terraform variables.

VPN Mesh Networking

Headscale provides self-hosted Tailscale control server for secure mesh VPN:

Address Range: 100.64.0.0/10 (CGNAT space)
Protocol: WireGuard
Enrollment: Pre-auth keys via kubectl exec
Client: Official Tailscale client on all platforms
Access: All services VPN-only (no public exposure)

Architecture:

┌─────────────┐           ┌──────────────┐          ┌────────────┐
│   Laptop    │           │   Desktop    │          │ Kubernetes │
│ Tailscale   │◀─────────▶│  Tailscale   │◀────────▶│    Pods    │
│ 100.64.x.x  │           │  100.64.x.x  │          │ (sidecars) │
└─────────────┘           └──────────────┘          └────────────┘
       │                         │                         │
       └─────────────────────────┼─────────────────────────┘
                                 ▼
                         ┌───────────────┐
                         │   Headscale   │
                         │  (core ns)    │
                         │ 100.64.0.1    │
                         └───────────────┘

See Networking Architecture and VPN Enrollment Guide.

Identity Management

FreeIPA provides centralized authentication and user management:

Protocol: LDAPS (port 636)
Base DN: dc=example,dc=org (configured via Terraform)
Services: LDAP directory, Kerberos KDC, certificate authority
Integration: All services authenticate via FreeIPA
Web UI: https://ipa.example.com (VPN-only)

LDAP Integration:

Redmine project management
Grafana dashboarding
Future services (GitLab, NetBox, Vault)

See FreeIPA Service and LDAP Integration Guide.

Multi-Container StatefulSet Pattern

All services use standardized 3-container (or 5-container with lifecycle) architecture:

Core Containers:

nginx-tls - HTTPS termination (port 443), proxies to localhost
Application - Main service on localhost (not exposed externally)
Tailscale - VPN sidecar for mesh connectivity

Lifecycle Containers (when Tailscale enabled): 4. lifecycle-cleanup (init) - Cleans up old Headscale nodes and DNS records before startup 5. lifecycle-dns-create (sidecar) - Creates DNS record after Tailscale registers VPN IP

Benefits:

Security isolation (app never exposed directly)
Automatic cleanup of orphaned resources
Self-healing DNS on pod recreation
VPN-only access enforcement
Consistent deployment pattern

See StatefulSet Pattern Details.

Data Flow

Service Access Flow

User ──▶ VPN ──▶ DNS ──▶ nginx-tls ──▶ Application
         (WG)    (A)     (HTTPS)       (localhost)

User connects to VPN (Tailscale client → Headscale)
DNS resolves service hostname to pod VPN IP
nginx-tls terminates TLS, validates VPN IP range
nginx-tls proxies request to application on localhost
Application processes request (may authenticate via FreeIPA LDAP)

Metrics Collection Flow

Pods ──▶ Prometheus ──▶ Thanos ──▶ Grafana
         (scrape)       (store)    (query)
                                     ▲
Pods ──▶ Promtail ──▶ Loki ─────────┘
         (push)        (index)

Prometheus scrapes /metrics endpoints (ServiceMonitor auto-discovery)
Thanos optionally archives and downsamples metrics for long-term storage
Promtail DaemonSet collects logs from all pods
Loki indexes logs with Kubernetes metadata labels
Grafana queries Prometheus/Thanos for metrics and Loki for logs

See Monitoring Guide.

DNS Management Flow

Terraform ──▶ Cloudflare API ──▶ DNS Records
              (create A record)
                    │
                    ▼
Init Container ──▶ Update IP ──▶ Service VPN IP
(lifecycle)        (on startup)
                    │
                    ▼
DNS Sidecar ────▶ Update IP ──▶ Final VPN IP
(lifecycle)       (after VPN up)

Terraform creates DNS A record with fallback IP (node IP)
Init container updates DNS to pod's VPN IP on startup
DNS sidecar waits for Tailscale connection, updates to final VPN IP
Cleanup on deletion: Init container removes old records before starting

See DNS Management Guide.

Security Architecture

Network Security

VPN-only access: All services accessible only via Tailscale VPN (100.64.0.0/10)
nginx IP restrictions: allow 100.64.0.0/10; deny all;
No public exposure: Services not accessible from internet
TLS everywhere: cert-manager + Let's Encrypt for all HTTPS
External ingress: Only Headscale enrollment endpoint public

Authentication & Authorization

Centralized auth: FreeIPA LDAP for all service logins
LDAPS encryption: Port 636 for LDAP communication
RBAC boundaries: Kubernetes namespaces with strict RoleBindings
Cross-namespace RBAC: Explicit bindings for lifecycle scripts
Service accounts: Minimal permissions per service

Secrets Management

Kubernetes secrets: Passwords, tokens, keys
Terraform sensitive vars: Marked sensitive = true
Never committed: .env, *.tfvars, credentials gitignored
Vault (future): Centralized secret storage with auto-rotation

See Security Architecture for detailed security design.

Deployment Model

Infrastructure as Code

Tool: Terraform (HCL)
Pattern: Single terraform apply deploys everything
State: Local state file (S3/MinIO planned)
Variables: terraform.tfvars for configuration
Modules: None (flat structure for simplicity)

Dependency Management

Pattern: Explicit depends_on without [0] indexing
Count-based: All services toggleable via var.service_enabled
No circular deps: Fallback IPs prevent chicken-egg scenarios
Self-healing: Services recover automatically on failures

See Dependency Tree Management.

GitOps (Future)

ArgoCD planned: Automatic sync from Git
Current: Manual Terraform apply
Dashboard sync: Grafana uses git-sync sidecar pattern

Scalability Considerations

Current Limitations

Single-replica: Most services run 1 replica (StatefulSet pattern)
Local storage: PVCs on Linode block storage
Thanos storage: Filesystem-backed (not S3/object storage)
Loki retention: emptyDir (ephemeral)

Scaling Strategies

Vertical Scaling:

Adjust CPU/memory limits in Terraform variables
Increase PVC sizes (requires storage class support)

Horizontal Scaling (Future):

Convert StatefulSets to Deployments where applicable
Add LoadBalancer services for multi-replica
Implement object storage for Thanos/Loki

Node Scaling:

Linode LKE autoscaling enabled
Node affinity for CPU vs GPU workloads
Toleration for specialized nodes

See Scaling Guide.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Architecture Overview

System Architecture

Core Components

Category-Based Namespaces

VPN Mesh Networking

Identity Management

Multi-Container StatefulSet Pattern

Data Flow

Service Access Flow

Metrics Collection Flow

DNS Management Flow

Security Architecture

Network Security

Authentication & Authorization

Secrets Management

Deployment Model

Infrastructure as Code

Dependency Management

GitOps (Future)

Scalability Considerations

Current Limitations

Scaling Strategies

Related Documentation

Architecture Deep-Dives

Service Documentation

Operations

FilesExpand file tree

overview.md

Latest commit

History

overview.md

File metadata and controls

Architecture Overview

System Architecture

Core Components

Category-Based Namespaces

VPN Mesh Networking

Identity Management

Multi-Container StatefulSet Pattern

Data Flow

Service Access Flow

Metrics Collection Flow

DNS Management Flow

Security Architecture

Network Security

Authentication & Authorization

Secrets Management

Deployment Model

Infrastructure as Code

Dependency Management

GitOps (Future)

Scalability Considerations

Current Limitations

Scaling Strategies

Related Documentation

Architecture Deep-Dives

Service Documentation

Operations