Flux Gitops

Flux GitOps Platform

The homelab Kubernetes platform uses Flux ResourceSets for centralized, declarative management of Helm releases and configurations.

For ResourceSet patterns, version management, and platform architecture, see kubernetes/platform/CLAUDE.md.

How to Add a New Helm Release

Add to helm-charts.yaml inputs → create charts/<release-name>.yaml values file → register in kustomization.yaml configMapGenerator → optionally add config/<name>/ resources.

helm-charts.yaml entry

inputs:
  - name: "my-new-chart"
    namespace: "my-namespace"
    chart:
      name: "actual-chart-name"
      version: "${my_chart_version}"   # From versions.env via Flux substitution
      url: "https://example.com/charts"
    dependsOn: [cilium]

For OCI registries, prefix url with oci://:

    chart:
      url: "oci://ghcr.io/bjw-s/helm"

The ResourceSet template auto-detects OCI URLs and sets type: oci on the HelmRepository.

Values file

Create charts/<release-name>.yaml:

# yaml-language-server: $schema=<chart-schema-url>
---
replicas: 1

kustomization.yaml registration

configMapGenerator:
  - name: platform-values
    files:
      - charts/my-new-chart.yaml

PodSecurity compliance

Check the target namespace's security level in namespaces.yaml. For restricted namespaces (cert-manager, external-secrets, system, database, kromgo), every container requires:

# Pod-level
podSecurityContext:
  runAsNonRoot: true
  seccompProfile:
    type: RuntimeDefault

# Container-level (every container including init containers)
securityContext:
  allowPrivilegeEscalation: false
  capabilities:
    drop: ["ALL"]
  readOnlyRootFilesystem: true
  runAsNonRoot: true
  seccompProfile:
    type: RuntimeDefault

If the image runs as root, set runAsUser: 65534. task k8s:validate does NOT catch PodSecurity violations — only admission time reveals them.

ResourceSet Template Syntax

The resourcesTemplate uses Go text/template with << >> delimiters. See templates.md for full template examples.

Key functions:

• << inputs.field >> — access input field
• <<- if condition >> / <<- end >> — conditional (leading - trims whitespace)
• <<- range $item := inputs.array >> — loop
• hasPrefix "oci://" inputs.chart.url — string prefix check

Dependency Management

Release dependencies (waits for other HelmReleases):

inputs:
  - name: "grafana"
    dependsOn: [kube-prometheus-stack, alloy]

ResourceSet dependencies (waits for another ResourceSet):

spec:
  dependsOn:
    - apiVersion: fluxcd.controlplane.io/v1
      kind: ResourceSet
      name: platform-namespaces

Version Management

Add a version entry to kubernetes/platform/versions.env with a Renovate annotation, then reference via ${variable_name} in helm-charts.yaml. For annotation syntax and datasource selection, see the versions-renovate skill.

Debugging Flux

Check status: kubectl get resourcesets -n flux-system → kubectl describe resourceset platform-resources -n flux-system

Check HelmRelease: kubectl get helmreleases -A → kubectl describe helmrelease <name> -n <namespace>

Force reconciliation: flux reconcile helmrelease <name> -n <namespace> or flux reconcile kustomization flux-system -n flux-system