### Verify binary installation

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/addons/mcp-stdio.md

Check that the binary is correctly installed and accessible in the system PATH.

```shell
flux-operator-mcp --help
```

--------------------------------

### Guide frontmatter configuration

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/site/AGENTS.md

Required YAML frontmatter for new guide files located in docs/guides/.

```yaml
---
title: Flux Something Guide
description: One-line summary used for meta tags and search
---
```

--------------------------------

### Push Production Artifacts Workflow

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/actions/push/README.md

Example workflow for pushing production artifacts. It checks out code, sets up the distribution action, installs cosign, logs into a container registry, and then uses the push action. It also includes a step to sign the artifact if it was pushed.

```yaml
name: Push Production Artifacts

on:
  push:
    branches: [production]

jobs:
  push:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write # for pushing
      id-token: write # for signing
    steps:
    - uses: actions/checkout@v4
    - uses: controlplaneio-fluxcd/distribution/actions/setup@main
    - uses: sigstore/cosign-installer@v3
    - uses: docker/login-action@v3
      with:
        registry: ghcr.io
        username: ${{ github.actor }}
        password: ${{ secrets.GITHUB_TOKEN }}
    - uses: controlplaneio-fluxcd/distribution/actions/push@main
      id: push
      with:
        repository: ghcr.io/${{ github.repository }}
        path: clusters
        diff-tag: production
        tags: |
          prod-eu
          prod-us
        ignore-paths: |
          staging
        annotations: |
          app=my-app
          cluster=production
          env=production
    - if: steps.push.outputs.pushed == 'true'
      run: cosign sign --yes $DIGEST_URL
      env:
        DIGEST_URL: ${{ steps.push.outputs.digest-url }}
```

--------------------------------

### Get Help for Flux Get Commands

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-cli-quick-reference.md

Displays available subcommands and options for the 'flux get' command, useful for discovering resource kinds.

```shell
flux get --help
```

--------------------------------

### Install Flux CLI with Winget (Windows)

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-cli-quick-reference.md

Use winget to install the Flux CLI on Windows systems.

```shell
winget install --id=FluxCD.Flux  -e
```

--------------------------------

### Run development and build commands

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/site/AGENTS.md

Execute these commands from the site/ directory to manage dependencies, start the development server, and build the production site.

```sh
npm install          # Node >= 20 required
npm run dev          # dev server on http://localhost:4321
npx astro check      # type-check .astro/.ts files
npm run build        # astro build + pagefind index over dist/
```

--------------------------------

### Bootstrap Flux CLI with FIPS images

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/marketplace/aws.md

Example command to bootstrap Flux using FIPS-compliant images hosted on AWS ECR.

```bash
flux bootstrap github \
  --owner=customer-org \
  --repository=customer-repo \
  --branch=main \
  --path=clusters/production \
  --registry=709825985650.dkr.ecr.us-east-1.amazonaws.com/controlplane/fluxcd
```

--------------------------------

### Install Flux CLI with Homebrew (macOS)

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-cli-quick-reference.md

Use Homebrew to install the Flux CLI on macOS systems.

```shell
brew install fluxcd/tap/flux
```

--------------------------------

### Get Kustomization Controller Logs

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-cli-quick-reference.md

Display the logs from the kustomize-controller for a specific Kustomization.

```shell
flux -n apps logs --kind Kustomization --name podinfo
```

--------------------------------

### Install Flux AIO Enterprise Version

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/flux-aio/README.md

Use these commands to clone the distribution repository and apply the enterprise version of Flux AIO using Timoni. Ensure you have a subscription token and the `flux-aio.cue` file is present.

```shell
gh repo clone controlplaneio-fluxcd/distribution
cd distribution/flux-aio/bundles

TOKEN=<SUBSCRIPTION TOKEN> timoni bundle apply -f flux-aio.cue --runtime-from-env
```

--------------------------------

### FluxInstance Spec Example

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/rfcs/0001-flux-operator/README.md

Define the desired state for a Flux distribution, including version, registry, components, cluster settings, sharding, storage, and kustomize patches.

