Overview

Deploy Helm charts to a Kubernetes cluster using Harness CD.

A Helm stage lets you deploy applications packaged as Helm charts to any Kubernetes cluster. You configure a Native Helm service with your chart and values, point it at a Helm infrastructure definition, choose a deployment strategy, and Harness manages the full Helm release lifecycle: install, upgrade, and rollback.

---

Before you begin

• A Kubernetes cluster with outbound HTTPS access to app.harness.io.

• A delegate running in the cluster. Go to Getting Started to install one.

• A Helm chart in a Git repository, Helm repository, OCI registry, S3, or GCS.

---

Set up a Helm deployment

When you create a pipeline, Harness adds a default Stage 1 automatically. You can edit it and add a deployment target, service, and environment, but editing an existing stage does not give you the execution strategy wizard and you have to add steps manually.

To get the strategy wizard, create a new stage:

1. Go to Pipelines and select Create Pipeline. Enter a name, select Inline or a Git store, and select Create.

2. Delete the default Stage 1, then select + to add a new stage.

3. Select Deploy and select Next.

4. Enter a stage name and set Deployment Target to Native Helm. Select Next.

The wizard then walks you through service, environment, and strategy. The sections below explain each piece.

---

Service

A Helm service holds the chart source, values files, and service-level variables. The service deployment type is Native Helm. Services are reusable — configure once and reference across multiple stages and pipelines. Stages can override values files and variables per deployment without changing the shared service definition.

Go to Helm services to configure chart sources and values overrides.

---

Environment and infrastructure

An environment is a logical target (dev, staging, production). The infrastructure definition within the environment is a Native Helm infrastructure — it points to the Kubernetes cluster and namespace where Harness runs the Helm release. It references a Kubernetes connector, which uses a Delegate running inside your network to connect to the cluster.

Go to Helm infrastructure to configure environments, infrastructure definitions, and connectors.

---

Deployment strategies

Strategy	What it does
Helm Basic Deploy Strategy	Runs helm upgrade --install in a single phase. Suitable for most workloads.
Helm Canary Deploy Strategy	Deploys a canary release at a reduced instance count alongside the stable release, then promotes to full rollout.
Helm Blue Green Deploy Strategy	Brings up a full new Helm release, routes staging traffic to it, then swaps production traffic once validated.
Blank canvas	No steps pre-populated. Build the execution sequence manually.

Go to Helm deployment strategies to view step-by-step walkthroughs.

Additional steps

The strategy wizard adds the minimum steps for the selected strategy. You can add further Helm steps to extend the stage.

Step	What it does
Helm Basic Deploy	Run helm upgrade --install as a standalone step
Helm Rollback	Roll back a Helm release to a previous revision
Helm Delete	Delete a Helm release from the cluster
Helm Canary Deploy	Deploy a canary release at a specified instance count
Helm Canary Delete	Remove the canary release before promoting to full rollout
Helm Blue Green Deploy	Deploy the new release to the stage environment
Helm Blue Green Swap	Swap traffic from the stage environment to production

---

Stage settings

Each stage has a set of settings accessible from the stage editor, organized into four sections: Code & build, Inputs & outputs, Execution controls, and Runtime Environment.

---

Code & build

Controls whether the stage clones source code before running steps. Set to false to skip cloning (disabled by default).

clone: false

---

Inputs & outputs

Define this stage's inputs, environment variables, and outputs.

Inputs — declare typed inputs available as ${{inputs.<name>}} within the stage.

inputs:
  target_env:
    type: environment
    description: Target deployment environment

Outputs — declare typed outputs the stage produces, available to downstream stages.

outputs:
  release_id:
    type: string

Environment variables — set key-value pairs available to all steps in the stage.

env:
  APP_ENV: production
  LOG_LEVEL: info

---

Execution controls

Set conditions, looping strategy, concurrency, failure strategy, and timeout.

Strategy — configures a looping strategy so the stage runs multiple times across a set of values or conditions.

Matrix — runs the stage for each combination of values in the matrix.

strategy:
  matrix:
    environment: [dev, staging, prod]
  max-concurrency: 2

For loop — runs the stage a fixed number of times.

strategy:
  for:
    iterations: 3

While loop — runs the stage until a condition is false or a max iteration count is reached.

strategy:
  while:
    max-iterations: 10
    condition: "${{some.expression}}"

Add fast-fail: true to any strategy to stop remaining iterations immediately if one fails.

Concurrency — limits how many instances of this stage can run simultaneously across pipeline executions.

On failure — defines what Harness does when the stage fails. Common actions are stage-rollback, retry, skip, and mark-as-success.

on-failure:
  errors: all
  action: stage-rollback

Conditional execution — controls whether the stage runs based on an expression evaluated at runtime.

when:
  condition: "${{inputs.deploy_env == 'prod'}}"

Timeout duration — maximum time the stage is allowed to run before Harness terminates it. Default: 24h.

timeout: 2h

---

Runtime Environment

Configure where the stage runs.

Platform — sets the operating system and CPU architecture for the stage execution environment.

OS	Supported architectures
Linux	AMD64, ARM64
macOS	ARM64 only
Windows	AMD64 only

platform:
  os: linux
  arch: amd64

Runtime — defines where steps in the stage run. This block is mandatory for Helm deployments — a stage without it cannot connect to a cluster and fails immediately.

Kubernetes (Ephemeral Pod) — steps run as pods on a cluster you specify.

runtime:
  kubernetes:
    namespace: <target-namespace>
    connector: <your-kubernetes-connector-id>

Harness Cloud — steps run on Harness-managed infrastructure. No cluster or delegate setup required.

runtime:
  cloud: {}

Delegate — steps run on a configured Harness delegate.

runtime:
  delegate: {}

Shared paths — use shared-paths to make additional filesystem paths available across steps in the stage.

shared-paths:
  - /shared/output

---

Next steps

• Go to Helm services to configure chart sources, values files, and artifact sources

• Go to Helm infrastructure to configure environments and infrastructure definitions

• Go to Basic deployment to walk through a single-phase Helm upgrade

• Go to Canary deployment to walk through a staged rollout with canary release

• Go to Blue-green deployment to walk through stage/production swap and rollback

• Go to Step reference to view all available Helm steps