tf-kube-any-compute

Universal Kubernetes Infrastructure for Any Compute Platform

[![LinkedIn][linkedin-shield]][linkedin-url]

tf-kube-any-compute provides a comprehensive, cloud-agnostic Kubernetes infrastructure designed for tech enthusiasts and homelab builders who want to:

• 🚀 Spin up clusters quickly on any Kubernetes distribution (K3s, MicroK8s, EKS, GKE, AKS)
• 🔧 Learn Kubernetes through hands-on experience with production-grade services
• 📈 Scale incrementally by adding services based on their architecture and needs
• 🏗️ Build expertise in Infrastructure as Code, monitoring, service mesh, and security

Perfect for any compute platform: Raspberry Pi clusters, home servers, cloud environments, edge devices, and learning labs.

🛠️ Services Deployed

Core Infrastructure

• 🌐 Traefik - Modern ingress controller with automatic SSL
• ⚖️ MetalLB - Load balancer for bare metal clusters
• 💾 Storage Drivers - NFS CSI + HostPath for flexible storage
• 🔍 Node Feature Discovery - Hardware detection and labeling with enhanced storage detection (NVMe, SATA, USB, high-capacity drives)

Platform Services

• 📊 Prometheus + Grafana + Kube-State-Metrics - Complete monitoring and visualization stack with Kubernetes metrics
• 📈 Metrics Server - Kubernetes metrics API for kubectl top and HPA functionality
• 🔐 Vault + Consul - Secrets management and service discovery with service mesh
• 🐳 Portainer - Container management web UI
• 🛡️ Gatekeeper - Policy engine (optional)
• 🔒 Traefik Middleware - Centralized authentication (Basic Auth + LDAP) with rate limiting
• 🔑 Authelia - SSO and 2FA authentication provider with LDAP, OIDC, and Duo integration (optional)
• 💉 Redis - In-memory data structure store for caching, session storage, and message queuing (optional)

Automation & Workflow Services

• 🏠 Home Assistant - Open-source home automation platform with 1000+ integrations
• 🏢 openHAB - Vendor-neutral home automation with enterprise-grade Java runtime
• 🍎 Homebridge - Apple HomeKit bridge for smart home devices with 3000+ plugins
• 🔴 Node-RED - Visual programming tool for IoT and automation workflows
• ⚡ n8n - Workflow automation platform (self-hosted Zapier/IFTTT alternative)

Built With

• Terraform - Infrastructure as Code
• Helm - Kubernetes package manager
• Kubernetes - Container orchestration

🚀 Quick Start

Prerequisites

# Install required tools
terraform >= 1.0
kubectl
helm >= 3.0

# Verify cluster access
kubectl cluster-info

1. Clone and Configure

git clone https://github.com/gannino/tf-kube-any-compute.git
cd tf-kube-any-compute

# Copy and customize configuration
cp terraform.tfvars.example terraform.tfvars
vi terraform.tfvars

2. Deploy Infrastructure (Two-Step Process)

Step 1: Initial Deployment

# Initialize Terraform
make init

# Create environment workspace
terraform workspace new homelab

# Review planned changes
make plan

# Deploy core services (without authentication)
make apply

Step 2: Enable Authentication (After CRDs are ready)

# Edit terraform.tfvars and change enabled = false to enabled = true
vi terraform.tfvars

# Find this line and change it:
# enabled = false  # CHANGE TO TRUE after first deployment
# to:
# enabled = true

# Apply authentication configuration
make apply

🔐 Two-Step Deployment: The first deployment installs core services without authentication to avoid CRD dependency issues. After Traefik CRDs are installed, simply change middleware_overrides.enabled = false to middleware_overrides.enabled = true in your terraform.tfvars to enable basic authentication for monitoring services.

3. Access Your Services

After deployment, access services at:

• Traefik Dashboard: https://traefik.homelab.k3s.example.com
• Grafana: https://grafana.homelab.k3s.example.com
• Portainer: https://portainer.homelab.k3s.example.com
• Consul: https://consul.homelab.k3s.example.com
• Vault: https://vault.homelab.k3s.example.com
• Home Assistant: https://home-assistant.homelab.k3s.example.com
• openHAB: https://openhab.homelab.k3s.example.com
• Homebridge: https://homebridge.homelab.k3s.example.com
• Node-RED: https://node-red.homelab.k3s.example.com
• n8n: https://n8n.homelab.k3s.example.com
• Authelia: https://authelia.homelab.k3s.example.com

🔒 SSL Certificates: All services automatically get SSL certificates via Let's Encrypt using your configured DNS provider

📊 Enhanced Monitoring & Dashboards

tf-kube-any-compute provides comprehensive Kubernetes monitoring out-of-the-box with curated Grafana dashboards:

📈 Pre-configured Dashboards

