Skip to content

CLAUDE.md

Latest commit

 

History

History
113 lines (83 loc) · 3.52 KB

CLAUDE.md

File metadata and controls

113 lines (83 loc) · 3.52 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

This repository manages home infrastructure services deployed to a Kubernetes cluster using Helmfile. The infrastructure is hosted on mbcaas and uses nginx proxies to route traffic to internal services.

Architecture

Infrastructure as Code Pattern

The repository uses a modular Helmfile structure:

  • helmfile.yaml - Main deployment orchestrator with environment and release definitions
    • Defines default environment with secrets loading
    • Uses YAML anchors for DRY configuration
  • modules/*.gotmpl - Go template files for service-specific configurations (home-assistant, frigate)
    • Templates are evaluated by Helmfile with access to environment secrets
  • secrets.sops.yaml - Encrypted secrets managed with SOPS (age encryption)
  • michalski.fr-cert.yaml - Certificate management via cert-manager

Service Architecture

Each service follows a common pattern:

  1. Uses bitnami/nginx chart as a reverse proxy
  2. Proxies requests to backend services (defined in secrets)
  3. Exposes via Traefik ingress with TLS termination
  4. Uses external-dns for automatic DNS configuration
  5. WebSocket support through nginx upgrade header handling

All services:

  • Deploy to the home namespace
  • Share the michalski.fr-cert TLS certificate (wildcard cert)
  • Use ipv4.mbcaas.com as external-dns target
  • Have health checks at /nginx-health

Commands

Deploy all services

helmfile apply

Deploy specific service

helmfile apply --selector name=home-assistant
helmfile apply --selector name=frigate

Preview changes (dry-run)

helmfile diff

Sync (idempotent apply)

helmfile sync

Manage secrets

Secrets are encrypted using SOPS with age encryption. To edit:

sops secrets.sops.yaml

The .sops.yaml configuration file defines the age key used for encryption.

Apply certificate configuration

kubectl apply -f michalski.fr-cert.yaml

Configuration Structure

Environment and Templating

Helmfile uses a default environment that loads secrets from secrets.sops.yaml. The secrets are available in .gotmpl files via {{ .Values.secrets.service_name.key }} syntax.

Module Configuration Pattern

Each module in modules/*.gotmpl is a Go template file that defines:

  • Ingress configuration (hostname, TLS, annotations) - uses templated values from secrets
  • Resource limits and requests
  • Custom nginx serverBlock with proxy configuration
  • Service-specific proxy_pass target (templated from secrets)

Secret Values

The secrets.sops.yaml file contains nested structure:

  • secrets.home_assistant.domain - Domain for Home Assistant
  • secrets.home_assistant.proxy_pass - Backend URL for Home Assistant
  • secrets.frigate.domain - Domain for Frigate
  • secrets.frigate.proxy_pass - Backend URL for Frigate

Ingress Configuration

All services use Traefik ingress with:

  • traefik.ingress.kubernetes.io/router.entrypoints: websecure - HTTPS only
  • external-dns.alpha.kubernetes.io/target: "ipv4.mbcaas.com" - DNS automation
  • Shared wildcard certificate from cert-manager

Dependencies

  • helmfile - Kubernetes deployment orchestration
  • sops - Secret encryption/decryption
  • age - Encryption key management (for sops)
  • kubectl - Kubernetes CLI access
  • Kubernetes cluster with:
    • Traefik ingress controller
    • cert-manager with letsencrypt ClusterIssuer
    • external-dns configured