> 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/kubernetes/overview.md).

# Overview

Deploy container images to a Kubernetes cluster using Harness CD.

A Kubernetes stage lets you deploy container-based applications to any Kubernetes cluster. You define the service (your manifests and images), the target infrastructure (cluster and namespace), and the deployment strategy. Harness manages the rollout, tracks release state, and rolls back automatically on failure.

***

### Before you begin <a href="#before-you-begin" id="before-you-begin"></a>

Before you add Kubernetes deployment steps to a stage, make sure you have:

* A Kubernetes cluster with outbound HTTPS access to `app.harness.io`, `github.com`, and `hub.docker.com`.
* A Kubernetes service account with `list`, `get`, `create`, and `delete` permissions on the target namespace. Cluster-admin or namespace admin permission is sufficient.
* A delegate running in the cluster. Go to [Getting Started](/continuous-delivery/3.0/new-to-deployments/get-started.md#step-1-install-a-delegate) to install one.

***

### What Harness deploys <a href="#what-harness-deploys" id="what-harness-deploys"></a>

Harness takes the Kubernetes manifests and container images you configure and applies them to the target cluster. You can source manifests from a Git repository, Helm chart, or Kustomize overlay.

A **managed workload** is a Kubernetes object that Harness deploys and tracks to steady state. If steady state is not reached, the deployment fails and the failure strategy runs (typically rollback). The table below shows which object types each strategy supports as managed workloads.

| Object type | Apply | Rolling | Rollback |  Blue Green  |    Canary    | Scale |
| ----------- | :---: | :-----: | :------: | :----------: | :----------: | :---: |
| Deployment  |  Yes  |   Yes   |    Yes   | Yes (1 only) | Yes (1 only) |  Yes  |
| DaemonSet   |  Yes  |   Yes   |    Yes   |      No      |      No      |  Yes  |
| CRDs        |  Yes  |   Yes   |    Yes   |      No      |      No      |   No  |
| Any object  |  Yes  |    No   |    No    |      No      |      No      |   No  |

To deploy objects outside this list alongside a managed workload, add the annotation `harness.io/direct-apply: "true"` to the manifest. Harness applies these as unmanaged workloads without tracking steady state.

***

### Set up a Kubernetes deployment <a href="#set-up-a-kubernetes-deployment" id="set-up-a-kubernetes-deployment"></a>

When you create a pipeline, Harness adds a default **Stage 1** automatically. You can edit this stage: add a deployment target (for example, Kubernetes), then add a service and environment. The stage also has options for clone, platform, runtime, shared path, and strategy (looping strategy, failure strategy, and fast-fail).

However, **editing an existing stage does not give you the execution strategy wizard**. You can add service and environment, but you have to add deployment steps manually.

To get the full deployment wizard (including the execution strategy step where you choose Rolling, Canary, or Blue-green), you need to **create a new stage**:

1. Go to the **Pipelines** section and click **Create Pipeline**.
2. Enter a pipeline name. Under **Storage**, select **Inline** (Harness manages the pipeline YAML) or a Git repository (Harness Code, GitHub, GitLab, or Bitbucket). Click **Create**.
3. A default **Stage 1** is added. Delete it, then click the **+** icon to add a new stage.
4. When prompted with "What would you like to do?", select **Deploy** and click **Next**. Other options here include Build and Test, Blank Canvas, Use Template, and Chain Pipeline; Deploy is what triggers the deployment configuration wizard.
5. Enter a stage name, set **Deployment Target** to **Kubernetes**, and click **Next**.

The wizard then walks you through configuring the service, environment, and execution strategy in sequence. The sections below explain each piece.

***

### Service <a href="#service" id="service"></a>

A **service** in Harness represents what you deploy. It holds the Kubernetes manifests (or Helm charts, Kustomize overlays), artifact sources, config files, and service-level variables. Services are independent of pipelines; you configure them once and reuse them across stages and pipelines.

When you configure a stage, you either create a new service inline or pick an existing one. The stage can override service-level variables and artifact sources for that specific deployment without changing the shared service definition.

Go to [Kubernetes services](/continuous-delivery/3.0/use-deployments/kubernetes/kubernetes-services.md) to configure manifests, artifact sources, and values overrides.

***

### Environment and infrastructure <a href="#environment-and-infrastructure" id="environment-and-infrastructure"></a>

An **environment** is a logical deployment target: development, staging, or production. An **infrastructure definition** within an environment points to the actual Kubernetes cluster and namespace where Harness runs the deployment.

The infrastructure definition references a **Kubernetes connector**, which authenticates to the cluster. The connector uses a **Delegate** running inside your network to connect to the cluster; no inbound access to your environment is required. The Delegate picks up tasks from Harness and executes steps on its behalf.

Go to [Kubernetes infrastructure](/continuous-delivery/3.0/use-deployments/kubernetes/kubernetes-infrastructure.md) to configure environments, infrastructure definitions, and connectors.

***

### Deployment strategies <a href="#deployment-strategies" id="deployment-strategies"></a>

Harness supports the following Kubernetes strategies. Select the one that fits your release pattern when you add a stage.

| Strategy         | What it does                                                                                                                                                                               |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Rolling**      | Applies updated manifests incrementally. Uses `25% max unavailable, 25% max surge` by default.                                                                                             |
| **Canary**       | Deploys a subset of pods with the new version alongside stable pods, then shifts traffic when the canary is healthy.                                                                       |
| **Blue Green**   | Brings up a full new environment, routes staging traffic to it, then swaps production traffic once validated.                                                                              |
| **Blank canvas** | No steps are pre-populated. Build the execution sequence manually. Use this for non-standard workloads such as Jobs, CronJobs, and ConfigMaps that do not need a managed rollout strategy. |

Go to [Kubernetes deployment strategies](/continuous-delivery/3.0/use-deployments/kubernetes/kubernetes-deployment-strategies/rolling.md) for step-by-step walkthroughs of each strategy.

### Additional steps <a href="#additional-steps" id="additional-steps"></a>

When the strategy wizard populates a stage, it adds the minimum steps needed for that strategy. You can add further Kubernetes steps to the stage to extend the pipeline, before, after, or between the strategy steps.

| Step                                                                                                                        | What it does                                                                   |
| --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| [Kubernetes Apply](/continuous-delivery/3.0/use-deployments/kubernetes/step-library/k8s-apply.md)                           | Apply specific manifest files outside the standard rollout flow                |
| [Kubernetes Delete](/continuous-delivery/3.0/use-deployments/kubernetes/step-library/k8s-delete.md)                         | Delete specific Kubernetes resources by name or selector                       |
| [Kubernetes Diff](/continuous-delivery/3.0/use-deployments/kubernetes/step-library/k8s-diff.md)                             | Preview what would change if manifests were applied, without applying them     |
| [Kubernetes Dry Run](/continuous-delivery/3.0/use-deployments/kubernetes/step-library/k8s-dry-run.md)                       | Validate manifests server-side without creating resources                      |
| [Kubernetes Patch](/continuous-delivery/3.0/use-deployments/kubernetes/step-library/k8s-patch.md)                           | Modify a specific resource field without affecting the rest of the manifest    |
| [Kubernetes Rollout](/continuous-delivery/3.0/use-deployments/kubernetes/step-library/k8s-rollout.md)                       | Check or wait on the status of a Kubernetes rollout                            |
| [Kubernetes Scale](/continuous-delivery/3.0/use-deployments/kubernetes/step-library/k8s-scale.md)                           | Scale a workload to a target pod count or percentage                           |
| [Kubernetes Steady State Check](/continuous-delivery/3.0/use-deployments/kubernetes/step-library/k8s-steady-state-check.md) | Explicitly wait for a workload to reach steady state at any point in the stage |
| [Kubernetes Traffic Shift](/continuous-delivery/3.0/use-deployments/kubernetes/step-library/k8s-traffic-shift.md)           | Shift a percentage of traffic between services during a staged rollout         |

***

### 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: **Code & build**, **Inputs & outputs**, **Execution controls**, and **Runtime Environment**.

***

#### 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
```

***

#### 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 Kubernetes 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 Harness delegate.

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

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

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

***

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

* Go to [Kubernetes services](/continuous-delivery/3.0/use-deployments/kubernetes/kubernetes-services.md) to configure manifests, artifact sources, and values overrides
* Go to [Kubernetes infrastructure](/continuous-delivery/3.0/use-deployments/kubernetes/kubernetes-infrastructure.md) to configure environments, infrastructure definitions, and connectors
* Go to [Rolling deployment](/continuous-delivery/3.0/use-deployments/kubernetes/kubernetes-deployment-strategies/rolling.md) to learn the step sequence, YAML, and configuration
* Go to [Canary deployment](/continuous-delivery/3.0/use-deployments/kubernetes/kubernetes-deployment-strategies/canary.md) to learn the step sequence, traffic shifting, and promotion
* Go to [Blue-green deployment](/continuous-delivery/3.0/use-deployments/kubernetes/kubernetes-deployment-strategies/blue-green.md) to learn the stage/production swap and rollback
* Go to [Blank canvas](/continuous-delivery/3.0/use-deployments/kubernetes/kubernetes-deployment-strategies/blank-canvas.md) to manually build a stage for non-standard workloads
* Go to [Step reference](/continuous-delivery/3.0/use-deployments/kubernetes/step-library/k8s-apply.md) to review all available Kubernetes steps

{% @harness-feedback/feedback %}