Flux CD Agent Skills

Gitless image automation updates running workloads (like HelmRelease or Kustomization) when new container images or Helm chart versions are published, without committing tag bumps back to Git. It uses Flux Operator's ResourceSetInputProvider to scan registries and re-renders the owning ResourceSet directly.

Comparison: Git-based vs. Gitless

Use Git-based automation if you require a PR-based approval workflow and a Git audit trail. Use Gitless automation if you want to avoid Git write permissions and reduce complexity by upgrading resources directly in the cluster.

Instead of a flat list of resources, you can use spec.steps to define an ordered sequence of up to 20 named steps. Each step's resources are applied and health-checked to completion before the next step begins. This provides in-ResourceSet ordering without the latency of dependsOn between multiple objects.

Key Rules:

• spec.steps is mutually exclusive with resources and resourcesTemplate.
• Each step can contain its own resources or resourcesTemplate using << >> templating.
• A resource can only be defined in exactly one step; duplicates cause build failures.
• Step names must be unique DNS labels (max 63 chars).
• Use steps for internal ordering (e.g., Namespace $\rightarrow$ RBAC $\rightarrow$ App).
• Use dependsOn for ordering between different ResourceSet objects.

spec:
  steps:
    - name: step-one
      resources:
        - apiVersion: v1
          kind: ConfigMap
          ...
    - name: step-two
      resources:
        - apiVersion: v1
          kind: Secret
          ...

This pattern uses separate repositories for fleet management, infrastructure, and applications. It is ideal for organizations with distinct platform and application teams.

Key Characteristics

• Fleet Repo Orchestration: The fleet repository creates GitRepository objects that point to the specific infrastructure and application repositories.
• RBAC Isolation: Each tenant is assigned its own ServiceAccount with scoped RoleBinding.
• Variable Injection: Uses postBuild.substituteFrom to inject cluster variables (like environment or domain) from ConfigMaps.
• Image Automation: ImageUpdateAutomation runs within the fleet repository to push updates to the infrastructure or application repositories.

Typical Repository Structure

• fleet-repo: Owns cluster definitions and tenant orchestration.
• infra-repo: Owns infrastructure components (e.g., cert-manager) and includes update/ for image automation.
• apps-repo: Owned by dev teams; contains application manifests and image update policies.

fleet-repo/
├── clusters/
│   ├── staging/
│   │   ├── flux-system/
│   │   ├── runtime-info.yaml
│   │   ├── infra-tenant.yaml
│   │   └── apps-tenant.yaml
│   └── production/
├── tenants/
│   ├── infra/
│   │   └── components/
│   │       ├── source.yaml
│   │       └── sync.yaml
│   └── apps/
│       └── components/
│           └── <app>/
│               ├── namespace.yaml
│               ├── rbac.yaml
│               └── sync.yaml

infra-repo/
├── components/
│   └── <component>/
│       ├── controllers/
│       └── configs/
└── update/

apps-repo/
├── components/
│   └── <app>/
│       ├── base/
│       ├── staging/
│       └── production/
└── update/

The spec.sharding configuration horizontally partitions reconciliation across multiple controller replicas. This is useful for clusters with very large numbers of Flux resources.

Each shard processes resources that carry a matching shard label (default key: sharding.fluxcd.io/key).

Configuration Options:

Example Configuration:

spec:
  sharding:
    key: sharding.fluxcd.io/key
    shards:
      - shard1
      - shard2
    storage: ephemeral

Assigning a resource to a shard: Add the label to the resource: sharding.fluxcd.io/key: shard1.

In this pattern, the Flux Operator generates the delivery pipeline directly from the directory structure. No Flux Kustomization is written by hand; adding a directory deploys it, and removing it prunes it.

How it Works

1. An ArtifactGenerator with a pathPattern produces one labeled ExternalArtifact per <thing>/envs/<env> directory.
2. A ResourceSetInputProvider of type: ExternalArtifact exports one input per artifact.
3. A ResourceSet templates a Flux Kustomization per input.
4. Usually, the entire setup is pushed as one OCI artifact per cluster using a FluxInstance with sync.kind: OCIRepository, meaning the cluster never reads Git directly.

Key Characteristics

• Environment Types:
  • Cluster env (dev/prod): Selected via flux-vars to pick infra/**/envs/<env>.
  • App env (test/staging/prod): A namespace apps-<app_env> hosting instances of apps.
• Ordering: Managed at the ResourceSet level: infra-core → infra-controllers → apps-<app_env> → per-app ResourceSets. Use wait: true and dependsOn with namespace settings.
• App Composition: Apps combine manifests from a generated ExternalArtifact with image versions from an OCIArtifactTag provider pinned via spec.images (newTag + digest).
• Parameterization: Only clusters/<cluster>/ differs between clusters; all other paths are parameterized by ${env}, ${cluster_registry}, ${app_registry}, ${app_env}, and ${app_semver}.

Audit Checklist

When auditing this pattern, check for:

• source-watcher being enabled.
• base + overlay being copied by every pathPattern generator.
• YAML-safe substituted values.
• Plain image names in spec.images[].name.
• namespace defined on ResourceSet dependsOn.
• wait: true and reconcileTimeout on every ResourceSet.

kubernetes/
├── clusters/<cluster>/
│   ├── flux-instance.yaml
│   ├── flux-vars.yaml
│   ├── infra-reconcilers.yaml
│   └── apps-<app_env>-reconcilers.yaml
├── infra/
│   ├── reconcilers/
│   │   ├── core.yaml
│   │   ├── controllers.yaml
│   │   └── configs.yaml
│   ├── core/{base,envs/<env>}/
│   └── components/<name>/
│       ├── controllers/{base,envs/<env>}/
│       └── configs/{base,envs/<env>}/
└── apps/
    ├── reconcilers/
    │   ├── artifacts.yaml
    │   ├── env.yaml
    │   └── <app>.yaml
    └── <app>/{base,envs/<app_env>}/