### Reporting and Troubleshooting Prompts for Flux MCP Server

Source: https://raw.githubusercontent.com/controlplaneio-fluxcd/distribution/refs/heads/main/docs/mcp/prompt-engineering

Example prompts for analyzing Flux installations, checking component status, identifying reconciliation errors, and gathering information about deployments and resources managed by Flux.

```Prompt
Analyze the Flux installation in my current cluster and report the status of all components.
```

```Prompt
List the clusters in my kubeconfig and compare the Flux instances across them.
```

```Prompt
Are there any reconciliation errors in the Flux-managed resources?
```

```Prompt
Are the Flux kustomizations and Helm releases configured correctly?
```

```Prompt
Based on Flux events, what deployments have been updated today?
```

```Prompt
Draw a diagram of the Flux dependency flow in the cluster.
```

```Prompt
What is the Git source and revision of the Flux OCI repositories?
```

```Prompt
Which Kubernetes deployments are managed by Flux in the current cluster?
```

```Prompt
Which images are deployed by Flux in the monitoring namespace?
```

```Prompt
Perform a root cause analysis of the last failed deployment in the frontend namespace.
```

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

### Learning and Documentation Prompts for Flux MCP Server

Source: https://raw.githubusercontent.com/controlplaneio-fluxcd/distribution/refs/heads/main/docs/mcp/prompt-engineering

Example prompts for querying Flux documentation to understand features, settings, and advanced configurations.

```Prompt
How to configure mutual TLS for Git? Answer using the latest Flux docs.
```

```Prompt
What is the role of the interval setting in a Flux Kustomization? Search the latest docs.
```

```Prompt
How to trigger a Flux reconciliation with a webhook? Search the latest docs.
```

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

### Action-Oriented Prompts for Flux MCP Server

Source: https://raw.githubusercontent.com/controlplaneio-fluxcd/distribution/refs/heads/main/docs/mcp/prompt-engineering

Example prompts for performing actions on Flux resources, such as reconciling kustomizations, suspending or deleting Helm releases, and managing Kubernetes namespaces.

```Prompt
Reconcile the flux-system kustomization with its source in the current cluster.
```

```Prompt
Reconcile all the Flux Kustomization from flux-system namespace in the depends-on order, then verify their status.
```

```Prompt
Suspend all failing Helm releases in the test namespace, then delete them from the cluster.
```

```Prompt
Search for all the suspended Flux Kustomizations in the cluster and resume them.
```

```Prompt
Generate a namespace called test and apply it on my current cluster.
```

```Prompt
Copy the flux service account and its RBAC from the frontend namespace into test (remove the fluxcd labels).
```

```Prompt
Delete the test namespace from my current cluster.
```

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

### Build Flux MCP Server from Source

Source: https://raw.githubusercontent.com/controlplaneio-fluxcd/distribution/refs/heads/main/docs/mcp/install

These commands clone the Flux Operator repository and build the `flux-operator-mcp` binary from source. This method requires Go version 1.24 or newer to be installed on your system.

```shell
git clone https://github.com/controlplaneio-fluxcd/flux-operator.git
cd flux-operator
make mcp-build
```

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

### Example FluxCD Kustomization with SOPS Decryption

Source: https://raw.githubusercontent.com/fluxcd/kustomize-controller/refs/heads/main/docs/spec/v1/kustomizations

This example demonstrates a Kustomization resource configured to use SOPS for secret decryption. It specifies the SOPS provider, a service account for secret-less authentication, and a secret reference for additional keys or credentials. This setup allows the Kustomization controller to automatically decrypt encrypted secrets from the Git repository.

```yaml
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: sops-encrypted
  namespace: default
spec:
  interval: 5m
  path: "./"
  sourceRef:
    kind: GitRepository
    name: repository-with-secrets
  decryption:
    provider: sops
    serviceAccountName: sops-identity
    secretRef:
      name: sops-keys-and-credentials
```

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

### Configure Flux Components

Source: https://raw.githubusercontent.com/controlplaneio-fluxcd/distribution/refs/heads/main/docs/operator/fluxinstance

This example demonstrates the optional `.spec.components` field, which allows specifying a list of Flux components to install. If omitted, the operator will install the default set of components for the chosen Flux distribution.

```yaml
spec:
  components:
    - source-controller
    - kustomize-controller
    - helm-controller
    - notification-controller
```

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

### Configure Flux Distribution Version and Registry

Source: https://raw.githubusercontent.com/controlplaneio-fluxcd/distribution/refs/heads/main/docs/operator/fluxinstance

This example demonstrates the required `.spec.distribution` field, specifying the Flux distribution to install, including its version and container registry.

```yaml
spec:
  distribution:
    version: "2.x"
    registry: "ghcr.io/fluxcd"
```

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

### Example Output of Tracing ImageUpdateAutomation Events

Source: https://raw.githubusercontent.com/fluxcd/image-automation-controller/refs/heads/main/docs/spec/v1beta2/imageupdateautomations

This console output illustrates the typical events displayed when tracing an ImageUpdateAutomation resource using `kubectl events --for`. It shows various event types, reasons, and messages, providing insights into the resource's operational status and any encountered issues.

```console
LAST SEEN               TYPE      REASON               OBJECT                                 MESSAGE
3m29s (x7 over 4m17s)   Warning   GitOperationFailed   ImageUpdateAutomation/<automation-name>   failed to checkout source: unable to clone 'https://github.com/fluxcd/example': couldn't find remote ref "refs/heads/non-existing-branch"
3m14s (x4 over 3h24m)   Normal    Succeeded            ImageUpdateAutomation/<automation-name>   repository up-to-date
2m41s (x12 over 174m)   Normal    Succeeded            ImageUpdateAutomation/<automation-name>   no change since last reconciliation
```

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

### Install Flux MCP Server using Homebrew

Source: https://raw.githubusercontent.com/controlplaneio-fluxcd/distribution/refs/heads/main/docs/mcp/install

This command installs the Flux MCP Server on macOS or Linux systems using the Homebrew package manager, adding the necessary tap first to access the formula.

```shell
brew install controlplaneio-fluxcd/tap/flux-operator-mcp
```

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

