Helm Release Health Sentinel for Kestra

id: helm-release-health-sentinel
namespace: company.team
description: |
  On a schedule, read-only check a Helm release's current status via
  `helm status` (nothing is installed, upgraded, or rolled back) and
  classify it as HEALTHY, WARNING, CRITICAL, or UNREACHABLE. Log clean
  runs and page Slack the moment a release is stuck mid-operation or has
  failed outright.

inputs:
  - id: release_name
    type: STRING
    defaults: "my-app"
    displayName: "Helm Release Name"
    description: "Name of the Helm release to check."
  - id: release_namespace
    type: STRING
    defaults: "default"
    displayName: "Kubernetes Namespace"
    description: "Namespace holding the release."
  - id: environment
    type: STRING
    defaults: "production"
    displayName: "Environment Label"
    description: "Recorded on the Status task's emitted Asset metadata as the
      environment key, e.g. production."

triggers:
  - id: release_health_schedule
    type: io.kestra.plugin.core.trigger.Schedule
    description: Check the release every 15 minutes. Shipped disabled; enable it
      once release_name/release_namespace point at a real cluster and a manual
      run has been verified.
    cron: "*/15 * * * *"
    disabled: true
    inputs:
      release_namespace: "default"
      environment: "production"

tasks:
  - id: check_release_status
    type: io.kestra.plugin.helm.Status
    description: Run helm status and helm get manifest to report the release's
      current revision and status. Changes nothing on the cluster.
    releaseName: "{{ inputs.release_name }}"
    namespace: "{{ inputs.release_namespace }}"
    environment: "{{ inputs.environment }}"
    connection:
      masterUrl: "{{ secret('K8S_MASTER_URL') }}"
      caCertData: "{{ secret('K8S_CA_CERT') }}"
      oauthToken: "{{ secret('K8S_TOKEN') }}"
    allowFailure: true

  - id: classify_release_health
    type: io.kestra.plugin.core.debug.Return
    description: Classify the release's reported status, treating a missing output
      as a cluster or release-lookup failure, any pending/transitional state as
      a stuck-operation warning, and anything else that is not the healthy
      deployed state as critical.
    format: "{{ outputs.check_release_status.status is not defined ? 'UNREACHABLE' :
      (outputs.check_release_status.status == 'deployed' ? 'HEALTHY' :
      ((outputs.check_release_status.status == 'pending-install' or
      outputs.check_release_status.status == 'pending-upgrade' or
      outputs.check_release_status.status == 'pending-rollback' or
      outputs.check_release_status.status == 'uninstalling') ? 'WARNING' :
      'CRITICAL')) }}"

  - id: route_by_release_health
    type: io.kestra.plugin.core.flow.Switch
    description: Route to a quiet log on a deployed release, an informational Slack
      message on a release stuck in a transitional state, or a Slack page for a
      failed or unreachable release.
    value: "{{ outputs.classify_release_health.value }}"
    cases:
      "HEALTHY":
        - id: log_healthy
          type: io.kestra.plugin.core.log.Log
          message: "Helm release {{ inputs.release_name }} in namespace {{
            inputs.release_namespace }} is healthy: status deployed at revision
            {{ outputs.check_release_status.revision }}."
      "WARNING":
        - id: alert_warning_status
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          description: Post an informational Slack message when the release is sitting in
            a pending or uninstalling state, which should normally resolve
            quickly on its own.
          url: "{{ secret('SLACK_WEBHOOK_URL') }}"
          payload: |
            {
              "text": "Helm release sentinel WARNING: release {{ inputs.release_name }} in namespace {{ inputs.release_namespace }} is reporting status '{{ outputs.check_release_status.status }}' at revision {{ outputs.check_release_status.revision }}. This should normally resolve within minutes; if it persists across the next check, an upgrade or rollback may be stuck. Execution {{ execution.id }}."
            }
      "CRITICAL":
        - id: alert_critical_status
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          description: Page Slack when the release is reporting a failed or otherwise
            unhealthy terminal status.
          url: "{{ secret('SLACK_WEBHOOK_URL') }}"
          payload: |
            {
              "text": "Helm release sentinel CRITICAL: release {{ inputs.release_name }} in namespace {{ inputs.release_namespace }} is reporting status '{{ outputs.check_release_status.status }}' at revision {{ outputs.check_release_status.revision }}. This release is not in the deployed state. Execution {{ execution.id }}."
            }
      "UNREACHABLE":
        - id: alert_unreachable_release
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          description: Page Slack when helm status could not return the release's state at
            all, indicating the cluster is unreachable or the release does not
            exist.
          url: "{{ secret('SLACK_WEBHOOK_URL') }}"
          payload: |
            {
              "text": "Helm release sentinel UNREACHABLE: checking release {{ inputs.release_name }} in namespace {{ inputs.release_namespace }} did not return a status (cluster unreachable, credentials invalid, or release not found). Execution {{ execution.id }}."
            }
    defaults:
      - id: log_unclassified
        type: io.kestra.plugin.core.log.Log
        message: "Helm release sentinel completed with an unexpected classification: {{
          outputs.classify_release_health.value }}."

  - id: log_audit_result
    type: io.kestra.plugin.core.log.Log
    description: Record a single audit line for every run regardless of branch
      taken, including the chart, chart version, and revision, so the check's
      own history stays queryable independent of Slack.
    message: "Helm release sentinel audit: release={{ inputs.release_name }}
      namespace={{ inputs.release_namespace }} status={{
      outputs.classify_release_health.value }} helm_status={{
      outputs.check_release_status.status is defined ?
      outputs.check_release_status.status : 'n/a' }} revision={{
      outputs.check_release_status.revision is defined ?
      outputs.check_release_status.revision : 'n/a' }} chart={{
      outputs.check_release_status.chart is defined ?
      outputs.check_release_status.chart : 'n/a' }} execution={{ execution.id
      }}."