```yaml
apiVersion: fluxcd.controlplane.io/v1
kind: FluxInstance
metadata:
  name: flux
  namespace: flux-system
  annotations:
    # Continuously check for updates
    fluxcd.controlplane.io/reconcile: "Enabled"
    fluxcd.controlplane.io/reconcileTimeout: "5m"
    fluxcd.controlplane.io/reconcileEvery: "1h"
spec:
  # Enterprise distribution settings
  distribution:
    # Hotfixes and CVE patches auto-updates
    version: "2.3.x"
    # Container registry hosting the FIPS-compliant images
    registry: ghcr.io/controlplaneio-fluxcd/distroless
    # Pull secret for the enterprise container images
    imagePullSecret: enterprise-flux-auth
    # URL to the OCI artifact containing the latest Flux manifests and image digests
    artifact: "oci://ghcr.io/controlplaneio-fluxcd/flux-operator-manifests"
  # Flux CRD controllers to deploy on this cluster
  components:
    - source-controller
    - kustomize-controller
    - helm-controller
    - notification-controller
    - image-reflector-controller
    - image-automation-controller
  # Kubernetes cluster specification
  cluster:
    # Enable specific config for aks, eks, gke and openshift
    type: kubernetes
    # Enable Flux multi-tenancy lockdown
    multitenant: true
    tenantDefaultServiceAccount: default
    # Cluster internal domain name
    domain: cluster.local
    # Restrict network access to the Flux namespace
    networkPolicy: true
  # Configure Flux sharding and horizontal scaling
  sharding:
    key: "sharding.fluxcd.io/key"
    shards:
      - "shard1"
      - "shard2"
  # Persistent storage for Flux internal artifacts
  storage:
    class: standard
    size: 10Gi
  # Kustomize patches for Flux controllers
  kustomize:
    patches:
      - target:
          kind: Deployment
          labelSelector: "app.kubernetes.io/component in (kustomize-controller, helm-controller)"
        patch: |
          - op: add
            path: /spec/template/spec/containers/0/args/- 
            value: --concurrent=10
          - op: add
            path: /spec/template/spec/containers/0/args/- 
            value: --requeue-dependency=10s

```

--------------------------------

### FluxInstance Status Example

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/rfcs/0001-flux-operator/README.md

Observe the current state of a Flux distribution, including reconciliation status, versioning, component details, and observed generation.

```yaml
apiVersion: fluxcd.controlplane.io/v1
kind: FluxInstance
metadata:
  name: flux
  namespace: flux-system
  finalizers:
  - fluxcd.controlplane.io/finalizer
status:
  conditions:
  - lastTransitionTime: "2024-05-25T16:11:42Z"
    message: "Reconciliation finished in 25s"
    observedGeneration: 2
    reason: ReconciliationSucceeded
    status: "True"
    type: Ready
  - lastTransitionTime: "2024-05-25T16:11:42Z"
    message: "Upgrade to latest version v2.4.0 blocked by semver range 2.3.x"
    observedGeneration: 2
    reason: UpgradePending
    status: "False"
    type: UpToDate
  observedGeneration: 2
  lastAppliedRevision: v2.3.0@sha256:8d7eab6395c8e7c3558a2f3df2f280cb52139b4b480ac7b6f2b88b2c8056ec9f
  lastAttemptedRevision: v2.3.0@sha256:8d7eab6395c8e7c3558a2f3df2f280cb52139b4b480ac7b6f2b88b2c8056ec9f
  components:
    - digest: sha256:161da425b16b64dda4b3cec2ba0f8d7442973aba29bb446db3b340626181a0bc
      name: source-controller
      repository: ghcr.io/controlplaneio-fluxcd/distroless/source-controller
      tag: v1.3.0
    - digest: sha256:48a032574dd45c39750ba0f1488e6f1ae36756a38f40976a6b7a588d83acefc1
      name: kustomize-controller
      repository: ghcr.io/controlplaneio-fluxcd/distroless/kustomize-controller
      tag: v1.3.0
    - digest: sha256:a67a037faa850220ff94d8090253732079589ad9ff10b6ddf294f3b7cd0f3424
      name: helm-controller
      repository: ghcr.io/controlplaneio-fluxcd/distroless/helm-controller
      tag: v1.0.1
    - digest: sha256:c0fab940c7e578ea519097d36c040238b0cc039ce366fdb753947428bbf0c3d6
      name: notification-controller
      repository: ghcr.io/controlplaneio-fluxcd/distroless/notification-controller
      tag: v1.3.0
    - digest: sha256:aed795c7a8b85bca93f6d199d5a14bbefaf925ad5aa5316b32a716cfa4070d0b
      name: image-reflector-controller
      repository: ghcr.io/controlplaneio-fluxcd/distroless/image-reflector-controller
      tag: v0.32.0
    - digest: sha256:ab5097213194f3cd9f0e68d8a937d94c4fc7e821f6544453211e94815b282aa2
      name: image-automation-controller
      repository: ghcr.io/controlplaneio-fluxcd/distroless/image-automation-controller
      tag: v0.38.0
  inventory: [...]
```

