flux

Documentation

Overview

Package flux provides Flux manifest generation for AICR recipes.

The flux package generates Flux custom resources from RecipeResult objects, enabling GitOps-based deployment of GPU-accelerated infrastructure components using the Flux toolkit.

Overview

The package generates:

• HelmRelease CRs for all components (helm.toolkit.fluxcd.io/v2)
• HelmRepository source CRs for upstream chart repositories (source.toolkit.fluxcd.io/v1)
• GitRepository source CRs for local Helm chart sources (source.toolkit.fluxcd.io/v1)
• Local Helm charts (Chart.yaml + templates/) for manifest-only components
• A root kustomization.yaml (plain Kustomize) that orchestrates all resources
• README with deployment instructions

Deployment Ordering

Components are deployed in order using Flux dependsOn references. The deployment order is determined by the recipe's DeploymentOrder field. Each component depends on the component immediately preceding it in the order.

When a component declares pre-manifests (ComponentRef.PreManifestFiles, or synthesized bundler manifests like the GKE critical-priority ResourceQuota), the generator emits a <name>-pre HelmRelease ahead of the primary chart and rewires the primary's dependsOn to point at <name>-pre. The chain becomes: previous → <name>-pre → <name> → <name>-post → next.

Source Deduplication

Multiple components sharing the same upstream repository (e.g., two charts from the same Helm repo) produce a single HelmRepository source CR.

OCI Support

