tracer-cloud--opensre/docs/helm.mdx

---
title: "Helm (CLI)"
description: "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.

<Note>
  **Helm 2 is not supported.** Verification checks `helm version` and requires a Helm **3.x** client.
</Note>

## 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
# 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
# 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
{
  "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
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
{
  "labels": {
    "meta.helm.sh/release-name": "my-api",
    "meta.helm.sh/release-namespace": "prod"
  },
  "annotations": {
    "summary": "Errors after helm upgrade"
  }
}
```

Then run:

```bash
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 `./tests/e2e/kubernetes/helm/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. |