From gitops-skills
Generates schema-validated YAML for Flux CRDs like HelmRelease, Kustomization, GitRepository; explains Flux CD concepts, GitOps repo structure, OCI delivery, multi-tenancy, drift detection, notifications.
npx claudepluginhub fluxcd/agent-skills --plugin gitops-skillsThis skill uses the workspace's default tool permissions.
You are an expert on Flux CD, the GitOps toolkit for Kubernetes. Use this knowledge base
assets/schemas/alert-notification-v1beta2.jsonassets/schemas/alert-notification-v1beta3.jsonassets/schemas/artifactgenerator-source-v1beta1.jsonassets/schemas/bucket-source-v1.jsonassets/schemas/externalartifact-source-v1.jsonassets/schemas/fluxinstance-fluxcd-v1.jsonassets/schemas/fluxreport-fluxcd-v1.jsonassets/schemas/gitrepository-source-v1.jsonassets/schemas/helmchart-source-v1.jsonassets/schemas/helmrelease-helm-v2.jsonassets/schemas/helmrepository-source-v1.jsonassets/schemas/imagepolicy-image-v1.jsonassets/schemas/imagepolicy-image-v1beta2.jsonassets/schemas/imagerepository-image-v1.jsonassets/schemas/imagerepository-image-v1beta2.jsonassets/schemas/imageupdateautomation-image-v1.jsonassets/schemas/imageupdateautomation-image-v1beta2.jsonassets/schemas/kustomization-kustomize-v1.jsonassets/schemas/ocirepository-source-v1.jsonassets/schemas/provider-notification-v1beta2.jsonConstructs GitOps workflows using ArgoCD or Flux for Kubernetes. Generates manifests, sync policies, multi-environment promotion, RBAC, notifications, and CI updates for secure continuous deployment.
Guides GitOps implementations with ArgoCD and Flux for declarative Kubernetes deployments, multi-environment management, progressive delivery, and secure secrets.
Audits Flux CD GitOps repos by scanning local files: validates Kubernetes schemas, detects deprecated APIs, reviews RBAC/multi-tenancy/secrets, generates prioritized reports.
Share bugs, ideas, or general feedback.
You are an expert on Flux CD, the GitOps toolkit for Kubernetes. Use this knowledge base to answer questions accurately, generate correct YAML manifests, and explain Flux concepts.
Rules:
assets/schemas/ to verify field names, types, and enum values.<< >> delimiters, NEVER {{ }} (Go templates are only used inside ImageUpdateAutomation commit messages).references/. Load at most 1-2 reference files per question.flux bootstrap or legacy gotk-* files.Flux is a set of Kubernetes controllers that implement GitOps — the practice of using Git (or OCI registries) as the source of truth for declarative infrastructure and applications. Flux continuously reconciles the desired state stored in sources with the actual state of the cluster.
Flux Operator manages the Flux installation declaratively through a FluxInstance custom
resource. It handles installation, configuration, upgrades, and lifecycle of all Flux controllers.
Only one FluxInstance named flux can exist per cluster.
How resources relate:
Sources (Git, OCI, Helm, Bucket)
│
▼ produce artifacts
Artifacts (tarballs, Helm charts, OCI layers)
│
▼ consumed by
Appliers (Kustomization, HelmRelease)
│
▼ create/update
Managed Resources (Deployments, Services, ConfigMaps, ...)
│
▼ status reported to
Notifications (Provider + Alert → Slack, Teams, GitHub, ...)
ResourceSet orchestration flow:
ResourceSetInputProvider (GitHub PRs, OCI tags, ...)
│
▼ exports inputs
ResourceSet (template + input matrix)
│
▼ generates per-input
Namespaces, Sources, Kustomizations, HelmReleases, RBAC, ...
Two delivery models:
| Kind | apiVersion | Controller | Purpose |
|---|---|---|---|
| FluxInstance | fluxcd.controlplane.io/v1 | flux-operator | Manages Flux installation lifecycle |
| FluxReport | fluxcd.controlplane.io/v1 | flux-operator | Read-only observed state of Flux |
| ResourceSet | fluxcd.controlplane.io/v1 | flux-operator | Template resources from input matrix |
| ResourceSetInputProvider | fluxcd.controlplane.io/v1 | flux-operator | Fetch inputs from external services |
| GitRepository | source.toolkit.fluxcd.io/v1 | source-controller | Fetch from Git repositories |
| OCIRepository | source.toolkit.fluxcd.io/v1 | source-controller | Fetch OCI artifacts from registries |
| HelmRepository | source.toolkit.fluxcd.io/v1 | source-controller | Index Helm chart repositories |
| HelmChart | source.toolkit.fluxcd.io/v1 | source-controller | Fetch and package Helm charts |
| Bucket | source.toolkit.fluxcd.io/v1 | source-controller | Fetch from S3-compatible storage |
| ExternalArtifact | source.toolkit.fluxcd.io/v1 | (external) | Generic artifact storage for 3rd-party controllers |
| ArtifactGenerator | source.extensions.fluxcd.io/v1beta1 | source-controller | Compose/decompose artifacts from multiple sources |
| Kustomization | kustomize.toolkit.fluxcd.io/v1 | kustomize-controller | Build and apply Kustomize overlays or plain YAML |
| HelmRelease | helm.toolkit.fluxcd.io/v2 | helm-controller | Install and manage Helm releases |
| Provider | notification.toolkit.fluxcd.io/v1beta3 | notification-controller | External notification provider config |
| Alert | notification.toolkit.fluxcd.io/v1beta3 | notification-controller | Route events to notification providers |
| Receiver | notification.toolkit.fluxcd.io/v1 | notification-controller | Webhook receiver for incoming events |
| ImageRepository | image.toolkit.fluxcd.io/v1 | image-reflector-controller | Scan container image registries |
| ImagePolicy | image.toolkit.fluxcd.io/v1 | image-reflector-controller | Select image by version policy |
| ImageUpdateAutomation | image.toolkit.fluxcd.io/v1 | image-automation-controller | Update YAML in Git with new image tags |
Flux controllers run a continuous reconciliation loop:
Use dependsOn to control reconciliation order. For example, install CRDs before CRs,
or infrastructure before applications:
spec:
dependsOn:
- name: infra-controllers # wait for this Kustomization to be Ready
ResourceSets support richer dependencies with readyExpr (CEL expressions):
spec:
dependsOn:
- apiVersion: fluxcd.controlplane.io/v1
kind: ResourceSet
name: policies
ready: true
readyExpr: "status.conditions.filter(e, e.type == 'Ready').all(e, e.status == 'True')"
By default, Flux controllers poll sources at the configured interval. To react immediately when a dependency changes, add the watch label to the upstream resource:
metadata:
labels:
reconcile.fluxcd.io/watch: Enabled
When a ConfigMap or Secret with this label changes, any Kustomization or HelmRelease that
references it via postBuild.substituteFrom or valuesFrom will reconcile immediately.
GitRepositoryOCIRepositoryOCIRepository with layerSelector for Helm media typeHelmRepository (default type)BucketArtifactGenerator (creates ExternalArtifact per path)ArtifactGenerator (composes chart with values overlay)KustomizationHelmReleasekubeConfig and support dependsOn.Pattern 1 — HTTPS Helm repository:
# HelmRelease creates a HelmChart automatically
spec:
chart:
spec:
chart: metrics-server
version: "3.x"
sourceRef:
kind: HelmRepository
name: metrics-server
Pattern 2 — OCI registry with chartRef (recommended):
# Separate OCIRepository + HelmRelease with chartRef
spec:
chartRef:
kind: OCIRepository
name: nginx-chart
Pattern 3 — HelmChart from Git/Bucket source:
# Chart stored in Git, HelmRelease references HelmChart
spec:
chart:
spec:
chart: ./charts/my-app
sourceRef:
kind: GitRepository
name: my-repo
chart.spec and chartRef are mutually exclusive — use one or the other.
KustomizationResourceSetFluxInstance named flux in the flux-system namespace.spec.sync to point to your Git repo or OCI registryKustomization resources to apply manifests from the sourceProvider + Alert for notificationsapiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
name: my-app
namespace: flux-system
spec:
interval: 5m
url: https://github.com/org/my-app.git
ref:
branch: main
secretRef:
name: git-credentials # optional, for private repos
---
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
name: my-app
namespace: flux-system
spec:
interval: 10m
sourceRef:
kind: GitRepository
name: my-app
path: ./deploy/production
prune: true
wait: true
timeout: 5m
apiVersion: source.toolkit.fluxcd.io/v1
kind: HelmRepository
metadata:
name: metrics-server
namespace: kube-system
spec:
interval: 1h
url: https://kubernetes-sigs.github.io/metrics-server/
---
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
name: metrics-server
namespace: kube-system
spec:
interval: 30m
chart:
spec:
chart: metrics-server
version: "3.x"
sourceRef:
kind: HelmRepository
name: metrics-server
values:
args:
- --kubelet-insecure-tls
apiVersion: source.toolkit.fluxcd.io/v1
kind: OCIRepository
metadata:
name: cert-manager-chart
namespace: cert-manager
spec:
interval: 1h
url: oci://quay.io/jetstack/charts/cert-manager
layerSelector:
mediaType: "application/vnd.cncf.helm.chart.content.v1.tar+gzip"
operation: copy
ref:
semver: "1.x"
---
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
name: cert-manager
namespace: cert-manager
spec:
interval: 1h
chartRef:
kind: OCIRepository
name: cert-manager-chart
install:
strategy:
name: RetryOnFailure
retryInterval: 5m
upgrade:
strategy:
name: RetryOnFailure
retryInterval: 5m
values:
crds:
enabled: true
keep: false
apiVersion: fluxcd.controlplane.io/v1
kind: FluxInstance
metadata:
name: flux
namespace: flux-system
spec:
distribution:
version: "2.x"
registry: "ghcr.io/fluxcd"
components:
- source-controller
- source-watcher
- kustomize-controller
- helm-controller
- notification-controller
cluster:
type: kubernetes
size: medium
multitenant: true
tenantDefaultServiceAccount: flux
networkPolicy: true
sync:
kind: OCIRepository
url: "oci://ghcr.io/my-org/fleet-manifests"
ref: "latest"
path: "clusters/production"
pullSecret: "registry-auth"
apiVersion: fluxcd.controlplane.io/v1
kind: ResourceSet
metadata:
name: apps
namespace: flux-system
annotations:
fluxcd.controlplane.io/reconcileEvery: "5m"
spec:
dependsOn:
- apiVersion: fluxcd.controlplane.io/v1
kind: ResourceSet
name: infra
ready: true
inputs:
- tenant: "frontend"
tag: "latest"
environment: "production"
- tenant: "backend"
tag: "latest"
environment: "production"
resources:
- apiVersion: v1
kind: Namespace
metadata:
name: << inputs.tenant >>
labels:
toolkit.fluxcd.io/role: "tenant"
- apiVersion: v1
kind: ServiceAccount
metadata:
name: flux
namespace: << inputs.tenant >>
- apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: flux
namespace: << inputs.tenant >>
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: admin
subjects:
- kind: ServiceAccount
name: flux
namespace: << inputs.tenant >>
- apiVersion: source.toolkit.fluxcd.io/v1
kind: OCIRepository
metadata:
name: apps
namespace: << inputs.tenant >>
spec:
interval: 5m
url: "oci://ghcr.io/my-org/apps/<< inputs.tenant >>"
ref:
tag: << inputs.tag >>
- apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
name: apps
namespace: << inputs.tenant >>
spec:
targetNamespace: << inputs.tenant >>
serviceAccountName: flux
interval: 30m
retryInterval: 5m
wait: true
timeout: 5m
sourceRef:
kind: OCIRepository
name: apps
path: "./<< inputs.environment >>"
prune: true
Pipeline: ImageRepository → ImagePolicy → ImageUpdateAutomation. Mark images in YAML with
# {"$imagepolicy": "namespace:policy-name"} comment markers for automatic tag updates.
For complete YAML examples, tag filtering, commit message templates, and marker formats,
load references/image-automation.md.
Provider + Alert for outgoing notifications, Receiver for incoming webhooks.
Alert and Provider use v1beta3, Receiver uses v1.
For Slack, GitHub commit status, webhook receivers, and all provider types,
load references/notifications.md.
Wrong template delimiters:
<< inputs.field >> — NOT {{ .inputs.field }} or {{ inputs.field }}{{ }} are only used in ImageUpdateAutomation .spec.git.commit.messageTemplateMutual exclusivity:
spec.chart.spec and spec.chartRef are mutually exclusivefluxRequired fields often forgotten:
Kustomization.spec.prune — must be set (true or false), controls garbage collectionKustomization.spec.sourceRef — must specify kind and nameHelmRelease.spec.interval — required for reconciliationAlert.spec.eventSources — at least one source requiredWrong API versions:
v1beta3, not v1 — notification.toolkit.fluxcd.io/v1beta3v1 — notification.toolkit.fluxcd.io/v1v2, not v1 or v2beta1 — helm.toolkit.fluxcd.io/v2v1 — image.toolkit.fluxcd.io/v1HelmRelease strategy fields:
spec.install.strategy.name and spec.upgrade.strategy.nameRetryOnFailure — it retries without rollback or uninstall, avoiding downtimeRemediateOnFailure or spec.install.remediation / spec.upgrade.remediationOCIRepository for Helm charts:
layerSelector to extract the chart:
layerSelector:
mediaType: "application/vnd.cncf.helm.chart.content.v1.tar+gzip"
operation: copy
layerSelector, the OCIRepository fetches the full OCI artifact, not the extracted chart.Load reference files and OpenAPI schemas based on the question topic. Load at most 1-2 reference files per question. Read schemas for field-level validation when generating YAML.
| CRD | Reference | Schema |
|---|---|---|
| FluxInstance | references/flux-operator.md | assets/schemas/fluxinstance-fluxcd-v1.json |
| FluxReport | references/flux-operator.md | assets/schemas/fluxreport-fluxcd-v1.json |
| ResourceSet | references/resourcesets.md | assets/schemas/resourceset-fluxcd-v1.json |
| ResourceSetInputProvider | references/resourcesets.md | assets/schemas/resourcesetinputprovider-fluxcd-v1.json |
| GitRepository | references/sources.md | assets/schemas/gitrepository-source-v1.json |
| OCIRepository | references/sources.md | assets/schemas/ocirepository-source-v1.json |
| HelmRepository | references/sources.md | assets/schemas/helmrepository-source-v1.json |
| HelmChart | references/sources.md | assets/schemas/helmchart-source-v1.json |
| Bucket | references/sources.md | assets/schemas/bucket-source-v1.json |
| ExternalArtifact | references/sources.md | assets/schemas/externalartifact-source-v1.json |
| ArtifactGenerator | references/sources.md | assets/schemas/artifactgenerator-source-v1beta1.json |
| Kustomization | references/kustomization.md | assets/schemas/kustomization-kustomize-v1.json |
| HelmRelease | references/helmrelease.md | assets/schemas/helmrelease-helm-v2.json |
| Provider | references/notifications.md | assets/schemas/provider-notification-v1beta3.json |
| Alert | references/notifications.md | assets/schemas/alert-notification-v1beta3.json |
| Receiver | references/notifications.md | assets/schemas/receiver-notification-v1.json |
| ImageRepository | references/image-automation.md | assets/schemas/imagerepository-image-v1.json |
| ImagePolicy | references/image-automation.md | assets/schemas/imagepolicy-image-v1.json |
| ImageUpdateAutomation | references/image-automation.md | assets/schemas/imageupdateautomation-image-v1.json |
| Topic | Reference |
|---|---|
| Repository structure, monorepo vs multi-repo, OCI-based fleet management | references/repo-patterns.md |
| Best practices, dependency management, remediation, versioning | references/best-practices.md |
| Web UI, dashboard, SSO, OIDC, Dex, Keycloak, Entra ID, RBAC | references/web-ui.md |
| MCP Server, AI assistant integration, in-cluster deployment | references/mcp-server.md |
Cluster types: kubernetes, openshift, aws, azure, gcp
Cluster sizes: small (5 concurrency, 512Mi), medium (10, 1Gi), large (20, 3Gi)
Components: source-controller, kustomize-controller, helm-controller,
notification-controller, image-reflector-controller, image-automation-controller, source-watcher
Sync kinds: GitRepository, OCIRepository, Bucket
Distribution variants: upstream-alpine, enterprise-alpine, enterprise-distroless, enterprise-distroless-fips
For enums of other CRDs (HelmRelease strategies, Provider types, ImagePolicy types, ResourceSetInputProvider types, etc.), check the relevant reference file or OpenAPI schema.