OCI-based Helm repositories (prefixed with oci://) generate HelmRepository CRs with spec.type set to "oci". HTTPS repositories use the default type.

OCI Bundle Mode (ArtifactGenerator)

When Generator.OCISourceName is set (auto-derived by the CLI when --deployer flux and --output oci://... are combined), local-chart components emit an ArtifactGenerator CR (source.extensions.fluxcd.io/v1beta1) that extracts the chart sub-directory from the outer OCIRepository into an ExternalArtifact. The HelmRelease then references this ExternalArtifact via spec.chartRef instead of the traditional spec.chart.spec.sourceRef pointing at a GitRepository.

This eliminates the placeholder GitRepository URL (https://github.com/YOUR_ORG/YOUR_REPO.git) that is unreachable under OCI consumption, allowing Flux to fully reconcile all HelmReleases.

**Prerequisites (OCI output only):** Flux v2.7+ with source-watcher controller deployed (source.extensions.fluxcd.io) and ExternalArtifact=true feature gate enabled on helm-controller. These are only required when --output targets an OCI registry. Without both, OCI bundles generate successfully but HelmReleases will not reconcile at deploy time. Git-based bundles (--output /path/to/dir) do not use ArtifactGenerator and have no additional prerequisites.

**CLI flags:**

• --flux-oci-source-name: name of the OCIRepository CR that Flux uses to pull the bundle (default: "aicr-bundle"). Must match the OCIRepository deployed in the target cluster.
• --flux-namespace: Kubernetes namespace where Flux CRs are deployed (default: "flux-system"). Must match the Flux installation namespace.

Component Type Support

Only Helm components (type "helm") are currently supported. Kustomize components produce an ErrCodeInvalidRequest error at generation time.

Usage

generator := &flux.Generator{
	RecipeResult:     recipeResult,
	ComponentValues:  componentValues,
	Version:          "v0.9.0",
	RepoURL:          "https://github.com/my-org/my-gitops-repo.git",
	IncludeChecksums: true,
}

output, err := generator.Generate(ctx, "/path/to/output")
if err != nil {
	log.Fatal(err)
}

fmt.Printf("Generated %d files (%d bytes)\n", len(output.Files), output.TotalSize)

Generated Structure

output/
├── kustomization.yaml              # Root Kustomize orchestration
├── README.md                       # Deployment instructions
├── checksums.txt                   # SHA256 checksums (optional)
├── sources/
│   ├── gitrepo-<name>.yaml         # GitRepository (for local Helm charts)
│   ├── helmrepo-charts-jetstack-io.yaml
│   └── helmrepo-helm-ngc-nvidia-com-nvidia.yaml
├── cert-manager/
│   └── helmrelease.yaml            # HelmRelease (HelmRepository source)
├── gpu-operator-pre/               # Synthesized when PreManifestFiles is non-empty
│   ├── Chart.yaml                  # Local Helm chart for pre-phase manifest templates
│   ├── artifactgenerator.yaml      # ArtifactGenerator (OCI mode only)
│   ├── helmrelease.yaml            # HelmRelease (GitRepository or chartRef ExternalArtifact)
│   └── templates/
│       └── gke-critical-pods-quota.yaml  # e.g. synthesized GKE ResourceQuota (issue #915)
├── gpu-operator/
│   └── helmrelease.yaml            # HelmRelease (HelmRepository source); dependsOn gpu-operator-pre
└── nodewright-customizations/
    ├── Chart.yaml                  # Local Helm chart for manifest templates
    ├── artifactgenerator.yaml      # ArtifactGenerator (OCI mode only)
    ├── helmrelease.yaml            # HelmRelease (GitRepository or chartRef ExternalArtifact)
    └── templates/
        └── tuning.yaml             # Manifest template rendered by Helm controller

Index

• type ArtifactGeneratorData
• type ChartData
• type ChartRefHelmReleaseData
• type ComponentSummary
• type ConfigMapData
• type DependsOnRef
• type Generator
  • func (g *Generator) Generate(ctx context.Context, outputDir string) (*deployer.Output, error)
• type GitRepoSourceData
• type HelmReleaseData
• type HelmRepoSourceData
• type ReadmeData
• type RootKustomizationData
• type ValuesFromRef

Types

type ArtifactGeneratorData

type ArtifactGeneratorData struct {
	Name          string // ArtifactGenerator CR name
	Namespace     string // Flux install namespace (e.g. "flux-system")
	OCISourceName string // outer OCIRepository name (e.g. "aicr-bundle")
	ArtifactName  string // ExternalArtifact name that source-watcher will create
	ChartPath     string // sub-directory within the OCI artifact (e.g. "gpu-operator-pre")
}

ArtifactGeneratorData carries per-component data for the artifactgenerator.yaml template. Each local-chart component emits one ArtifactGenerator that extracts its chart directory from the outer OCIRepository into an ExternalArtifact.

type ChartData

type ChartData struct {
	Name    string
	Version string
}

ChartData carries data for generating a local Chart.yaml.

type ChartRefHelmReleaseData

type ChartRefHelmReleaseData struct {
	Name            string
	Namespace       string // Flux install namespace (e.g. "flux-system")
	TargetNamespace string
	ChartRefName    string // ExternalArtifact name for spec.chartRef
	DependsOn       []DependsOnRef
	ValuesFrom      []ValuesFromRef // ConfigMap references for dynamic values
	ValuesYAML      string          // Pre-rendered, indented YAML for spec.values
}

ChartRefHelmReleaseData carries per-component data for the helmrelease-chartref.yaml template. Used when OCISourceName is set, causing HelmReleases to reference an ExternalArtifact via spec.chartRef instead of a GitRepository/HelmRepository via spec.chart.spec.sourceRef.

type ComponentSummary

type ComponentSummary struct {
	Name         string
	Type         string
	Version      string
	Namespace    string
	DependsOnStr string
}

ComponentSummary is used in README rendering.

type ConfigMapData

type ConfigMapData struct {
	Name       string
	Namespace  string // Flux install namespace (e.g. "flux-system")
	ValuesYAML string // Indented YAML for the data.values.yaml field
}

ConfigMapData carries data for the configmap-values.yaml template.

type DependsOnRef

type DependsOnRef struct {
	Name string
}

DependsOnRef is a Flux dependsOn reference to another resource. All HelmReleases share a single namespace, so no namespace is needed.

type Generator

type Generator struct {
	// RecipeResult contains the recipe metadata and component references.
	RecipeResult *recipe.RecipeResult

	// ComponentValues maps component names to their values.
	ComponentValues map[string]map[string]any

	// Version is the generator version.
	Version string

	// RepoURL is the Git repository URL for GitRepository source CRs.
	// If empty, a placeholder URL will be used.
	RepoURL string

	// TargetRevision is the target revision for GitRepository refs (default: "main").
	TargetRevision string

	// IncludeChecksums indicates whether to generate a checksums.txt file.
	IncludeChecksums bool

	// DataFiles lists additional file paths (relative to output dir) to include
	// in checksum generation. Used for external data files copied into the bundle.
	DataFiles []string

	// ComponentManifests maps component name → manifest path → rendered bytes.
	// Drives generation of local Helm charts for manifest-only and mixed
	// components. Components without manifests do not appear in the map.
	ComponentManifests map[string]map[string][]byte

	// ComponentPreManifests maps component name → manifest path → rendered bytes.
	// Emitted as a <name>-pre HelmRelease that the primary HelmRelease
	// dependsOn, ensuring pre-phase manifests reconcile before the chart.
	// Wired by the bundler from ComponentRef.PreManifestFiles and the
	// synthesized GKE critical-priority ResourceQuota (see issue #915).
	// Components without pre-manifests do not appear in the map.
	ComponentPreManifests map[string]map[string][]byte

	// DynamicValues maps component names to their dynamic value paths.
	// When non-empty, dynamic paths are split from inline values into a
	// ConfigMap and referenced via spec.valuesFrom in the HelmRelease.
	DynamicValues map[string][]string

	// Namespace is the Kubernetes namespace where Flux CRs (HelmRelease,
	// sources, ArtifactGenerator) are deployed. Defaults to
	// config.DefaultFluxNamespace ("flux-system") via resolveNamespace().
	Namespace string

	// OCISourceName is the name of the outer OCIRepository that Flux pulls
	// the bundle from. When non-empty, local-chart components emit an
	// ArtifactGenerator + ExternalArtifact pair and reference the
	// ExternalArtifact via spec.chartRef in the HelmRelease (instead of
	// spec.chart.spec with a GitRepository source). This eliminates the
	// placeholder GitRepository URL that stalls helm-controller under OCI
	// consumption.
	// When empty, the generator falls back to the existing GitRepository path.
	OCISourceName string

	// VendorCharts pulls upstream Helm chart bytes into the bundle at
	// bundle time so the resulting artifact is air-gap deployable.
	// Off by default. With the flag set, vendorable Helm-typed components
	// emit a local wrapper chart (Chart.yaml + charts/<chart>-<ver>.tgz)
	// and HelmRelease CRs reference the GitRepository source instead of
	// HelmRepository.
	VendorCharts bool

	// Puller fetches upstream chart bytes when VendorCharts is set. nil
	// resolves to a default *CLIChartPuller; tests inject a stub here
	// without touching package state. Ignored when VendorCharts is false.
	Puller localformat.ChartPuller
	// contains filtered or unexported fields
}

Generator creates Flux manifests from recipe results. Configure it with the required fields, then call Generate.

func (*Generator) Generate

func (g *Generator) Generate(ctx context.Context, outputDir string) (*deployer.Output, error)

Generate produces Flux manifests in the given output directory.

type GitRepoSourceData

type GitRepoSourceData struct {
	Name      string
	Namespace string // Flux install namespace (e.g. "flux-system")
	URL       string
	Branch    string
}

GitRepoSourceData carries data for GitRepository source CRs.

type HelmReleaseData

type HelmReleaseData struct {
	Name            string
	Namespace       string // Flux install namespace (e.g. "flux-system")
	TargetNamespace string
	Chart           string
	Version         string
	SourceKind      string // "HelmRepository" or "GitRepository"
	SourceName      string
	DependsOn       []DependsOnRef
	ValuesFrom      []ValuesFromRef // ConfigMap references for dynamic values
	ValuesYAML      string          // Pre-rendered, indented YAML for spec.values
}

HelmReleaseData carries per-component data for the helmrelease.yaml template.

type HelmRepoSourceData

type HelmRepoSourceData struct {
	Name      string
	Namespace string // Flux install namespace (e.g. "flux-system")
	URL       string
	IsOCI     bool
}

HelmRepoSourceData carries data for HelmRepository source CRs.

type ReadmeData

type ReadmeData struct {
	Namespace      string // Flux install namespace (e.g. "flux-system")
	BundlerVersion string
	Components     []ComponentSummary
}

ReadmeData carries data for the README.md template.

type RootKustomizationData

type RootKustomizationData struct {
	Resources []string
}

RootKustomizationData carries data for the root kustomization.yaml.

type ValuesFromRef

type ValuesFromRef struct {
	Name string
}

ValuesFromRef is a Flux valuesFrom reference to a ConfigMap.