Kubernetes Platform Modules

This repository contains modules for deploying and managing a complete Kubernetes platform. It provides both foundational infrastructure capabilities and end-user applications, using a modular approach that enables consistent deployment and management through GitOps practices.

What This Project Provides

This platform enables you to:

• Deploy and manage infrastructure capabilities:

  • Secure service communication with automated TLS certificate management
  • Provide distributed storage with automated backup and replication
  • Configure networking with automated DNS and load balancing
  • Monitor system health with metrics, logs, and alerts
  • Manage databases with automated failover and backups

• Run end-user applications:

  • Secure password management with Bitwarden
  • Remote development environments with Coder
  • Container image registry with Harbor
  • Home automation through Home Assistant
  • Media management with Plex, Jellyfin, and automated content organization
  • Utility services including SMTP relay with Maddy

Module Type	Module Name	Applications (↗)	Capabilities
Infrastructure (Core)	security-core	cert-manager external-secrets trust-manager Kyverno Policy Reporter	• Provides automated TLS certificate management • Enables secure secret management with external providers • Facilitates certificate distribution across namespaces • Enforces Kubernetes security policies • Provides policy reporting and visualization
	storage-core	Longhorn MinIO NFS CSI Driver	• Delivers distributed block storage with replication • Provides S3-compatible object storage • Enables dynamic provisioning from NFS shares
	networking-core	MetalLB external-dns Traefik	• Supplies Layer 2 load balancing for services • Manages DNS records automatically • Controls ingress with TLS and middleware support
	observability-core	Prometheus Loki Grafana Goldilocks	• Collects metrics with ServiceMonitor support • Aggregates logs with retention policies • Provides unified visualization dashboards • Visualizes resource optimization
	database-core	CloudNativePG	• Manages PostgreSQL clusters with automation • Enables high availability with failover • Configures backup with retention policies
	kubernetes-core	CoreDNS Node Feature Discovery Vertical Pod Autoscaler	• Configures cluster-wide service discovery • Provides secure API access • Supports custom DNS zones• Discovers and labels node hardware • Optimizes resource allocation
	clusterops-core	Flux CD system-upgrade-controller reloader	• Manages GitOps-based deployments • Automates component upgrades • Automates pod restarts on config changes
Infrastructure (Extra)	security-extra	Authentik	• Deploys identity provider for SSO • Implements policy-based access control • Secures service ingress with identity headers
	networking-extra	Pi-hole FreeRADIUS Tailscale UniFi	• Filters DNS and blocks ads • Provides secure VPN access • Manages network devices comprehensively • Maps wireless clients to VLANs based on MAC addresses
	observability-extra	Kubernetes Event Exporter Node Problem Detector SNMP Exporter Syslog-ng UniFi Poller	• Exports Kubernetes events to Loki • Collects metrics from network devices • Detects node problems with custom definitions
	kubernetes-extra	descheduler	• Balances workloads with policies
Applications	ai	Ollama OpenWebUI	• Hosts large language models locally • Provides web-based chat interface • Enables model selection and configuration
	bitwarden	Bitwarden	• Provides end-to-end encrypted password vault • Enables credential autofill in browsers • Supports two-factor authentication
	coder	Coder	• Creates cloud-based development environments • Provides server-grade compute resources • Enables consistent environment configuration
	downloaders	Sonarr Radarr Lidarr Prowlarr SABnzbd	• Manages TV shows with quality profiles • Handles movies with automated organization • Provides unified indexer management
	harbor	Harbor	• Stores and manages container images and charts • Performs vulnerability scanning on images • Enables image signing and content trust
	home-automation	Home Assistant	• Integrates with smart home devices • Provides automation engine for device control • Enables custom monitoring dashboards
	media	Plex Jellyfin FreeTube Tautulli	• Streams media with transcoding capabilities • Enables privacy-focused YouTube viewing • Monitors Plex statistics and usage
	misc	Maddy	• Houses misc applications • Provides SMTP relay services •
Components	sso	SSO integration patches	• Adds single sign-on to multiple applications • Secures ingress with authentication middleware • Provides consistent login experience
	db-backups	Database backup configuration	• Configures scheduled database backups • Manages backup credentials securely • Applies consistent backup policies
	oidc-credentials	OIDC credential configuration	• Configures OIDC credentials for applications • Enables secure authentication flows • Provides consistent identity integration

Project Structure & Concepts

The platform organizes functionality into module types with clear responsibilities:

classDiagram
    class Module {
        +kustomization.yaml
        +CHANGELOG.md
        +namespace.yaml
        +deploy()
        +configure()
    }

    class InfrastructureModule {
        +core services
        +platform capabilities
        +core/extra pattern
        +provideCapability()
    }

    class ApplicationModule {
        +user services
        +specific use case
        +useInfrastructure()
    }

    class ComponentModule {
        +cross-cutting config
        +kustomize components
        +applyConfiguration()
    }

    Module <|-- InfrastructureModule
    Module <|-- ApplicationModule
    Module <|-- ComponentModule

Module Type	Purpose	Characteristics	Examples
Infrastructure	Provides foundational platform capabilities	• Supplies core services • Uses core/extra pattern • Focuses on platform features • Other modules depend on it	Infrastructure Modules: • Security (certs, secrets) • Storage (block, object) • Networking (DNS, ingress)
Application	Delivers end-user functionality	• Provides user services • Focuses on use cases • Uses infrastructure capabilities • Independent deployment	Application Modules: • Password management • Development environments • Media streaming
Component	Enables cross-cutting features	• Configures shared features • Uses Kustomize components • Applies to other modules • Flexible application	Component Modules: • Single sign-on • Backup policies • Monitoring templates

Finding Your Way

Category	When you need to…	Look in…	To find…	For example…
Project Understanding	Understand the project structure	Project Brief - Organization	Module types and relationships	• Infrastructure/Apps/Components • Core/Extra pattern • Module boundaries
	Learn about design decisions	Project Brief - Design	Architecture principles and patterns	• Module independence • Configuration flexibility • Dependency management
	See how changes are managed	Project Brief - Development	Quality controls and workflows	• Version management • Automated updates • Release process
Module Usage	Find infrastructure capabilities	Infrastructure Modules	Platform services by category	• Security (cert-manager, secrets) • Storage (Longhorn, MinIO) • Networking (MetalLB, Traefik)
	Set up end-user applications	Application Modules	User-facing services	• Password management (Bitwarden) • Development environments (Coder) • Media streaming (Plex)
	Configure cross-cutting features	Component Modules	Reusable configurations	• Single sign-on setup • Backup configurations • Monitoring templates
Configuration	Configure modules	Project Brief - Configuration	Configuration methods	• Kustomize patches • Post-build variables • Component overlays
	Handle dependencies	Project Brief - Dependencies	Dependency management	• Hard vs soft dependencies • Core/Extra pattern • Dependency cycles
	Set up integrations	Project Brief - Integration	Integration patterns	• Certificate management • Secret handling • Monitoring setup