errors:
  - id: alert_flow_failure
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    description: Alert Slack when the sentinel flow itself fails outright, so a
      broken check is never mistaken for a healthy release.
    url: "{{ secret('SLACK_WEBHOOK_URL') }}"
    payload: |
      {
        "text": "Helm release sentinel flow {{ flow.id }} FAILED (execution {{ execution.id }}). Health of release {{ inputs.release_name }} in namespace {{ inputs.release_namespace }} is now unknown; check the task logs and the cluster manually."
      }

outputs:
  - id: status
    type: STRING
    value: "{{ outputs.classify_release_health.value }}"

A Helm release can get stuck mid-upgrade or land in a failed state long after the person who ran helm upgrade has moved on, and nothing in Helm itself pages anyone about it. This blueprint turns a scheduled, read-only helm status call into a Day 2 health gate: io.kestra.plugin.helm.Status reports the release's current revision and status without changing anything on the cluster, a single Pebble expression classifies that status, and the result routes to a quiet log, an informational Slack note, or a Slack page depending on severity.

How it works

check_release_status (io.kestra.plugin.helm.Status) runs helm status and helm get manifest for release_name in release_namespace, using the same cluster connection model as the Kubernetes plugin. It returns status, revision, chart, chartVersion, firstDeployed, lastDeployed, and the release's managed resources, without installing, upgrading, or rolling anything back. allowFailure: true keeps a cluster or release lookup failure from aborting the flow outright.
classify_release_health (io.kestra.plugin.core.debug.Return) evaluates a single Pebble expression against the reported status: missing entirely becomes UNREACHABLE, deployed becomes HEALTHY, any of Helm's transitional states (pending-install, pending-upgrade, pending-rollback, uninstalling) becomes WARNING, and anything else (failed, unknown, or any other value) becomes CRITICAL.
route_by_release_health (io.kestra.plugin.core.flow.Switch) branches on that classification: HEALTHY logs a quiet confirmation; WARNING posts an informational Slack note; CRITICAL and UNREACHABLE each page Slack with the reported status and revision; a defaults fallback logs the raw value for any classification outside the four known cases.
log_audit_result (io.kestra.plugin.core.log.Log) writes one audit line per run, independent of which Switch branch fired, including the chart name and revision, so the check's own history stays queryable even if Slack delivery fails.
The flow-level errors block pages Slack separately if the flow fails outright, so a broken sentinel is never mistaken for a healthy release.
The release_health_schedule trigger checks every 15 minutes and ships disabled: true, with explicit inputs: overrides for release_namespace and environment so the scheduled run's target is pinned regardless of this flow's own defaults.

What you get

A scheduled, read-only health check for any Helm release with zero custom helm CLI scripting.
A single status output (HEALTHY / WARNING / CRITICAL / UNREACHABLE) other flows can gate on.
Three distinct Slack messages, one per severity, each carrying the release's reported Helm status and revision.
An audit log line on every run, separate from Slack, carrying the chart and revision, so the check's own history survives a webhook outage.

