Kubernetes

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

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 to install one.

---

What Harness deploys

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

To set up a Kubernetes deployment, use the deployment wizard to configure a service, environment, and execution strategy in sequence.

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. Select 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 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 to configure manifests, artifact sources, and values overrides.

---

Environment and infrastructure

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 to configure environments, infrastructure definitions, and connectors.

---

Deployment strategies

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 for step-by-step walkthroughs of each strategy.

Additional steps

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	Apply specific manifest files outside the standard rollout flow
Kubernetes Delete	Delete specific Kubernetes resources by name or selector
Kubernetes Diff	Preview what would change if manifests were applied, without applying them
Kubernetes Dry Run	Validate manifests server-side without creating resources
Kubernetes Patch	Modify a specific resource field without affecting the rest of the manifest
Kubernetes Rollout	Check or wait on the status of a Kubernetes rollout
Kubernetes Scale	Scale a workload to a target pod count or percentage
Kubernetes Steady State Check	Explicitly wait for a workload to reach steady state at any point in the stage
Kubernetes Traffic Shift	Shift a percentage of traffic between services during a staged rollout

---

Stage settings

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

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

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 any installed Classic Delegate or Delegate 3.x (on Harness Cloud for deployments).

runtime:
  delegate: {}

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

shared-paths:
  - /shared/output

---

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

---

Next steps

• Go to Kubernetes services to configure manifests, artifact sources, and values overrides

• Go to Kubernetes infrastructure to configure environments, infrastructure definitions, and connectors

• Go to Rolling deployment to learn the step sequence, YAML, and configuration

• Go to Canary deployment to learn the step sequence, traffic shifting, and promotion

• Go to Blue-green deployment to learn the stage/production swap and rollback

• Go to Blank canvas to manually build a stage for non-standard workloads

• Go to Step reference to review all available Kubernetes steps