--------------------------------

### Example Validation Error Message

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-policies.md

This is an example of the error message a user would receive if they attempt to create or update a workload with a container image from a disallowed registry.

```text
The deployments "test-deployment" is invalid:
ValidatingAdmissionPolicy 'registry.policy.fluxcd.controlplane.io' with binding 'tenant-registries' denied request:
Init container image is not allowed, must be one of ghcr.io/controlplaneio-fluxcd/, 709825985650.dkr.ecr.us-east-1.amazonaws.com/controlplane/
```

--------------------------------

### Reporting Tools

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/addons/mcp-stdio.md

Tools for inspecting Flux installations, Kubernetes resources, logs, metrics, and API versions.

```APIDOC
## get_flux_instance
Inspect the Flux installation on a cluster, including component versions, health status, and overall sync statistics.

## get_kubernetes_resources
Browse Flux sources, kustomizations, Helm releases, and other Kubernetes resources along with their current status and recent events.

## get_kubernetes_logs
Retrieve container logs from workloads managed by Flux to help diagnose deployment failures and runtime errors.

## get_kubernetes_metrics
Check CPU and memory consumption of pods to spot resource pressure or abnormal usage patterns.

## get_kubernetes_api_versions
Discover which Kubernetes API versions are available on the cluster for a given resource kind.
```

--------------------------------

### Get Source Controller Logs for Helm Chart Source

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-cli-quick-reference.md

Display the logs from the source-controller for a specific Helm chart source, such as an OCIRepository.

```shell
flux -n apps logs --kind OCIRepository --name podinfo
```

--------------------------------

### Get HelmRelease Controller Logs

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-cli-quick-reference.md

Display the logs from the helm-controller for a specific HelmRelease.

```shell
flux -n apps logs --kind HelmRelease --name podinfo
```

--------------------------------

### Setup Flux CLI in GitHub Workflow

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/actions/setup/README.md

Use this snippet to set up the Flux CLI in your GitHub Actions workflow. It defaults to the latest stable Enterprise Distribution version. You can customize the version, binary directory, and distribution URL using action inputs.

```yaml
name: Check the latest verions of the Flux Enterprise Distribution

on:
  workflow_dispatch:

jobs:
  check-latest-flux-enterprise-version:
    runs-on: ubuntu-latest
    steps:
      - name: Setup Flux
        uses: controlplaneio-fluxcd/distribution/actions/setup@main
      - name: Print Flux Version
        run: flux version --client
```

--------------------------------

### Example of a disallowed HelmRepository manifest

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-policies.md

This HelmRepository manifest attempts to pull charts from a registry not present in the allow list, triggering a policy violation.

```yaml
apiVersion: source.toolkit.fluxcd.io/v1
kind: HelmRepository
metadata:
  name: podinfo
  namespace: apps
spec:
  type: oci
  url: oci://ghcr.io/stefanprodan/charts/
```

--------------------------------

### Flux Operator Events Example

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/rfcs/0001-flux-operator/README.md

Illustrates typical events generated by the Flux operator during reconciliation and upgrade processes.

```text
  Type     Reason                   Age   From             Message
  ----     ------                   ----  ----             -------
  Normal   Progressing              59s   flux-operator    Installing revision v2.3.0@sha256:8d7eab6395c8e7c3558a2f3df2f280cb52139b4b480ac7b6f2b88b2c8056ec9f
  Normal   ReconciliationSucceeded  35s   flux-operator    Reconciliation finished in 25s

```

--------------------------------

### Install Flux Operator via Helm

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/marketplace/aws.md

Deploys the flux-operator Helm chart to the flux-system namespace with AWS marketplace configuration.

```yaml
helm upgrade -i flux-operator oci://ghcr.io/controlplaneio-fluxcd/charts/flux-operator \
  --namespace flux-system \
  --set serviceAccount.create=false \
  --set image.repository=709825985650.dkr.ecr.us-east-1.amazonaws.com/controlplane/fluxcd/flux-operator \
  --set marketplace.type=aws
```

--------------------------------

### View Flux Distribution Version

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-cli-quick-reference.md

Displays the installed Flux distribution version. It's recommended that the CLI minor version matches the distribution's minor version to avoid potential issues.

```shell
flux version
```

--------------------------------

### Scan Image with Trivy using VEX Document

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/distribution/security.md

