FluxCD Builders

pkg/kubernetes/fluxcd

Low-level builder functions for FluxCD Kubernetes resources. Each resource type follows the Create*(name, namespace) + Set*()/Add*() pattern.

Constructors

Every kind this package registers has a generated Create<Kind> wrapper in zz_generated_create.go, produced from the scheme by pkg/kubernetes/internal/gen (make gen-builders, checked by make check-builders in CI). A wrapper delegates to kubernetes.Create[T] and emits TypeMeta and identity only: no default, no label, no spec value. Namespaced kinds take (name, namespace), cluster-scoped kinds take (name). The upstream struct is the construction API; set spec fields directly or through the admissible Set*/Add* sugar below.

obj := fluxcd.CreateGitRepository("my-repo", "flux-system")

The hand-written Create* helpers for spec fragments (sub-types that are not client.Object) that remain in this package are legacy and are removed by the prune work item of the builder-contract epic; a struct literal is the idiom.

See the Kubernetes Builders page for the full builder contract: construction, sugar admission classes, purity and the release-1 migration ledger.

Source Controllers

GitRepository

gr := fluxcd.CreateGitRepository("my-repo", "flux-system")
gr.Spec.URL = "https://github.com/org/repo"
fluxcd.SetGitRepositoryReference(gr, &sourcev1.GitRepositoryRef{Branch: "main"})
gr.Spec.Interval = metav1.Duration{Duration: 5 * time.Minute}
fluxcd.SetGitRepositorySecretRef(gr, &meta.LocalObjectReference{Name: "git-credentials"})

Additional setters: SetGitRepositoryTimeout, SetGitRepositoryVerification, SetGitRepositoryProxySecretRef, SetGitRepositoryIgnore, AddGitRepositoryInclude, AddGitRepositorySparseCheckoutPath.

OCIRepository

oci := fluxcd.CreateOCIRepository("my-manifests", "flux-system")
oci.Spec.URL = "oci://registry.example.com/manifests"
fluxcd.SetOCIRepositoryReference(oci, &sourcev1.OCIRepositoryRef{Tag: "latest"})
oci.Spec.Interval = metav1.Duration{Duration: 10 * time.Minute}
fluxcd.SetOCIRepositorySecretRef(oci, &meta.LocalObjectReference{Name: "registry-credentials"})

Additional setters: SetOCIRepositoryLayerSelector, SetOCIRepositoryVerify, SetOCIRepositoryCertSecretRef, SetOCIRepositoryProxySecretRef, SetOCIRepositoryTimeout, SetOCIRepositoryIgnore.

HelmRepository

HTTP/HTTPS repository:

hr := fluxcd.CreateHelmRepository("bitnami", "flux-system")
hr.Spec.URL = "https://charts.bitnami.com/bitnami"
hr.Spec.Type = "default"
hr.Spec.Interval = metav1.Duration{Duration: 10 * time.Minute}
fluxcd.SetHelmRepositoryTimeout(hr, &metav1.Duration{Duration: 60 * time.Second})
hr.Spec.PassCredentials = true
fluxcd.SetHelmRepositorySecretRef(hr, &meta.LocalObjectReference{Name: "bitnami-auth"})

OCI registry:

hr := fluxcd.CreateHelmRepository("ghcr-charts", "flux-system")
hr.Spec.URL = "oci://ghcr.io/example/charts"
hr.Spec.Type = "oci"
hr.Spec.Provider = "generic" // OCI-only: generic, aws, azure, gcp
hr.Spec.Interval = metav1.Duration{Duration: 5 * time.Minute}
fluxcd.SetHelmRepositorySecretRef(hr, &meta.LocalObjectReference{Name: "ghcr-auth"})

Additional setters: SetHelmRepositoryCertSecretRef, SetHelmRepositoryAccessFrom.

HelmChart

hc := fluxcd.CreateHelmChart("redis", "flux-system")
hc.Spec.Chart = "redis"
hc.Spec.Version = "19.0.0"
hc.Spec.SourceRef = sourcev1.LocalHelmChartSourceReference{
    Kind: "HelmRepository",
    Name: "bitnami",
}
hc.Spec.Interval = metav1.Duration{Duration: 10 * time.Minute}

Additional setters: AddHelmChartValuesFile, SetHelmChartVerify.

Note (Flux 2.9): source-controller/api v1.9 split the verification types. SetHelmChartVerify now takes *sourcev1.HelmChartVerification (previously *sourcev1.OCIRepositoryVerification); SetOCIRepositoryVerify still takes *sourcev1.OCIRepositoryVerification. The API version is unchanged (both v1).

