📚 ARM64 Kubernetes Documentation

Welcome to the comprehensive documentation for the Home Lab to the Moon and Back project - validating ARM64 architecture in the cloud before committing to bare-metal hardware.

🎯 Mission: Develop a cloud-validated, ARM64-first Kubernetes deployment for CozySummit Virtual 2025 on December 3, 2025 to replace traditional high-power AMD64 home lab setups.

🏗️ Architecture Decision Records

📋 ADR Index - Formal architectural decisions and their rationale

ADR Title Status
ADR-001 ARM64 Architecture Choice ✅ Accepted
ADR-002 Test-Driven Generation Methodology ✅ Accepted
ADR-003 Patch Generation Best Practices ✅ Accepted
ADR-004 Role-Based Talos Image Architecture ✅ Accepted

📖 Implementation Guides

🔧 Step-by-step guides for building and deploying the system

Infrastructure Setup

Development & Testing

💰 Cost Analysis & Planning

📈 Financial planning and cost validation

Budget Targets:

  • Baseline: <$0.10/month (idle infrastructure)
  • Validation: <$15/month (active testing periods)
  • Demo: Efficient resource usage for live presentation

🚀 Quick Start

1. Validate ARM64 Talos Images

# Pull the demo-ready ARM64 image
docker pull ghcr.io/urmanac/talos-cozystack-demo:demo-stable

# Extract boot assets for validation
mkdir -p /tmp/talos-assets
docker create --name temp ghcr.io/urmanac/talos-cozystack-demo:demo-stable true
docker cp temp:/assets/. /tmp/talos-assets/
docker rm temp

# Verify ARM64 Talos files
ls -la /tmp/talos-assets/talos/arm64/

2. Run Local Validation

# Comprehensive validation suite (6 stages)
./validate-complete.sh

# Individual validations
./validate-patch.sh                    # Patch application
yq eval '.jobs.build-cozystack-talos-arm64' .github/workflows/build-talos-images.yml  # Workflow syntax

3. Deploy to AWS (Optional)

# See AWS Infrastructure Handoff guide
cd terraform/
terraform init
terraform plan -var="environment=demo"
terraform apply

📊 Project Status

✅ Completed Milestones

  • Matrix Strategy Success: Dual ARM64 Talos image variants with role-based architecture
  • ARM64 Talos image builds with Spin + Tailscale extensions working in parallel
  • GitHub Actions CI/CD pipeline with comprehensive validation and matrix builds
  • Container image publishing to GitHub Container Registry with clean tagging
  • Test-Driven Generation methodology implementation
  • Comprehensive documentation with ADRs

🎯 Working Image Variants

  • Compute Nodes: ghcr.io/urmanac/talos-cozystack-spin-only/talos:v1.11.5
  • Gateway Nodes: ghcr.io/urmanac/talos-cozystack-spin-tailscale/talos:v1.11.5

🔄 Current Phase: Live Testing

  • GitHub Pages setup with beautiful navigation
  • Integration with upstream CozyStack build system
  • Role-based cluster formation testing
  • Performance benchmarking on AWS t4g instances
  • Cost optimization and monitoring setup

🎯 December 3, 2025 Demo Targets

  • Live SpinKube demonstration on ARM64
  • Role-based cluster formation showcase
  • Tailscale subnet router demonstration
  • Real-time cost transparency during presentation
  • Home lab transition plan presentation

🛠️ Development Workflow

Test-Driven Generation (TDG) Process

  1. 🔍 Understand - Analyze requirements and constraints
  2. 🧪 Local Validation - Run complete validation suite
  3. ✅ Validate Changes - Ensure patches apply cleanly
  4. 🚀 Generate Solutions - Use proper tooling (Git, not manual)
  5. 📚 Document Decisions - Capture knowledge in ADRs

Validation Gates

# Before any commit
./validate-complete.sh          # 6-stage comprehensive validation

# Before any push  
git apply --check patches/*.patch  # Patch compatibility
yq eval '.jobs' .github/workflows/build-talos-images.yml  # Workflow syntax

🌟 Key Technologies

Technology Purpose ARM64 Status
Talos Linux Immutable Kubernetes OS ✅ Full support
CozyStack Kubernetes distribution 🔄 Custom ARM64 build
Spin WebAssembly runtime ✅ Native ARM64
Tailscale VPC subnet router ✅ ARM64 optimized
AWS Graviton ARM64 cloud validation ✅ t4g instances

📞 Support & Contributing

Contributing Guidelines

  1. Follow TDG methodology (see ADR-002)
  2. Run local validation before PR submission
  3. Document architectural decisions in ADRs
  4. Update cost analysis for infrastructure changes

📋 Meta Documentation

📚 Project organization and build system documentation

🏷️ Project Meta

  • License: Apache 2.0
  • Status: Active Development (Demo: Dec 3, 2025)
  • Architecture: ARM64-first with cloud validation
  • Methodology: Test-Driven Generation (TDG)
📍 Navigation: 🏠 Project Home 🏗️ ADRs 📖 Guides