Scan a container image using Trivy and suppress vulnerabilities listed in a provided OpenVEX document. This example shows how to identify vulnerabilities marked as 'not_affected'.

```console
$ trivy image <registry>/source-controller:v1.2.2 --vex ./vex/v2.2.json --show-suppressed

Suppressed Vulnerabilities (Total: 1)

┌─────────────────┬────────────────┬──────────┬──────────────┬─────────────────────────────┬─────────┐
│     Library     │ Vulnerability  │ Severity │    Status    │          Statement          │ Source  │
├─────────────────┼────────────────┼──────────┼──────────────┼─────────────────────────────┼─────────┤
│ helm.sh/helm/v3 │ CVE-2019-25210 │ MEDIUM   │ not_affected │ vulnerable_code_not_present │ OpenVEX │
└─────────────────┴────────────────┴──────────┴──────────────┴─────────────────────────────┴─────────┘
```

--------------------------------

### Bootstrap Flux with CLI

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/distribution/install.md

Use the Flux CLI to bootstrap a repository with distroless enterprise images. Requires registry credentials and an image pull secret.

```bash
flux bootstrap github \
  --owner=customer-org \
  --repository=customer-repo \
  --branch=main \
  --path=clusters/production \
  --image-pull-secret=flux-enterprise-auth \
  --registry-creds=flux:$ENTERPRISE_TOKEN \
  --registry=ghcr.io/controlplaneio-fluxcd/distroless
```

--------------------------------

### Check Flux Distribution Status

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-cli-quick-reference.md

Use this command to verify the health of Flux controllers and installed CRDs on your cluster.

```shell
flux check
```

--------------------------------

### Export Kustomization Configuration

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-cli-quick-reference.md

Display the configuration of a specific Kustomization in the 'apps' namespace.

```shell
flux -n apps export kustomization podinfo
```

--------------------------------

### Flux Kustomization for Production Deployment

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-generic-helm-chart.md

This Flux Kustomization resource defines how to deploy the application stack to the production environment. It points to the specific Kustomize path (`my-java-apps/production`) and specifies the Git repository source.

```yaml
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: my-java-apps
  namespace: flux-system
spec:
  interval: 10m
  timeout: 5m
  prune: true
  sourceRef:
    kind: GitRepository
    name: flux-system
  path: my-java-apps/production
  targetNamespace: my-java-apps
```

--------------------------------

### List Failing Kustomizations

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-cli-quick-reference.md

Use this command to list all Kustomizations at the cluster level that are not ready.

```shell
flux get kustomizations -A --status-selector ready=false
```

--------------------------------

### Verify site build integrity

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/site/AGENTS.md

Run this command to ensure the site passes all type checks and build requirements without errors, warnings, or hints.

```sh
npx astro check && npm run build
```

--------------------------------

### Apply FluxInstance manifest

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/marketplace/aws.md

Command to apply the FluxInstance configuration using kubectl.

```shell
kubectl apply -f flux-instance.yaml
```

--------------------------------

### Debug Kustomization with Show Variables

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-cli-quick-reference.md

Debug a Kustomization and display the final variables used for post-build substitutions, including referred ConfigMaps and Secrets.

```shell
flux -n apps debug kustomization podinfo --show-vars
```

--------------------------------

### Display Kustomization Source Events

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-cli-quick-reference.md

View the events for the source of a Kustomization, such as a GitRepository.

```shell
flux -n apps events --for GitRepository/podinfo
```

--------------------------------

### Package, Login, Push, and Sign Helm Chart to OCI Registry

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-generic-helm-chart.md

Automate the release process by packaging, logging into, pushing, and optionally signing your Helm chart to an OCI-compliant container registry. Ensure your Git tags are in semver format for versioning.

```shell
# Package the Helm chart
helm package src/my-jmv-chart --version ${GIT_TAG}

# Login to the container registry
helm registry login my-registry.io

# Push the Helm chart to the container registry
helm push my-jvm-chart-${GIT_TAG}.tgz oci://my-registry.io/charts

# Sign the Helm chart
cosign sign my-registry.io/charts/my-jmv-chart:${GIT_TAG}
```

--------------------------------

### Configure Policies Synchronization Kustomization

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-policies.md

Use this Kustomization to ensure policies are reconciled before tenant resources. Set the path to the policies directory and enable pruning and waiting.

```yaml
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: policies
  namespace: flux-system
spec:
  path: "./policies"
  prune: true
  wait: true
```

--------------------------------

### Build Kustomization Locally

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-cli-quick-reference.md