### Example HelmRelease Resource Status Output

Source: https://raw.githubusercontent.com/fluxcd/helm-controller/refs/heads/main/docs/spec/v2/helmreleases

This YAML snippet displays the status and events of a Flux CD HelmRelease resource, showing its completion phases, last attempted revisions, and associated Helm controller actions like chart creation, synchronization, installation, and test success.

```YAML
         Podinfo - Jwt - Test - Scddu:
           Last Completed:  2023-12-04T14:17:45Z
           Last Started:    2023-12-04T14:17:42Z
           Phase:           Succeeded
         Podinfo - Service - Test - Uibss:
           Last Completed:           2023-12-04T14:17:47Z
           Last Started:             2023-12-04T14:17:45Z
           Phase:                    Succeeded
       Version:                      1
     Last Applied Revision:          6.5.3
     Last Attempted Config Digest:   sha256:e15c415d62760896bd8bec192a44c5716dc224db9e0fc609b9ac14718f8f9e56
     Last Attempted Generation:      1
     Last Attempted Release Action:  install
     Last Attempted Revision:        6.5.3
     Observed Generation:            1
     Storage Namespace:              default
   Events:
     Type    Reason            Age   From             Message
     ----    ------            ----  ----             -------
     Normal  HelmChartCreated  23s   helm-controller  Created HelmChart/default/default-podinfo with SourceRef 'HelmRepository/default/podinfo'
     Normal  HelmChartInSync   22s   helm-controller  HelmChart/default/default-podinfo with SourceRef 'HelmRepository/default/podinfo' is in-sync
     Normal  InstallSucceeded  18s   helm-controller  Helm install succeeded for release default/podinfo.v1 with chart podinfo@6.5.3
     Normal  TestSucceeded     10s   helm-controller  Helm test succeeded for release default/podinfo.v1 with chart podinfo@6.5.3: 3 test hooks completed successfully
```

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

### Example: Advanced Commit Message Template with Go/Sprig Functions

Source: https://raw.githubusercontent.com/fluxcd/image-automation-controller/refs/heads/main/docs/spec/v1beta2/imageupdateautomations

This example showcases the use of Go text template functions and Sprig template library functions within a FluxCD commit message template. It demonstrates data manipulation (e.g., `lower` for string transformation) and conditional logic (e.g., `if contains`) to generate more complex and dynamic commit messages.

```yaml
spec:
  commit:
    messageTemplate: |-
      Automated image update
      
      Automation name: {{ .AutomationObject }}

      Files:
      {{ range $filename, $_ := .Changed.FileChanges -}}
      - {{ $filename }}
      {{ end -}}

      Objects:
      {{ range $resource, $changes := .Changed.Objects -}}
      - {{ $resource.Kind | lower }} {{ $resource.Name | lower }}
        Changes:
      {{- range $_, $change := $changes }}
        {{ if contains "5.0.3" $change.NewValue -}}
          - {{ $change.OldValue }} -> {{ $change.NewValue }}
        {{ else -}}
          [skip ci] wrong image
        {{ end -}}
      {{ end -}}
      {{ end -}}
```

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

### Example Mock Data for ResourceSet Inputs

Source: https://raw.githubusercontent.com/controlplaneio-fluxcd/distribution/refs/heads/main/docs/operator/resourcesets/gitlab-merge-requests

This YAML snippet provides an example of the `test-inputs.yaml` file structure, containing mock Merge Request data. This data is used by the `flux-operator build resourceset` command to simulate inputs from a ResourceSetInputProvider during local validation.

```yaml
   - author: test
     branch: feat/test
     id: "1"
     sha: bf5d6e01cf802734853f6f3417b237e3ad0ba35d
     title: 'testing'
```

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

### Example FluxInstance Components Status

Source: https://raw.githubusercontent.com/controlplaneio-fluxcd/distribution/refs/heads/main/docs/operator/fluxinstance

Illustrates the structure of the `.status.components` field in a FluxInstance, showing the name, repository, tag, and digest for each installed Flux component. This provides visibility into the versions of the deployed Flux controllers.

```text
Status:
  Components:
    Digest:      sha256:161da425b16b64dda4b3cec2ba0f8d7442973aba29bb446db3b340626181a0bc
    Name:        source-controller
    Repository:  ghcr.io/fluxcd/source-controller
    Tag:         v1.3.0
    Digest:      sha256:48a032574dd45c39750ba0f1488e6f1ae36756a38f40976a6b7a588d83acefc1
    Name:        kustomize-controller
    Repository:  ghcr.io/fluxcd/kustomize-controller
    Tag:         v1.3.0
```

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

### Example Flux CLI Bootstrap Command

Source: https://raw.githubusercontent.com/controlplaneio-fluxcd/distribution/refs/heads/main/docs/operator/flux-bootstrap-migration

Illustrates a typical Flux CLI command used to bootstrap a cluster, linking it to a Git repository for configuration management.

```shell
flux bootstrap github \
  --owner=my-org \
  --repository=my-fleet \
  --branch=main \
  --path=clusters/my-cluster
```

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

### Install Flux Operator using Helm

Source: https://raw.githubusercontent.com/controlplaneio-fluxcd/distribution/refs/heads/main/docs/operator/install

This command installs the Flux Operator using its Helm chart from the GitHub Container Registry. It creates the `flux-system` namespace if it doesn't exist and deploys the operator within it.

```shell
helm install flux-operator oci://ghcr.io/controlplaneio-fluxcd/charts/flux-operator \
  --namespace flux-system \
  --create-namespace
```

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

### Example: Using Template Data and Helper Methods in FluxCD Commit Message

Source: https://raw.githubusercontent.com/fluxcd/image-automation-controller/refs/heads/main/docs/spec/v1beta2/imageupdateautomations

This YAML snippet provides an example of a `messageTemplate` that utilizes the `TemplateData` structure and its helper methods. It demonstrates how to access `AutomationObject` details, iterate over `FileChanges`, and range through `Objects` and their `Changes` to construct a detailed commit message.

