Homelab Infrastructure

A comprehensive infrastructure-as-code homelab setup featuring Kubernetes on Talos Linux, deployed on Proxmox VE with automated CI/CD pipelines.

Overview

This project provides a complete homelab infrastructure with:

• Infrastructure: Proxmox VE-based virtual machines managed by Terraform
• Operating System: Talos Linux for immutable, secure Kubernetes nodes
• Orchestration: Single-node Kubernetes cluster with Cilium CNI
• Services: Self-hosted Git platform (Forgejo) and container registry (CNCF Distribution)
• CI/CD: GitHub Actions with self-hosted runners for automated deployments

Quick Start

Prerequisites

• Proxmox VE cluster with API access
• PostgreSQL database for Terraform state backend
• GitHub repository with required secrets configured

Secrets Configuration

Configure the following GitHub secrets:

# Proxmox Access
pve_url                    # Proxmox VE API endpoint
pve_token_id              # Proxmox API token ID
pve_token_value           # Proxmox API token secret
pve_ssh_user              # SSH username for Proxmox hosts
pve_ssh_key               # SSH private key for Proxmox access
pve_ssh_pubkey            # SSH public key for VM access

# State Backend
pg_backend_connstring     # PostgreSQL connection string for Terraform state

# Application Secrets
forgejo_admin_password    # Admin password for Forgejo
forgejo_pg_password       # PostgreSQL password for Forgejo
forgejo_redis_password    # Redis password for Forgejo
forgejo_secret_key        # Secret key for Forgejo sessions
forgejo_runner_password   # Password for Forgejo runner registration

Deployment

1. Deploy Infrastructure:

   # Trigger via GitHub Actions
   gh workflow run "Deploy Infrastructure"
   
   # Or deploy manually
   cd infra
   terraform init
   terraform apply -var-file="prod.tfvars"
   

2. Deploy Services:

   # Automatically triggered after infrastructure deployment
   # Or trigger manually
   gh workflow run "Deploy Services"
   

3. Access Services:

   # Extract cluster configuration
   ./_scripts/fetchconfigs.sh
   
   # Access services
   kubectl get pods -A
   

Architecture

Infrastructure Layer

• Hypervisor: Proxmox VE with Terraform provider
• Virtual Machines:
  • Management cluster node (4 cores, 8GB RAM, 100GB storage)
  • Forgejo runner VM (2 cores, 4GB RAM, 40GB storage)
• Networking: VLAN-based isolation with load balancer IP pool

Platform Layer

• OS: Talos Linux v1.10.2 (immutable, API-driven)
• Kubernetes: v1.33.1 single-node cluster
• CNI: Cilium with eBPF networking and L2 announcements
• Storage: Local path provisioner for persistent volumes
• Ingress: Gateway API with cert-manager for TLS

Application Layer

• Git Platform: Forgejo with PostgreSQL and Redis
• Container Registry: CNCF Distribution with htpasswd auth
• CI/CD: Self-hosted Forgejo runners on dedicated VMs
• Certificate Management: Automated TLS via cert-manager

Directory Structure

infra/                    # Terraform infrastructure code
├── main.tf              # Root configuration
├── prod.tfvars          # Production variables
└── modules/
    ├── cluster/         # Kubernetes cluster module
    └── runner/          # CI/CD runner module

services/                 # Kubernetes service deployments
├── common/              # Shared infrastructure (Gateway API, etc.)
├── distribution/        # Container registry Helm chart
├── forgejo/             # Git platform configuration
└── forgejo-runner/      # Ansible playbooks for runner setup

_scripts/                 # Utility scripts
└── fetchconfigs.sh      # Extract kubeconfig and talosconfig

.github/workflows/        # CI/CD automation
├── deploy-infra.yaml
├── destroy-infra.yaml
├── deploy-services.yaml
└── destroy-services.yaml

Services

Forgejo (Git Platform)

• URL: https://git.bang.dev
• Features: Git hosting, issue tracking, CI/CD integration
• Storage: PostgreSQL database, Redis cache
• Access: Admin credentials via GitHub secrets

Distribution (Container Registry)

• URL: https://registry.bang.dev
• Features: Docker/OCI image storage with authentication
• Storage: Local filesystem with persistent volumes
• Access: htpasswd authentication

Network Configuration

• Management Network: 10.42.20.0/24 (VLAN 20)
• Cluster Node: 10.42.20.10/24
• Runner VM: 10.42.20.11/24
• Gateway: 10.42.20.1
• DNS: 10.42.20.1

Common Operations

Cluster Access

# Extract configurations
./_scripts/fetchconfigs.sh

# View cluster status
kubectl get nodes -o wide
talosctl health

# Check services
kubectl get pods -n forgejo
kubectl get pods -n distribution

Service Management

# Restart services
kubectl rollout restart deployment/forgejo -n forgejo
kubectl rollout restart deployment/distribution -n distribution

# View logs
kubectl logs -n forgejo deployment/forgejo -f
kubectl logs -n distribution deployment/distribution -f

Infrastructure Updates

# Update infrastructure
cd infra
terraform plan -var-file="prod.tfvars"
terraform apply -var-file="prod.tfvars"

# Update services via Helm
helm upgrade forgejo oci://code.forgejo.org/forgejo-helm/forgejo \
  --values services/forgejo/values.yaml \
  --namespace forgejo

Security

• TLS Termination: Automated certificate provisioning via cert-manager
• Network Isolation: VLAN segmentation and Kubernetes network policies
• Secret Management: GitHub Actions secrets and Kubernetes secrets
• Authentication: htpasswd for registry, admin accounts for services
• Access Control: SSH key-based VM access, RBAC for Kubernetes

Monitoring

• Infrastructure: Terraform state tracking and drift detection
• Platform: Kubernetes event monitoring and resource usage
• Applications: Service health checks and deployment status
• CI/CD: GitHub Actions workflow monitoring and runner status

Development

See CLAUDE.md for detailed technical documentation including:

• Comprehensive architecture details
• Configuration file references with line numbers
• Development workflows and conventions
• Troubleshooting guides and recovery procedures

License

This project is for personal homelab use. Adapt configurations for your environment.