Who it's for

Platform teams running Helm-deployed services who have no orchestrator-side check for a release stuck between deploys.
On-call engineers who want a signal that an upgrade or rollback never finished, before the next deploy collides with it.
Teams standardizing Day 2 release health monitoring across multiple clusters inside Kestra without writing a bespoke helm status cron script.

Why orchestrate this with Kestra

A cron job that shells out to helm status and greps the output is invisible the moment it succeeds and brittle the moment Helm's text output changes format. Kestra's Status task parses the release state into typed fields, so the check, the classification, and the Slack call are all one auditable execution history, with the Switch branch ready to grow into real remediation (triggering the existing rollback pattern, opening a ticket) without rewriting the check itself.

Prerequisites

A Kubernetes cluster reachable via connection (the same model as the Kubernetes plugin) with an existing Helm release named release_name in release_namespace.
A Slack incoming webhook for the WARNING, CRITICAL, UNREACHABLE, and flow-failure alerts.

Secrets

K8S_MASTER_URL, K8S_CA_CERT, K8S_TOKEN: cluster connection details for the connection block (same secrets already used by the existing helm-gated-release-with-rollback blueprint).
SLACK_WEBHOOK_URL: Slack incoming webhook used for every alert branch and the flow-failure alert.

In Kestra OSS (no Enterprise secrets backend), secrets are supplied as environment variables prefixed SECRET_, base64-encoded, and read back in flows with {{ secret('NAME') }}, for example SECRET_SLACK_WEBHOOK_URL=$(echo -n 'https://hooks.slack.com/services/<placeholder>' | base64). This keeps credentials out of the flow YAML but, per Kestra's own documentation, offers no encryption at rest or access control beyond the host environment; use the Enterprise secrets backend for stronger guarantees.

Quick start

Start a local single-node Kubernetes cluster in Docker, on its own API server port well away from Kestra's own UI: docker run -d --name k3s-server --privileged -p 6443:6443 rancher/k3s:latest server --tls-san=localhost
If Kestra is also running in Docker, attach the cluster to Kestra's network so the worker can reach it by container name: docker network connect YOUR_KESTRA_NETWORK k3s-server
Pull the cluster's kubeconfig and install a sample release to check: docker exec k3s-server cat /etc/rancher/k3s/k3s.yaml helm install my-app oci://registry-1.docker.io/bitnamicharts/nginx --namespace default --kubeconfig <path-from-previous-step>
Derive K8S_MASTER_URL, K8S_CA_CERT, and K8S_TOKEN from that kubeconfig, add them along with SLACK_WEBHOOK_URL as secrets, and run the flow once manually to confirm status reads HEALTHY.
Enable release_health_schedule once pointed at a real cluster and release.

How to extend

Chain a CRITICAL branch into the existing rollback pattern (io.kestra.plugin.helm.Rollback) for automatic remediation instead of a Slack page alone.
Loop this flow's release_name/release_namespace inputs over every release a team owns using io.kestra.plugin.core.flow.Loop, instead of checking one release per execution.
Add a staleness check on lastDeployed if your team also wants to know when a release has not been touched in a long time, as a separate signal from its current status.
Push status into a KV store and alert only on state transitions instead of every run.

Inputs

release_name: the Helm release to check.
release_namespace: the namespace holding the release.
environment: recorded as Asset metadata on the Status task; not used in the classification itself.

Outputs

status: one of HEALTHY, WARNING, CRITICAL, UNREACHABLE.

Pitfalls

Status reports the release's state as of the moment the call runs; a brief pending-upgrade window during a fast, healthy deploy can be caught by an unlucky poll and reported as WARNING even though the upgrade finishes seconds later. Treat a single WARNING as a prompt to check again before escalating, not as a confirmed incident.
This flow only ever calls helm status/helm get manifest; it never calls helm upgrade, helm rollback, or helm uninstall, so there is nothing destructive to default to dry-run for.
A release that was intentionally uninstalled will typically make helm status report nothing at all (not a status value of uninstalled), which this flow treats as UNREACHABLE; do not point this at a release you expect to be gone.
connection and kubeconfig are mutually exclusive on this task; this blueprint uses connection to match the existing helm-gated-release-with-rollback blueprint's convention.