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

Step 1: Add to helm-charts.yaml

Add an entry to the

inputs

array:

yaml

inputs:
  - name: "my-new-chart"           # Unique release name (kebab-case)
    namespace: "my-namespace"       # Target namespace
    chart:
      name: "actual-chart-name"    # Chart name in repository
      version: "1.0.0"             # Pinned version
      url: "https://example.com/charts"  # Helm repository URL
    dependsOn: [cilium]            # Array of release names this depends on

For OCI registries:

yaml

    chart:
      name: "app-template"
      version: "3.6.1"
      url: "oci://ghcr.io/bjw-s/helm"  # Prefix with oci://

Step 2: Create Values File

Create

charts/<release-name>.yaml

with Helm values:

yaml

# yaml-language-server: $schema=<chart-schema-url>
---
# Helm values for the chart
replicas: 1
image:
  repository: myapp
  tag: v1.0.0

Step 3: Add to kustomization.yaml

Add the values file to the

configMapGenerator

yaml

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

Step 4: Add Config Resources (Optional)

If the chart needs additional resources (secrets, configs), add to

config/

config/my-new-chart/
├── kustomization.yaml
├── secret.yaml
└── config.yaml

Then reference in

config.yaml

ResourceSet.

Step 5: Verify PodSecurity Compliance

Before finalizing values, check the target namespace's PodSecurity level in

namespaces.yaml

Identify the namespace security level: Look for
```
security: restricted
```
,
```
baseline
```
, or
```
privileged
```
in the namespace inputs
If
restricted
: Add full security context to chart values (see below)
Check the container image's default user: If it runs as root, set
```
runAsUser: 65534
```
Verify all init containers and sidecars also have security context set

Required security context for
restricted
namespaces:

yaml

# Pod-level (chart-specific key varies: podSecurityContext, securityContext, pod.securityContext)
podSecurityContext:
  runAsNonRoot: true
  seccompProfile:
    type: RuntimeDefault

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

Restricted namespaces: cert-manager, external-secrets, system, database, kromgo. See kubernetes/platform/CLAUDE.md for the full list.

Validation gap:

task k8s:validate

does NOT catch PodSecurity violations. These are only caught at admission time in the cluster.

ResourceSet Template Syntax

The

resourcesTemplate

uses Go text/template with

<<

>>

delimiters:

yaml

resourcesTemplate: |
  apiVersion: helm.toolkit.fluxcd.io/v2
  kind: HelmRelease
  metadata:
    name: << inputs.name >>
    namespace: << inputs.provider.namespace >>
  spec:
    <<- if inputs.dependsOn >>
    dependsOn:
    <<- range $dep := inputs.dependsOn >>
      - name: << $dep >>
    <<- end >>
    <<- end >>
    chart:
      spec:
        chart: << inputs.chart.name >>
        version: << inputs.chart.version >>

Template Functions

```
<< inputs.field >>
```
- Access input field
```
<<- if condition >>
```
- Conditional (with
```
-
```
to trim whitespace)
```
<<- range $item := inputs.array >>
```
- Loop over array
```
hasPrefix "oci://" inputs.chart.url
```
- String prefix check

Dependency Management

Release Dependencies

yaml

inputs:
  - name: "grafana"
    dependsOn: [kube-prometheus-stack, alloy]  # Waits for these

ResourceSet Dependencies

yaml

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

Debugging Flux

Check ResourceSet Status

bash

kubectl get resourcesets -n flux-system
kubectl describe resourceset platform-resources -n flux-system

Check HelmRelease Status

bash

kubectl get helmreleases -A
kubectl describe helmrelease <name> -n <namespace>

Check Reconciliation Logs

bash

kubectl logs -n flux-system deploy/flux-controller -f | grep <release-name>

Force Reconciliation

bash

flux reconcile helmrelease <name> -n <namespace>
flux reconcile kustomization flux-system -n flux-system

Common Issues

Symptom	Cause	Solution
`waiting for dependencies`	Dependency not ready	Check `dependsOn` releases
`values key not found`	Missing values file	Add to kustomization.yaml configMapGenerator
`chart not found`	Wrong chart name/URL	Verify chart exists in repository
`namespace not found`	Namespace not created	Add to namespaces.yaml

Version Management

When adding a new Helm release, you must also add a version entry to

kubernetes/platform/versions.env

with the correct Renovate annotation. Use

${variable_name}

helm-charts.yaml

to reference the version:

yaml

chart:
  version: "${my_chart_version}"  # Substituted from platform-versions ConfigMap

For annotation syntax, datasource selection, and debugging Renovate, see the versions-renovate skill.

OCI Registry Specifics

When using OCI registries like GHCR:

yaml

chart:
  name: "app-template"           # Just the chart name
  version: "3.6.1"
  url: "oci://ghcr.io/bjw-s/helm"  # Registry URL with oci:// prefix

The ResourceSet template automatically detects OCI URLs and sets

type: oci

on the HelmRepository.

flux-gitops

NPX Install

Tags

SKILL.md Content

Flux GitOps Platform

How to Add a New Helm Release

Step 1: Add to helm-charts.yaml

Step 2: Create Values File

Step 3: Add to kustomization.yaml

Step 4: Add Config Resources (Optional)

Step 5: Verify PodSecurity Compliance

ResourceSet Template Syntax

Template Functions

Dependency Management

Release Dependencies

ResourceSet Dependencies

Debugging Flux

Check ResourceSet Status

Check HelmRelease Status

Check Reconciliation Logs

Force Reconciliation

Common Issues

Version Management

OCI Registry Specifics