Homelab - Orbit

Repository for managing a Kubernetes cluster through GitOps workflows.

Powered by Proxmox VE, Terraform, Talos, Argo CD, and Sealed Secrets. Kept up to date with Renovate. Includes a healthy dose of automation and the occasional 3-letter commit message.

---

📖 Overview

This repository hosts the IaC (Infrastructure as Code) configuration for my homelab.

The homelab runs on Proxmox VE hypervisor nodes, with VMs provisioned using Terraform.

• helios — a Talos Kubernetes cluster (control plane + workers)
• atlas — an Ubuntu VM used as a file server for media storage and Longhorn backups

All cluster workloads are managed via GitOps with Argo CD and an ApplicationSet that auto-syncs from this repository. Secrets are encrypted in-repo with SOPS + age for shared/bootstrap material and selected bootstrap secrets, while Sealed Secrets handles Kubernetes-native secret workflows for application manifests.

Namespaces also carry Pod Security Admission labels. General-purpose namespaces (argocd, auth, and services) enforce the Kubernetes baseline profile and emit restricted warnings/audits, while infrastructure namespaces that still need elevated access (monitoring, network, storage, and velero) keep permissive enforcement and emit baseline warnings/audits so exceptions remain visible without breaking workloads.

🚀 Getting Started

1. Prepare the cluster-ops toolbox.

   Follow docs/operations/cluster-ops-toolbox.md to install the required CLI tools. Once the tools are present, validate the workstation toolchain from the repo root with:

   .\scripts\initialize-ClusterOps.ps1 -SkipConfigImport

2. Create Terraform variables in terraform/helios (and optionally terraform/atlas). Use the provided .example files as a reference.

3. Deploy the Talos cluster using Terraform:

cd terraform/helios
terraform init
terraform apply

4. Import dedicated kubeconfig and talosconfig files for day-2 work:

.\scripts\initialize-ClusterOps.ps1

This writes dedicated config files to ~/.kube/orbit-helios.config and ~/.talos/orbit-helios.config, then exports KUBECONFIG and TALOSCONFIG for the current shell.

5. Bootstrap the cluster (creates namespaces, reapplies sealed-secret-backup.yaml into the secrets namespace, installs ArgoCD and ArgoCD-Apps):

.\scripts\new-Cluster.ps1

ArgoCD will automatically sync all remaining applications from the repository. Retrieve the initial admin password with:

.\scripts\get-ArgoPassword.ps1

6. Creating a sealed value for a specific secret key:

.\scripts\new-SealedSecret.ps1 -password <value> -namespace <ns> -secretName <name> -key <secretKey>

7. Edit a SealedSecret file using your default editor (sops-like flow):

.\scripts\edit-SealedSecret.ps1 -FilePath <path-to-sealed-secret.yaml>

This decrypts the file to a temporary manifest, opens it in $VISUAL/$EDITOR (falls back to vi), and reseals it back to the original file when the editor exits. The script automatically preserves secret name, namespace, and scope (strict, namespace-wide, cluster-wide) from the existing manifest.

8. Backing up Sealed Secrets recovery keys from the secrets namespace:

.\scripts\backup-SealedSecret.ps1

Use -controllerNamespace <namespace> if your controller is not running in the repo default secrets namespace.

9. Configure Velero Azure credentials (create a velero-credentials secret with a cloud key in the velero namespace that includes your Azure subscription ID, then update kubernetes/velero/velero/values.yaml with your Azure storage account and resource group).

   The repo keeps this credential as a SOPS-encrypted secret manifest at kubernetes/velero/velero/velero-credentials.sops.yaml; prefer updating that file instead of introducing a second secret-management pattern.

10. Restore Velero backups during onboarding (optional):

.\scripts\new-Cluster.ps1 -RestoreVelero -VeleroSchedule daily

🧰 Cluster Ops Toolbox

Use the repo's cluster-ops helpers from a dedicated admin workstation shell:

.\scripts\initialize-ClusterOps.ps1
.\scripts\get-ClusterOpsSnapshot.ps1 -IncludeVelero

• initialize-ClusterOps.ps1 validates the CLI toolchain and imports dedicated kubectl/talosctl configs from the Terraform outputs.
• get-ClusterOpsSnapshot.ps1 gives a quick day-2 status view for nodes, Argo CD applications, unhealthy pods, and optional Velero resources.
• backup-SealedSecret.ps1 defaults to the repo's active secrets namespace, matching the checked-in Sealed Secrets key backup manifest.
• docs/operations/cluster-ops-toolbox.md includes the Grafana access flow for the repo-managed monitoring stack.
• docs/operations/storage-dr.md captures the repo's current Longhorn replica policy plus the Velero backup and restore drill workflow.

🌐 Networking and access conventions

• Public HTTP exposure should use Traefik IngressRoute resources on the websecure entrypoint.
• External TLS currently terminates in Traefik via the shared letsencrypt ACME resolver; cert-manager's internal-selfsigned issuer is reserved for cluster-internal certificates.
• Admin and operator-facing routes should usually attach the shared network/oauth2-proxy-auth middleware, with network/local-only available for LAN-only surfaces when needed.
• The helm-charts/generic-service chart now exposes ingress.entryPoints, ingress.middlewares, and ingress.tls settings so new services can follow the same Traefik and access pattern without copy/paste edits.

Apps

Services

End-user facing applications

Logo	Name	Description
	Hello-World	Example and template application for the repository
	Home Assistant	Open-source home automation platform (proxied via nginx).
	Memos	Lightweight, self-hosted note-taking service.
	AIOStreams	All-in-one Stremio addon aggregator and proxy.
	Nexus3	Universal artifact repository manager.
	Obsidian Sync	Self-hosted sync backend for Obsidian (proxied via nginx).
	RoomCtrlScraper	Custom service to scrape and manage room control data.

Network

Ingress, DNS, and identity services

Logo	Name	Description
	authentik	Identity provider enabling single sign-on (SSO) and centralized user management.
	Cert Manager	Manages TLS certificates for secure communication within Kubernetes.
	MetalLB	Load-balancer implementation for bare metal Kubernetes clusters.
	Traefik	Cloud-native reverse proxy and ingress controller for Kubernetes.
	Traefik CRDs	Custom Resource Definitions required by Traefik.

Storage

Persistent storage services

Logo	Name	Description
	Longhorn	Cloud-native distributed block storage for Kubernetes.
	Velero	Scheduled backups with retention and Azure off-site storage.
	Syncthing	Continuous file synchronization between devices.

Secrets

Secret management

Logo	Name	Description
	Sealed Secrets	Encrypts Kubernetes secrets for safe storage in Git.

Platform

Foundation components for running and deploying applications in my cluster

Logo	Name	Description
	Argo CD	GitOps tool for continuous delivery and Kubernetes application management.
	kube-prometheus-stack	Cluster monitoring foundation with Prometheus, Alertmanager, Grafana, and Traefik/Velero/Longhorn hooks.
	Renovate	Automates dependency and container image updates via pull requests.
	Intel QuickSync	Intel GPU device plugin enabling hardware-accelerated video transcoding in Kubernetes.

💻 Hardware

Name	Device	CPU	RAM	Storage	Purpose
pve1	Aoostar R7	AMD Ryzen 7 5825U	48 GB DDR4 SO-DIMM	8TB HDD + 2TB SSD	Compute/General