> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/continuous-delivery/3.0/use-deployments/overview-1.md).

# Helm

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 href="#before-you-begin" id="before-you-begin"></a>

* 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 <a href="#set-up-a-helm-deployment" id="set-up-a-helm-deployment"></a>

1. Go to **Pipelines** and select **Create Pipeline**. Enter a name, select **Inline** or a Git store, and select **Start**. Harness creates an empty pipeline with no stages.
2. Select **Add Stage**, then select **Deploy**.
3. In **Specify details**, 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 href="#service" id="service"></a>

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 <a href="#environment-and-infrastructure" id="environment-and-infrastructure"></a>

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 <a href="#deployment-strategies" id="deployment-strategies"></a>

| 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 <a href="#additional-steps" id="additional-steps"></a>

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 <a href="#stage-settings" id="stage-settings"></a>

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

***

#### Runtime Environment <a href="#runtime-environment" id="runtime-environment"></a>

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              |

```yaml
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.

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

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

```yaml
runtime:
  cloud: {}
```

**Delegate** — steps run on a configured Classic Delegate or [Delegate 3.x](https://developer.harness.io/harness-platform/3.0/harness-platform-resources/delegates) (on Harness Cloud for deployments).

```yaml
runtime:
  delegate: {}
```

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

```yaml
shared-paths:
  - /shared/output
```

***

#### Code & build <a href="#code-and-build" id="code-and-build"></a>

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

```yaml
clone: false
```

***

#### Inputs & outputs <a href="#inputs-and-outputs" id="inputs-and-outputs"></a>

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

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

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

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

```yaml
outputs:
  release_id:
    type: string
```

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

```yaml
env:
  APP_ENV: production
  LOG_LEVEL: info
```

***

#### Execution controls <a href="#execution-controls" id="execution-controls"></a>

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.

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

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

```yaml
strategy:
  for:
    iterations: 3
```

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

```yaml
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`.

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

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

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

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

```yaml
timeout: 2h
```

***

### Next steps <a href="#next-steps" id="next-steps"></a>

* 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

{% @harness-feedback/feedback %}