Build a Flux Kustomization locally to test changes before pushing to the Git repository. This command displays the resulting Kubernetes manifests.

```shell
flux -n apps build kustomization podinfo \
--path ./path/to/local/manifests \
--kustomization-file ./path/to/local/podinfo-kustomization.yaml
```

--------------------------------

### Update Flux Enterprise Distribution Workflow

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/actions/update/README.md

Example workflow to keep Flux controller image digests and manifests up-to-date with the latest Enterprise Distribution. It runs on a schedule and creates a pull request when new versions are available.

```yaml
name: Update Enterprise Distribution for Flux CD

on:
  workflow_dispatch:
  schedule:
    - cron: '00 7 * * 1-5'

permissions:
  contents: read

jobs:
  generate:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Flux
        id: setup
        uses: controlplaneio-fluxcd/distribution/actions/setup@main
      - name: Update manifests
        uses: controlplaneio-fluxcd/distribution/actions/update@main
        with:
          path: clusters/production/flux-system
          image-pull-secret: flux-enterprise-auth
          registry: ghcr.io/controlplaneio-fluxcd
          variant: distroless
      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v6
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          branch: update-flux-${{ steps.setup.outputs.version }}
          commit-message: |
            Update manifests and image digests for Flux ${{ steps.setup.outputs.version }}
          title: Update Flux to ${{ steps.setup.outputs.version }}
          body: |
            Update manifests and image digests for Flux ${{ steps.setup.outputs.version }}

```

--------------------------------

### Mirror Distribution for Air-Gapped Environments

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/distribution/install.md

Mirror the ControlPlane distribution to a private registry using the Flux Operator CLI.

```shell
echo $ENTERPRISE_TOKEN | flux-operator distro mirror registry.example.com/fluxcd \
  --version=2.9.x \
  --variant=enterprise-distroless \
  --pull-token-stdin
```

--------------------------------

### List Failing Flux Resources

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-cli-quick-reference.md

Use this command to list all Flux resources across all namespaces that are not ready.

```shell
flux get all -A --status-selector ready=false
```

--------------------------------

### Deploy Helm Chart Pre-releases on Staging

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-generic-helm-chart.md

Configure a Kustomization patch to override the OCIRepository's .spec.ref field, targeting only pre-release versions for deployment on staging environments.

```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: my-java-apps
resources:
  - ../base
patches:
  - patch: |
      - op: replace
        path: /spec/ref
        value:
          semver: ">= 0.0.0-0"
          semverFilter: ".*-rc.*"
    target:
      kind: OCIRepository
```

--------------------------------

### Enable Signature Verification with Cosign

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-generic-helm-chart.md

Configure the OCIRepository to verify Helm chart signatures using Sigstore cosign, specifying the provider and matching OIDC identity for keyless signing.

```yaml
kind: OCIRepository
spec:
  verify:
    provider: cosign
    matchOIDCIdentity:
      - issuer: "^https://token.actions.githubusercontent.com$"
        subject: "^https://github.com/my-org/my-jvm-chart.*$"
```

--------------------------------

### Extract SBOM from Source-Controller Image

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/distribution/security.md

Use this command to extract the Software Bill of Materials (SBOM) in SPDX format from the source-controller image for a specific architecture.

```shell
docker buildx imagetools inspect \
    <registry>/source-controller:v1.3.0 \
    --format "{{ json (index .SBOM \"linux/amd64\").SPDX}}"
```

--------------------------------

### Display Kustomization Events

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-cli-quick-reference.md

View the events for a specific Kustomization to understand each reconciliation step.

```shell
flux -n apps events --for Kustomization/podinfo
```

--------------------------------

### List Flux Resources in a Specific Namespace

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-cli-quick-reference.md

Lists all Flux resources within a specified namespace. If no namespace is provided, it defaults to 'flux-system'.

```shell
flux -n apps get all
```

--------------------------------

### Configure AI Agent for macOS

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/addons/mcp-stdio.md

Configure the AI agent to run the MCP server via Docker, mounting the local kubeconfig into the container.

```json
{
  "flux-operator-mcp":{
    "command":"docker",
    "args":[
      "run", "--rm", "-i",
      "-v", "/path/to/.kube/config:/home/nonroot/.kube/config:ro",
      "-e", "KUBECONFIG=/home/nonroot/.kube/config",
      "ghcr.io/controlplaneio-fluxcd/flux-mcp-enterprise:v0.1.0-stdio-readonly",
      "serve"
    ]
  }
}
```

--------------------------------

