Homelab: Kubernetes Home Cluster - Applications

This repository contains applications deployed on the home-cluster via Flux using GitOps.

Bootstrapping

A Kubernetes cluster needs to be bootstrapped with the Cilium CNI and Flux pointing to this repository.

For ksops and ArgoCD to decrypt the initial secrets for configuring the External Secrets Operator using Doppler, a Google Cloud Service Account with access to the correct KMS key needs to be set in the flux namespace.

Attention: some applications will be automatically deployed, others not (yet).

App-of-Apps

The repository follows the app-of-apps pattern.

The first Flux Kustomization being defined needs to reference app-of-apps/.

These are bootstrapping the main Flux applications, referring to the respective <PROJECT>/applications/ kosutomizations:

infrastructure: core cluster infrastructure
core: core applications
applications: (user) applications running on the cluster/network
home-assistant: Home Assistant related applications

Each of these applications follows the app-of-apps pattern again using sub-kustomizations defined in the respective application directories.

Hosted Services

Infrastructure

The following applications are defined in infrastructure/.

Cilium - Provides the cluster CNI.
CSI NFS Driver - Exposes the NAS' NFS storage as a Kubernetes StorageClass.
MetalLB - Provides a Kubernetes network load balancer to expose Kubernetes Services.
Longhorn - Exposes local storage to Kubernetes StorageClasses.
NFS CSI Driver - Exposes NAS NFS storage to Kubernetes StorageClasses.
External Secrets Operator - Synchronizes secrets from external stores to Kubernetes Secret objects.
- External Secrets Stores - Deploys the required ClusterSecretStores and Doppler Service Tokens as Kubernetes Secrets.
Traefik - Exposes Kubernetes Ingress resources to the "outside world".

Core Applications

The following applications are defined in core/.

cert-manager - Certificate management using ACME Let's Encrypt.
External DNS with Google Cloud DNS integration - Creates DNS records in Google Cloud DNS domains for publicly reachable services.
victoria-metrics-stack - Monitoring stack using Victoria Metrics.
loki-stack - Logging stack using Grafana Loki.

(User) Applications

The following applications are defined in applications/.

Adguard - DNS server with ad filtering/blocking capabilities.
dnsmasq - IPv4 and IPv6 DHCP server.
External DNS with Adguard integration - Creates DNS records in Adguard for internal, local only, reachable services. Uses the External DNS Adguard Webhook provider.
External Services - Deploys Kubernetes Services and Ingresses to local endpoints, and existing services outside of the cluster.
Grafana - Visualization of metrics, and other data.

Home Assistant

The following applications are defined in home-assistant/.

ecowitt2mqtt - Forwards data received from ecowitt devices to the MQTT broker.
EMQX - A MQTT broker.
Home Assistant - The Home Assistant instance.
Node-RED - Automation based on flows and Home Assistant data.
Ring MQTT - Amazon Ring devices to MQTT bridge.
Telegraf - Forwards Home Assistant state changes to a local InfluxDB instance.
Z-Wave JS UI - Full featured Z-Wave Control Panel and MQTT Gateway.

Notes: Backup and Restore

Home Assistant related backup and restore is currently handled via S3 backups.

The following services implement an initContainer as well as a nightly CronJob to backup data to an S3 bucket. If no data is found in the Persistent Volume yet, the data from will be retrieved and copied over which results in a full restore.

Ring MQTT

The following services use API calls to determine whether a backup or restore is necessary.

Node-RED
Home Assistant
Z-Wave JS UI

The following services also have Git repositories to store their configuration which gets pulled in upon start.

Home Assistant
- Home Assistant also defines it's own backup method via a trigger and a shell_command, and doesn't rely on a CronJob.
Ring MQTT

Backup and Restore

No (cluster-wide) backup and restore has been implemented as of yet.

Note: for Home Asisstant backup and restore, see the corresponding section.

Continuous Integration and Automations

GitHub Actions are linting all YAML files.
Renovate Bot is updating Helm releases and used container images in the values.yaml files, and GitHub Actions.

muhlba91 / homelab-home-cluster-applications