```yaml
spec:
  commit:
    messageTemplate: |-
      Automated image update
      
      Automation name: {{ .AutomationObject }}

      Files:
      {{ range $filename, $_ := .Changed.FileChanges -}}
      - {{ $filename }}
      {{ end -}}

      Objects:
      {{ range $resource, $changes := .Changed.Objects -}}
      - {{ $resource.Kind }} {{ $resource.Name }}
        Changes:
      {{- range $_, $change := $changes }}
          - {{ $change.OldValue }} -> {{ $change.NewValue }}
      {{ end -}}
      {{ end -}}
```

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

### API Reference: HelmRelease .spec.install Configuration

Source: https://raw.githubusercontent.com/fluxcd/helm-controller/refs/heads/main/docs/spec/v2/helmreleases

Defines the configuration parameters for the controller when performing a Helm install action. These settings control various aspects of the installation process, including timeouts, CRD handling, namespace creation, and hook execution.

```APIDOC
.spec.install:
  .timeout: string (Optional) - The time to wait for any individual Kubernetes operation (like Jobs for hooks) during the installation of the chart. Defaults to the global timeout value.
  .crds: string (Optional) - The Custom Resource Definition install policy to use. Valid values are Skip, Create and CreateReplace. Default is Create.
  .replace: boolean (Optional) - Instructs Helm to re-use the release name, but only if that name is a deleted release which remains in the history. Defaults to false.
  .createNamespace: boolean (Optional) - Instructs Helm to create the target namespace if it does not exist. On uninstall, the created namespace will not be garbage collected. Defaults to false.
  .disableHooks: boolean (Optional) - Prevents chart hooks from running during the installation of the chart. Defaults to false.
  .disableOpenAPIValidation: boolean (Optional) - Prevents Helm from validating the rendered templates against the Kubernetes OpenAPI Schema. Defaults to false.
  .disableSchemaValidation: boolean (Optional) - Prevents Helm from validating the values against the JSON Schema. Defaults to false.
  .disableTakeOwnership: boolean (Optional) - Disables taking ownership of existing resources during the Helm install action. Defaults to false.
  .disableWait: boolean (Optional) - Disables waiting for resources to be ready after the installation of the chart. Defaults to false.
  .disableWaitForJobs: boolean (Optional) - Disables waiting for any Jobs to complete after the installation of the chart. Defaults to false.
```

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

### Example Output of kubectl events for GitRepository

Source: https://raw.githubusercontent.com/fluxcd/source-controller/refs/heads/main/docs/spec/v1/gitrepositories

Shows a sample output from 'kubectl events --for GitRepository/<repository-name>', illustrating the types of events (Normal, Warning) and their associated messages, reasons, and objects for a GitRepository.

```sh
LAST SEEN   TYPE     REASON                OBJECT                               MESSAGE
2m14s       Normal   NewArtifact           gitrepository/<repository-name>      stored artifact for commit 'Merge pull request #160 from stefanprodan/release-6.0.3'
36s         Normal   ArtifactUpToDate      gitrepository/<repository-name>      artifact up-to-date with remote revision: 'master@sha1:132f4e719209eb10b9485302f8593fc0e680f4fc'
94s         Warning  GitOperationFailed    gitrepository/<repository-name>      failed to checkout and determine revision: unable to clone 'https://github.com/stefanprodan/podinfo': couldn't find remote ref "refs/heads/invalid"
```

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

### Retrieve ImageUpdateAutomation Resources

Source: https://raw.githubusercontent.com/fluxcd/image-automation-controller/refs/heads/main/docs/spec/v1beta2/imageupdateautomations

This command lists the `ImageUpdateAutomation` resources deployed in the cluster, providing a quick overview of their names and last automation run times.

```sh
kubectl get imageupdateautomation
```

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

### Set Git Push Options for ImageUpdateAutomation

Source: https://raw.githubusercontent.com/fluxcd/image-automation-controller/refs/heads/main/docs/spec/v1beta2/imageupdateautomations

This snippet demonstrates how to use `spec.git.push.options` to send specific options to the upstream Git server during a push. The example shows how to automatically create a GitLab Merge Request targeting the `release` branch when pushing to the `dev` branch.

```yaml
spec:
  git:
    push:
      branch: dev
      options:
        merge_request.create: ""
        merge_request.target: release
```

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

### Example Output for FluxInstance Metrics

Source: https://raw.githubusercontent.com/controlplaneio-fluxcd/distribution/refs/heads/main/docs/operator/fluxinstance

This snippet provides a concrete example of the `flux_instance_info` metric output, showing typical values for its various labels such as `exported_namespace`, `kind`, `name`, `ready`, `reason`, `registry`, `revision`, `suspended`, and `uid`.

```text
flux_instance_info{
   exported_namespace="flux-system",
   kind="FluxInstance",
   name="flux",
   ready="True",
   reason="ReconciliationSucceeded",
   registry="ghcr.io/fluxcd",
   revision="v2.3.0@sha256:75aa209c6a2e25b97114ccf092246d02ab4363bc136edefc239d2a88da882b63",
   suspended="False",
   uid="16ca7202-9319-445b-99d0-617c25bda182"
}
```

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

### ResourceSetInputProvider CRD Example

Source: https://raw.githubusercontent.com/controlplaneio-fluxcd/distribution/refs/heads/main/docs/operator/resourcesetinputprovider

Defines a ResourceSetInputProvider that fetches input values from GitHub Pull Requests labeled with `deploy/flux-preview` from the specified repository `https://github.com/controlplaneio-fluxcd/flux-appx`.

```yaml
apiVersion: fluxcd.controlplane.io/v1
kind: ResourceSetInputProvider
metadata:
  name: flux-appx-prs
  namespace: default
  annotations:
    fluxcd.controlplane.io/reconcile: "enabled"
    fluxcd.controlplane.io/reconcileEvery: "5m"
spec:
  type: GitHubPullRequest
  url: https://github.com/controlplaneio-fluxcd/flux-appx
  filter:
    labels:
      - "deploy/flux-preview"
  defaultValues:
    chart: "charts/flux-appx"
```

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

### Example YAML Manifest with FluxCD Variables

