Home Kubernetes cluster

A monorepo that collects the pieces needed to run my homelab Kubernetes cluster and services. It contains infrastructure, cluster manifests, helper scripts and small service projects (for example the Bitwarden SDK server and a Rust connector). The repo is organized to keep infra, apps and bootstrap tooling together so a single place holds the canonical manifests and generation scripts.

• Monorepo: infra, Kubernetes manifests, bootstrap helpers and service code live together.
• Goal: reproducible, git-driven cluster configuration (Flux + sops) with a small Bootstrap helper to generate local TLS material and secrets.
• Primary features used: Cilium for networking, Gateway API driven by Envoy (envoy-gateway) for ingress & edge, and the Bitwarden SDK as an out‑of‑cluster secrets provider.

• Kubernetes manifests

  • Path: kubernetes/main/... — apps and components are organized per-namespace and per-app.
  • Flux and GitOps friendly YAML layout (Flux will pick manifests from the cluster repo).

• Networking: Cilium

  • Cluster CNI: Cilium handles L3/L4 networking, policy and load-balancing.

• Ingress / edge: Gateway API + Envoy (envoy-gateway)

  • Gateway resources live under kubernetes/main/apps/networking/gateway/envoy/manifests.
  • Uses Gateway API (Gateway, HTTPRoute, Backend, BackendTLSPolicy, BackendTrafficPolicy, ClientTrafficPolicy) to explicitly configure client TLS and upstream TLS.

• Secrets & Secrets provider

  • ExternalSecrets configuration lives under kubernetes/main/apps/kube-system/external-secrets/....
  • A ClusterSecretStore is configured to use the Bitwarden SDK provider; the provider typically talks to bw.garb.dev (or an in-cluster service).

• The external-secrets provider can be run outside the cluster (e.g., on your NAS) or inside.
• The ClusterSecretStore config points at the SDK server URL and a caProvider secret used to validate the server certificate:
  • File: kubernetes/main/apps/kube-system/external-secrets/stores/secret-store.yaml
  • Common gotcha: When the provider runs outside the cluster, it must trust the CA that issued the server cert (or you must use an in-cluster service URL instead).

• Two separate TLS problems commonly show up:
  1. Client TLS (client → Gateway): configure the Gateway listener with certificateRefs pointing at a TLS secret in the Gateway's namespace (e.g., networking).
  2. Upstream TLS (Gateway/Envoy → backend): configure Backend and BackendTLSPolicy to instruct Envoy how to speak TLS to upstream services: trust/CA, SNI/hostname, min/max TLS versions. Secrets referenced for upstream trust must be accessible to the Gateway/controller namespace.

• Bootstrap / cert generation

  • bootstrap/bitwarden-sdk/generate.sh
  • bootstrap/bootstrap.sh (creates bitwarden-css-certs secret and optionally annotates it)

• Gateway (Envoy)

  • kubernetes/main/apps/networking/gateway/envoy/manifests/gateway.yaml
  • kubernetes/main/apps/networking/gateway/envoy/manifests/backend-policy.yaml

• ExternalSecrets store

  • kubernetes/main/apps/kube-system/external-secrets/stores/secret-store.yaml

• Regenerate certs and update secret:

bash bootstrap/bitwarden-sdk/generate.sh
bash bootstrap/bootstrap.sh

1. frigate
2. scrypted

Thanks to all the people who donate their time to the Home Operations Discord community. Be sure to check out kubesearch.dev for ideas on how to deploy applications or get ideas on what you may deploy.

• onedr0p
• bernd-schorgers / bjw-s
• buroa
• joryirving
• home-operations

For all their hard work and dedication