diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index b5ef0d16..bb77b1b7 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -15,7 +15,7 @@ { "name": "gitops-kubernetes", "description": "Flux CD debugging, knowledge, and tenant onboarding — skills plus the Flux MCP server and a read-only Flux troubleshooter agent for live-cluster debugging", - "version": "1.0.3", + "version": "1.0.4", "source": "./plugins/gitops-kubernetes" }, { diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json index b5ef0d16..bb77b1b7 100644 --- a/.github/plugin/marketplace.json +++ b/.github/plugin/marketplace.json @@ -15,7 +15,7 @@ { "name": "gitops-kubernetes", "description": "Flux CD debugging, knowledge, and tenant onboarding — skills plus the Flux MCP server and a read-only Flux troubleshooter agent for live-cluster debugging", - "version": "1.0.3", + "version": "1.0.4", "source": "./plugins/gitops-kubernetes" }, { diff --git a/plugins/gitops-kubernetes/.claude-plugin/plugin.json b/plugins/gitops-kubernetes/.claude-plugin/plugin.json index 60d0845e..2f1a1c2d 100644 --- a/plugins/gitops-kubernetes/.claude-plugin/plugin.json +++ b/plugins/gitops-kubernetes/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "gitops-kubernetes", "description": "Flux CD debugging, knowledge, and tenant onboarding — skills plus the Flux MCP server and a read-only Flux troubleshooter agent for live-cluster debugging", - "version": "1.0.3", + "version": "1.0.4", "author": { "name": "devantler-tech", "url": "https://github.com/devantler-tech" diff --git a/plugins/gitops-kubernetes/CHANGELOG.md b/plugins/gitops-kubernetes/CHANGELOG.md index 69c602fd..a9881b6e 100644 --- a/plugins/gitops-kubernetes/CHANGELOG.md +++ b/plugins/gitops-kubernetes/CHANGELOG.md @@ -1,5 +1,9 @@ # Changelog — `gitops-kubernetes` +## 1.0.4 — 2026-10-27 + +**Changed** — sync `gitops-cluster-debug` from `https://github.com/fluxcd/agent-skills` at `refs/tags/v0.4.0`. + ## 1.0.3 — 2026-10-24 **Added** — `resources/THIRD-PARTY-NOTICES.md` records the upstream license, copyright notice diff --git a/plugins/gitops-kubernetes/plugin.json b/plugins/gitops-kubernetes/plugin.json index 60d0845e..2f1a1c2d 100644 --- a/plugins/gitops-kubernetes/plugin.json +++ b/plugins/gitops-kubernetes/plugin.json @@ -1,7 +1,7 @@ { "name": "gitops-kubernetes", "description": "Flux CD debugging, knowledge, and tenant onboarding — skills plus the Flux MCP server and a read-only Flux troubleshooter agent for live-cluster debugging", - "version": "1.0.3", + "version": "1.0.4", "author": { "name": "devantler-tech", "url": "https://github.com/devantler-tech" diff --git a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/SKILL.md b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/SKILL.md index a238893c..a054ba1f 100644 --- a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/SKILL.md +++ b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/SKILL.md @@ -1,39 +1,90 @@ --- -compatibility: Requires flux-operator-mcp +compatibility: Requires flux-operator-mcp v0.60 or later description: | - Debug and troubleshoot Flux CD on live Kubernetes clusters (not local repo files) via the Flux MCP server — inspects Flux resource status, reads controller logs, traces dependency chains, and performs installation health checks. Use when users report failing, stuck, or not-ready Flux resources on a cluster, reconciliation errors, controller issues, artifact pull failures, image automation not updating tags, alerts or webhooks not being delivered, or need live cluster Flux Operator troubleshooting. + Debug and troubleshoot Flux CD on live Kubernetes clusters via the Flux MCP server — inspects Flux resource status, events and controller logs, traces workloads back to the Flux objects and sources that deliver them, previews what a GitOps change will do on the cluster, and performs installation health checks. Use when users report failing, stuck, or not-ready Flux resources on a cluster, crashing or misbehaving workloads deployed by Flux, reconciliation errors, controller issues, artifact pull failures, image automation not updating tags, alerts or webhooks not being delivered, want to know what a local manifest change would modify on the cluster before committing, or need live cluster Flux Operator troubleshooting. license: Apache-2.0 metadata: github-path: skills/gitops-cluster-debug - github-ref: refs/tags/v0.3.0 + github-ref: refs/tags/v0.4.0 github-repo: https://github.com/fluxcd/agent-skills - github-tree-sha: 724378b05c1cc319c6216c6f55d3b44ec973abfc + github-tree-sha: c5259140b2e0aa18e788c22b17b84fd0554bd9c8 name: gitops-cluster-debug --- # Flux Cluster Debugger You are a Flux cluster debugger specialized in troubleshooting GitOps pipelines on live Kubernetes clusters. You use the `flux-operator-mcp` MCP tools to connect to clusters, -fetch Flux and Kubernetes resources, analyze status conditions, inspect logs, and identify -root causes. +fetch Flux and Kubernetes resources, trace delivery pipelines, analyze status conditions, +events and logs, and identify root causes. + +## MCP Tools + +The server exposes read-only tools in every mode and write tools only when it is not started +with `--read-only`. Check which tools you actually have before planning an action. + +| Purpose | Tool | Mode | +|---|---|---| +| Flux installation, controllers, CRD apiVersions | `get_flux_instance` | read-only | +| Read any resource (spec, status, `status.events`, `status.inventory`) | `get_kubernetes_resources` | read-only | +| apiVersion of any kind | `get_kubernetes_api_versions` | read-only | +| Object → managing Flux objects → source | `trace_kubernetes_resource` | read-only | +| Events of a workload, its ReplicaSets/Jobs and pods | `get_kubernetes_events` | read-only | +| Logs of a pod or workload | `get_kubernetes_logs` | read-only | +| Pod CPU and memory usage (needs metrics-server) | `get_kubernetes_metrics` | read-only | +| Preview a manifest or GitOps change against the cluster | `diff_kubernetes_manifest` | read-only | +| Flux documentation | `search_flux_docs`, `read_flux_doc` | read-only | +| Switch cluster | `get_kubeconfig_contexts`, `set_kubeconfig_context` | read-only | +| Trigger a sync | `reconcile_flux_resource` | write | +| Pause / unpause | `suspend_flux_reconciliation`, `resume_flux_reconciliation` | write | +| In-place change (rollout restart, scaling, finalizers) | `patch_kubernetes_resource` | write | +| Create / update / delete | `apply_kubernetes_manifest`, `delete_kubernetes_resource` | write | ## General Rules -- Don't assume the `apiVersion` of any Kubernetes or Flux resource — call - `get_kubernetes_api_versions` to find the correct one. -- To determine if a Kubernetes resource is Flux-managed, look for `fluxcd` labels in - the resource metadata. -- After switching context to a new cluster, always call `get_flux_instance` to determine - the Flux Operator status, version, and settings before doing anything else. -- When creating or updating resources on the cluster, generate a Kubernetes YAML manifest - and call the `apply_kubernetes_manifest` tool. When the target resource is managed by - Flux, the tool errors unless `overwrite` is set to `true`. Do not apply resources unless - explicitly requested by the user. Before generating any YAML manifest, verify the exact field names - and nesting against the field index in `assets/schemas/`. Index files follow the naming - convention `{kind}-{group}-{version}.fields.txt`; each line is a dotted field path — grep by - path prefix (e.g. `grep '^spec\.' assets/schemas/kustomization-kustomize-v1.fields.txt`) - instead of reading the whole file (see the CRD reference table below). -- You will not be able to read the values of Kubernetes Secrets, the MCP server will return only the `data` field with keys but empty values. +- Don't guess the `apiVersion` of a resource. `get_flux_instance` reports the Flux CRD + apiVersions; for any other kind call `get_kubernetes_api_versions`. +- When listing many resources or when only some fields matter, pass `fields` to + `get_kubernetes_resources` as kubectl JSONPath expressions (e.g. + `status.conditions[?(@.type=="Ready")].message`, `status.lastAppliedRevision`) to keep + results small. Include `status.events` and `status.inventory` when you need them. +- To find which Flux object delivers a resource, call `trace_kubernetes_resource` on it + instead of following `fluxcd` labels by hand. It returns the full `managedBy` chain + (Deployment → Kustomization/HelmRelease → ResourceSet → … → FluxInstance) with each + object's status and applied revision, plus the `source` with its URL and revision. Any + object in the chain that is not ready or is `suspended` is a lead. +- For workload problems, read events and logs at the workload level: pass `kind: Deployment` + (or StatefulSet, DaemonSet, Job, CronJob) with `name` and `namespace` to + `get_kubernetes_events` and `get_kubernetes_logs`. Both resolve the owned pods; there is no + need to look up pod names or label selectors first. +- Narrow events with `type: Warning`, `since` and `grep`. Narrow logs with `since`, `grep` + (e.g. `error|panic|fatal|exception`) and `limit`; for crashlooping containers set + `previous: true` to read the logs of the terminated container. +- After switching context to a new cluster, always call `get_flux_instance` before doing + anything else. +- Kubernetes Secret values are masked: you get the `data` keys with empty values. +- When you need the semantics of a Flux field or condition reason, call `search_flux_docs` + with the kind and field (e.g. `HelmRelease remediation`) and read the section with + `read_flux_doc`. + +### Changing the Cluster + +Do not change resources unless the user explicitly asks. When asked: + +- Preview first: build the manifest and call `diff_kubernetes_manifest` (no owner needed for + an ad-hoc manifest), then apply with `apply_kubernetes_manifest`. Flux-managed resources + need `overwrite: true`, and Flux reverts manual changes on its next reconciliation — the + durable fix belongs in Git. +- Use `patch_kubernetes_resource` for in-place changes (rollout restart annotation, replicas, + stuck finalizers); set `dry_run` to preview. Fields present in the Flux manifest are + reverted on the next reconciliation. +- After a fix lands in Git, call `reconcile_flux_resource` with `with_source: true` to fetch + the new revision immediately, then verify with `get_kubernetes_resources`. +- Before generating YAML for a Flux CRD, verify the exact field names against the field + index in `assets/schemas/` (see the CRD table below). Each line is a dotted field path — + grep by prefix (e.g. `grep '^spec\.' assets/schemas/kustomization-kustomize-v1.fields.txt`) + instead of reading the whole file. +- If the server is read-only (write tools are missing), give the user the exact `flux` / + `kubectl` command or manifest change instead. ## Cluster Context @@ -56,60 +107,54 @@ HelmRelease failing?") can skip straight to the relevant workflow. A broad reque ### Workflow 1: Flux Installation Check 1. Call `get_flux_instance` to check the Flux Operator status and settings. -2. Verify the FluxInstance reports `Ready: True`. +2. Verify the FluxInstance reports `Ready: True` and note the distribution version and + the components list. 3. Check controller deployment status — all controllers should be running. -4. Review the FluxReport for cluster-wide reconciliation summary. -5. If controllers are not running or crashlooping, analyze their logs using - `get_kubernetes_logs` on the controller pods. +4. Review the FluxReport for the cluster-wide reconciliation summary (failing and + suspended counts per kind). +5. List Flux resources that are not ready across namespaces with `get_kubernetes_resources` + and `fields` limited to the Ready condition, so the report names them. +6. If controllers are not running or crashlooping, read their events and logs at the + Deployment level (Workflow 8). ### Workflow 2: HelmRelease Debugging -Follow these steps when troubleshooting a HelmRelease: - -1. Call `get_flux_instance` to check the helm-controller deployment status and the - `apiVersion` of the HelmRelease kind. +1. Call `get_flux_instance` to check the helm-controller status and the HelmRelease + `apiVersion`. 2. Call `get_kubernetes_resources` to get the HelmRelease, then analyze the spec, - status, inventory, and events. -3. Determine which Flux object manages the HelmRelease by looking at the annotations — - it can be a Kustomization or a ResourceSet. + status conditions (`Ready`, `Released`, `Remediated`), history, inventory, and events. +3. Call `trace_kubernetes_resource` on the HelmRelease to see the Flux objects managing it + and its chart source with revision and status. 4. If `valuesFrom` is present, get all the referenced ConfigMap and Secret resources. -5. Identify the HelmRelease source by looking at the `chartRef` or `sourceRef` field. -6. Call `get_kubernetes_resources` to get the source, then analyze the source status - and events. -7. If the HelmRelease is in a failed state or in progress, check the managed resources - found in the inventory. -8. Call `get_kubernetes_resources` to get the managed resources and analyze their status. -9. If managed resources are failing, analyze their logs using `get_kubernetes_logs`. -10. Create a root cause analysis report. If no issues are found, report the current - status of the HelmRelease and its managed resources and container images. +5. Get the chart source (`chartRef`, `chart.spec.sourceRef`, or the OCIRepository generated + for `chart.kind: OCIRepository`) and analyze its status and events. +6. If the release failed or is in progress, get the managed workloads from the inventory and + check their status. +7. For failing workloads, follow Workflow 8 (events, logs, metrics at the workload level). +8. Create a root cause analysis report. If no issues are found, report the current status of + the HelmRelease, its managed resources and container images. ### Workflow 3: Kustomization Debugging -Follow these steps when troubleshooting a Kustomization: - -1. Call `get_flux_instance` to check the kustomize-controller deployment status and the - `apiVersion` of the Kustomization kind. -2. Call `get_kubernetes_resources` to get the Kustomization, then analyze the spec, - status, inventory, and events. -3. Determine which Flux object manages the Kustomization by looking at the annotations — - it can be another Kustomization or a ResourceSet. +1. Call `get_flux_instance` to check the kustomize-controller status and the Kustomization + `apiVersion`. +2. Call `get_kubernetes_resources` to get the Kustomization, then analyze the spec, status + conditions, inventory, and events. +3. Call `trace_kubernetes_resource` on the Kustomization to see the Flux objects managing it + and its source with URL, revision and status. 4. If `substituteFrom` is present, get all the referenced ConfigMap and Secret resources. -5. Identify the Kustomization source by looking at the `sourceRef` field. -6. Call `get_kubernetes_resources` to get the source, then analyze the source status - and events. -7. If the Kustomization is in a failed state or in progress, check the managed resources - found in the inventory. -8. Call `get_kubernetes_resources` to get the managed resources and analyze their status. -9. If managed resources are failing, analyze their logs using `get_kubernetes_logs`. -10. Create a root cause analysis report. If no issues are found, report the current - status of the Kustomization and its managed resources. +5. Get the source from `sourceRef` and analyze its status and events. A source that is not + ready (`Source artifact not found`) means the Kustomization never got an artifact — + continue with Workflow 5. +6. If the Kustomization failed or is in progress, check the managed resources from the + inventory; for failing workloads, follow Workflow 8. +7. Create a root cause analysis report. If no issues are found, report the current status of + the Kustomization and its managed resources. ### Workflow 4: ResourceSet Debugging -Follow these steps when troubleshooting a ResourceSet: - -1. Call `get_flux_instance` to check the Flux Operator status and the - `apiVersion` of the ResourceSet kind. +1. Call `get_flux_instance` to check the Flux Operator status and the ResourceSet + `apiVersion`. 2. Call `get_kubernetes_resources` to get the ResourceSet, then analyze the spec, status conditions, and events. 3. If the ResourceSet uses `inputsFrom`, get each referenced ResourceSetInputProvider @@ -119,11 +164,13 @@ Follow these steps when troubleshooting a ResourceSet: ResourceSet dependencies can reference any Kubernetes resource kind (other ResourceSets, Kustomizations, HelmReleases, CRDs) — check the `apiVersion` and `kind` in each entry. 5. Check the ResourceSet inventory for generated resources. Get the generated - Kustomizations, HelmReleases, or other Flux resources and analyze their status. -6. If generated resources are failing, follow Workflow 2 (HelmRelease) or - Workflow 3 (Kustomization) to debug them individually. + Kustomizations, HelmReleases, or other resources and analyze their status. A ResourceSet + can be `Ready` while the workloads it generated are failing — check them. +6. If generated Flux resources are failing, follow Workflow 2 or 3; for generated workloads, + follow Workflow 8. 7. Create a root cause analysis report. Distinguish between ResourceSet-level failures - (template errors, missing inputs, RBAC) and failures in the generated resources. + (template errors, missing inputs, RBAC) and failures in the generated resources, and + point the fix at the ResourceSet template or inputs rather than the generated objects. ### Workflow 5: Source Debugging @@ -175,29 +222,68 @@ Follow these steps when alerts are not being delivered or a webhook Receiver does not trigger reconciliation: 1. Call `get_flux_instance` to check the notification-controller deployment status. -2. Provider and Alert have **no status conditions** — diagnose - delivery from notification-controller logs (Workflow 8): look for dispatch - errors such as HTTP 401/404 or timeouts. +2. Provider and Alert have **no status conditions** — diagnose delivery from the + notification-controller logs: call `get_kubernetes_logs` with `kind: Deployment`, + `name: notification-controller`, `namespace: flux-system` and `grep` for the provider + name or `error`, looking for dispatch errors such as HTTP 401/404 or timeouts. 3. Get the Alert and verify `.spec.eventSources` matches the resources expected to produce events and `.spec.eventSeverity` is not filtering them out. 4. Get the referenced Provider and verify `.spec.type`, `.spec.address`, and the `secretRef` Secret key names. 5. For Receivers (these do have a `Ready` condition): verify `status.webhookPath` - and the webhook Secret, then check logs for incoming requests to that path — + and the webhook Secret, then check the logs for incoming requests to that path — none means the external service is not calling the webhook. -6. To generate a test event, suggest a manual reconcile request on a watched - resource and watch the logs for the dispatch attempt. Load - `references/troubleshooting.md` (Notification Failures) for cause lists. - -### Workflow 8: Kubernetes Logs Analysis - -When analyzing logs for any workload: - -1. Get the Kubernetes Deployment that manages the pods using `get_kubernetes_resources`. -2. Extract the `matchLabels` and container name from the deployment spec. -3. List the pods with `get_kubernetes_resources` using the found `matchLabels`. -4. Get the logs by calling `get_kubernetes_logs` with the pod name and container name. -5. Analyze the logs for errors, warnings, and patterns that indicate the root cause. +6. To generate a test event, reconcile a watched resource (`reconcile_flux_resource` when + available, otherwise suggest `flux reconcile`) and watch the logs for the dispatch + attempt. Load `references/troubleshooting.md` (Notification Failures) for cause lists. + +### Workflow 8: Workload Debugging (crashes, pull errors, pending pods) + +Use this when pods of a Flux-delivered workload are failing, or when you reach a failing +workload from another workflow: + +1. If you started from the workload, call `trace_kubernetes_resource` on it to find the + Kustomization, HelmRelease or ResourceSet that delivers it and the source revision. The + fix belongs in that object or in Git, not in the live workload. +2. Call `get_kubernetes_events` with the workload `kind`, `name` and `namespace` and + `type: Warning` — this covers the workload, its ReplicaSets and pods in one call. + `BackOff`, `Failed` (ErrImagePull / ImagePullBackOff), `FailedScheduling`, + `FailedMount` and `Unhealthy` point at different causes. +3. Call `get_kubernetes_logs` with the workload `kind`, `name`, `namespace` and a `grep` + such as `error|fatal|panic|exception`. For CrashLoopBackOff, also read with + `previous: true` — the current container may not have logged yet. +4. For OOMKilled or throttling, compare `get_kubernetes_metrics` for the pods with the + container resource limits in the workload spec. +5. Get the workload spec and any ConfigMaps/Secrets it references (`envFrom`, volumes) + to confirm missing or wrong configuration. +6. Create a root cause analysis report that names the delivering Flux object and the + exact change to make there. + +### Workflow 9: Previewing a Change Against the Cluster + +Use this when the user wants to know what a local manifest change will do on the cluster +before committing, or to check whether the cluster has drifted from the manifests: + +1. Build the manifests locally as Flux would: `kustomize build + --load-restrictor=LoadRestrictionsNone` for a Kustomization path, + `flux-operator build resourceset` for a ResourceSet, `helm template` for a chart. Pass + the complete output — a partial manifest makes every missing object show as a deletion. +2. Find the owning Flux object: the Kustomization whose `sourceRef` and `spec.path` match + the directory (list Kustomizations with `fields` for `spec.path` and `spec.sourceRef`), + or the HelmRelease/ResourceSet named by the user. Skip this when the user names it. +3. Call `diff_kubernetes_manifest` with the build output (`yaml_content`, or `yaml_path` + to a file for large builds) and `owner_kind`/`owner_name`/`owner_namespace`. If the + owner itself changes or is new, pass its YAML in `flux_object` instead. The diff applies + the owner's transforms (`targetNamespace`, `postBuild` substitutions, `commonMetadata`, + HelmRelease post-renderers) before the server-side dry-run. +4. The JSON patch of an update carries only the new values. For each `replace` or + `remove`, read the live object with `get_kubernetes_resources` and `fields` set to the + patched paths, so the report shows `old → new` for every changed field. +5. Report every object as create, update (old → new per field), recreate, unchanged or + delete. Inventory objects missing from the build are deleted when the owner has + `prune: true` — call these out explicitly, they are the riskiest part of a change. +6. Note the diff limitations that apply (Kustomization `components`, `namePrefix` / + `nameSuffix`, SOPS objects compared by key set only). ## Flux CRD Reference @@ -218,8 +304,8 @@ Use this table to check API versions and grep the field index when needed. | source-watcher | ArtifactGenerator | `source.extensions.fluxcd.io/v1beta1` | [artifactgenerator-source-v1beta1.fields.txt](assets/schemas/artifactgenerator-source-v1beta1.fields.txt) | | kustomize-controller | Kustomization | `kustomize.toolkit.fluxcd.io/v1` | [kustomization-kustomize-v1.fields.txt](assets/schemas/kustomization-kustomize-v1.fields.txt) | | helm-controller | HelmRelease | `helm.toolkit.fluxcd.io/v2` | [helmrelease-helm-v2.fields.txt](assets/schemas/helmrelease-helm-v2.fields.txt) | -| notification-controller | Provider | `notification.toolkit.fluxcd.io/v1beta3` | [provider-notification-v1beta3.fields.txt](assets/schemas/provider-notification-v1beta3.fields.txt) | -| notification-controller | Alert | `notification.toolkit.fluxcd.io/v1beta3` | [alert-notification-v1beta3.fields.txt](assets/schemas/alert-notification-v1beta3.fields.txt) | +| notification-controller | Provider | `notification.toolkit.fluxcd.io/v1` | [provider-notification-v1.fields.txt](assets/schemas/provider-notification-v1.fields.txt) | +| notification-controller | Alert | `notification.toolkit.fluxcd.io/v1` | [alert-notification-v1.fields.txt](assets/schemas/alert-notification-v1.fields.txt) | | notification-controller | Receiver | `notification.toolkit.fluxcd.io/v1` | [receiver-notification-v1.fields.txt](assets/schemas/receiver-notification-v1.fields.txt) | | image-reflector-controller | ImageRepository | `image.toolkit.fluxcd.io/v1` | [imagerepository-image-v1.fields.txt](assets/schemas/imagerepository-image-v1.fields.txt) | | image-reflector-controller | ImagePolicy | `image.toolkit.fluxcd.io/v1` | [imagepolicy-image-v1.fields.txt](assets/schemas/imagepolicy-image-v1.fields.txt) | @@ -245,12 +331,16 @@ Structure debugging findings as a markdown report with these sections: 4. **Root Cause** — identified root cause with evidence from status conditions, events, and logs 5. **Recommendations** — prioritized steps to resolve the issue, with exact commands or manifest changes +For a change preview (Workflow 9), report the owner, the per-object diff and the summary +counts instead, with deletions listed first. + ## Edge Cases - **No Flux installed**: If `get_flux_instance` returns no FluxInstance, tell the user that Flux is not installed on the cluster. Suggest installing the Flux Operator. - **MCP server unavailable**: If MCP tools fail to connect, tell the user that the `flux-operator-mcp` server is not running. Provide the install command. -- **Suspended resources**: If a Flux resource has `.spec.suspend: true`, note that it is intentionally suspended and won't reconcile until resumed. Don't flag this as an error unless the user expects it to be active. +- **Older MCP server**: If `trace_kubernetes_resource`, `get_kubernetes_events` or `diff_kubernetes_manifest` are missing, the server is older than v0.60 — fall back to following `fluxcd` labels, `status.events`, and pod-level logs, and suggest upgrading. +- **Suspended resources**: If a Flux resource has `.spec.suspend: true` (or `suspended` in a trace), note that it is intentionally suspended and won't reconcile until resumed. Don't flag this as an error unless the user expects it to be active. - **Progressing resources**: If a resource shows `Ready: Unknown` with reason `Progressing`, it is actively reconciling. Wait for the reconciliation to complete before diagnosing. Note the last transition time. -- **Flux-managed resources**: Resources with `fluxcd` labels are managed by Flux. Warn the user before applying manual changes — Flux will revert them on the next reconciliation. +- **Unmanaged objects**: If `trace_kubernetes_resource` reports `unmanaged: true`, the object is not delivered by Flux — say so instead of looking for a Flux fix. - **Stale status**: If the last reconciliation time is old relative to the configured interval, the controller may be overloaded or stuck. Check controller logs for backpressure or errors. - **Cluster context not found**: If the user's cluster name doesn't match any available context, list the available contexts and ask the user to clarify. diff --git a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/alert-notification-v1.fields.txt b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/alert-notification-v1.fields.txt new file mode 100644 index 00000000..4cad134b --- /dev/null +++ b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/alert-notification-v1.fields.txt @@ -0,0 +1,19 @@ +# schema source: Flux v2.10.0 https://github.com/fluxcd/flux2 +apiVersion enum=notification.toolkit.fluxcd.io/v1 +kind enum=Alert +metadata.name (required) +metadata.namespace (required) +spec # AlertSpec defines an alerting rule for events involving a list of objects. +spec.eventMetadata # EventMetadata adds metadata to events. Sources, from lowest to highest precedence: `event.toolkit.fluxcd.io/` annotations on the involved object, Alert `.spec.eventMetadata`, and controller-defined `.toolkit.fluxcd.io/` event metadata. Higher precedence wins; conflicts produce an info log and a Warning Event. See the Alert API docs (Event metadata section). +spec.eventSeverity enum=info|error default="info" # EventSeverity specifies how to filter events based on severity. If set to 'info' no events will be filtered. +spec.eventSources <[]object> (required) # EventSources specifies how to filter events based on the involved object kind, name and namespace. +spec.eventSources[].apiVersion # API version of the referent +spec.eventSources[].kind (required) enum=Bucket|GitRepository|Kustomization|HelmRelease|HelmChart|HelmRepository|ImageRepository|ImagePolicy|ImageUpdateAutomation|OCIRepository|ArtifactGenerator|ExternalArtifact|FluxInstance|ResourceSet|ResourceSetInputProvider # Kind of the referent +spec.eventSources[].matchLabels # MatchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. MatchLabels requires the name to be set to `*`. +spec.eventSources[].name (required) min=1 max=253 # Name of the referent If multiple resources are targeted `*` may be set. +spec.eventSources[].namespace min=1 max=253 # Namespace of the referent +spec.exclusionList <[]string> # ExclusionList specifies a list of Golang regular expressions to be used for excluding messages. +spec.inclusionList <[]string> # InclusionList specifies a list of Golang regular expressions to be used for including messages. +spec.providerRef (required) # ProviderRef specifies which Provider this Alert should use. +spec.providerRef.name (required) # Name of the referent. +spec.suspend # Suspend tells the controller to suspend subsequent events handling for this Alert. diff --git a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/alert-notification-v1beta3.fields.txt b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/alert-notification-v1beta3.fields.txt index d77f4a99..6673ce4b 100644 --- a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/alert-notification-v1beta3.fields.txt +++ b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/alert-notification-v1beta3.fields.txt @@ -1,5 +1,5 @@ -# schema source: Flux v2.9.4 https://github.com/fluxcd/flux2 -apiVersion enum=notification.toolkit.fluxcd.io/v1beta3 +# schema source: Flux v2.10.0 https://github.com/fluxcd/flux2 +apiVersion enum=notification.toolkit.fluxcd.io/v1beta3 (deprecated) # v1beta3 Alert is deprecated, upgrade to v1 kind enum=Alert metadata.name (required) metadata.namespace (required) diff --git a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/artifactgenerator-source-v1beta1.fields.txt b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/artifactgenerator-source-v1beta1.fields.txt index 06c4ee4f..31b74c31 100644 --- a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/artifactgenerator-source-v1beta1.fields.txt +++ b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/artifactgenerator-source-v1beta1.fields.txt @@ -1,4 +1,4 @@ -# schema source: Flux v2.9.4 https://github.com/fluxcd/flux2 +# schema source: Flux v2.10.0 https://github.com/fluxcd/flux2 apiVersion enum=source.extensions.fluxcd.io/v1beta1 kind enum=ArtifactGenerator metadata.name (required) @@ -8,15 +8,32 @@ spec.artifacts <[]object> (required) min=1 max=1000 # OutputArtifacts is a list spec.artifacts[].copy <[]object> (required) min=1 # Copy defines a list of copy operations to perform from the sources to the generated artifact. The copy operations are performed in the order they are listed with existing files being overwritten by later copy operations. spec.artifacts[].copy[].exclude <[]string> max=100 # Exclude specifies a list of glob patterns to exclude files and dirs matched by the 'From' field. Patterns are matched against paths relative to the source alias root or to the non-glob prefix of 'From'. Patterns without a separator (e.g. "*.md") match the file name at any depth. spec.artifacts[].copy[].from (required) pattern="^@([a-z0-9]([a-z0-9_-]*[a-z0-9])?)/(.*)$" min=1 max=1024 # From specifies the source (by alias) and the glob pattern to match files. The format is "@/". When pathPattern is set, the path may use capture placeholders such as "{app}". +spec.artifacts[].copy[].optional # Optional, when set to true, allows the copy operation to silently skip when the source path or glob pattern matches no files. When false (default), the reconciliation fails with an error if no files are matched. spec.artifacts[].copy[].strategy enum=Overwrite|Merge|Extract # Strategy specifies the copy strategy to use. 'Overwrite' will overwrite existing files in the destination. 'Merge' is for merging YAML files using Helm values merge strategy. 'Extract' is for extracting the contents of tarball archives (.tar.gz, .tgz) When using glob patterns, non-tarball files are silently skipped. For single file sources, the file must be a tarball or an error is returned. Directories are not supported. If not specified, defaults to 'Overwrite'. spec.artifacts[].copy[].to (required) pattern="^@artifact/([^/]{0,1}|[^./][^/]|[.][^./]|[^/]{3,})(/([^/]{0,1}|[^./][^/]|[.][^./]|[^/]{3,}))*$" min=1 max=1024 # To specifies the destination path within the artifact. The format is "@artifact/path", the alias "artifact" refers to the root path of the generated artifact. When pathPattern is set, the path may use capture placeholders such as "{app}". -spec.artifacts[].name (required) min=1 max=253 # Name is the name of the generated artifact. When pathPattern is set, this field may use capture placeholders such as "{app}". +spec.artifacts[].inputsFrom pattern="^@([a-z0-9]([a-z0-9_-]*[a-z0-9])?)/(.*)$" min=1 max=1024 # InputsFrom specifies a source path to a YAML file whose contents are exported in the ExternalArtifact .status.exportedInputs field. The format is "@/", where references a source or "artifact" for the generated artifact itself. When pathPattern is set, the path may use capture placeholders such as "{module}". +spec.artifacts[].name (required) max=1024 # Name is the name of the generated artifact. When pathPattern is set, this field may use capture placeholders such as "{app}". The maximum length accommodates capture placeholders; the effective limits are enforced by the CEL validation when pathPattern is not set. +spec.artifacts[].namespace max=1024 # Namespace is the namespace of the generated artifact. If not provided, defaults to the same namespace as the ArtifactGenerator. When pathPattern is set, this field may use capture placeholders such as "{app}". The credentials used to reconcile the artifact are described in .spec.serviceAccountName: an explicit ServiceAccount applies to every generated artifact, while the --default-service-account flag only applies to artifacts in a namespace other than the ArtifactGenerator namespace. The maximum length accommodates capture placeholders; the effective limits are enforced by the CEL validation when pathPattern is not set. spec.artifacts[].originRevision pattern="^@([a-z0-9]([a-z0-9_-]*[a-z0-9])?)$" max=64 # OriginRevision is used to set the 'org.opencontainers.image.revision' annotation on the generated artifact metadata. If specified, it must point to an existing source alias in the format "@". If the referenced source has an origin revision (e.g. a Git commit SHA), it will be used to set the annotation on the generated artifact. If the referenced source does not have an origin revision, the field is ignored. spec.artifacts[].revision pattern="^@([a-z0-9]([a-z0-9_-]*[a-z0-9])?)$" max=64 # Revision is the revision of the generated artifact. If specified, it must point to an existing source alias in the format "@". If not specified, the revision is automatically set to the digest of the artifact content. spec.commonMetadata # CommonMetadata specifies the common labels and annotations that are applied to all resources. Any existing label or annotation will be overridden if its key matches a common one. spec.commonMetadata.annotations # Annotations to be added to the object's metadata. spec.commonMetadata.labels # Labels to be added to the object's metadata. +spec.managedNamespaces # ManagedNamespaces defines how the controller manages the namespaces targeted by the generated artifacts. When omitted, the target namespaces are unmanaged: they must already exist and are left untouched. +spec.managedNamespaces.allowedNames <[]string> (required) min=1 # AllowedNames is a list of CEL expressions that define the set of namespaces the ArtifactGenerator agrees to manage. Each expression receives the namespace name through the 'ns' string variable and must return a boolean. A namespace is managed only when at least one expression returns true. The 'default', 'kube-system', 'kube-public' and 'flux-system' namespaces are always rejected, regardless of the expressions. +spec.managedNamespaces.metadata # Metadata defines how the metadata of the desired namespaces is built, on top of .spec.commonMetadata. +spec.managedNamespaces.metadata.from <[]object> # From is a list of metadata operations applied in order to the desired namespaces, on top of .spec.commonMetadata and .fromSource. +spec.managedNamespaces.metadata.from[].annotations # Annotations to be applied to the namespace. +spec.managedNamespaces.metadata.from[].labels # Labels to be applied to the namespace. +spec.managedNamespaces.metadata.from[].namespace (required) pattern="^(\\*|[a-z0-9]([-a-z0-9]*[a-z0-9])?)$" max=63 # Namespace is the name of the desired namespace the metadata applies to, or '*' to apply the metadata to all desired namespaces. +spec.managedNamespaces.metadata.from[].strategy (required) enum=Reset|Override|Merge # Strategy specifies how the labels and annotations are applied. 'Reset' clears all the existing labels and annotations before applying the ones defined in the operation (fields that are not set clear the corresponding metadata), 'Override' merges the ones defined in the operation into the existing values, overriding existing keys, while 'Merge' merges only the absent keys, preserving existing values. +spec.managedNamespaces.metadata.fromSource # FromSource sources namespace metadata from a NamespaceMetadata file inside a source artifact. +spec.managedNamespaces.metadata.fromSource.allowedAnnotations # AllowedAnnotations is a schema for the annotations that the NamespaceMetadata file is allowed to set. Each key is an annotation key and each value is a CEL expression that receives the annotation value through the 'value' string variable and must return a boolean. Annotations whose key is not present in this map are ignored, while annotations whose value does not satisfy the respective expression are rejected. The expressions are compiled, so a malformed expression or one that does not return a boolean fails validation at the start of the reconciliation. +spec.managedNamespaces.metadata.fromSource.allowedLabels # AllowedLabels is a schema for the labels that the NamespaceMetadata file is allowed to set. Each key is a label key and each value is a CEL expression that receives the label value through the 'value' string variable and must return a boolean. Labels whose key is not present in this map are ignored, while labels whose value does not satisfy the respective expression are rejected. The expressions are compiled, so a malformed expression or one that does not return a boolean fails validation at the start of the reconciliation. +spec.managedNamespaces.metadata.fromSource.path (required) pattern="^@([a-z0-9]([a-z0-9_-]*[a-z0-9])?)/(.*)$" min=1 max=1024 # Path is the path to the NamespaceMetadata file inside a source artifact, in the format "@/". When pathPattern is set, the path may use capture placeholders such as "{namespace}". Only namespace-level captures are allowed, so that every artifact targeting a namespace resolves to the same file. +spec.managedNamespaces.prune (required) # Prune specifies whether the controller deletes managed namespaces that are no longer targeted by any generated artifact, or when the ArtifactGenerator is deleted. spec.pathPattern pattern="^@([a-z0-9]([a-z0-9_-]*[a-z0-9])?)/(.*)$" max=1024 # PathPattern specifies a directory traversal pattern to match within the sources. The format is "@/". Named captures in the pattern (e.g. "{app}") can be used as placeholders in OutputArtifacts fields. +spec.serviceAccountName pattern="^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" min=1 max=63 # ServiceAccountName is the name of the ServiceAccount used to authorize the reconciliation of the generated ExternalArtifacts and the managed Namespaces. The name is resolved in the ArtifactGenerator namespace. When specified, the controller checks this ServiceAccount with SubjectAccessReview for every namespace targeted by the generated ExternalArtifacts, including the ArtifactGenerator namespace, and its RBAC bindings determine the namespaces in which they can be created, updated and deleted. When not specified, the controller uses its own credentials for ExternalArtifacts in the ArtifactGenerator namespace, and the ServiceAccount configured with the --default-service-account flag (when set) for artifacts targeting another namespace. Namespace management (.spec.managedNamespaces) always requires a ServiceAccount for authorization, so either this field or the --default-service-account flag must be set; otherwise the reconciliation fails with a terminal error. The controller performs the namespace operations with its own credentials. spec.sources <[]object> (required) min=1 max=1000 # Sources is a list of references to the Flux source-controller resources that will be used to generate the artifact. spec.sources[].alias (required) pattern="^[a-z0-9]([a-z0-9_-]*[a-z0-9])?$" max=63 # Alias of the source within the ArtifactGenerator context. The alias must be unique per ArtifactGenerator, and must consist of lower case alphanumeric characters, underscores, and hyphens. It must start and end with an alphanumeric character. spec.sources[].kind (required) enum=Bucket|GitRepository|OCIRepository|HelmChart|ExternalArtifact # Kind of the source. @@ -30,10 +47,11 @@ status.conditions[].observedGeneration format=int64 min=0 # observedGe status.conditions[].reason (required) pattern="^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$" min=1 max=1024 # reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty. status.conditions[].status (required) enum=True|False|Unknown # status of the condition, one of True, False, Unknown. status.conditions[].type (required) pattern="^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$" max=316 # type of condition in CamelCase or in foo.example.com/CamelCase. -status.inventory <[]object> # Inventory contains the list of generated ExternalArtifact references. -status.inventory[].digest (required) # Digest of the referent artifact. -status.inventory[].filename (required) # Filename is the name of the artifact file. -status.inventory[].name (required) # Name of the referent artifact. -status.inventory[].namespace (required) # Namespace of the referent artifact. +status.inventory <[]object> # Inventory contains the list of objects managed by the ArtifactGenerator, such as the generated ExternalArtifacts and the managed Namespaces. +status.inventory[].digest (required) # Digest of the referent object. For generated artifacts this is the artifact content digest; for managed namespaces this is a digest of the metadata applied by the controller. +status.inventory[].filename # Filename is the name of the artifact file. +status.inventory[].kind enum=ExternalArtifact|Namespace # Kind is the kind of the referent object. +status.inventory[].name (required) # Name of the referent object. +status.inventory[].namespace # Namespace of the referent object. Empty for cluster-scoped objects. status.lastHandledReconcileAt # LastHandledReconcileAt holds the value of the most recent reconcile request value, so a change of the annotation value can be detected. status.observedSourcesDigest # ObservedSourcesDigest is a hash representing the current state of all the sources referenced by the ArtifactGenerator. diff --git a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/bucket-source-v1.fields.txt b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/bucket-source-v1.fields.txt index 5ee36407..429e7e9f 100644 --- a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/bucket-source-v1.fields.txt +++ b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/bucket-source-v1.fields.txt @@ -1,4 +1,4 @@ -# schema source: Flux v2.9.4 https://github.com/fluxcd/flux2 +# schema source: Flux v2.10.0 https://github.com/fluxcd/flux2 apiVersion enum=source.toolkit.fluxcd.io/v1 kind enum=Bucket metadata.name (required) @@ -18,7 +18,7 @@ spec.proxySecretRef.name (required) # Name of the referent. spec.region # Region of the Endpoint where the BucketName is located in. spec.secretRef # SecretRef specifies the Secret containing authentication credentials for the Bucket. spec.secretRef.name (required) # Name of the referent. -spec.serviceAccountName # ServiceAccountName is the name of the Kubernetes ServiceAccount used to authenticate the bucket. This field is only supported for the 'gcp' and 'aws' providers. For more information about workload identity: https://fluxcd.io/flux/components/source/buckets/#workload-identity +spec.serviceAccountName # ServiceAccountName is the name of the Kubernetes ServiceAccount used to authenticate the bucket. This field is only supported for the 'gcp' and 'aws' providers. For more information about object identity: https://fluxcd.io/flux/integrations/object-identity/ spec.sts # STS specifies the required configuration to use a Security Token Service for fetching temporary credentials to authenticate in a Bucket provider. This field is only supported for the `aws` and `generic` providers. spec.sts.certSecretRef # CertSecretRef can be given the name of a Secret containing either or both of - a PEM-encoded client certificate (`tls.crt`) and private key (`tls.key`); - a PEM-encoded CA certificate (`ca.crt`) and whichever are supplied, will be used for connecting to the STS endpoint. The client cert and key are useful if you are authenticating with a certificate; the CA cert is useful if you are using a self-signed server certificate. The Secret must be of type `Opaque` or `kubernetes.io/tls`. This field is only supported for the `ldap` provider. spec.sts.certSecretRef.name (required) # Name of the referent. diff --git a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/externalartifact-source-v1.fields.txt b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/externalartifact-source-v1.fields.txt index 6eee8a4a..3a791085 100644 --- a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/externalartifact-source-v1.fields.txt +++ b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/externalartifact-source-v1.fields.txt @@ -1,4 +1,4 @@ -# schema source: Flux v2.9.4 https://github.com/fluxcd/flux2 +# schema source: Flux v2.10.0 https://github.com/fluxcd/flux2 apiVersion enum=source.toolkit.fluxcd.io/v1 kind enum=ExternalArtifact metadata.name (required) @@ -25,3 +25,4 @@ status.conditions[].observedGeneration format=int64 min=0 # observedGe status.conditions[].reason (required) pattern="^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$" min=1 max=1024 # reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty. status.conditions[].status (required) enum=True|False|Unknown # status of the condition, one of True, False, Unknown. status.conditions[].type (required) pattern="^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$" max=316 # type of condition in CamelCase or in foo.example.com/CamelCase. +status.exportedInputs # ExportedInputs holds a map of structured data optionally extracted from the source resource. It may be used, for example, by downstream consumers such as templating engines like ResourceSet to consume these inputs for implementing templating logic. diff --git a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/fluxinstance-fluxcd-v1.fields.txt b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/fluxinstance-fluxcd-v1.fields.txt index bbb35b72..abedae5b 100644 --- a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/fluxinstance-fluxcd-v1.fields.txt +++ b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/fluxinstance-fluxcd-v1.fields.txt @@ -1,4 +1,4 @@ -# schema source: Flux Operator v0.58.1 https://github.com/controlplaneio-fluxcd/flux-operator +# schema source: Flux Operator v0.62.0 https://github.com/controlplaneio-fluxcd/flux-operator apiVersion enum=fluxcd.controlplane.io/v1 kind enum=FluxInstance metadata.name (required) @@ -7,13 +7,15 @@ spec # FluxInstanceSpec defines the desired state of FluxInstance spec.cluster # Cluster holds the specification of the Kubernetes cluster. spec.cluster.domain default="cluster.local" # Domain is the cluster domain used for generating the FQDN of services. Defaults to 'cluster.local'. spec.cluster.multitenant default=false # Multitenant enables the multitenancy lockdown. Defaults to false. -spec.cluster.multitenantWorkloadIdentity default=false # MultitenantWorkloadIdentity enables the multitenancy lockdown for workload identity. Defaults to false. +spec.cluster.multitenantObjectIdentity default=false # MultitenantObjectIdentity enables the multitenancy lockdown for object identity. Defaults to false. +spec.cluster.multitenantWorkloadIdentity default=false # MultitenantWorkloadIdentity is now legacy. Legacy: Use MultitenantObjectIdentity instead. spec.cluster.networkPolicy default=true # NetworkPolicy restricts network access to the current namespace. Defaults to true. -spec.cluster.objectLevelWorkloadIdentity # ObjectLevelWorkloadIdentity enables the feature gate required for object-level workload identity. This feature is only available in Flux v2.6.0 and later. +spec.cluster.objectIdentityRBAC # ObjectIdentityRBAC configures the RBAC required for object identity using Kubernetes service account tokens. Object identity is the new name of the upstream Flux object-level workload identity feature. In Flux v2.6.0 to v2.9.x this enables the ObjectLevelWorkloadIdentity feature gate and leaves the RBAC for creating service account tokens in place. When disabled, the operator removes that RBAC from the Flux controllers' ClusterRole. Starting with Flux v2.10.0, the ObjectLevelWorkloadIdentity feature gate is retired and no longer changes behavior, so the operator no longer passes it to the controllers. Starting with Flux v2.10.0, the RBAC for creating service account tokens is removed from the Flux distribution, and this field controls whether the operator adds it. This feature is only available in Flux v2.6.0 and later. +spec.cluster.objectLevelWorkloadIdentity # ObjectLevelWorkloadIdentity is now legacy. Legacy: Use ObjectIdentityRBAC instead. spec.cluster.size enum=small|medium|large # Size defines the vertical scaling profile of the Flux controllers. The size is used to determine the concurrency and CPU/Memory limits for the Flux controllers. Accepted values are: 'small', 'medium' and 'large'. -spec.cluster.tenantDefaultDecryptionServiceAccount # TenantDefaultDecryptionServiceAccount is the name of the service account to use as default for kustomize-controller SOPS decryption when the multitenant lockdown for workload identity is enabled. Defaults to the 'default' service account from the tenant namespace. -spec.cluster.tenantDefaultKubeConfigServiceAccount # TenantDefaultKubeConfigServiceAccount is the name of the service account to use as default for kustomize-controller and helm-controller remote cluster access via spec.kubeConfig.configMapRef when the multitenant lockdown for workload identity is enabled. Defaults to the 'default' service account from the tenant namespace. -spec.cluster.tenantDefaultServiceAccount # TenantDefaultServiceAccount is the name of the service account to use as default when the multitenant lockdown is enabled, for kustomize-controller and helm-controller. This field will also be used for multitenant workload identity lockdown for source-controller, notification-controller, image-reflector-controller and image-automation-controller. Defaults to the 'default' service account from the tenant namespace. +spec.cluster.tenantDefaultDecryptionServiceAccount # TenantDefaultDecryptionServiceAccount is the name of the service account to use as default for kustomize-controller SOPS decryption when the multitenant lockdown for object identity is enabled. Defaults to the 'default' service account from the tenant namespace. +spec.cluster.tenantDefaultKubeConfigServiceAccount # TenantDefaultKubeConfigServiceAccount is the name of the service account to use as default for kustomize-controller and helm-controller remote cluster access via spec.kubeConfig.configMapRef when the multitenant lockdown for object identity is enabled. Defaults to the 'default' service account from the tenant namespace. +spec.cluster.tenantDefaultServiceAccount # TenantDefaultServiceAccount is the name of the service account to use as default when the multitenant lockdown is enabled, for kustomize-controller and helm-controller. This field will also be used for multitenant object identity lockdown for source-controller, notification-controller, image-reflector-controller and image-automation-controller. Defaults to the 'default' service account from the tenant namespace. spec.cluster.type enum=kubernetes|openshift|aws|azure|gcp default="kubernetes" # Type specifies the distro of the Kubernetes cluster. Defaults to 'kubernetes'. spec.commonMetadata # CommonMetadata specifies the common labels and annotations that are applied to all resources. Any existing label or annotation will be overridden if its key matches a common one. spec.commonMetadata.annotations # Annotations to be added to the object's metadata. @@ -42,6 +44,20 @@ spec.sharding # Sharding holds the specification of the sharding config spec.sharding.key default="sharding.fluxcd.io/key" # Key is the label key used to shard the resources. spec.sharding.shards <[]string> (required) min=1 # Shards is the list of shard names. spec.sharding.storage enum=ephemeral|persistent # Storage defines if the source-controller shards should use an emptyDir or a persistent volume claim for storage. Accepted values are 'ephemeral' or 'persistent', defaults to 'ephemeral'. When set to 'persistent', the '.spec.storage' field must be set. +spec.spiffe # SPIFFE holds the configuration for the SPIFFE integration. When set, the operator configures the Flux controllers to use the SPIFFE Workload API and optionally enables object identity and mTLS between the controllers. The flux-operator pod must also be configured with the same Workload API and, when used, Broker API settings, but does not need the inter-controller flags. +spec.spiffe.brokerAPI # BrokerAPI holds the configuration for the SPIFFE Broker API. When set, enables the object-level SPIFFE features. +spec.spiffe.brokerAPI.endpoint (required) pattern="^[!-~]+$" min=1 max=1024 # Endpoint is the address of the SPIFFE Broker API endpoint, e.g. 'dns:///spiffe-broker.example.com:443'. The flux-operator pod accepts the same --spiffe-broker-endpoint flag as the Flux controllers. For OLM installations, the endpoint can be set with the SPIFFE_BROKER_ENDPOINT environment variable. +spec.spiffe.brokerAPI.ids <[]string> (required) min=1 max=64 # IDs is the list of SPIFFE IDs or SPIFFE ID prefixes authorized for the SPIFFE Broker API endpoint. SPIFFE IDs ending with a slash are treated as prefixes. The flux-operator pod accepts the same repeatable --spiffe-broker-id flag as the Flux controllers. For OLM installations, the IDs can be set with the SPIFFE_BROKER_IDS environment variable as a comma-separated list. +spec.spiffe.mtls # MTLS holds the configuration for mTLS between the Flux controllers. The flux-operator reads the controller SPIFFE IDs from .status.spiffe. +spec.spiffe.mtls.componentIDTemplate (required) pattern="^spiffe://[a-z0-9._-]{1,255}(?:/(?:[a-zA-Z0-9_-]|[.][a-zA-Z0-9_-]|[{]component[}])[a-zA-Z0-9._-]*(?:[{]component[}][a-zA-Z0-9._-]*)*)+(?:/)?$" max=2048 # ComponentIDTemplate is the SPIFFE ID template for the Flux controllers. The '{component}' placeholder is replaced with the name of each installed component. A trailing slash indicates a SPIFFE ID prefix. The flux-operator ID is the SPIFFE ID of the operator's X.509-SVID, or this template with 'flux-operator' when the operator has no Workload API source. The flux-operator ID is always added to notification-controller as an authorized notifier, and to source-controller and source-watcher as an authorized artifact client for the Web UI artifact downloads. For a standalone Web UI, use ExtraArtifactClients and ExtraNotifiers. +spec.spiffe.mtls.enabled (required) # Enabled enables mTLS between the Flux controllers. +spec.spiffe.mtls.extraArtifactClients <[]string> max=64 # ExtraArtifactClients is a list of additional SPIFFE IDs added to source-controller and source-watcher as authorized artifact clients, e.g. the standalone Web UI or the Flux MCP Server. +spec.spiffe.mtls.extraArtifactServers <[]string> max=64 # ExtraArtifactServers is a list of additional SPIFFE IDs added to kustomize-controller, helm-controller and source-watcher as authorized artifact servers, e.g. an external source controller. +spec.spiffe.mtls.extraNotifiers <[]string> max=64 # ExtraNotifiers is a list of additional SPIFFE IDs added to notification-controller as authorized notifiers, e.g. the standalone Web UI or the Flux MCP Server. +spec.spiffe.mtls.receivers <[]string> max=64 # Receivers is the list of SPIFFE IDs of external Ingress or Gateway controllers authorized to send webhook requests to notification-controller. Setting at least one ID makes the receiver accept only SPIFFE mTLS clients. +spec.spiffe.workloadAPI (required) # WorkloadAPI holds the configuration for the SPIFFE Workload API. It is required for enabling any of the SPIFFE features and is used to render the go-spiffe environment variable and the SPIFFE CSI volume. +spec.spiffe.workloadAPI.csiDriver pattern="^[a-zA-Z0-9](?:[-a-zA-Z0-9]*[a-zA-Z0-9])?(?:\\.[a-zA-Z0-9](?:[-a-zA-Z0-9]*[a-zA-Z0-9])?)*$" min=1 max=63 # CSIDriver is the name of the SPIFFE CSI driver used to mount the Workload API socket into the Flux controller pods. When set, the operator mounts the CSI volume at /spiffe-workload-api and the endpoint must be a unix socket under that path. When omitted, no CSI volume is configured. +spec.spiffe.workloadAPI.endpoint (required) pattern="^(?:unix:(?:///[!$&->@-~]+|/[!$&-.0->@-~][!$&->@-~]*)|tcp://(?:[0-9]{1,3}(?:\\.[0-9]{1,3}){3}|\\[[0-9a-fA-F:.]+\\]):[0-9]{1,5})$" min=1 max=1024 # Endpoint is the address of the SPIFFE Workload API endpoint, in the form 'unix:///', 'unix:/' or 'tcp://:', e.g. 'unix:///spiffe-workload-api/agent.sock'. The flux-operator pod must be configured with the same endpoint through the SPIFFE_ENDPOINT_SOCKET environment variable. spec.storage # Storage holds the specification of the source-controller persistent volume claim. spec.storage.class (required) # Class is the storage class to use for the PVC. spec.storage.size (required) # Size is the size of the PVC. @@ -85,3 +101,8 @@ status.lastArtifactRevision # LastArtifactRevision is the digest of the status.lastAttemptedRevision # LastAttemptedRevision is the version and digest of the distribution config that was last attempted to reconcile. status.lastHandledForceAt # LastHandledForceAt holds the value of the most recent force request value, so a change of the annotation value can be detected. status.lastHandledReconcileAt # LastHandledReconcileAt holds the value of the most recent reconcile request value, so a change of the annotation value can be detected. +status.spiffe # SPIFFE holds the SPIFFE settings of the last applied distribution. +status.spiffe.mtls # MTLS holds the applied mTLS settings. +status.spiffe.mtls.componentIDTemplate # ComponentIDTemplate is the SPIFFE ID template of the Flux controllers. +status.spiffe.mtls.enabled (required) # Enabled is true when the Flux controllers were deployed with mTLS. +status.spiffe.mtls.extraArtifactServers <[]string> # ExtraArtifactServers is the list of additional SPIFFE IDs authorized as artifact servers. diff --git a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/fluxreport-fluxcd-v1.fields.txt b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/fluxreport-fluxcd-v1.fields.txt index 02e2afb1..71d1348c 100644 --- a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/fluxreport-fluxcd-v1.fields.txt +++ b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/fluxreport-fluxcd-v1.fields.txt @@ -1,4 +1,4 @@ -# schema source: Flux Operator v0.58.1 https://github.com/controlplaneio-fluxcd/flux-operator +# schema source: Flux Operator v0.62.0 https://github.com/controlplaneio-fluxcd/flux-operator apiVersion enum=fluxcd.controlplane.io/v1 kind enum=FluxReport metadata.name (required) diff --git a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/gitrepository-source-v1.fields.txt b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/gitrepository-source-v1.fields.txt index 6258cfba..0ac953da 100644 --- a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/gitrepository-source-v1.fields.txt +++ b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/gitrepository-source-v1.fields.txt @@ -1,4 +1,4 @@ -# schema source: Flux v2.9.4 https://github.com/fluxcd/flux2 +# schema source: Flux v2.10.0 https://github.com/fluxcd/flux2 apiVersion enum=source.toolkit.fluxcd.io/v1 kind enum=GitRepository metadata.name (required) @@ -66,4 +66,5 @@ status.observedInclude[].repository.name (required) # Name of the refer status.observedInclude[].toPath # ToPath specifies the path to copy contents to, defaults to the name of the GitRepositoryRef. status.observedRecurseSubmodules # ObservedRecurseSubmodules is the observed resource submodules configuration used to produce the current Artifact. status.observedSparseCheckout <[]string> # ObservedSparseCheckout is the observed list of directories used to produce the current Artifact. +status.sourceVerificationFingerprint # SourceVerificationFingerprint is the fingerprint of the public keys used to verify the signature of the Git object(s) for the current Artifact. It is used to detect changes to the verification policy, such as a key rotation, that require the current revision to be verified again. status.sourceVerificationMode # SourceVerificationMode is the last used verification mode indicating which Git object(s) have been verified. diff --git a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/helmchart-source-v1.fields.txt b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/helmchart-source-v1.fields.txt index 3996a994..3af821db 100644 --- a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/helmchart-source-v1.fields.txt +++ b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/helmchart-source-v1.fields.txt @@ -1,4 +1,4 @@ -# schema source: Flux v2.9.4 https://github.com/fluxcd/flux2 +# schema source: Flux v2.10.0 https://github.com/fluxcd/flux2 apiVersion enum=source.toolkit.fluxcd.io/v1 kind enum=HelmChart metadata.name (required) diff --git a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/helmrelease-helm-v2.fields.txt b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/helmrelease-helm-v2.fields.txt index dc5a6ccf..e22f151f 100644 --- a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/helmrelease-helm-v2.fields.txt +++ b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/helmrelease-helm-v2.fields.txt @@ -1,29 +1,56 @@ -# schema source: Flux v2.9.4 https://github.com/fluxcd/flux2 +# schema source: Flux v2.10.0 https://github.com/fluxcd/flux2 apiVersion enum=helm.toolkit.fluxcd.io/v2 kind enum=HelmRelease metadata.name (required) metadata.namespace (required) spec # HelmReleaseSpec defines the desired state of a Helm release. -spec.chart # Chart defines the template of the v1.HelmChart that should be created for this HelmRelease. +spec.chart # Chart defines the template of the source object that should be created for this HelmRelease. The Kind field determines whether a sourcev1.HelmChart or sourcev1.OCIRepository is created. +spec.chart.kind enum=HelmChart|OCIRepository # Kind is the kind of the source object generated from this template. Valid values: - HelmChart (default): generates a source.toolkit.fluxcd.io/v1 HelmChart from the HelmChartSpec-compatible fields under .spec.chart.spec. In particular, .spec.chart.spec.chart and .spec.chart.spec.sourceRef are required. - OCIRepository: generates a source.toolkit.fluxcd.io/v1 OCIRepository from the OCIRepositorySpec fields under .spec.chart.spec. In particular, .spec.chart.spec.url is required, and .spec.chart.spec.interval defaults to .spec.interval (interval is required in a plain OCIRepository). Use OCIRepository for charts hosted in OCI registries; use HelmChart for HelmRepository, GitRepository or Bucket sources. spec.chart.metadata # ObjectMeta holds the template for metadata like labels and annotations. spec.chart.metadata.annotations # Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. They are not queryable and should be preserved when modifying objects. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/ spec.chart.metadata.labels # Map of string keys and values that can be used to organize and categorize (scope and select) objects. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/ -spec.chart.spec (required) # Spec holds the template for the v1.HelmChartSpec for this HelmRelease. -spec.chart.spec.chart (required) min=1 max=2048 # The name or path the Helm chart is available at in the SourceRef. +spec.chart.spec (required) # Spec holds the spec of the object generated for this HelmRelease. +spec.chart.spec.certSecretRef # CertSecretRef can be given the name of a Secret containing either or both of - a PEM-encoded client certificate (`tls.crt`) and private key (`tls.key`); - a PEM-encoded CA certificate (`ca.crt`) and whichever are supplied, will be used for connecting to the registry. The client cert and key are useful if you are authenticating with a certificate; the CA cert is useful if you are using a self-signed server certificate. The Secret must be of type `Opaque` or `kubernetes.io/tls`. +spec.chart.spec.certSecretRef.name (required) # Name of the referent. +spec.chart.spec.chart min=1 max=2048 # The name or path the Helm chart is available at in the SourceRef. +spec.chart.spec.ignore # Ignore overrides the set of excluded patterns in the .sourceignore format (which is the same as .gitignore). If not provided, a default will be used, consult the documentation for your version to find out what those are. spec.chart.spec.ignoreMissingValuesFiles # IgnoreMissingValuesFiles controls whether to silently ignore missing values files rather than failing. -spec.chart.spec.interval pattern="^([0-9]+(\\.[0-9]+)?(ms|s|m|h))+$" # Interval at which to check the v1.Source for updates. Defaults to 'HelmReleaseSpec.Interval'. -spec.chart.spec.reconcileStrategy enum=ChartVersion|Revision default="ChartVersion" # Determines what enables the creation of a new artifact. Valid values are ('ChartVersion', 'Revision'). See the documentation of the values for an explanation on their behavior. Defaults to ChartVersion when omitted. -spec.chart.spec.sourceRef (required) # The name and namespace of the v1.Source the chart is available at. +spec.chart.spec.insecure # Insecure allows connecting to a non-TLS HTTP container registry. +spec.chart.spec.interval pattern="^([0-9]+(\\.[0-9]+)?(ms|s|m|h))+$" # Interval at which the OCIRepository URL is checked for updates. This interval is approximate and may be subject to jitter to ensure efficient use of resources. +spec.chart.spec.layerSelector # LayerSelector specifies which layer should be extracted from the OCI artifact. When not specified, the first layer found in the artifact is selected. +spec.chart.spec.layerSelector.mediaType # MediaType specifies the OCI media type of the layer which should be extracted from the OCI Artifact. The first layer matching this type is selected. +spec.chart.spec.layerSelector.operation enum=extract|copy # Operation specifies how the selected layer should be processed. By default, the layer compressed content is extracted to storage. When the operation is set to 'copy', the layer compressed content is persisted to storage as it is. +spec.chart.spec.provider enum=generic|aws|azure|gcp # The provider used for authentication, can be 'aws', 'azure', 'gcp' or 'generic'. When not specified, defaults to 'generic'. +spec.chart.spec.proxySecretRef # ProxySecretRef specifies the Secret containing the proxy configuration to use while communicating with the container registry. +spec.chart.spec.proxySecretRef.name (required) # Name of the referent. +spec.chart.spec.reconcileStrategy enum=ChartVersion|Revision # Determines what enables the creation of a new artifact. Valid values are ('ChartVersion', 'Revision'). See the documentation of the values for an explanation on their behavior. Defaults to ChartVersion when omitted. +spec.chart.spec.ref # The OCI reference to pull and monitor for changes, defaults to the latest tag. +spec.chart.spec.ref.digest # Digest is the image digest to pull, takes precedence over SemVer. The value should be in the format 'sha256:'. +spec.chart.spec.ref.semver # SemVer is the range of tags to pull selecting the latest within the range, takes precedence over Tag. +spec.chart.spec.ref.semverFilter # SemverFilter is a regex pattern to filter the tags within the SemVer range. +spec.chart.spec.ref.tag # Tag is the image tag to pull, defaults to latest. +spec.chart.spec.secretRef # SecretRef contains the secret name containing the registry login credentials to resolve image metadata. The secret must be of type kubernetes.io/dockerconfigjson. +spec.chart.spec.secretRef.name (required) # Name of the referent. +spec.chart.spec.serviceAccountName # ServiceAccountName is the name of the Kubernetes ServiceAccount used to authenticate the image pull, either with the pull secrets attached to the service account or with an object identity. For more information about object identity: https://fluxcd.io/flux/integrations/object-identity/ For more information about image pull secrets: https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#add-imagepullsecrets-to-a-service-account +spec.chart.spec.sourceRef # The name and namespace of the v1.Source the chart is available at. spec.chart.spec.sourceRef.apiVersion # APIVersion of the referent. spec.chart.spec.sourceRef.kind (required) enum=HelmRepository|GitRepository|Bucket # Kind of the referent. spec.chart.spec.sourceRef.name (required) min=1 max=253 # Name of the referent. spec.chart.spec.sourceRef.namespace min=1 max=63 # Namespace of the referent. +spec.chart.spec.suspend # This flag tells the controller to suspend the reconciliation of this source. +spec.chart.spec.timeout pattern="^([0-9]+(\\.[0-9]+)?(ms|s|m))+$" # The timeout for remote OCI Repository operations like pulling, defaults to 60s. +spec.chart.spec.url pattern="^oci://.*$" # URL is a reference to an OCI artifact repository hosted on a remote container registry. spec.chart.spec.valuesFiles <[]string> # Alternative list of values files to use as the chart values (values.yaml is not included by default), expected to be a relative path in the SourceRef. Values files are merged in the order of this list with the last file overriding the first. Ignored when omitted. -spec.chart.spec.verify # Verify contains the secret name containing the trusted public keys used to verify the signature and specifies which provider to use to check whether OCI image is authentic. This field is only supported for OCI sources. Chart dependencies, which are not bundled in the umbrella chart artifact, are not verified. -spec.chart.spec.verify.provider (required) enum=cosign|notation default="cosign" # Provider specifies the technology used to sign the OCI Helm chart. +spec.chart.spec.verify # Verify contains the secret name containing the trusted public keys used to verify the signature and specifies which provider to use to check whether OCI image is authentic. +spec.chart.spec.verify.matchOIDCIdentity <[]object> # MatchOIDCIdentity specifies the identity matching criteria to use while verifying an OCI artifact which was signed using Cosign keyless signing. The artifact's identity is deemed to be verified if any of the specified matchers match against the identity. +spec.chart.spec.verify.matchOIDCIdentity[].issuer (required) # Issuer specifies the regex pattern to match against to verify the OIDC issuer in the Fulcio certificate. The pattern must be a valid Go regular expression. +spec.chart.spec.verify.matchOIDCIdentity[].subject (required) # Subject specifies the regex pattern to match against to verify the identity subject in the Fulcio certificate. The pattern must be a valid Go regular expression. +spec.chart.spec.verify.provider (required) enum=cosign|notation default="cosign" # Provider specifies the technology used to sign the OCI Artifact. spec.chart.spec.verify.secretRef # SecretRef specifies the Kubernetes Secret containing the trusted public keys. spec.chart.spec.verify.secretRef.name (required) # Name of the referent. -spec.chart.spec.version default="*" # Version semver expression, ignored for charts from v1.GitRepository and v1beta2.Bucket sources. Defaults to latest when omitted. +spec.chart.spec.verify.trustedRootSecretRef # TrustedRootSecretRef specifies the Kubernetes Secret containing a Sigstore trusted_root.json file. This enables verification against self-hosted Sigstore infrastructure (custom Fulcio CA, self-hosted Rekor instance). The Secret must contain a key named "trusted_root.json". +spec.chart.spec.verify.trustedRootSecretRef.name (required) # Name of the referent. +spec.chart.spec.version # Version semver expression, ignored for charts from v1.GitRepository and v1beta2.Bucket sources. Defaults to latest when omitted i.e. to '*'. spec.chartRef # ChartRef holds a reference to a source controller resource containing the Helm chart artifact. spec.chartRef.apiVersion # APIVersion of the referent. spec.chartRef.kind (required) enum=OCIRepository|HelmChart|ExternalArtifact # Kind of the referent. @@ -75,8 +102,8 @@ spec.install.strategy.name (required) enum=RemediateOnFailure|RetryOnFa spec.install.strategy.retryInterval pattern="^([0-9]+(\\.[0-9]+)?(ms|s|m|h))+$" # RetryInterval is the interval at which to retry a failed install. Can be used only when Name is set to RetryOnFailure. Defaults to '5m'. spec.install.timeout pattern="^([0-9]+(\\.[0-9]+)?(ms|s|m|h))+$" # Timeout is the time to wait for any individual Kubernetes operation (like Jobs for hooks) during the performance of a Helm install action. Defaults to 'HelmReleaseSpec.Timeout'. spec.interval (required) pattern="^([0-9]+(\\.[0-9]+)?(ms|s|m|h))+$" # Interval at which to reconcile the Helm release. -spec.kubeConfig # KubeConfig for reconciling the HelmRelease on a remote cluster. When used in combination with HelmReleaseSpec.ServiceAccountName, forces the controller to act on behalf of that Service Account at the target cluster. If the --default-service-account flag is set, its value will be used as a controller level fallback for when HelmReleaseSpec.ServiceAccountName is empty. -spec.kubeConfig.configMapRef # ConfigMapRef holds an optional name of a ConfigMap that contains the following keys: - `provider`: the provider to use. One of `aws`, `azure`, `gcp`, or `generic`. Required. - `cluster`: the fully qualified resource name of the Kubernetes cluster in the cloud provider API. Not used by the `generic` provider. Required when one of `address` or `ca.crt` is not set. - `address`: the address of the Kubernetes API server. Required for `generic`. For the other providers, if not specified, the first address in the cluster resource will be used, and if specified, it must match one of the addresses in the cluster resource. If audiences is not set, will be used as the audience for the `generic` provider. - `ca.crt`: the optional PEM-encoded CA certificate for the Kubernetes API server. If not set, the controller will use the CA certificate from the cluster resource. - `audiences`: the optional audiences as a list of line-break-separated strings for the Kubernetes ServiceAccount token. Defaults to the `address` for the `generic` provider, or to specific values for the other providers depending on the provider. - `serviceAccountName`: the optional name of the Kubernetes ServiceAccount in the same namespace that should be used for authentication. If not specified, the controller ServiceAccount will be used. Mutually exclusive with SecretRef. +spec.kubeConfig # KubeConfig for reconciling the HelmRelease on a remote cluster. When used in combination with HelmReleaseSpec.ServiceAccountName, forces the controller to act on behalf of that Service Account at the target cluster. If the --default-service-account flag is set, its value will be used as the default for HelmReleaseSpec.ServiceAccountName when it is empty. +spec.kubeConfig.configMapRef # ConfigMapRef holds an optional name of a ConfigMap that contains the following keys: - `provider`: the provider to use. One of `aws`, `azure`, `gcp`, or `generic`. Required. - `cluster`: the fully qualified resource name of the Kubernetes cluster in the cloud provider API. Not used by the `generic` provider. Required when one of `address` or `ca.crt` is not set. - `address`: the address of the Kubernetes API server. Required for `generic`. For the other providers, if not specified, the first address in the cluster resource will be used, and if specified, it must match one of the addresses in the cluster resource. If audiences is not set, will be used as the audience for the `generic` provider. - `ca.crt`: the optional PEM-encoded CA certificate for the Kubernetes API server. If not set, the controller will use the CA certificate from the cluster resource. - `serviceAccountName`: the optional name of the Kubernetes ServiceAccount in the same namespace that should be used for authentication. If not specified, the controller ServiceAccount will be used. - `audiences`: the optional audiences as a list of string separated by commas and/or whitespaces/newlines for the Kubernetes ServiceAccount token. Defaults to the `address` for the `generic` provider, or to specific values for the other providers depending on the provider. Mutually exclusive with SecretRef. spec.kubeConfig.configMapRef.name (required) # Name of the referent. spec.kubeConfig.secretRef # SecretRef holds an optional name of a secret that contains a key with the kubeconfig file as the value. If no key is set, the key will default to 'value'. Mutually exclusive with ConfigMapRef. It is recommended that the kubeconfig is self-contained, and the secret is regularly updated if credentials such as a cloud-access-token expire. Cloud specific `cmd-path` auth helpers will not function without adding binaries and credentials to the Pod that is responsible for reconciling Kubernetes resources. Supported only for the generic provider. spec.kubeConfig.secretRef.key # Key in the Secret, when not specified an implementation-specific default key is used. @@ -170,7 +197,7 @@ status.conditions[].reason (required) pattern="^[A-Za-z]([A-Za-z0-9_,:] status.conditions[].status (required) enum=True|False|Unknown # status of the condition, one of True, False, Unknown. status.conditions[].type (required) pattern="^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$" max=316 # type of condition in CamelCase or in foo.example.com/CamelCase. status.failures format=int64 # Failures is the reconciliation failure count against the latest desired state. It is reset after a successful reconciliation. -status.helmChart # HelmChart is the namespaced name of the HelmChart resource created by the controller for the HelmRelease. +status.helmChart # HelmChart is the namespaced name of the HelmChart resource created by the controller for the HelmRelease, in the format '/', or the typed and namespaced name of the OCIRepository resource, in the format '//'. status.history <[]object> # History holds the history of Helm releases performed for this HelmRelease up to the last successfully completed release. status.history[].action # Action is the action that resulted in this snapshot being created. status.history[].apiVersion # APIVersion is the API version of the Snapshot. When the calculation method of the Digest field is changed, this field will be used to distinguish between the old and new methods. diff --git a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/helmrepository-source-v1.fields.txt b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/helmrepository-source-v1.fields.txt index 5d226215..2bb7c9c9 100644 --- a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/helmrepository-source-v1.fields.txt +++ b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/helmrepository-source-v1.fields.txt @@ -1,4 +1,4 @@ -# schema source: Flux v2.9.4 https://github.com/fluxcd/flux2 +# schema source: Flux v2.10.0 https://github.com/fluxcd/flux2 apiVersion enum=source.toolkit.fluxcd.io/v1 kind enum=HelmRepository metadata.name (required) diff --git a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/imagepolicy-image-v1.fields.txt b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/imagepolicy-image-v1.fields.txt index 0e3de7db..b95b122f 100644 --- a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/imagepolicy-image-v1.fields.txt +++ b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/imagepolicy-image-v1.fields.txt @@ -1,4 +1,4 @@ -# schema source: Flux v2.9.4 https://github.com/fluxcd/flux2 +# schema source: Flux v2.10.0 https://github.com/fluxcd/flux2 apiVersion enum=image.toolkit.fluxcd.io/v1 kind enum=ImagePolicy metadata.name (required) diff --git a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/imagerepository-image-v1.fields.txt b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/imagerepository-image-v1.fields.txt index 58faf507..3dc106e7 100644 --- a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/imagerepository-image-v1.fields.txt +++ b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/imagerepository-image-v1.fields.txt @@ -1,4 +1,4 @@ -# schema source: Flux v2.9.4 https://github.com/fluxcd/flux2 +# schema source: Flux v2.10.0 https://github.com/fluxcd/flux2 apiVersion enum=image.toolkit.fluxcd.io/v1 kind enum=ImageRepository metadata.name (required) @@ -18,7 +18,7 @@ spec.proxySecretRef # ProxySecretRef specifies the Secret containing th spec.proxySecretRef.name (required) # Name of the referent. spec.secretRef # SecretRef can be given the name of a secret containing credentials to use for the image registry. The secret should be created with `kubectl create secret docker-registry`, or the equivalent. spec.secretRef.name (required) # Name of the referent. -spec.serviceAccountName max=253 # ServiceAccountName is the name of the Kubernetes ServiceAccount used to authenticate the image pull if the service account has attached pull secrets. +spec.serviceAccountName max=253 # ServiceAccountName is the name of the Kubernetes ServiceAccount used to authenticate the image pull, either with the pull secrets attached to the service account or with an object identity. For more information about object identity: https://fluxcd.io/flux/integrations/object-identity/ spec.suspend # This flag tells the controller to suspend subsequent image scans. It does not apply to already started scans. Defaults to false. spec.timeout pattern="^([0-9]+(\\.[0-9]+)?(ms|s|m))+$" # Timeout for image scanning. Defaults to 'Interval' duration. status default={"observedGeneration":-1} # ImageRepositoryStatus defines the observed state of ImageRepository diff --git a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/imageupdateautomation-image-v1.fields.txt b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/imageupdateautomation-image-v1.fields.txt index 8ecadb20..5a379804 100644 --- a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/imageupdateautomation-image-v1.fields.txt +++ b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/imageupdateautomation-image-v1.fields.txt @@ -1,4 +1,4 @@ -# schema source: Flux v2.9.4 https://github.com/fluxcd/flux2 +# schema source: Flux v2.10.0 https://github.com/fluxcd/flux2 apiVersion enum=image.toolkit.fluxcd.io/v1 kind enum=ImageUpdateAutomation metadata.name (required) @@ -27,6 +27,7 @@ spec.git.push.branch # Branch specifies that commits should be pushed t spec.git.push.options # Options specifies the push options that are sent to the Git server when performing a push operation. For details, see: https://git-scm.com/docs/git-push#Documentation/git-push.txt---push-optionltoptiongt spec.git.push.refspec pattern="^$|^[^+:]" # Refspec specifies the Git Refspec to use for a push operation. If both Branch and Refspec are provided, then the commit is pushed to the branch and also using the specified refspec. Deletion refspecs and refspecs prefixed with '+' are not supported. For more details about Git Refspecs, see: https://git-scm.com/book/en/v2/Git-Internals-The-Refspec spec.interval (required) pattern="^([0-9]+(\\.[0-9]+)?(ms|s|m|h))+$" # Interval gives an lower bound for how often the automation run should be attempted. +spec.policyChangeDelay pattern="^([0-9]+(\\.[0-9]+)?(ms|s|m|h))+$" # PolicyChangeDelay delays the run triggered by ImagePolicy changes, so that image updates arriving within the delay are committed together. If PolicySelector is also set, only changes to the selected policies trigger a run. By default, the automation runs as soon as a policy changes. spec.policySelector # PolicySelector allows to filter applied policies based on labels. By default includes all policies in namespace. spec.policySelector.matchExpressions <[]object> # matchExpressions is a list of label selector requirements. The requirements are ANDed. spec.policySelector.matchExpressions[].key (required) # key is the label key that the selector applies to. diff --git a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/kustomization-kustomize-v1.fields.txt b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/kustomization-kustomize-v1.fields.txt index 4cd60c6c..d9d2eb8d 100644 --- a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/kustomization-kustomize-v1.fields.txt +++ b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/kustomization-kustomize-v1.fields.txt @@ -1,4 +1,4 @@ -# schema source: Flux v2.9.4 https://github.com/fluxcd/flux2 +# schema source: Flux v2.10.0 https://github.com/fluxcd/flux2 apiVersion enum=kustomize.toolkit.fluxcd.io/v1 kind enum=Kustomization metadata.name (required) @@ -48,8 +48,8 @@ spec.images[].name (required) # Name is a tag-less image name. spec.images[].newName # NewName is the value used to replace the original name. spec.images[].newTag # NewTag is the value used to replace the original tag. spec.interval (required) pattern="^([0-9]+(\\.[0-9]+)?(ms|s|m|h))+$" # The interval at which to reconcile the Kustomization. This interval is approximate and may be subject to jitter to ensure efficient use of resources. -spec.kubeConfig # The KubeConfig for reconciling the Kustomization on a remote cluster. When used in combination with KustomizationSpec.ServiceAccountName, forces the controller to act on behalf of that Service Account at the target cluster. If the --default-service-account flag is set, its value will be used as a controller level fallback for when KustomizationSpec.ServiceAccountName is empty. -spec.kubeConfig.configMapRef # ConfigMapRef holds an optional name of a ConfigMap that contains the following keys: - `provider`: the provider to use. One of `aws`, `azure`, `gcp`, or `generic`. Required. - `cluster`: the fully qualified resource name of the Kubernetes cluster in the cloud provider API. Not used by the `generic` provider. Required when one of `address` or `ca.crt` is not set. - `address`: the address of the Kubernetes API server. Required for `generic`. For the other providers, if not specified, the first address in the cluster resource will be used, and if specified, it must match one of the addresses in the cluster resource. If audiences is not set, will be used as the audience for the `generic` provider. - `ca.crt`: the optional PEM-encoded CA certificate for the Kubernetes API server. If not set, the controller will use the CA certificate from the cluster resource. - `audiences`: the optional audiences as a list of line-break-separated strings for the Kubernetes ServiceAccount token. Defaults to the `address` for the `generic` provider, or to specific values for the other providers depending on the provider. - `serviceAccountName`: the optional name of the Kubernetes ServiceAccount in the same namespace that should be used for authentication. If not specified, the controller ServiceAccount will be used. Mutually exclusive with SecretRef. +spec.kubeConfig # The KubeConfig for reconciling the Kustomization on a remote cluster. When used in combination with KustomizationSpec.ServiceAccountName, forces the controller to act on behalf of that Service Account at the target cluster. If the --default-service-account flag is set, its value will be used as the default for KustomizationSpec.ServiceAccountName when it is empty. +spec.kubeConfig.configMapRef # ConfigMapRef holds an optional name of a ConfigMap that contains the following keys: - `provider`: the provider to use. One of `aws`, `azure`, `gcp`, or `generic`. Required. - `cluster`: the fully qualified resource name of the Kubernetes cluster in the cloud provider API. Not used by the `generic` provider. Required when one of `address` or `ca.crt` is not set. - `address`: the address of the Kubernetes API server. Required for `generic`. For the other providers, if not specified, the first address in the cluster resource will be used, and if specified, it must match one of the addresses in the cluster resource. If audiences is not set, will be used as the audience for the `generic` provider. - `ca.crt`: the optional PEM-encoded CA certificate for the Kubernetes API server. If not set, the controller will use the CA certificate from the cluster resource. - `serviceAccountName`: the optional name of the Kubernetes ServiceAccount in the same namespace that should be used for authentication. If not specified, the controller ServiceAccount will be used. - `audiences`: the optional audiences as a list of string separated by commas and/or whitespaces/newlines for the Kubernetes ServiceAccount token. Defaults to the `address` for the `generic` provider, or to specific values for the other providers depending on the provider. Mutually exclusive with SecretRef. spec.kubeConfig.configMapRef.name (required) # Name of the referent. spec.kubeConfig.secretRef # SecretRef holds an optional name of a secret that contains a key with the kubeconfig file as the value. If no key is set, the key will default to 'value'. Mutually exclusive with ConfigMapRef. It is recommended that the kubeconfig is self-contained, and the secret is regularly updated if credentials such as a cloud-access-token expire. Cloud specific `cmd-path` auth helpers will not function without adding binaries and credentials to the Pod that is responsible for reconciling Kubernetes resources. Supported only for the generic provider. spec.kubeConfig.secretRef.key # Key in the Secret, when not specified an implementation-specific default key is used. diff --git a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/ocirepository-source-v1.fields.txt b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/ocirepository-source-v1.fields.txt index 0a58bcd8..ea3bbc6e 100644 --- a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/ocirepository-source-v1.fields.txt +++ b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/ocirepository-source-v1.fields.txt @@ -1,4 +1,4 @@ -# schema source: Flux v2.9.4 https://github.com/fluxcd/flux2 +# schema source: Flux v2.10.0 https://github.com/fluxcd/flux2 apiVersion enum=source.toolkit.fluxcd.io/v1 kind enum=OCIRepository metadata.name (required) @@ -8,11 +8,11 @@ spec.certSecretRef # CertSecretRef can be given the name of a Secret co spec.certSecretRef.name (required) # Name of the referent. spec.ignore # Ignore overrides the set of excluded patterns in the .sourceignore format (which is the same as .gitignore). If not provided, a default will be used, consult the documentation for your version to find out what those are. spec.insecure # Insecure allows connecting to a non-TLS HTTP container registry. -spec.interval (required) pattern="^([0-9]+(\\.[0-9]+)?(ms|s|m|h))+$" # Interval at which the OCIRepository URL is checked for updates. This interval is approximate and may be subject to jitter to ensure efficient use of resources. +spec.interval pattern="^([0-9]+(\\.[0-9]+)?(ms|s|m|h))+$" # Interval at which the OCIRepository URL is checked for updates. This interval is approximate and may be subject to jitter to ensure efficient use of resources. spec.layerSelector # LayerSelector specifies which layer should be extracted from the OCI artifact. When not specified, the first layer found in the artifact is selected. spec.layerSelector.mediaType # MediaType specifies the OCI media type of the layer which should be extracted from the OCI Artifact. The first layer matching this type is selected. spec.layerSelector.operation enum=extract|copy # Operation specifies how the selected layer should be processed. By default, the layer compressed content is extracted to storage. When the operation is set to 'copy', the layer compressed content is persisted to storage as it is. -spec.provider enum=generic|aws|azure|gcp default="generic" # The provider used for authentication, can be 'aws', 'azure', 'gcp' or 'generic'. When not specified, defaults to 'generic'. +spec.provider enum=generic|aws|azure|gcp # The provider used for authentication, can be 'aws', 'azure', 'gcp' or 'generic'. When not specified, defaults to 'generic'. spec.proxySecretRef # ProxySecretRef specifies the Secret containing the proxy configuration to use while communicating with the container registry. spec.proxySecretRef.name (required) # Name of the referent. spec.ref # The OCI reference to pull and monitor for changes, defaults to the latest tag. @@ -22,10 +22,10 @@ spec.ref.semverFilter # SemverFilter is a regex pattern to filter the t spec.ref.tag # Tag is the image tag to pull, defaults to latest. spec.secretRef # SecretRef contains the secret name containing the registry login credentials to resolve image metadata. The secret must be of type kubernetes.io/dockerconfigjson. spec.secretRef.name (required) # Name of the referent. -spec.serviceAccountName # ServiceAccountName is the name of the Kubernetes ServiceAccount used to authenticate the image pull if the service account has attached pull secrets. For more information: https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#add-imagepullsecrets-to-a-service-account +spec.serviceAccountName # ServiceAccountName is the name of the Kubernetes ServiceAccount used to authenticate the image pull, either with the pull secrets attached to the service account or with an object identity. For more information about object identity: https://fluxcd.io/flux/integrations/object-identity/ For more information about image pull secrets: https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#add-imagepullsecrets-to-a-service-account spec.suspend # This flag tells the controller to suspend the reconciliation of this source. -spec.timeout default="60s" pattern="^([0-9]+(\\.[0-9]+)?(ms|s|m))+$" # The timeout for remote OCI Repository operations like pulling, defaults to 60s. -spec.url (required) pattern="^oci://.*$" # URL is a reference to an OCI artifact repository hosted on a remote container registry. +spec.timeout pattern="^([0-9]+(\\.[0-9]+)?(ms|s|m))+$" # The timeout for remote OCI Repository operations like pulling, defaults to 60s. +spec.url pattern="^oci://.*$" # URL is a reference to an OCI artifact repository hosted on a remote container registry. spec.verify # Verify contains the secret name containing the trusted public keys used to verify the signature and specifies which provider to use to check whether OCI image is authentic. spec.verify.matchOIDCIdentity <[]object> # MatchOIDCIdentity specifies the identity matching criteria to use while verifying an OCI artifact which was signed using Cosign keyless signing. The artifact's identity is deemed to be verified if any of the specified matchers match against the identity. spec.verify.matchOIDCIdentity[].issuer (required) # Issuer specifies the regex pattern to match against to verify the OIDC issuer in the Fulcio certificate. The pattern must be a valid Go regular expression. @@ -57,4 +57,5 @@ status.observedIgnore # ObservedIgnore is the observed exclusion patter status.observedLayerSelector # ObservedLayerSelector is the observed layer selector used for constructing the source artifact. status.observedLayerSelector.mediaType # MediaType specifies the OCI media type of the layer which should be extracted from the OCI Artifact. The first layer matching this type is selected. status.observedLayerSelector.operation enum=extract|copy # Operation specifies how the selected layer should be processed. By default, the layer compressed content is extracted to storage. When the operation is set to 'copy', the layer compressed content is persisted to storage as it is. +status.sourceVerificationFingerprint # SourceVerificationFingerprint is the fingerprint of the verification material used to verify the signature of the current Artifact. It is used to detect changes to the verification policy, such as a key rotation, that require the current revision to be verified again. status.url # URL is the download link for the artifact output of the last OCI Repository sync. diff --git a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/provider-notification-v1.fields.txt b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/provider-notification-v1.fields.txt new file mode 100644 index 00000000..562a162e --- /dev/null +++ b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/provider-notification-v1.fields.txt @@ -0,0 +1,20 @@ +# schema source: Flux v2.10.0 https://github.com/fluxcd/flux2 +apiVersion enum=notification.toolkit.fluxcd.io/v1 +kind enum=Provider +metadata.name (required) +metadata.namespace (required) +spec # ProviderSpec defines the desired state of the Provider. +spec.address max=2048 # Address specifies the endpoint, in a generic sense, to where alerts are sent. What kind of endpoint depends on the specific Provider type being used. For the generic Provider, for example, this is an HTTP/S address. For other Provider types this could be a project ID or a namespace. +spec.certSecretRef # CertSecretRef specifies the Secret containing TLS certificates for secure communication. Supported configurations: - CA-only: Server authentication (provide ca.crt only) - mTLS: Mutual authentication (provide ca.crt + tls.crt + tls.key) - Client-only: Client authentication with system CA (provide tls.crt + tls.key only) Legacy keys "caFile", "certFile", "keyFile" are supported but deprecated. Use "ca.crt", "tls.crt", "tls.key" instead. +spec.certSecretRef.name (required) # Name of the referent. +spec.channel max=2048 # Channel specifies the destination channel where events should be posted. +spec.commitStatusExpr # CommitStatusExpr is a CEL expression that evaluates to a string value that can be used to generate a custom commit status message for use with eligible Provider types (github, gitlab, gitea, bitbucketserver, bitbucket, azuredevops). Supported variables are: event, provider, and alert. +spec.proxySecretRef # ProxySecretRef specifies the Secret containing the proxy configuration for this Provider. The Secret should contain an 'address' key with the HTTP/S address of the proxy server. Optional 'username' and 'password' keys can be provided for proxy authentication. +spec.proxySecretRef.name (required) # Name of the referent. +spec.secretRef # SecretRef specifies the Secret containing the authentication credentials for this Provider. +spec.secretRef.name (required) # Name of the referent. +spec.serviceAccountName # ServiceAccountName is the name of the Kubernetes ServiceAccount used to authenticate with cloud provider services through object identity. This enables multi-tenant authentication without storing static credentials. Supported provider types: azureeventhub, azuredevops, googlepubsub When specified, the controller will: 1. Create an OIDC token for the specified ServiceAccount 2. Exchange it for cloud provider credentials via STS 3. Use the obtained credentials for API authentication When unspecified, the controller's workload identity is used (single-tenant). An error is thrown if static credentials are also defined in SecretRef. +spec.suspend # Suspend tells the controller to suspend subsequent events handling for this Provider. +spec.timeout pattern="^([0-9]+(\\.[0-9]+)?(ms|s|m))+$" # Timeout for sending alerts to the Provider. +spec.type (required) enum=slack|discord|msteams|rocket|generic|generic-hmac|github|gitlab|gitea|giteapullrequestcomment|bitbucketserver|bitbucket|azuredevops|googlechat|googlepubsub|webex|sentry|azureeventhub|telegram|lark|matrix|opsgenie|alertmanager|grafana|githubdispatch|githubpullrequestcomment|gitlabmergerequestcomment|pagerduty|datadog|nats|zulip|otel|zoom|incident.io|mastodon # Type specifies which Provider implementation to use. +spec.username max=2048 # Username specifies the name under which events are posted. diff --git a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/provider-notification-v1beta3.fields.txt b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/provider-notification-v1beta3.fields.txt index 2b31bc46..5f55c156 100644 --- a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/provider-notification-v1beta3.fields.txt +++ b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/provider-notification-v1beta3.fields.txt @@ -1,5 +1,5 @@ -# schema source: Flux v2.9.4 https://github.com/fluxcd/flux2 -apiVersion enum=notification.toolkit.fluxcd.io/v1beta3 +# schema source: Flux v2.10.0 https://github.com/fluxcd/flux2 +apiVersion enum=notification.toolkit.fluxcd.io/v1beta3 (deprecated) # v1beta3 Provider is deprecated, upgrade to v1 kind enum=Provider metadata.name (required) metadata.namespace (required) @@ -15,8 +15,8 @@ spec.proxySecretRef # ProxySecretRef specifies the Secret containing th spec.proxySecretRef.name (required) # Name of the referent. spec.secretRef # SecretRef specifies the Secret containing the authentication credentials for this Provider. spec.secretRef.name (required) # Name of the referent. -spec.serviceAccountName # ServiceAccountName is the name of the Kubernetes ServiceAccount used to authenticate with cloud provider services through workload identity. This enables multi-tenant authentication without storing static credentials. Supported provider types: azureeventhub, azuredevops, googlepubsub When specified, the controller will: 1. Create an OIDC token for the specified ServiceAccount 2. Exchange it for cloud provider credentials via STS 3. Use the obtained credentials for API authentication When unspecified, controller-level authentication is used (single-tenant). An error is thrown if static credentials are also defined in SecretRef. This field requires the ObjectLevelWorkloadIdentity feature gate to be enabled. +spec.serviceAccountName # ServiceAccountName is the name of the Kubernetes ServiceAccount used to authenticate with cloud provider services through workload identity. This enables multi-tenant authentication without storing static credentials. Supported provider types: azureeventhub, azuredevops, googlepubsub When specified, the controller will: 1. Create an OIDC token for the specified ServiceAccount 2. Exchange it for cloud provider credentials via STS 3. Use the obtained credentials for API authentication When unspecified, controller-level authentication is used (single-tenant). An error is thrown if static credentials are also defined in SecretRef. spec.suspend # Suspend tells the controller to suspend subsequent events handling for this Provider. spec.timeout pattern="^([0-9]+(\\.[0-9]+)?(ms|s|m))+$" # Timeout for sending alerts to the Provider. -spec.type (required) enum=slack|discord|msteams|rocket|generic|generic-hmac|github|gitlab|gitea|giteapullrequestcomment|bitbucketserver|bitbucket|azuredevops|googlechat|googlepubsub|webex|sentry|azureeventhub|telegram|lark|matrix|opsgenie|alertmanager|grafana|githubdispatch|githubpullrequestcomment|gitlabmergerequestcomment|pagerduty|datadog|nats|zulip|otel # Type specifies which Provider implementation to use. +spec.type (required) enum=slack|discord|msteams|rocket|generic|generic-hmac|github|gitlab|gitea|giteapullrequestcomment|bitbucketserver|bitbucket|azuredevops|googlechat|googlepubsub|webex|sentry|azureeventhub|telegram|lark|matrix|opsgenie|alertmanager|grafana|githubdispatch|githubpullrequestcomment|gitlabmergerequestcomment|pagerduty|datadog|nats|zulip|otel|zoom|incident.io # Type specifies which Provider implementation to use. spec.username max=2048 # Username specifies the name under which events are posted. diff --git a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/receiver-notification-v1.fields.txt b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/receiver-notification-v1.fields.txt index 65b28bd4..fb381503 100644 --- a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/receiver-notification-v1.fields.txt +++ b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/receiver-notification-v1.fields.txt @@ -1,4 +1,4 @@ -# schema source: Flux v2.9.4 https://github.com/fluxcd/flux2 +# schema source: Flux v2.10.0 https://github.com/fluxcd/flux2 apiVersion enum=notification.toolkit.fluxcd.io/v1 kind enum=Receiver metadata.name (required) diff --git a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/resourceset-fluxcd-v1.fields.txt b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/resourceset-fluxcd-v1.fields.txt index ab0cf517..ec45be7f 100644 --- a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/resourceset-fluxcd-v1.fields.txt +++ b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/resourceset-fluxcd-v1.fields.txt @@ -1,4 +1,4 @@ -# schema source: Flux Operator v0.58.1 https://github.com/controlplaneio-fluxcd/flux-operator +# schema source: Flux Operator v0.62.0 https://github.com/controlplaneio-fluxcd/flux-operator apiVersion enum=fluxcd.controlplane.io/v1 kind enum=ResourceSet metadata.name (required) diff --git a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/resourcesetinputprovider-fluxcd-v1.fields.txt b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/resourcesetinputprovider-fluxcd-v1.fields.txt index edd3e0fd..8c9b7f17 100644 --- a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/resourcesetinputprovider-fluxcd-v1.fields.txt +++ b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/assets/schemas/resourcesetinputprovider-fluxcd-v1.fields.txt @@ -1,4 +1,4 @@ -# schema source: Flux Operator v0.58.1 https://github.com/controlplaneio-fluxcd/flux-operator +# schema source: Flux Operator v0.62.0 https://github.com/controlplaneio-fluxcd/flux-operator apiVersion enum=fluxcd.controlplane.io/v1 kind enum=ResourceSetInputProvider metadata.name (required) @@ -32,7 +32,7 @@ spec.selectors[].matchExpressions[].values <[]string> # values is an array of st spec.selectors[].matchLabels # matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. spec.selectors[].name # Name selects a single ExternalArtifact by metadata.name. This field is mutually exclusive with matchLabels and matchExpressions. spec.selectors[].namespace # Namespace scopes ExternalArtifact discovery. When empty, ExternalArtifacts are listed in the ResourceSetInputProvider namespace. When set to "*", ExternalArtifacts are listed across all namespaces by omitting the namespace option from List(). Otherwise, ExternalArtifacts are listed only in the specified namespace. -spec.serviceAccountName # ServiceAccountName specifies the name of the Kubernetes ServiceAccount used for authentication with AWS, Azure or GCP services through workload identity federation features. If not specified, the authentication for these cloud providers will use the ServiceAccount of the operator (or any other environment authentication configuration). +spec.serviceAccountName # ServiceAccountName specifies the name of the Kubernetes ServiceAccount used for authentication with external services using object identity. If not specified, the default object identity ServiceAccount configured with the --default-object-identity-service-account flag or the DEFAULT_OBJECT_IDENTITY_SERVICE_ACCOUNT environment variable is used. This field can also be set for the ExternalArtifact type, where it is used only for impersonation and its annotations are ignored. For a complete guide to the ServiceAccount annotations used for object identity, including the spiffe credential provider, see: https://fluxcd.io/flux/integrations/object-identity/ spec.skip # Skip defines whether we need to skip input provider response updates. spec.skip.labels <[]string> # Labels specifies list of labels to skip input provider response when any of the label conditions matched. When prefixed with !, input provider response will be skipped if it does not have this label. spec.type (required) enum=Static|GitHubBranch|GitHubTag|GitHubPullRequest|GitLabBranch|GitLabTag|GitLabMergeRequest|GitLabEnvironment|AzureDevOpsBranch|AzureDevOpsTag|AzureDevOpsPullRequest|AWSCodeCommitBranch|AWSCodeCommitTag|AWSCodeCommitPullRequest|GiteaBranch|GiteaTag|GiteaPullRequest|OCIArtifactTag|ACRArtifactTag|ECRArtifactTag|GARArtifactTag|ExternalService|ExternalArtifact # Type specifies the type of the input provider. diff --git a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/evals/evals.json b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/evals/evals.json index f68484b3..fb90f170 100644 --- a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/evals/evals.json +++ b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/evals/evals.json @@ -1,55 +1,77 @@ { "skill_name": "gitops-cluster-debug", - "note": "These evals require a live Kubernetes cluster with Flux Operator and the flux-operator-mcp server running. They serve as documentation for expected skill behavior.", + "note": "These evals need a live cluster running Flux Operator and Flux 2.10 with the scenarios from tests/gitops-cluster-debug/scenarios.yaml applied, and the flux-operator-mcp server (v0.60+) running with --read-only. Executors get only the MCP tools plus local file tools; they have no kubectl access to the cluster.", "evals": [ { "id": 1, "prompt": "Check the Flux installation health on the current cluster and provide a status report.", - "expected_output": "A report showing the Flux Operator status, FluxInstance readiness, controller deployment health, installed Flux version, and a summary from the FluxReport.", + "expected_output": "A report showing the Flux Operator and FluxInstance status, the Flux version and components, controller health, and the Flux resources that are not ready across the cluster.", "files": [], "expectations": [ - "Calls get_flux_instance to check the Flux Operator status", - "Reports the FluxInstance Ready condition and any issues", - "Lists all Flux controller deployments and their status", - "Reports the installed Flux distribution version", - "Summarizes the FluxReport resource counts and conditions", - "If controllers are unhealthy, checks controller pod logs", - "Produces a structured report with summary and recommendations" + "Calls get_flux_instance to check the Flux Operator and FluxInstance status", + "Reports the installed Flux distribution version (v2.10.0) and that the FluxInstance is Ready", + "Lists the Flux controller deployments and their status", + "Names the failing Kustomization tenant-a/apps and the failing GitRepository tenant-a/tenant-a", + "Names the failing HelmRelease default/podinfo", + "Produces a structured report with a summary and recommendations" ] }, { "id": 2, - "prompt": "Debug the failing Kustomization 'apps' in the 'flux-system' namespace.", - "expected_output": "A root cause analysis identifying that the Kustomization fails because its source GitRepository has an authentication error, with recommendations to fix the Git credentials.", + "prompt": "Debug the failing Kustomization 'apps' in the 'tenant-a' namespace.", + "expected_output": "A root cause analysis identifying that the Kustomization has no artifact because its GitRepository tenant-a fails to clone with an authentication error, with recommendations to fix the Git credentials in the git-auth Secret.", "files": [], "expectations": [ - "Calls get_flux_instance to check the kustomize-controller status", - "Calls get_kubernetes_api_versions to verify the Kustomization apiVersion", - "Gets the Kustomization resource and analyzes its status conditions and events", - "Identifies the sourceRef pointing to a GitRepository", - "Gets the GitRepository resource and finds the FetchFailed condition", - "Identifies the authentication error as the root cause", - "Checks if the referenced secretRef Secret exists and has the expected keys", - "Produces a root cause analysis report with the dependency chain", - "Recommends fixing the Git credentials in the referenced Secret" + "Gets the Kustomization and reports its Ready condition (source artifact not found)", + "Identifies the sourceRef GitRepository tenant-a and gets it", + "Identifies the GitRepository authentication failure (invalid username or token) as the root cause", + "Checks that the referenced Secret git-auth exists and reports its key names (username, password)", + "Produces a root cause analysis report with the dependency chain GitRepository -> Kustomization", + "Recommends replacing the credentials in the git-auth Secret with a valid token (or GitHub App) and reconciling the source" ] }, { "id": 3, "prompt": "Debug the failing HelmRelease 'podinfo' in the 'default' namespace.", - "expected_output": "A root cause analysis identifying that the HelmRelease upgrade failed with managed Deployment pods in ImagePullBackOff due to a non-existent container image tag.", + "expected_output": "A root cause analysis identifying that the HelmRelease install fails because the podinfo Deployment pods are in ImagePullBackOff for the non-existent image tag 6.99.0-hotfix set in the HelmRelease values.", "files": [], "expectations": [ - "Calls get_flux_instance to check the helm-controller status", - "Calls get_kubernetes_api_versions to verify the HelmRelease apiVersion", - "Gets the HelmRelease resource and analyzes its status conditions and events", - "Identifies the chart source from chartRef or sourceRef", - "Gets the source resource and verifies it is ready", - "Checks the HelmRelease inventory for managed resources", - "Gets managed Deployments and finds pods in ImagePullBackOff", - "Analyzes pod events to identify the image pull error", - "Produces a root cause analysis tracing from HelmRelease to Deployment to Pod", - "Recommends fixing the container image reference in the HelmRelease values" + "Gets the HelmRelease and analyzes its status conditions (install failed or retrying)", + "Identifies the chart source OCIRepository default/podinfo and reports it as ready", + "Gets the managed podinfo Deployment or its pods from the release inventory", + "Finds the pods in ErrImagePull/ImagePullBackOff from events or pod status", + "Identifies the non-existent image tag 6.99.0-hotfix as the root cause", + "Traces the tag to spec.values.image.tag in the HelmRelease", + "Recommends fixing image.tag in the HelmRelease values (in Git) to an existing tag" + ] + }, + { + "id": 4, + "prompt": "Pods of the 'orders' deployment in the 'shop' namespace keep crashing. Find out what deploys it through GitOps and why it crashes.", + "expected_output": "Traces the Deployment to the ResourceSet shop/shop-services, finds CrashLoopBackOff/BackOff events, reads the container logs showing DB_PASSWORD is not set, and recommends adding DB_PASSWORD (from a Secret) in the ResourceSet template.", + "files": [], + "expectations": [ + "Calls trace_kubernetes_resource on the orders Deployment (or one of its pods)", + "Identifies the ResourceSet shop/shop-services as the Flux object that deploys the Deployment", + "Calls get_kubernetes_events for the orders workload and reports the BackOff / CrashLoopBackOff warnings", + "Calls get_kubernetes_logs with kind Deployment (not a pod name looked up first)", + "Identifies from the logs that the app exits because DB_PASSWORD is not set", + "Notes that the orders-config ConfigMap provides DB_HOST/DB_PORT/DB_NAME but no DB_PASSWORD", + "Recommends adding DB_PASSWORD from a Secret in the ResourceSet template (not editing the live Deployment)" + ] + }, + { + "id": 5, + "prompt": "I edited the podinfo manifests in {FIXTURE:tests/gitops-cluster-debug/podinfo-change} (this directory is deployed by the Flux Kustomization 'podinfo' in the 'web' namespace). Before I commit, tell me exactly what this change will do on the cluster.", + "expected_output": "Builds the directory, diffs it against the cluster with the web/podinfo Kustomization as owner, and reports the Deployment memory limit change, the HPA maxReplicas change and that the Service web/podinfo will be deleted (pruned).", + "files": ["tests/gitops-cluster-debug/podinfo-change"], + "expectations": [ + "Builds the manifests locally (kustomize build or equivalent) and passes the complete build output", + "Calls diff_kubernetes_manifest with owner Kustomization web/podinfo (owner_kind/owner_name/owner_namespace or flux_object)", + "Reports the Deployment update: memory limit 512Mi -> 256Mi", + "Reports the HorizontalPodAutoscaler update: maxReplicas 4 -> 8", + "Reports that the Service web/podinfo will be deleted because prune is enabled", + "Does not modify the cluster or the local files" ] } ] diff --git a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/references/flux-crds.md b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/references/flux-crds.md index 34ed3ce1..1e469510 100644 --- a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/references/flux-crds.md +++ b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/references/flux-crds.md @@ -220,6 +220,7 @@ Note: OCI HelmRepositories have no status conditions. **Key spec fields**: - `.spec.chartRef` / `.spec.chart.spec.sourceRef` — Chart source reference +- `.spec.chart.kind: OCIRepository` (Flux 2.10+) — `.spec.chart.spec` is an inline OCIRepository spec (`url`, `ref`); the controller creates and owns an OCIRepository named `-`, reported in `.status.helmChart` as `OCIRepository//` (event `OCIRepositoryCreated`). Debug that OCIRepository like any other source - `.spec.interval` — Reconciliation interval - `.spec.values` — Inline Helm values - `.spec.valuesFrom` — Values from ConfigMaps/Secrets @@ -242,18 +243,21 @@ Note: OCI HelmRepositories have no status conditions. ## Notification Controller -### Provider (`notification.toolkit.fluxcd.io/v1beta3`) +### Provider (`notification.toolkit.fluxcd.io/v1`) **Purpose**: Represents a notification service (Slack, MS Teams, GitHub, etc.). **Key spec fields**: - `.spec.type` — Provider type (slack, msteams, github, generic, etc.) - `.spec.address` — Webhook URL or API endpoint -- `.spec.secretRef` — Secret with authentication token +- `.spec.secretRef` — Secret with credentials (`address`, `token`, `username`, `password`, `headers`) +- `.spec.proxySecretRef` — Secret with proxy `address`; replaces `.spec.proxy` (removed in v1) +- `.spec.certSecretRef` — TLS data (`ca.crt`, `tls.crt`, `tls.key`) -Note: Providers have no status conditions. +Note: Providers have no status conditions. `v1beta3` is deprecated in Flux 2.10 (warning +`v1beta3 Provider is deprecated, upgrade to v1`); `v1` drops `.spec.proxy` and `.spec.interval`. -### Alert (`notification.toolkit.fluxcd.io/v1beta3`) +### Alert (`notification.toolkit.fluxcd.io/v1`) **Purpose**: Configures events to be forwarded to notification providers. @@ -263,6 +267,7 @@ Note: Providers have no status conditions. - `.spec.eventSeverity` — Minimum severity to forward (info, error) Note: Alerts have no status conditions. +`v1beta3` is deprecated in Flux 2.10; `v1` drops `.spec.summary` (use `.spec.eventMetadata.summary`). ### Receiver (`notification.toolkit.fluxcd.io/v1`) diff --git a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/references/troubleshooting.md b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/references/troubleshooting.md index 135e0b9d..0fc2f1cc 100644 --- a/plugins/gitops-kubernetes/skills/gitops-cluster-debug/references/troubleshooting.md +++ b/plugins/gitops-kubernetes/skills/gitops-cluster-debug/references/troubleshooting.md @@ -31,6 +31,30 @@ Common failure patterns and debugging procedures for Flux on Kubernetes clusters - OOMKilled (increase memory limits in FluxInstance kustomize patches) - Incompatible CRD version (controller binary doesn't match installed CRDs) - Corrupt cache or storage (delete the pod to force fresh start) +- Unsupported Kubernetes version (Flux 2.10 requires Kubernetes 1.35 or later) + +### Object identity credentials fail (Flux 2.10+) + +**Symptoms**: Sources, Providers, image or applier objects with `.spec.serviceAccountName` fail auth +(cloud `.spec.provider`, `generic` with `credential.auth.fluxcd.io/*` ServiceAccount annotations, or +`kubeConfig.configMapRef`) — typically right after upgrading to 2.10; errors mention `serviceaccounts/token` or forbidden. + +**Common causes**: +- **Missing token RBAC**: Flux 2.10 default RBAC no longer grants `create` on `serviceaccounts/token`. Bind a ClusterRole with that permission to the controller ServiceAccounts (or set FluxInstance `.spec.cluster.objectIdentityRBAC: true`). +- **Incomplete annotations**: `generic` ServiceAccount tokens need both `credential.auth.fluxcd.io/provider: kubernetes` and `credential.auth.fluxcd.io/type: jwt`; one without the other is an error, and they can't be combined with `imagePullSecrets`. +- **Lockdown default SA**: With the object identity lockdown (`--default-service-account`, `multitenantObjectIdentity`), objects without `serviceAccountName` use the tenant's default SA, not the controller identity. +- **`spiffe` provider**: Requires the SPIFFE Workload API socket plus `--spiffe-broker-endpoint` and `--spiffe-broker-id` flags on the controller. + +### Inter-controller mTLS failures (SPIFFE, Flux 2.10+) + +**Symptoms**: Kustomizations/HelmReleases fail to fetch artifacts while the source is `Ready`, or +events stop reaching notification-controller, after `--authorized-*-spiffe-id` flags were added. + +**Diagnosis**: mTLS is enabled per traffic type by the presence of a flag, on both sides. Check that the +peer's flag is also set (e.g. `--authorized-artifact-client-spiffe-id` on source-controller pairs with +`--authorized-artifact-server-spiffe-id` on kustomize/helm-controller), that each flag holds the **peer's** SPIFFE ID +exactly as issued by the SPIFFE runtime, that `SPIFFE_ENDPOINT_SOCKET` and the socket mount exist on every +controller, and that the Services expose port 443 (`https`). ## Source Failures @@ -169,6 +193,12 @@ notification-controller logs, not object status. - **Event filtered**: Alert `.spec.eventSeverity: error` drops info events; `.spec.eventSources` doesn't match the resource kind/name/namespace producing the event. - **Provider auth/address error**: Wrong or expired token in the `secretRef`, wrong webhook `address` — look for HTTP 401/404/timeout errors in controller logs. - **Wrong provider type**: `.spec.type` doesn't match the receiving service's expected payload format. +- **Secret keys rejected after upgrading to Flux 2.10** (applies to `v1beta3` objects too, the controller reads `v1`): + - a `proxy` key in the `secretRef` Secret is rejected — move it to a Secret referenced by `.spec.proxySecretRef`; + - commit status Providers (`github`, `gitlab`, `gitea`, `bitbucket`, `bitbucketserver`, `azuredevops`) fail when the `secretRef` Secret holds TLS data and `.spec.certSecretRef` is unset; + - `azureeventhub` fails when its Secret has a `token` key (static JWT auth removed; use SAS `address` or object identity); + - `bitbucket` rejects `:` tokens — use a Bitbucket Cloud API token. +- **Alert summary or Provider proxy gone after upgrade**: `v1` dropped Alert `.spec.summary` and Provider `.spec.proxy`/`.spec.interval`; the API server drops them when objects are served or written at the `v1` storage version, with no error. Restore with `.spec.eventMetadata.summary` and `.spec.proxySecretRef`. Warnings like `v1beta3 Alert is deprecated, upgrade to v1` mean manifests in Git still use `v1beta3` — run `flux migrate -f .`. ### Receiver not triggering