Source: https://raw.githubusercontent.com/fluxcd/kustomize-controller/refs/heads/main/docs/spec/v1/kustomizations

This YAML snippet demonstrates how variables are defined within a Kubernetes Namespace manifest, using FluxCD's post-build substitution syntax. It shows examples of variables with default values (`${var:=default}`) and without (`${var}`).

```YAML
---
apiVersion: v1
kind: Namespace
metadata:
  name: apps
  labels:
    environment: ${cluster_env:=dev}
    region: "${cluster_region}"
```

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

### Verify FluxInstance Installation Status

Source: https://raw.githubusercontent.com/controlplaneio-fluxcd/distribution/refs/heads/main/docs/operator/flux-config

This command checks the status of the FluxInstance resource in the flux-system namespace, allowing users to confirm if the Flux distribution has been successfully installed and reconciled by the operator.

```shell
kubectl -n flux-system get fluxinstance flux
```

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

### Define Flux CD HelmRepository and HelmRelease for Podinfo Chart

Source: https://raw.githubusercontent.com/fluxcd/helm-controller/refs/heads/main/docs/spec/v2/helmreleases

This YAML manifest configures Flux CD to deploy the `podinfo` Helm chart. It first defines a `HelmRepository` to specify the chart's source, then a `HelmRelease` to manage its lifecycle, including versioning, installation, upgrade remediation, test execution, and drift detection. This setup automates the deployment and continuous reconciliation of the Helm chart.

```YAML
---
apiVersion: source.toolkit.fluxcd.io/v1
kind: HelmRepository
metadata:
  name: podinfo
  namespace: default
spec:
  interval: 5m
  url: https://stefanprodan.github.io/podinfo
---
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: podinfo
  namespace: default
spec:
  interval: 10m
  timeout: 5m
  chart:
    spec:
      chart: podinfo
      version: '6.5.*'
      sourceRef:
        kind: HelmRepository
        name: podinfo
      interval: 5m
  releaseName: podinfo
  install:
    remediation:
      retries: 3
  upgrade:
    remediation:
      retries: 3
  test:
    enable: true
  driftDetection:
    mode: enabled
    ignore:
    - paths: ["/spec/replicas"]
      target:
        kind: Deployment
  values:
    replicaCount: 2
```

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

### Example Mock PR Data for ResourceSet Validation

Source: https://raw.githubusercontent.com/controlplaneio-fluxcd/distribution/refs/heads/main/docs/operator/resourcesets/github-pull-requests

This YAML snippet provides an example structure for the `test-inputs.yaml` file. This file contains mock pull request data (author, branch, ID, SHA, title) that is used by the `flux-operator CLI` to test the `ResourceSet` template's dynamic input processing.

```yaml
- author: test
  branch: feat/test
  id: "1"
  sha: bf5d6e01cf802734853f6f3417b237e3ad0ba35d
  title: 'testing'
```

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

### Example: FluxCD Bucket with LDAP STS Configuration

Source: https://raw.githubusercontent.com/fluxcd/source-controller/refs/heads/main/docs/spec/v1/buckets

Provides a comprehensive YAML example demonstrating the configuration of a FluxCD Bucket object using the `generic` provider with an LDAP-based Security Token Service. It includes the `Bucket` resource definition and associated `Secret` objects for LDAP credentials and TLS certificates, showcasing how to link them by name.

```YAML
---
apiVersion: source.toolkit.fluxcd.io/v1
kind: Bucket
metadata:
  name: example
  namespace: example
spec:
  interval: 5m
  bucketName: example
  provider: generic
  endpoint: minio.example.com
  sts:
    provider: ldap
    endpoint: https://ldap.example.com
    secretRef:
      name: ldap-credentials
    certSecretRef:
      name: ldap-tls
---
apiVersion: v1
kind: Secret
metadata:
  name: ldap-credentials
  namespace: example
type: Opaque
stringData:
  username: <username>
  password: <password>
---
apiVersion: v1
kind: Secret
metadata:
  name: ldap-tls
  namespace: example
type: kubernetes.io/tls # or Opaque
stringData:
  tls.crt: <PEM-encoded cert>
  tls.key: <PEM-encoded key>
  ca.crt: <PEM-encoded cert>
```

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

### ImageUpdateAutomation Summary Output

Source: https://raw.githubusercontent.com/fluxcd/image-automation-controller/refs/heads/main/docs/spec/v1beta2/imageupdateautomations

This console output shows the summary status of the `podinfo-update` ImageUpdateAutomation resource, indicating its name and the timestamp of its last successful run.

```console
NAME             LAST RUN
podinfo-update   2024-03-17T22:22:34Z
```

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

### ImageUpdateAutomation Git Specification (APIDOC)

Source: https://raw.githubusercontent.com/fluxcd/image-automation-controller/refs/heads/main/docs/spec/v1beta2/imageupdateautomations

Detailed API documentation for the `.spec.git` field of the `ImageUpdateAutomation` kind, outlining its sub-fields for checkout, commit author, and commit signing key configuration.

```APIDOC
ImageUpdateAutomation.spec.git:
  checkout: (optional)
    Description: Specifies the Git reference to checkout.
    ref:
      branch: string (optional)
        Description: The Git branch to checkout. Overrides GitRepository.spec.ref.
  commit: (required)
    Description: Details about the commit made by the automation.
    author: (required)
      Description: Specifies the commit author.
      email: string (required)
        Description: The author's email for the commits.
      name: string (optional)
        Description: The author's name for the commits.
    signingKey: (optional)
      Description: Specifies the PGP key to sign commits with.
      secretRef: (required)
        Description: Reference to a Secret containing the PGP key.
        name: string (required)
          Description: Name of a Secret in the same namespace, containing 'git.asc' (ASCII-armored PGP key) and optionally 'passphrase'.
```

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

### Example Secret for SOPS Decryption Keys and Credentials

Source: https://raw.githubusercontent.com/fluxcd/kustomize-controller/refs/heads/main/docs/spec/v1/kustomizations

