Skip to main content

Documentation Index

Fetch the complete documentation index at: https://opensre.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

OpenSRE runs the Helm 3 command-line client on the machine where the agent executes. It uses read-only subcommands (helm list, helm status, helm history, helm get values, helm get manifest) with explicit --kube-context and --kubeconfig flags so investigations target the same cluster your engineers use.
Helm 2 is not supported. Verification checks helm version --client and requires a Helm 3.x client.

​
Prerequisites

  • Helm 3 installed and on PATH (or configured via helm_path)
  • kubectl access to the cluster (kubeconfig on disk or in the default search path)
  • Optional: alert annotations or Kubernetes labels that identify a Helm release and namespace (see Usage in investigations)

​
Setup

Configure Helm like other local integrations: environment variables and/or ~/.config/opensre/integrations.json.

​
Option 1: Environment variables

Enable the integration and point it at your cluster: 
# Required gate — set to 1, true, or yes
OSRE_HELM_INTEGRATION=1

# Optional overrides (defaults shown where applicable)
HELM_PATH=helm
HELM_KUBE_CONTEXT=
HELM_KUBECONFIG=
# Default namespace hint when the alert does not specify one
HELM_NAMESPACE=
VariableDefaultDescription
OSRE_HELM_INTEGRATION—Required to activate Helm from env. Must be 1, true, or yes (case-insensitive).
HELM_PATHhelmHelm binary name or absolute path.
HELM_KUBE_CONTEXT—Passed to every Helm invocation as --kube-context.
HELM_KUBECONFIG—Passed as --kubeconfig (path to the kubeconfig file).
HELM_NAMESPACE—default_namespace in the resolved integration; used as a fallback namespace when the alert does not supply one.
To raise the maximum size of stored manifest text (see Advanced): 
# Integer, minimum 1024; default in code is 600_000 characters
HELM_MANIFEST_MAX_CHARS=600000

​
Option 2: Persistent store

Add an active helm record to ~/.config/opensre/integrations.json: 
{
  "version": 1,
  "integrations": [
    {
      "id": "helm-prod",
      "service": "helm",
      "status": "active",
      "credentials": {
        "helm_path": "helm",
        "kube_context": "prod-admin",
        "kubeconfig": "",
        "default_namespace": "production"
      }
    }
  ]
}
Credential field aliases (store / API compatibility): context for kube_context, kubeconfig_path or kube_config for kubeconfig, and namespace for default_namespace.

​
Verify

opensre integrations verify helm
A passing check runs helm version --client (must report Helm 3) and a minimal helm list -A --max 1 -o json against your cluster to validate JSON output and reachability.

​
Usage in investigations

When Helm is configured, OpenSRE adds a helm entry to detect_sources only if the alert shows Helm-specific context — avoiding generic “deployment” noise. Annotations (including top-level enriched fields merged into annotations):
KeyPurpose
helm_release / helm_release_nameRelease name
helm_namespaceNamespace hint
helm_chart, helm_revisionExtra Helm signals
Keys prefixed with meta.helm.sh/Treated as Helm metadata
Labels (from Prometheus/Alertmanager-style labels / commonLabels on the alert payload):
LabelPurpose
meta.helm.sh/release-nameRelease name
meta.helm.sh/release-namespaceNamespace paired with the release
Alert text: Strong phrases such as helm upgrade, helm install, helm rollback, helm chart, or helm release in summary / description / message (or top-level alert_name / error_message) can also enable the Helm source when other hints are absent. Top-level payload fields (dict alerts only): helm_release, helm_release_name, helm_namespace, etc., are consulted as fallbacks. Example minimal alert: 
{
  "labels": {
    "meta.helm.sh/release-name": "my-api",
    "meta.helm.sh/release-namespace": "prod"
  },
  "annotations": {
    "summary": "Errors after helm upgrade"
  }
}
Then run: 
opensre investigate -i alert.json

​
Investigation tools

ToolWhat it does
helm_list_releasesLists releases (JSON from helm list); uses all namespaces when no namespace filter is set.
helm_release_statushelm status -o json for one release.
helm_release_historyhelm history -o json for one release.
helm_get_release_valueshelm get values -o json (user-supplied values; JSON null from Helm is treated as an empty object).
helm_get_release_manifestRendered manifest YAML (may be truncated; see below).

​
Evidence keys

Post-processing writes distinct evidence keys so parallel tools do not overwrite each other:
Evidence keyContent
helm_releasesParsed release list
helm_release_statusStatus object from helm status
helm_release_historyRevision history array
helm_release_valuesValues object
helm_release_manifestRendered manifest YAML string; unchanged key name. When the manifest exceeds the size cap, this value is truncated text, not a separate key.
helm_manifest_truncatedBoolean: true when helm_release_manifest was truncated because of HELM_MANIFEST_MAX_CHARS / the client default cap.

​
Advanced

  • Manifest size: Very large charts can produce multi-megabyte manifests. The client truncates manifest text by default; override with HELM_MANIFEST_MAX_CHARS (see Option 1).
  • Local kind demo: From a repo checkout with Docker, kind, kubectl, and Helm installed, run ./scripts/demo-helm-kind.sh to create a sample cluster and release (see script comments for teardown).

​
Security and operations

  • The integration is read-only: it does not install, upgrade, or uninstall releases.
  • helm get values output can include secrets; treat evidence like any other sensitive kubectl/Helm output.
  • Prefer a dedicated kubeconfig or context with least privilege if your policy requires it.

​
Troubleshooting

SymptomWhat to check
Verify: missingHelm not in store / env gate OSRE_HELM_INTEGRATION not set / invalid JSON store entry.
Verify: Helm 3 requiredUpgrade to Helm 3 or point helm_path at a v3 binary.
Verify: list JSON / clusterkubeconfig and context; cluster reachable with helm list -A manually.
No Helm tools in planAlert must include Helm annotations, meta.helm.sh/* labels, or strong Helm phrases (see above).
Wrong namespace / release not foundEnsure meta.helm.sh/release-namespace or helm_namespace / k8s_namespace annotations match the release; set default_namespace in config when alerts lack namespace.