DOCSEARCHbyAlgolia
Submit Docs

LorenzoLab Homelab Documentation

website·Indexed 30 days ago

https://docs.lorenzolab.com

Documentation for a personal homelab setup, featuring guides on Kubernetes with k3s, GitOps management using Flux, secrets encryption with SOPS, and server preparation including static IP assignment and hardware configuration.

Tokens
1.8K
Snippets
14
Records
17
Agent score
50%

What's inside LorenzoLab

  1. Homelab Kubernetes cluster hardware and software architecture

    The cluster is built on three HP EliteDesk 800 G4 mini PCs (Intel i5-8500T CPU, 16GB RAM, 1TB SSD). Proxmox is installed on the bare metal of each PC to host three virtual machines (one master and two workers), each allocated 10GB of RAM and 4 CPU cores. The software stack consists of k3s as the Kubernetes distribution, Traefik as the ingress controller, and Longhorn for distributed block storage.

  4. Deploy an existing age key to Kubernetes

    If you have an existing age key (e.g., stored in 1Password), you can deploy it directly to the flux-system namespace as a Kubernetes secret named sops-age without saving it to a local file.
    op document get --vault=Homelab "AGE_KEY" |
kubectl create secret generic sops-age \
--namespace=flux-system \
--from-file=age.agekey=/dev/stdin

  5. Bootstrap Flux into an existing repository without manifests

    Use the flux bootstrap git command to initialize Flux in an existing repository. You must provide the SSH URL of the repository, the target branch, the path where manifests should be stored, and the path to your local private key. Additionally, the corresponding SSH public key must be added to your GitHub account.
    flux bootstrap git \
  --url=ssh://git@github.com/lorenzorapetti/homelab.git \
  --branch=main \
  --path=kubernetes/cluster \
  --private-key-file=/Users/lorenzo/.ssh/id_ed25519

  8. Configure SSH key access for k3s servers

    Set up SSH key-based authentication to manage servers. Generate an Ed25519 key pair and copy the public key to the target servers using ssh-copy-id.
    # Generate the SSH key
ssh-keygen -t ed25519 -C "your_email@example.com"

# Copy the key to the server (replace <host ip> and username)
ssh-copy-id -i ~/.ssh/id_ed25519.pub lorenzo@<host ip>

  9. Deploy a multi-master HA k3s cluster with k3sup

    Use k3sup to install a high-availability (HA) k3s cluster with embedded etcd. The process involves installing the first master node and then joining subsequent master nodes to the cluster.
    # 1. Install the first master node
export SERVER_IP=10.0.2.10
export USER=lorenzo

k3sup install \
  --ip $SERVER_IP \
  --user $USER \
  --cluster \
  --k3s-version v1.33.1+k3s1 \
  --ssh-key ~/.ssh/id_ed25519 \
  --local-path ~/.kube/config

# 2. Join additional master nodes
export NEXT_SERVER_IP=10.0.2.11

k3sup join \
  --ip $NEXT_SERVER_IP \
  --user $USER \
  --server-user $USER \
  --server-ip $SERVER_IP \
  --server \
  --k3s-version v1.33.1+k3s1 \
  --ssh-key ~/.ssh/id_ed25519

  10. Install Kubernetes CLI tools and utilities

    To manage a Kubernetes cluster, install kubectl along with common utilities for secret encryption (kubeseal), cluster switching (kubectx), object management (kustomize), terminal UI (k9s), application management (helm), and GitOps (flux).
    brew install kubectl kubeseal kubectx kustomize k9s helm fluxcd/tap/flux

  11. Install Flux using an existing repository with manifests

    When deploying Flux from a repository that already contains Flux manifests, you must first apply the private key secret to the cluster. Ensure that the SOPS secret is applied before proceeding. Use the -k flag with kubectl apply to ensure the kustomization.yaml file is processed.
    # 1. Create namespace and apply the private key secret
kubectl create ns flux-system && op document get --vault Homelab "Flux Key" | kubectl apply -f -

# 2. Apply the Flux manifests using the kustomization flag
kubectl apply -k kubernetes/cluster/flux-system

  12. Organize Flux repository for dependency-aware deployments

    To ensure that critical infrastructure (like CRDs and secrets) is deployed before applications, use a structured directory layout and define dependencies via Kustomization objects. When Flux is bootstrapped with --path=kubernetes/cluster, it reconciles the cluster based on the definitions in that directory (e.g., infrastructure.yaml).

    Recommended directory structure:

    • kubernetes/cluster/: Contains the primary reconciliation logic and Flux system components.
    • kubernetes/infrastructure/: Contains infrastructure-specific manifests (e.g., cert-manager, sealed-secrets).
    • kubernetes/apps/: Contains the actual applications to be deployed.

    Typical deployment order and dependencies:

    1. sealed-secrets: Deployed first as other objects depend on it.
    2. cert-manager: Deployed after sealed-secrets (e.g., to access Cloudflare tokens for DNS challenges).
    3. longhorn: Installs operators and CRDs.
    4. apps: Deployed last, with explicit dependencies on cert-manager, sealed-secrets, and longhorn.
    kubernetes/
├─ apps/
├─ cluster/
│  ├─ infrastructure.yaml
│  ├─ flux-system/
│  │  ├─ gotk-components.yaml
│  │  ├─ gotk-sync.yaml
│  │  ├─ kustomization.yaml
├─ infrastructure/
│  ├─ cert-manager/
│  ├─ sealed-secrets/