### Define Allow List for Flux Sources

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-policies.md

Define a ConfigMap in the flux-system namespace to list allowed URL prefixes for tenant-owned Flux sources like GitRepository, OCIRepository, and HelmRepository.

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: allowlist
  namespace: flux-system
  labels:
    fluxcd.controlplane.io/role: "policy"
data:
  sources: >-
    oci://ghcr.io/controlplaneio-fluxcd/charts/
    https://github.com/controlplaneio-fluxcd/
    ssh://git@github.com/controlplaneio-fluxcd/
```

--------------------------------

### Verify Signature of Source-Controller Image

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/distribution/security.md

Verify the Sigstore Cosign signature of the source-controller image using GitHub OIDC for identity and issuer validation.

```shell
cosign verify <registry>/source-controller:v1.3.0 \
  --certificate-identity-regexp=^https://github\.com/controlplaneio-fluxcd/.*$ \
  --certificate-oidc-issuer=https://token.actions.githubusercontent.com
```

--------------------------------

### Configure Semver and SemverFilter for Pre-release Versions

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-generic-helm-chart.md

Specify a semver range to match pre-release versions and use semverFilter to exclude stable versions when testing on staging clusters.

```yaml
kind: OCIRepository
spec:
  ref:
    semver: ">= 0.0.0-0"
    semverFilter: ".*-rc.*"
```

--------------------------------

### Export HelmRelease Configuration

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-cli-quick-reference.md

Display the configuration of a specific HelmRelease in the 'apps' namespace.

```shell
flux -n apps export helmrelease podinfo
```

--------------------------------

### List All Flux Resources in All Namespaces

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-cli-quick-reference.md

Retrieves a list of all Flux resources across all namespaces in the cluster, along with their reconciliation status.

```shell
flux get all --all-namespaces
```

--------------------------------

### List Reconciling Flux Resources

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-cli-quick-reference.md

Use this command to list all Flux resources across all namespaces that are currently reconciling and have not reached a ready state.

```shell
flux get all -A --status-selector ready=unknown
```

--------------------------------

### List Failing HelmReleases

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-cli-quick-reference.md

Use this command to list all HelmReleases at the cluster level that are not ready.

```shell
flux get helmreleases -A --status-selector ready=false
```

--------------------------------

### Configure Tenants Synchronization Kustomization with Dependency

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-policies.md

This Kustomization reconciles tenant resources after policies are applied. It depends on the 'policies' Kustomization to ensure order.

```yaml
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: tenants
  namespace: flux-system
spec:
  dependsOn:
    - name: policies
  path: "./tenants"
  prune: true
```

--------------------------------

### Multi-Cluster Tools

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/addons/mcp-stdio.md

Tools for managing and switching between Kubernetes cluster contexts.

```APIDOC
## get_kubeconfig_contexts
List all Kubernetes clusters available in the local kubeconfig so the agent can offer cluster selection.

## set_kubeconfig_context
Switch the active cluster context for the current session, enabling cross-cluster investigation without manual context changes.
```

--------------------------------

### FluxInstance Sync Configuration

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/rfcs/0001-flux-operator/README.md

Defines the sync configuration for a FluxInstance, specifying the source kind, URL, reference, path, and optional pull secret and sync interval.

```yaml
apiVersion: fluxcd.controlplane.io/v1
kind: FluxInstance
metadata:
  name: flux
  namespace: flux-system
spec:
  sync:
    kind: GitRepository
    url: "https://github.com/my-org/my-fleet.git"
    ref: "refs/heads/main"
    path: "clusters/my-cluster"
    pullSecret: "flux-system"
```

--------------------------------

### Configure AI Agent for Linux/WSL

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/addons/mcp-stdio.md

Add the flux-operator-mcp command to the AI agent configuration file, ensuring the KUBECONFIG environment variable is set.

```json
{
  "flux-operator-mcp":{
    "command":"flux-operator-mcp",
    "args":["serve"],
    "env":{
      "KUBECONFIG":"/path/to/.kube/config"
    }
  }
}
```

--------------------------------

### Configure FluxInstance for automatic updates

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/marketplace/aws.md

FluxInstance configuration enabling automatic patch updates from the GitHub Container Registry.

```yaml
apiVersion: fluxcd.controlplane.io/v1
kind: FluxInstance
metadata:
  name: flux
  namespace: flux-system
  annotations:
    fluxcd.controlplane.io/reconcileEvery: "1h"
    fluxcd.controlplane.io/reconcileTimeout: "5m"
