DRAFT - WORK IN PROGRESS

Description

Last year my wife came to me a said: "Oren you should start a project so you will have something to do outside of work", So I created this repository 😁

This repo holds all the configuration and documentation that is needed to set up my self-hosting home Kubernetes cluster on raspberry pie boards.

Project Goals

• The goal of the project is to fully automate my hosting environment at home.
• To have the entire state of the environment declared in GIT
• Learn and implement the latest DevOps tools and methods.

Architecture

graph TD
    subgraph Nodes [Physical Layer: Raspberry Pi 4 4GB]
        K3S01[k8s-master-01<br/>192.168.1.10]
        K3S02[k8s-node-01<br/>192.168.1.11]
        K3S03[k8s-node-02<br/>192.168.1.12]
        K3S04[k8s-node-03<br/>192.168.1.13]
        SSD[(250GB SSD SATA)] --- K3S01
    end

    subgraph Cluster [Kubernetes Layer: K3s Cluster]
        Flux[FluxCD GitOps]
        Sealed[Sealed Secrets]
        Prom[Prometheus Operator]
        Metal[MetalLB L2 LB]
        Longhorn[Longhorn Storage]
    end

    subgraph Apps [Applications]
        HA[Home Assistant]
        PH[Pi-Hole]
        WG[WireGuard]
        PI[Podinfo]
    end

    Nodes --> Cluster
    Flux -.-> Cluster
    Cluster --> Metal
    Cluster --> Longhorn
    Longhorn --> HA
    Longhorn --> PH
    Metal --> Ingress[Ingress Nginx]
    Ingress --> Apps

Loading

Stack Components

• Infrastructure

  • FluxCD - GitOps Toolkit
  • K3S - Kubernetes Distro
  • METALLB - Layer 2 LB
  • LongHorn - Distributed storage for K8S
  • Ingress Nginx - Ingress Controller
  • Cert-Manager - SSL Certificate Management
  • Kube-Prometheus-Stack - Monitoring & Alerting

• Applications

  • Podinfo - Demo app
  • Home Assistant - Home Automation
  • Pi-Hole - DNS Ad Blocker
  • Plex - Media Center
  • WireGuard VPN

Continues Integration Pipeline ---

I use Github Action to enable a Continues Integration solution to check the new code and config that I plan to represent to the system.

• GitHub Actions

Bootstrapping

The requirements to bootstrapping the Kubernetes Cluster on my raspberry pies. The bootstrap process is divided into two steps. First bootstrap the cluster, then deploy the FluxCD Controller to deploy all my Kubernetes Resources.

• Node Setup Guide - Provisioning: Flash SD cards and configure static IPs.

• Ansible Automation - Automated Setup: Install K3s and bootstrap FluxCD.

• FluxCD Clusters - Cluster Config: Define the GitOps state for production and staging.

• Applications Guide - Apps Deployment: Manage applications via Kustomize and FluxCD.

• Cluster Bootstrap

• GitOps Bootstrap

Automated Setup (Ansible + Bitwarden)

A fully automated setup is available to provision the nodes, install K3s, and bootstrap FluxCD. See the Ansible README for full details.

1. Provision Nodes

Flash your SD cards and follow the Node Setup Guide to enable root login with a preset password and static IP.

2. Login to Bitwarden

Ensure the Bitwarden CLI (bw) is installed and authenticated on your machine:

bw login
export BW_SESSION=$(bw unlock --raw)

3. Run the Ansible Playbook

Update ansible/hosts.ini with your nodes' IPs and then run:

ansible-playbook -i ansible/hosts.ini ansible/site.yml

This single command will:

1. Prepare nodes: Disable swap, enable cgroups, and install K8s dependencies.
2. Install K3s: Deploy the master and join all workers.
3. Bootstrap FluxCD: Fetch your GitHub token from Bitwarden and initialize GitOps on the cluster.

Containerized Bootstrap Environment

To avoid installing tools locally, you can use the provided Docker image which contains all necessary tools (ansible, gh, bw, helm, kubectl, flux).

1. Build the image

docker build -t homelab-bootstrap -f Dockerfile.bootstrap .

2. Run the container

Mount your SSH keys and the current directory to the container:

docker run -it --rm \
  -v $(pwd):/workspace \
  -v ~/.ssh:/root/.ssh:ro \
  homelab-bootstrap

Once inside, you can run the bootstrap commands (e.g., bw login, ansible-playbook ...).