> ## 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. # Helm (CLI) > Connect Helm 3 so OpenSRE can list releases, inspect status and history, and read rendered values and manifests during Kubernetes investigations 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` 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](#usage-in-investigations)) ## Setup Configure Helm like other local integrations: run `opensre integrations setup helm`, use environment variables, and/or `~/.opensre/integrations.json`. ### Option 1: Environment variables Enable the integration and point it at your cluster: ```bash theme={null} # 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= ``` | Variable | Default | Description | | ----------------------- | ------- | ----------------------------------------------------------------------------------------------------------------- | | `OSRE_HELM_INTEGRATION` | — | **Required** to activate Helm from env. Must be `1`, `true`, or `yes` (case-insensitive). | | `HELM_PATH` | `helm` | Helm 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](#advanced)): ```bash theme={null} # 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 `~/.opensre/integrations.json`: ```json theme={null} { "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 ```bash theme={null} opensre integrations verify helm ``` A passing check runs `helm version` (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): | Key | Purpose | | ------------------------------------ | ------------------------ | | `helm_release` / `helm_release_name` | Release name | | `helm_namespace` | Namespace hint | | `helm_chart`, `helm_revision` | Extra Helm signals | | Keys prefixed with `meta.helm.sh/` | Treated as Helm metadata | **Labels** (from Prometheus/Alertmanager-style `labels` / `commonLabels` on the alert payload): | Label | Purpose | | -------------------------------- | --------------------------------- | | `meta.helm.sh/release-name` | Release name | | `meta.helm.sh/release-namespace` | Namespace 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: ```json theme={null} { "labels": { "meta.helm.sh/release-name": "my-api", "meta.helm.sh/release-namespace": "prod" }, "annotations": { "summary": "Errors after helm upgrade" } } ``` Then run: ```bash theme={null} opensre investigate -i alert.json ``` ## Investigation tools | Tool | What it does | | --------------------------- | ------------------------------------------------------------------------------------------------------ | | `helm_list_releases` | Lists releases (JSON from `helm list`); uses all namespaces when no namespace filter is set. | | `helm_release_status` | `helm status -o json` for one release. | | `helm_release_history` | `helm history -o json` for one release. | | `helm_get_release_values` | `helm get values -o json` (user-supplied values; JSON `null` from Helm is treated as an empty object). | | `helm_get_release_manifest` | Rendered manifest YAML (may be truncated; see below). | ## Evidence keys Post-processing writes **distinct** evidence keys so parallel tools do not overwrite each other: | Evidence key | Content | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `helm_releases` | Parsed release list | | `helm_release_status` | Status object from `helm status` | | `helm_release_history` | Revision history array | | `helm_release_values` | Values object | | `helm_release_manifest` | Rendered manifest YAML **string**; unchanged key name. When the manifest exceeds the size cap, this value is **truncated** text, not a separate key. | | `helm_manifest_truncated` | Boolean: `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 `./infra/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 | Symptom | What to check | | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Verify: missing** | Helm not in store / env gate `OSRE_HELM_INTEGRATION` not set / invalid JSON store entry. | | **Verify: Helm 3 required** | Upgrade to Helm 3 or point `helm_path` at a v3 binary. | | **Verify: list JSON / cluster** | kubeconfig and context; cluster reachable with `helm list -A` manually. | | **No Helm tools in plan** | Alert must include Helm annotations, `meta.helm.sh/*` labels, or strong Helm phrases (see above). | | **Wrong namespace / release not found** | Ensure `meta.helm.sh/release-namespace` or `helm_namespace` / `k8s_namespace` annotations match the release; set `default_namespace` in config when alerts lack namespace. |