This Kubernetes Secret example shows how to store various decryption keys and credentials for SOPS. The controller identifies the type of entry by the key's suffix (e.g., `.agekey` for age private keys) or a fixed key (e.g., `sops.vault-token` for Hashicorp Vault tokens). This secret is referenced by the Kustomization's `.spec.decryption.secretRef` field.

```yaml
---
apiVersion: v1
kind: Secret
metadata:
  name: sops-keys-and-credentials
  namespace: default
data:
  # Exemplary age private key
  identity.agekey: <BASE64>
  # Exemplary Hashicorp Vault token
  sops.vault-token: <BASE64>
```

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

### Example OCIRepository with TLS Certificate Reference

Source: https://raw.githubusercontent.com/fluxcd/source-controller/refs/heads/main/docs/spec/v1/ocirepositories

This YAML example shows an `OCIRepository` resource configured to use a `certSecretRef` for TLS authentication. It also includes the corresponding `Secret` definition, demonstrating how to structure TLS certificate data for `tls.crt`, `tls.key`, and `ca.crt`.

```yaml
---
apiVersion: source.toolkit.fluxcd.io/v1
kind: OCIRepository
metadata:
  name: example
  namespace: default
spec:
  interval: 5m0s
  url: oci://example.com
  certSecretRef:
    name: example-tls
---
apiVersion: v1
kind: Secret
metadata:
  name: example-tls
  namespace: default
type: kubernetes.io/tls # or Opaque
data:
  tls.crt: <BASE64>
  tls.key: <BASE64>
  # NOTE: Can be supplied without the above values
  ca.crt: <BASE64>
```

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

### Retrieve Flux Instance Details

Source: https://raw.githubusercontent.com/controlplaneio-fluxcd/distribution/refs/heads/main/docs/mcp/tools

Retrieves comprehensive details about the Flux installation, including distribution version, component status, health, and cluster sync statistics.

```APIDOC
get_flux_instance()
  Parameters: None
  Output: Comprehensive details about the Flux instance configuration, including the distribution version information, component status and health, cluster sync statistics.
```

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

### Kustomization Spec: Name Prefix and Suffix Example

Source: https://raw.githubusercontent.com/fluxcd/kustomize-controller/refs/heads/main/docs/spec/v1/kustomizations

Illustrates the use of the optional `.spec.namePrefix` and `.spec.nameSuffix` fields to add a prefix and suffix to the names of all resources within a Kustomization.

```YAML
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: app
spec:
  # ...omitted for brevity
  namePrefix: "prefix-"
  nameSuffix: "-suffix"
```

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

### Kustomize Overlay Structure for Multi-Tenant Application Deployment

Source: https://raw.githubusercontent.com/controlplaneio-fluxcd/distribution/refs/heads/main/docs/operator/resourcesets/app-definition

This snippet illustrates the complex file structure required when using Kustomize overlays to deploy multiple instances of an application, each with different Helm values, for various tenants. It highlights the increased number of files and directories needed compared to using ResourceSets.

```text
apps/
└── app1
    ├── base
    │   ├── flux-helm-release.yaml
    │   ├── flux-oci-repository.yaml
    │   └── kustomization.yaml
    ├── overlays
    │   ├── tenant1
    │   │   ├── kustomization.yaml
    │   │   ├── values-patch.yaml
    │   │   └── version-patch.yaml
    │   └── tenant2
    │       ├── kustomization.yaml
    │       ├── values-patch.yaml
    │       └── version-patch.yaml
    └── bundle
        └── kustomization.yaml
```

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

### Example Application Folder Structure for Flux Kustomizations

Source: https://raw.githubusercontent.com/fluxcd/notification-controller/refs/heads/main/docs/spec/v1beta3/providers

This bash snippet illustrates a recommended folder structure for organizing application kustomization manifests. It suggests a hierarchy with 'apps' containing individual application directories, each with 'overlays' for different environments like 'production' and 'staging'.

```bash
apps/
├── app1
│   └── overlays
│       ├── production
│       └── staging
└── app2
    └── overlays
        ├── production
        └── staging
```

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

### Configure Flux Distribution with Exact Version

Source: https://raw.githubusercontent.com/controlplaneio-fluxcd/distribution/refs/heads/main/docs/operator/fluxinstance

Example using an exact version (`2.3.0`) to install a specific, fixed Flux version, preventing automatic upgrades.

```yaml
spec:
  distribution:
    version: "2.3.0"
```

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

### Kustomize Overlay Structure for Multi-cluster Deployment

Source: https://raw.githubusercontent.com/controlplaneio-fluxcd/distribution/refs/heads/main/docs/operator/resourcesets/app-definition

This text snippet illustrates the directory structure required for deploying applications across multiple environments using Kustomize overlays. It shows a base directory for common configurations and overlays for environment-specific customizations (dev, production), including patches for variables and kubeconfig.

```text
apps/
└── app1
    ├── base
    │   ├── flux-kustomization.yaml
    │   ├── flux-git-repository.yaml
    │   └── kustomization.yaml
    ├── overlays
    │   ├── dev
    │   │   ├── kustomization.yaml
    │   │   ├── vars-patch.yaml
    │   │   └── kubeconfig-patch.yaml
    │   └── production
    │       ├── kustomization.yaml
    │       ├── vars-patch.yaml
    │       └── kubeconfig-patch.yaml
    └── bundle
        └── kustomization.yaml
```

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

### FluxCD GitRepository and Kustomization Recommended Production Settings

Source: https://raw.githubusercontent.com/fluxcd/kustomize-controller/refs/heads/main/docs/spec/v1/kustomizations

Demonstrates recommended production configurations for FluxCD's GitRepository and Kustomization resources, including interval, URL, secret reference, branch, ignore patterns, drift detection, wait, timeout, retry, prune, and force settings.