spec:
  distribution:
    version: "2.9.x"
    registry: "709825985650.dkr.ecr.us-east-1.amazonaws.com/controlplane/fluxcd"
    artifact: "oci://ghcr.io/controlplaneio-fluxcd/flux-operator-manifests"
  cluster:
    type: aws
    multitenant: false
    networkPolicy: true
    domain: "cluster.local"
```

--------------------------------

### Deploy FluxInstance via Operator

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/marketplace/aws.md

Manifest to deploy the enterprise distribution using the Flux Operator.

```yaml
apiVersion: fluxcd.controlplane.io/v1
kind: FluxInstance
metadata:
  name: flux
  namespace: flux-system
spec:
  distribution:
    version: "2.9.x"
    registry: "709825985650.dkr.ecr.us-east-1.amazonaws.com/controlplane/fluxcd"
  cluster:
    type: aws
    multitenant: false
    networkPolicy: true
    domain: "cluster.local"
```

--------------------------------

### Define a typical Flux bootstrap repository structure

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-architecture.md

Organize cluster configurations, infrastructure components, and tenant applications within a single repository to support multi-tenant environments.

```sh
├── clusters
│   ├── prod1
│   ├── prod2
│   ├── staging
├── infrastructure
│   ├── base
│   ├── production
│   └── staging
└── tenants
    ├── team1
    └── team2
```

--------------------------------

### View Flux Resource Statistics

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-cli-quick-reference.md

Generates a report summarizing Flux resources grouped by kind, including their readiness status and cumulative storage usage from sources.

```shell
flux stats -A
```

--------------------------------

### Configure FluxInstance for Private Registry

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/distribution/install.md

Update the FluxInstance specification to point to a private registry for air-gapped deployments.

```yaml
apiVersion: fluxcd.controlplane.io/v1
kind: FluxInstance
metadata:
  name: flux
  namespace: flux-system
spec:
  distribution:
    version: "2.9.x"
    registry: "registry.example.com/fluxcd"
    variant: "enterprise-distroless"
  cluster:
    type: kubernetes
    multitenant: true
    networkPolicy: true
```

--------------------------------

### Kustomization for Environment-Specific Values

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-generic-helm-chart.md

This Kustomization configuration defines how to generate ConfigMaps and Secrets from local value files and apply them to Helm Releases. The `configMapGenerator` and `secretGenerator` fields are used to create these resources, and `kustomizeconfig.yaml` handles patching the HelmRelease.

```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: my-java-apps
resources:
  - ../base
configMapGenerator:
  - name: app1-values
    files:
      - values.yaml=app1/values.yaml
secretGenerator:
  - name: app1-values-secrets
    files:
      - values.yaml=app1/values-secrets.yaml
configurations:
  - kustomizeconfig.yaml
```

--------------------------------

### Extract SLSA Provenance from Source-Controller Image

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/distribution/security.md

Extract the SLSA provenance attestation in JSON format for the source-controller image, including build details.

```shell
docker buildx imagetools inspect \
  <registry>/source-controller:v1.3.0 \
  --format "{{ json (index .Provenance \"linux/amd64\").SLSA}}"
```

--------------------------------

### Deploy FluxInstance for Enterprise Distribution

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/distribution/install.md

Define a FluxInstance resource to deploy the enterprise distribution of Flux within a Kubernetes cluster.

```yaml
apiVersion: fluxcd.controlplane.io/v1
kind: FluxInstance
metadata:
  name: flux
  namespace: flux-system
spec:
  distribution:
    version: "2.9.x"
    artifact: "oci://ghcr.io/controlplaneio-fluxcd/flux-operator-manifests"
    registry: "ghcr.io/controlplaneio-fluxcd/distroless"
    imagePullSecret: "flux-enterprise-auth"
  cluster:
    type: kubernetes
    multitenant: true
    networkPolicy: true
```

--------------------------------

### List Flux Resources of a Specific Kind

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-cli-quick-reference.md

Fetches all Flux resources of a particular kind within the default namespace ('flux-system').

```shell
flux get kustomizations
```

--------------------------------

### Documentation Tools

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/addons/mcp-stdio.md

Tool for searching embedded Flux documentation.

```APIDOC
## search_flux_docs
Search the Flux documentation to surface relevant guides, API references, and troubleshooting steps. The documentation is embedded in the server binary, so no internet access is required.
```

--------------------------------

### Display Warning Events in a Namespace

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-cli-quick-reference.md

This command displays warning events for all Flux resources within a specific namespace.

```shell
flux -n apps events --types warning
```

--------------------------------

### Bind Admission Policy to Tenant Namespaces

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-policies.md

Create a ValidatingAdmissionPolicyBinding to link the source policy to all tenant namespaces, excluding system namespaces. It references the ConfigMap containing the allow list for validation.

```yaml
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingAdmissionPolicyBinding
metadata:
  name: tenant-sources
