Helm (CLI)

HealOps 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/healops/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=

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):

# 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/healops/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

healops 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, HealOps 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:

{
  "labels": {
    "meta.helm.sh/release-name": "my-api",
    "meta.helm.sh/release-namespace": "prod"
  },
  "annotations": {
    "summary": "Errors after helm upgrade"
  }
}

Then run:

healops 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.

Overview

LLM providers

Observability and incidents

Cloud, code, and collaboration

Messaging

Data and workflow systems

Prerequisites

Setup

Option 1: Environment variables

Option 2: Persistent store

Verify

Usage in investigations

Investigation tools

Evidence keys

Advanced

Security and operations

Troubleshooting

​Prerequisites

​Setup

​Option 1: Environment variables

​Option 2: Persistent store

​Verify

​Usage in investigations

​Investigation tools

​Evidence keys

​Advanced

​Security and operations

​Troubleshooting

Prerequisites

Setup

Option 1: Environment variables

Option 2: Persistent store

Verify

Usage in investigations

Investigation tools

Evidence keys

Advanced

Security and operations

Troubleshooting