```yaml
apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: webapp
  namespace: apps
spec:
  interval: 1m0s # check for new commits every minute and apply changes
  url: https://github.com/org/webapp # clone over HTTPS
  secretRef: # use token auth
    name: webapp-git-token # Flux user PAT (read-only access)
  ref:
    branch: main
  ignore: |
    # exclude all
    /*
    # include deploy dir
    !/deploy
---
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: webapp
  namespace: apps
spec:
  interval: 60m0s # detect drift and undo kubectl edits every hour
  wait: true # wait for all applied resources to become ready
  timeout: 3m0s # give up waiting after three minutes
  retryInterval: 2m0s # retry every two minutes on apply or waiting failures
  prune: true # remove stale resources from cluster
  force: false # enable this to recreate resources on immutable fields changes
  targetNamespace: apps # set the namespace for all resources
  sourceRef:
    kind: GitRepository
    name: webapp
    namespace: apps
  path: "./deploy/production"
```

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

### Waiting for ImageUpdateAutomation to Become Ready

Source: https://raw.githubusercontent.com/fluxcd/image-automation-controller/refs/heads/main/docs/spec/v1beta2/imageupdateautomations

After applying changes, it's possible to wait for an ImageUpdateAutomation resource to reach a 'ready' state. This ensures the automation is active and healthy before proceeding with further operations.

```sh
kubectl wait imageupdateautomation/<automation-name> --for=condition=ready --timeout=1m
```

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

### Configure HelmRelease to Update CRDs on Install and Upgrade

Source: https://raw.githubusercontent.com/fluxcd/helm-controller/refs/heads/main/docs/spec/v2/helmreleases

This YAML example demonstrates how to configure a `HelmRelease` object in FluxCD to manage Custom Resource Definitions (CRDs) during both installation and upgrade processes. By setting `.spec.install.crds` and `.spec.upgrade.crds` to `CreateReplace`, new CRDs will be created, and existing ones will be updated, ensuring CRDs are kept in sync with the Helm chart.

```yaml
---
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: my-operator
  namespace: default
spec:
  interval: 10m
  chart:
    spec:
      chart: my-operator
      version: "1.0.1"
      sourceRef:
        kind: HelmRepository
        name: my-operator-repo
      interval: 5m
  install:
    crds: CreateReplace
  upgrade:
    crds: CreateReplace
```

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

### Verifying FluxInstance Patches Locally with CLI

Source: https://raw.githubusercontent.com/controlplaneio-fluxcd/distribution/refs/heads/main/docs/operator/flux-kustomize

Shows how to use the Flux Operator CLI's `build instance` command to locally build a `FluxInstance` and print the generated manifests. This allows for verification of applied Kustomize patches before actual deployment to a cluster.

```bash
flux-operator build instance -f flux.yaml
```

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

### Example FluxReport Distribution Field

Source: https://raw.githubusercontent.com/controlplaneio-fluxcd/distribution/refs/heads/main/docs/operator/fluxreport

Illustrates the `.spec.distribution` field of a FluxReport, showing how it captures details like the entitlement issuer, the tool used for management (e.g., 'flux bootstrap'), installation status, and the Flux version.

```yaml
spec:
  distribution:
    entitlement: Issued by controlplane
    managedBy: 'flux bootstrap'
    status: Installed
    version: v2.3.0
```

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

### Configure FluxInstance for Sharding with Persistent Storage

Source: https://raw.githubusercontent.com/controlplaneio-fluxcd/distribution/refs/heads/main/docs/operator/flux-sharding

This `FluxInstance` configuration extends the sharding setup to include persistent storage for the `source-controller` shards. It defines a storage class and size, ensuring that each source-controller shard, including the main instance, gets a dedicated PersistentVolumeClaim.

```yaml
apiVersion: fluxcd.controlplane.io/v1
kind: FluxInstance
metadata:
  name: flux
  namespace: flux-system
spec:
  distribution:
    version: "2.x"
    registry: "ghcr.io/fluxcd"
  storage:
    class: "standard"
    size: "10Gi"
  sharding:
    key: "sharding.fluxcd.io/key"
    shards:
      - "shard1"
      - "shard2"
    storage: "persistent"
```

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

### Replicating FluxCD Post-Build Substitution Locally

Source: https://raw.githubusercontent.com/fluxcd/kustomize-controller/refs/heads/main/docs/spec/v1/kustomizations

This console command sequence shows how to replicate FluxCD's post-build variable substitution locally. It uses `export` to set a variable, `kustomize build` to generate manifests, and `flux envsubst --strict` to perform the actual variable replacement, demonstrating the final output.

```Console
$ export cluster_region=eu-central-1
$ kustomize build ./apps/ | flux envsubst --strict
---
apiVersion: v1
kind: Namespace
metadata:
  name: apps
  labels:
    environment: dev
    region: eu-central-1
```

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

### Install Flux Operator using Kubectl

Source: https://raw.githubusercontent.com/controlplaneio-fluxcd/distribution/refs/heads/main/docs/operator/install

This command applies the latest Flux Operator Kubernetes manifests directly from its GitHub releases page, installing the operator into the cluster.

```shell
kubectl apply -f https://github.com/controlplaneio-fluxcd/flux-operator/releases/latest/download/install.yaml
```

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

### ImageUpdateAutomation and GitRepository API Reference

Source: https://raw.githubusercontent.com/fluxcd/image-automation-controller/refs/heads/main/docs/spec/v1beta2/imageupdateautomations

Detailed API specification for the ImageUpdateAutomation kind and relevant fields of the GitRepository, outlining their core structure, source reference configuration, and Git-related properties. It covers how to link to Git repositories and configure Git operations, including timeouts, proxy settings, and OIDC providers.

```APIDOC
ImageUpdateAutomation:
  apiVersion: image.toolkit.fluxcd.io/v1beta2
  kind: ImageUpdateAutomation
  metadata:
    name: string (DNS subdomain name)
  spec:
    sourceRef:
      kind: GitRepository (default)
      name: string (required, reference to GitRepository)
      namespace: string (optional, defaults to same namespace)
    git:
      description: Git configurations for checkout, commit, and push operations (required)

GitRepository (referenced by ImageUpdateAutomation):
  spec:
    timeout: string (duration, e.g., "1m", for Git operations)
    proxySecretRef:
      name: string (reference to Secret for proxy configuration)
    provider: string (e.g., "azure", "github" for OIDC authentication)
```

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

### Apply FluxInstance Resource to Kubernetes Cluster

Source: https://raw.githubusercontent.com/controlplaneio-fluxcd/distribution/refs/heads/main/docs/operator/fluxinstance