Bucket

b := fluxcd.CreateBucket("my-bucket", "flux-system")
b.Spec.Endpoint = "minio.example.com"
b.Spec.BucketName = "manifests"
b.Spec.Interval = metav1.Duration{Duration: 10 * time.Minute}
fluxcd.SetBucketSecretRef(b, &meta.LocalObjectReference{Name: "minio-credentials"})

Additional setters: SetBucketSTS, SetBucketCertSecretRef, SetBucketProxySecretRef, SetBucketTimeout, SetBucketIgnore.

Deployment Controllers

Kustomization

k := fluxcd.CreateKustomization("my-app", "flux-system")
k.Spec.SourceRef = kustv1.CrossNamespaceSourceReference{
    Kind: "GitRepository",
    Name: "my-repo",
}
k.Spec.Path = "./clusters/production/apps"
k.Spec.Interval = metav1.Duration{Duration: 10 * time.Minute}
k.Spec.Prune = true
k.Spec.TargetNamespace = "production"
k.Spec.Wait = true
fluxcd.AddKustomizationDependsOn(k, kustv1.DependencyReference{Name: "cert-manager"})

Additional setters: SetKustomizationRetryInterval, SetKustomizationKubeConfig, AddKustomizationHealthCheck, AddKustomizationHealthCheckExpr, AddKustomizationComponent, SetKustomizationTimeout, AddKustomizationImage, AddKustomizationPatch, SetKustomizationCommonMetadata, SetKustomizationDecryption, SetKustomizationPostBuild.

HelmRelease

Chart template (chart + version + source reference):

hr := fluxcd.CreateHelmRelease("redis", "apps")
hr.Spec.ReleaseName = "redis-prod"
hr.Spec.TargetNamespace = "apps"
hr.Spec.Interval = metav1.Duration{Duration: 10 * time.Minute}
fluxcd.SetHelmReleaseChart(hr, &helmv2.HelmChartTemplate{
    Spec: helmv2.HelmChartTemplateSpec{
        Chart:   "redis",
        Version: "19.0.0",
        SourceRef: helmv2.CrossNamespaceObjectReference{
            Kind:      "HelmRepository",
            Name:      "bitnami",
            Namespace: "flux-system",
        },
    },
})
// Panics if the map does not marshal (a channel, a function, a NaN).
fluxcd.SetHelmReleaseValuesFromMap(hr, map[string]any{"replicaCount": 3})
// Alternative — pre-marshalled JSON:
// fluxcd.SetHelmReleaseValues(hr, &apiextensionsv1.JSON{Raw: []byte(`{"replicaCount":3}`)})
fluxcd.AddHelmReleaseValuesFrom(hr, helmv2.ValuesReference{
    Kind: "ConfigMap",
    Name: "redis-defaults",
})

SetHelmReleaseValuesFromMap panics rather than returning an error, because a sugar helper cannot return one under the builder contract. Only a value that encoding/json refuses outright — a channel, a function, a NaN or +Inf float, a cyclic structure — reaches that panic; ordinary user-supplied YAML or JSON decoded into map[string]any always marshals. When values come from somewhere that could produce such a value, marshal them yourself and hand the result to SetHelmReleaseValues:

import "github.com/go-kure/kure/pkg/errors"

raw, err := json.Marshal(values)
if err != nil {
    return errors.Wrap(err, "helm values")
}
fluxcd.SetHelmReleaseValues(hr, &apiextensionsv1.JSON{Raw: raw})

ChartRef mode (existing OCIRepository or HelmChart):

hr := fluxcd.CreateHelmRelease("my-app", "apps")
fluxcd.SetHelmReleaseChartRef(hr, &helmv2.CrossNamespaceSourceReference{
    Kind:      "OCIRepository",
    Name:      "my-oci-source",
    Namespace: "flux-system",
})

Drift detection and remediation:

fluxcd.SetHelmReleaseDriftDetection(hr, fluxcd.CreateDriftDetection(helmv2.DriftDetectionEnabled))
fluxcd.SetHelmReleaseInstallCRDs(hr, helmv2.CreateReplace)
fluxcd.SetHelmReleaseInstallRemediation(hr, fluxcd.CreateInstallRemediation(3))
fluxcd.SetHelmReleaseUpgradeCRDs(hr, helmv2.CreateReplace)
fluxcd.SetHelmReleaseUpgradeRemediation(hr, fluxcd.CreateUpgradeRemediation(3))