• Cluster Overview - Complete cluster health and resource utilization
• Node Monitoring - Detailed node metrics with ARM64/AMD64 support
• Workload Analysis - Pods, Deployments, StatefulSets, DaemonSets
• Storage Monitoring - Persistent Volumes and storage classes
• Network Insights - Services, Ingress, and networking metrics
• Infrastructure Stack - Prometheus, Grafana, Traefik monitoring
• Homelab Specific - Raspberry Pi and ARM64 optimized dashboards

🔍 Kubernetes Metrics Collection

• kube-state-metrics - Comprehensive Kubernetes object metrics
• Node Exporter - System and hardware metrics
• Prometheus Operator - Advanced monitoring capabilities
• ServiceMonitor - Automatic service discovery

📁 Organized Dashboard Structure

• Overview - Main cluster dashboards
• Kubernetes - Kubernetes-specific monitoring
• Infrastructure - Monitoring stack and applications

All dashboards are automatically imported and organized for the best out-of-the-box experience.

⚙️ Configuration

For comprehensive configuration options, see:

• Authentication Guide - Complete authentication setup guide
• Variables Reference - All configuration options including:
  • Service Overrides: Fine-tune every aspect of your deployment
  • Mixed Architecture Management: ARM64/AMD64 cluster strategies
  • Storage Configuration: NFS, HostPath, and storage class options
  • Password Management: Auto-generation and custom overrides
  • DNS & SSL: Multi-provider DNS and Let's Encrypt setup
  • Architecture Detection: Intelligent service placement

🔒 Authentication & Security

Centralized Authentication

tf-kube-any-compute provides centralized authentication through Traefik middleware with support for multiple authentication methods:

• 🔑 Basic Authentication - Secure username/password authentication (default)
• 🏢 LDAP Integration - Enterprise directory integration (JumpCloud, Active Directory, OpenLDAP)
• 🛡️ Rate Limiting - Protection against brute force attacks
• 🔄 Priority System - Automatic fallback from LDAP to Basic Auth

Two-Step Authentication Setup

Step 1: Initial Deployment (No Authentication)

# Copy example configuration
cp terraform.tfvars.example terraform.tfvars

# Deploy core services first
terraform apply

Step 2: Enable Authentication

# Edit terraform.tfvars and change enabled flag
vi terraform.tfvars

# Change this line:
# enabled = false  # CHANGE TO TRUE after first deployment
# to:
# enabled = true

# Apply authentication
terraform apply

Advanced Authentication Examples

Basic Authentication (Recommended for most users)

service_overrides = {
  traefik = {
    middleware_config = {
      basic_auth = {
        enabled         = true
        username        = "admin"
        static_password = ""  # Auto-generated secure password
        realm           = "Monitoring Services"
      }
    }
  }
}

LDAP Authentication (JumpCloud)

service_overrides = {
  traefik = {
    middleware_config = {
      ldap_auth = {
        enabled   = true
        method    = "forwardauth"  # or "plugin"
        url       = "ldap://ldap.jumpcloud.com"
        base_dn   = "ou=Users,o=YOUR_ORG_ID,dc=jumpcloud,dc=com"
        attribute = "uid"
      }
    }
  }
}

LDAP Authentication (Active Directory)

service_overrides = {
  traefik = {
    middleware_config = {
      ldap_auth = {
        enabled       = true
        method        = "forwardauth"
        url           = "ldap://ad.company.com"
        base_dn       = "dc=company,dc=com"
        bind_dn       = "cn=service,dc=company,dc=com"
        bind_password = "service-password"
        search_filter = "(sAMAccountName={username})"
      }
    }
  }
}

Protected Services:

• Traefik Dashboard, Prometheus, AlertManager

Services with Built-in Auth:

• Grafana, Portainer, Vault, Consul (use native authentication)

Authelia SSO and 2FA Authentication

Authelia provides enterprise-grade Single Sign-On (SSO) and Two-Factor Authentication (2FA) for your entire infrastructure stack. It integrates seamlessly with Traefik for centralized authentication management.

Key Features

• 🔐 SSO Authentication: Single login for all your services
• 📱 2FA Support: TOTP, Duo Security, and U2F
• 🏢 LDAP Integration: Active Directory, OpenLDAP, JumpCloud
• 🔑 OIDC Provider: OpenID Connect for modern applications
• 🎯 Fine-Grained Policies: Per-service access control rules
• 🔄 Session Management: Redis-based HA session storage

Quick Start

Enable Authelia:

# Edit terraform.tfvars
vi terraform.tfvars

# Enable Authelia
services.authelia = true

# Basic configuration
service_overrides = {
  authelia = {
    default_policy = "bypass"  # Start with bypass, then tighten
    totp_enabled  = true       # Enable 2FA
  }
}

# Apply
terraform apply

A