spec:
  policyName: "source.policy.fluxcd.controlplane.io"
  validationActions: [ "Deny" ]
  paramRef:
    name: allowlist
    namespace: flux-system
    parameterNotFoundAction: "Deny"
  matchResources:
    namespaceSelector:
      matchExpressions:
        - key: kubernetes.io/metadata.name
          operator: NotIn
          values:
            - flux-system
            - kube-system
```

--------------------------------

### KustomizeConfig for Patching HelmRelease

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-generic-helm-chart.md

This Kustomize configuration specifies how to patch HelmRelease resources to include generated ConfigMaps and Secrets. It ensures that the `spec/valuesFrom/name` field in HelmRelease is updated with the names of the generated resources, including a hash for cache busting.

```yaml
nameReference:
  - kind: ConfigMap
    version: v1
    fieldSpecs:
      - path: spec/valuesFrom/name
        kind: HelmRelease
  - kind: Secret
    version: v1
    fieldSpecs:
      - path: spec/valuesFrom/name
        kind: HelmRelease
```

--------------------------------

### Login to ControlPlane registry

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/addons/mcp-stdio.md

Authenticate with the ControlPlane registry using the Flux enterprise distribution token.

```shell
echo $ENTERPRISE_TOKEN | docker login ghcr.io -u flux-enterprise --password-stdin
```

--------------------------------

### Verify SLSA Provenance of Source-Controller Image

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/distribution/security.md

Verify the SLSA provenance attestation for the source-controller image, ensuring it was generated by the official SLSA GitHub Generator.

```shell
cosign verify-attestation --type slsaprovenance \
  --certificate-identity-regexp=^https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_container_slsa3.yml.*$ \
  --certificate-oidc-issuer=https://token.actions.githubusercontent.com \
  <registry>/source-controller:v1.3.0
```

--------------------------------

### Bind Policy to Tenant Namespaces

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-policies.md

Create a ValidatingAdmissionPolicyBinding to associate the registry policy with all tenant namespaces, excluding system namespaces. It references the 'allowlist' ConfigMap for the allowed registries.

```yaml
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingAdmissionPolicyBinding
metadata:
  name: tenant-registries
spec:
  policyName: "registry.policy.fluxcd.controlplane.io"
  validationActions: [ "Deny" ]
  paramRef:
    name: allowlist
    namespace: flux-system
    parameterNotFoundAction: "Deny"
  matchResources:
    namespaceSelector:
      matchExpressions:
        - key: kubernetes.io/metadata.name
          operator: NotIn
          values:
            - flux-system
            - kube-system
```

--------------------------------

### Define OCIRepository to Pull Helm Chart

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-generic-helm-chart.md

Use this resource to specify the OCI registry URL, interval for checking updates, and a layer selector for the Helm chart. It can be reused across multiple HelmRelease resources.

```yaml
apiVersion: source.toolkit.fluxcd.io/v1
kind: OCIRepository
metadata:
  name: my-jvm-chart
  namespace: my-java-apps
spec:
  interval: 10m
  url: oci://my-registry.io/charts/my-jvm-chart
  layerSelector:
    mediaType: "application/vnd.cncf.helm.chart.content.v1.tar+gzip"
    operation: copy
  ref:
    semver: "1.x"
```

--------------------------------

### Configure OCIRepository for Dex

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/addons/dex.md

Defines a Flux OCIRepository to pull the Dex Helm chart from the ControlPlane registry.

```yaml
apiVersion: source.toolkit.fluxcd.io/v1
kind: OCIRepository
metadata:
  name: dex
  namespace: flux-addons
spec:
  interval: 24h
  url: oci://ghcr.io/controlplaneio-fluxcd/charts/dex
  ref:
    tag: 0.24.0
  secretRef:
    name: flux-enterprise-auth
```

--------------------------------

### Inspect Kubernetes Objects Managed by a Kustomization

Source: https://github.com/controlplaneio-fluxcd/distribution/blob/main/docs/guides/flux-cli-quick-reference.md

Recursively lists all Kubernetes objects managed by a specific Flux Kustomization, including those managed by nested HelmReleases.

```shell
flux tree kustomization monitoring
```