Post-render:

k := fluxcd.CreatePostRendererKustomize()
fluxcd.AddPostRendererKustomizeImage(k, kustomize.Image{Name: "redis", NewTag: "7.0"})
fluxcd.AddHelmReleasePostRenderer(hr, helmv2.PostRenderer{Kustomize: k})

Additional setters: SetHelmReleaseKubeConfig, AddHelmReleaseDependsOn, SetHelmReleaseTimeout, SetHelmReleaseMaxHistory, SetHelmReleasePersistentClient, SetHelmReleaseInstall, SetHelmReleaseUpgrade, SetHelmReleaseRollback, SetHelmReleaseUninstall, SetHelmReleaseTest, SetHelmReleaseValues, SetHelmReleaseValuesFromMap, SetHelmReleaseCommonMetadata, AddHelmReleaseHealthCheckExpr, SetHelmReleaseWaitStrategy.

Install flag setters: SetHelmReleaseInstallTimeout, SetHelmReleaseInstallCRDs, SetHelmReleaseInstallCreateNamespace, SetHelmReleaseInstallDisableSchemaValidation, SetHelmReleaseInstallDisableOpenAPIValidation, SetHelmReleaseInstallDisableHooks, SetHelmReleaseInstallDisableWait, SetHelmReleaseInstallDisableWaitForJobs, SetHelmReleaseInstallDisableTakeOwnership, SetHelmReleaseInstallReplace, SetHelmReleaseInstallRemediation.

Upgrade flag setters: SetHelmReleaseUpgradeTimeout, SetHelmReleaseUpgradeCRDs, SetHelmReleaseUpgradeDisableSchemaValidation, SetHelmReleaseUpgradeDisableOpenAPIValidation, SetHelmReleaseUpgradeDisableHooks, SetHelmReleaseUpgradeDisableWait, SetHelmReleaseUpgradeDisableWaitForJobs, SetHelmReleaseUpgradeDisableTakeOwnership, SetHelmReleaseUpgradeForce, SetHelmReleaseUpgradePreserveValues, SetHelmReleaseUpgradeCleanupOnFail, SetHelmReleaseUpgradeRemediation.

Notification Controllers

Note: Provider and Alert use notification.toolkit.fluxcd.io/v1beta3. Receiver is on v1. See compatibility for details and tracking issue #250 .

provider := fluxcd.CreateProvider("slack", "flux-system")
// SetProvider* setters configure type, channel, secretRef, etc.

alert := fluxcd.CreateAlert("slack-alert", "flux-system")
// SetAlert* setters configure providerRef, eventSeverity, summary, etc.

receiver := fluxcd.CreateReceiver("github-receiver", "flux-system")
// SetReceiver* setters configure type, events, resources, secretRef, etc.

Flux Operator

instance := fluxcd.CreateFluxInstance("flux", "flux-system")
instance.Spec.Distribution.Variant = "upstream-alpine"
// Additional: SetFluxInstance* for distribution, cluster, sharding, storage, kustomize, sync, wait.

Extended Resource Types

ExternalArtifact

Allows a Flux source artifact produced outside the cluster to be referenced by other Flux resources.

ea := fluxcd.CreateExternalArtifact("my-artifact", "flux-system")
fluxcd.SetExternalArtifactSourceRef(ea, &meta.NamespacedObjectKindReference{
    APIVersion: "source.toolkit.fluxcd.io/v1",
    Kind:       "OCIRepository",
    Name:       "my-oci-source",
    Namespace:  "flux-system",
})

ArtifactGenerator

Provided by the optional source-watcher component. Assembles a new artifact by copying files from one or more source artifacts.

ag := fluxcd.CreateArtifactGenerator("my-gen", "flux-system")

src := fluxcd.CreateSourceReference("app", "my-oci-source", "OCIRepository")
src.Namespace = "flux-system"
fluxcd.AddArtifactGeneratorSource(ag, src)

out := fluxcd.CreateOutputArtifact("combined")
out.Revision = "@app"
cp := fluxcd.CreateCopyOperation("@app/manifests/**", "@artifact/manifests")
fluxcd.AddOutputArtifactCopyOperation(&out, cp)
fluxcd.AddArtifactGeneratorOutputArtifact(ag, out)

stack/fluxcd — high-level Flux workflow engine
stack — domain model that produces Flux resources