Applies the `fluxinstance.yaml` manifest to the Kubernetes cluster, creating or updating the FluxInstance resource defined in the previous step. This command initiates the installation and configuration of Flux.

```shell
kubectl apply -f fluxinstance.yaml
```

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

### Define Multi-Instance Application with Flux ResourceSet YAML

Source: https://raw.githubusercontent.com/controlplaneio-fluxcd/distribution/refs/heads/main/docs/operator/resourcesets/app-definition

This YAML snippet demonstrates how a single Flux ResourceSet can define multiple instances of an application with varying configurations (e.g., different versions and replica counts per tenant). It bundles an OCIRepository and HelmRelease, leveraging templating to simplify multi-instance provisioning and reduce file overhead.

```yaml
apiVersion: fluxcd.controlplane.io/v1
kind: ResourceSet
metadata:
  name: app1
  namespace: apps
spec:
  inputs:
    - tenant: "tenant1"
      app:
       version: "6.7.x"
       replicas: 2
    - tenant: "tenant2"
      app:
       version: "6.6.x"
       replicas: 3
  resources:
    - apiVersion: source.toolkit.fluxcd.io/v1
      kind: OCIRepository
      metadata:
        name: app1-<< inputs.tenant >>
        namespace: apps
      spec:
        interval: 10m
        url: oci://my.registry/org/charts/app1
        ref:
          semver: << inputs.app.version | quote >>
    - apiVersion: helm.toolkit.fluxcd.io/v2
      kind: HelmRelease
      metadata:
        name: app1-<< inputs.tenant >>
        namespace: apps
      spec:
        interval: 1h
        releaseName: app1-<< inputs.tenant >>
        chartRef:
          kind: OCIRepository
          name: app1-<< inputs.tenant >>
        values:
          replicaCount: << inputs.app.replicas | int >>
```

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

### Configure FluxInstance to Sync from GitHub App

Source: https://raw.githubusercontent.com/controlplaneio-fluxcd/distribution/refs/heads/main/docs/operator/flux-sync

This example illustrates how to configure `FluxInstance` to use GitHub App authentication for syncing from a GitHub repository. It includes the necessary Flux components and sets the `provider` to `github`. A separate shell command is provided to create the Kubernetes secret containing the GitHub App's private key, application ID, and installation ID.

```yaml
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
    - kustomize-controller
    - helm-controller
    - notification-controller
    - image-reflector-controller
    - image-automation-controller
  sync:
    kind: GitRepository
    provider: github
    url: "https://github.com/my-org/my-fleet.git"
    ref: "refs/heads/main"
    path: "clusters/my-cluster"
    pullSecret: "flux-system"
```

```shell
flux create secret githubapp flux-system \
  --app-id=1 \
  --app-installation-id=2 \
  --app-private-key=./path/to/private-key-file.pem
```

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

### Describe GitRepository Status and Events with kubectl

Source: https://raw.githubusercontent.com/fluxcd/source-controller/refs/heads/main/docs/spec/v1/gitrepositories

Provides an example output of 'kubectl describe gitrepository', highlighting the 'Status' and 'Events' sections which contain crucial debugging information like reconciliation progress, observed generation, and failure reasons for a GitRepository.

```sh
...
Status:
...
  Conditions:
    Last Transition Time:  2022-02-14T09:40:27Z
    Message:               processing object: new generation 1 -> 2
    Observed Generation:   2
    Reason:                ProgressingWithRetry
    Status:                True
    Type:                  Reconciling
    Last Transition Time:  2022-02-14T09:40:27Z
    Message:               failed to checkout and determine revision: unable to clone 'https://github.com/stefanprodan/podinfo': couldn't find remote ref "refs/heads/invalid"
    Observed Generation:   2
    Reason:                GitOperationFailed
    Status:                False
    Type:                  Ready
    Last Transition Time:  2022-02-14T09:40:27Z
    Message:               failed to checkout and determine revision: unable to clone 'https://github.com/stefanprodan/podinfo': couldn't find remote ref "refs/heads/invalid"
    Observed Generation:   2
    Reason:                GitOperationFailed
    Status:                True
    Type:                  FetchFailed
  Observed Generation:     1
Events:
  Type     Reason                      Age                  From               Message
  ----     ------                      ----                 ----               -------
  Warning  GitOperationFailed          2s (x9 over 4s)      source-controller  failed to checkout and determine revision: unable to clone 'https://github.com/stefanprodan/podinfo': couldn't find remote ref "refs/heads/invalid"
```

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

### Install Flux Operator and Instance using Terraform Helm Provider

Source: https://raw.githubusercontent.com/controlplaneio-fluxcd/distribution/refs/heads/main/docs/operator/install

This Terraform configuration uses the Helm provider to install both the Flux Operator and a Flux instance. The `flux_operator` resource deploys the operator, and the `flux_instance` resource, which depends on the operator, configures the Flux instance using a `values/components.yaml` file.

```hcl
resource "helm_release" "flux_operator" {
  name             = "flux-operator"
  namespace        = "flux-system"
  repository       = "oci://ghcr.io/controlplaneio-fluxcd/charts"
  chart            = "flux-operator"
  create_namespace = true
}

resource "helm_release" "flux_instance" {
  depends_on = [helm_release.flux_operator]

  name       = "flux"
  namespace  = "flux-system"
  repository = "oci://ghcr.io/controlplaneio-fluxcd/charts"
  chart      = "flux-instance"

  values = [
    file("values/components.yaml")
  ]
}
```

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

### Enabling FluxCD Substitution with Placeholder Variable

Source: https://raw.githubusercontent.com/fluxcd/kustomize-controller/refs/heads/main/docs/spec/v1/kustomizations

This Kustomization snippet demonstrates a workaround to ensure variable substitution is enabled even when no other variables are configured. An arbitrary key-value pair is added to `postBuild.substitute` to trigger the substitution process.

```YAML
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: apps
spec:
  # ...omitted for brevity
  postBuild:
    substitute:
      var_substitution_enabled: "true"
```

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

### Inspect OCIRepository Details with kubectl describe

Source: https://raw.githubusercontent.com/fluxcd/source-controller/refs/heads/main/docs/spec/v1/ocirepositories

This command provides detailed information about the `podinfo` OCIRepository, including its artifact status, conditions, observed generation, and events. It shows how the artifact is stored, its path, size, and the URL for direct access, along with the lifecycle events.

```console
...
Status:
  Artifact:
    Digest:            sha256:d7e924b4882e55b97627355c7b3d2e711e9b54303afa2f50c25377f4df66a83b
    Last Update Time:  2025-06-14T11:23:36Z
    Path:              ocirepository/default/podinfo/3b6cdcc7adcc9a84d3214ee1c029543789d90b5ae69debe9efa3f66e982875de.tar.gz
    Revision:          latest@sha256:3b6cdcc7adcc9a84d3214ee1c029543789d90b5ae69debe9efa3f66e982875de
    Size:              1105
    URL:               http://source-controller.flux-system.svc.cluster.local./ocirepository/oci/podinfo/3b6cdcc7adcc9a84d3214ee1c029543789d90b5ae69debe9efa3f66e982875de.tar.gz
  Conditions:
    Last Transition Time:  2025-06-14T11:23:36Z
    Message:               stored artifact for revision 'latest@sha256:3b6cdcc7adcc9a84d3214ee1c029543789d90b5ae69debe9efa3f66e982875de'
    Observed Generation:   1
    Reason:                Succeeded
    Status:                True
    Type:                  Ready
    Last Transition Time:  2025-06-14T11:23:36Z
    Message:               stored artifact for revision 'latest@sha256:3b6cdcc7adcc9a84d3214ee1c029543789d90b5ae69debe9efa3f66e982875de'
    Observed Generation:   1
    Reason:                Succeeded
    Status:                True
    Type:                  ArtifactInStorage
  Observed Generation:     1
  URL:                     http://source-controller.source-system.svc.cluster.local./gitrepository/default/podinfo/latest.tar.gz
Events:
  Type    Reason               Age   From               Message
  ----    ------               ----  ----               -------
  Normal  NewArtifact          62s   source-controller  stored artifact with revision 'latest/3b6cdcc7adcc9a84d3214ee1c029543789d90b5ae69debe9efa3f66e982875de' from 'oci://ghcr.io/stefanprodan/manifests/podinfo'
```

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

### Build and Validate FluxCD ResourceSet Locally

Source: https://raw.githubusercontent.com/controlplaneio-fluxcd/distribution/refs/heads/main/docs/operator/resourcesets/github-pull-requests

This shell command demonstrates how to use the `flux-operator CLI` to locally build and validate `ResourceSet` templates. It takes the `ResourceSet` definition file and a mock inputs file (`test-inputs.yaml`) to simulate PR data, ensuring the templates are correctly rendered before actual deployment.

```shell
flux-operator build resourceset -f app-resourceset.yaml \
  --inputs-from test-inputs.yaml
```

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

### Install Flux Operator via Helm

Source: https://raw.githubusercontent.com/controlplaneio-fluxcd/distribution/refs/heads/main/docs/operator/flux-bootstrap-migration

Installs the Flux Operator into the `flux-system` namespace using its OCI Helm chart, preparing the cluster for operator-managed Flux.

```shell
helm install flux-operator oci://ghcr.io/controlplaneio-fluxcd/charts/flux-operator \
  --namespace flux-system
```

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

### Configure Flux MCP Server for Claude, Cursor, and Windsurf

Source: https://raw.githubusercontent.com/controlplaneio-fluxcd/distribution/refs/heads/main/docs/mcp/install

This JSON configuration snippet integrates the Flux MCP Server with AI assistants like Claude, Cursor, and Windsurf. It specifies the command path for the `flux-operator-mcp` binary, its arguments, and environment variables, including the critical KUBECONFIG path.

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

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

### Detailed ImageUpdateAutomation Status Output

Source: https://raw.githubusercontent.com/fluxcd/image-automation-controller/refs/heads/main/docs/spec/v1beta2/imageupdateautomations

This console output displays the comprehensive status of the `podinfo-update` ImageUpdateAutomation resource, detailing its conditions (e.g., `Ready`), last push commit hash, last push time, observed policies with image tags, and recent events from the image automation controller.

```console
Status:
  Conditions:
    Last Transition Time:    2024-03-17T22:22:33Z
    Message:                 repository up-to-date
    Observed Generation:     1
    Reason:                  Succeeded
    Status:                  True
    Type:                    Ready
  Last Automation Run Time:  2024-03-17T22:22:34Z
  Last Push Commit:          3ebb95cc56d2db59bc6ffbe0d9dd0ea445edeb77
  Last Push Time:            2024-03-17T22:22:34Z
  Observed Generation:       1
  Observed Policies:
    Podinfo - Policy:
      Name:  ghcr.io/stefanprodan/podinfo
      Tag:   5.0.3
  Observed Source Revision:  main@sha1:3ebb95cc56d2db59bc6ffbe0d9dd0ea445edeb77
Events:
  Type    Reason     Age              From                         Message
  ----    ------     ----             ----                         -------
  Normal  Succeeded  5s (x2 over 6s)  image-automation-controller  repository up-to-date
  Normal  Succeeded  5s               image-automation-controller  pushed commit '3ebb95c' to branch 'main'
Update from image update automation
```

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

### Example Flux Resource Info Metric

Source: https://raw.githubusercontent.com/controlplaneio-fluxcd/distribution/refs/heads/main/docs/operator/fluxreport

An example of the `flux_resource_info` metric for a Kustomization resource, showing specific label values for a successful reconciliation. This demonstrates how the metric appears with populated data.

```text
flux_resource_info{
    exported_namespace="flux-system",
    kind="Kustomization",
    name="flux-system",
    path="production/clusters",
    ready="True",
    reason="ReconciliationSucceeded",
    revision="refs/heads/main@sha1:d3c6dfa21465cc540d214811f46694fee0ce700d",
    source_name="flux-system",
    suspended="False",
    uid="359219f3-0793-4cf0-89a1-990ef1ac8098"
}
```