> 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/step-library/k8s-steady-state-check.md).

# Kubernetes Steady State Check

The Kubernetes Steady State Check step watches workloads until all pods are running and ready, or until the step times out. Use it after a Kubernetes Apply step, a Scale step, or any operation that modifies workloads but does not have a built-in wait.

Most Harness deployment strategies, Rolling, Canary, and Blue-Green, include a steady-state check automatically. Use the standalone step when you deploy with the Apply step, use custom or unmanaged workloads, or disable the built-in check on another step and want to defer it.

***

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

Before you configure the step, make sure you have the following in place:

* **A Kubernetes service:** Go to [Kubernetes services](/continuous-delivery/3.0/use-deployments/kubernetes/kubernetes-services.md) to set up service manifests and an artifact source.
* **A Kubernetes infrastructure:** Go to [Kubernetes infrastructure](/continuous-delivery/3.0/use-deployments/kubernetes/kubernetes-infrastructure.md) to connect your cluster and namespace.
* **A Harness delegate in the target cluster:** The delegate runs deployment steps in the cluster.
* **Runtime configuration:** Every Kubernetes stage requires a `runtime` block specifying a connector and namespace. Go to [Kubernetes runtime configuration](/continuous-delivery/3.0/use-deployments/kubernetes/overview.md#kubernetes-runtime-configuration) to understand the required fields.

***

### Add the Kubernetes Steady State Check step <a href="#add-the-kubernetes-steady-state-check-step" id="add-the-kubernetes-steady-state-check-step"></a>

To add the step:

1. In your pipeline, go to the Kubernetes stage.
2. Select **+ Add Step** in the execution section.
3. Search for **Kubernetes Steady State Check** and select it.
4. Configure the step parameters described below.
5. Select **Apply Changes**.

***

### Configure the step <a href="#configure-the-step" id="configure-the-step"></a>

The following parameters are available on the Kubernetes Steady State Check step.

| Parameter             | Description                                                                                                                                                 | Required      |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| **Name**              | Display name for the step in the pipeline.                                                                                                                  | Required      |
| **Kubeconfig Path**   | Path to the kubeconfig file, derived from the infrastructure configuration. Default: `${{infra.kube_config_path}}`.                                         | Required      |
| **Manifest Path**     | One or more relative paths to the manifest files containing the workloads to watch. Harness resolves workload identifiers from these files.                 | Conditional\* |
| **Managed Workloads** | Comma-separated or JSON array of workloads managed by a preceding step, in `namespace/Kind/resource-name` format. For example, `default/Deployment/my-app`. | Conditional\* |
| **Custom Workloads**  | Comma-separated or JSON array of unmanaged workloads to watch, in `namespace/Kind/resource-name` format.                                                    | Conditional\* |
| **Namespace**         | Target namespace on the cluster. Default: `default`.                                                                                                        | Optional      |
| **Release Name**      | Release name used to identify the cluster release secret. Default: `${{infra.releaseName}}`.                                                                | Optional      |
| **Timeout**           | Maximum time the step waits for workloads to reach steady state. Default: `10m`.                                                                            | Optional      |

\*At least one of **Manifest Path**, **Managed Workloads**, or **Custom Workloads** is required. The step fails with a configuration error if all three are empty.

***

### Specify workloads to watch <a href="#specify-workloads-to-watch" id="specify-workloads-to-watch"></a>

You can identify workloads in three ways, and you can combine them:

**Manifest Path:** Provide the path to a rendered manifest file. Harness parses the file to find all managed workload resources and watches them. This is the most common approach when using the step after a Kubernetes Apply step.

Use the output expression from a preceding Apply step to pass the manifest path automatically:

```
<+steps.[Apply_Step_Id].output.outputVariables.manifest>
```

**Managed Workloads:** Specify workloads by identity in `namespace/Kind/resource-name` format. Use this when you know the workloads explicitly or want to watch workloads from a preceding step by expression:

```
<+steps.[Apply_Step_Id].output.outputVariables.managedWorkloads>
```

**Custom Workloads:** Specify workloads that Harness does not manage as part of a release. Use the same `namespace/Kind/resource-name` format.

***

### Supported workload types <a href="#supported-workload-types" id="supported-workload-types"></a>

The step supports the following workload types:

* Deployment
* DaemonSet
* Job
* DeploymentConfig (OpenShift)

***

### YAML example <a href="#yaml-example" id="yaml-example"></a>

```yaml
- name: Kubernetes Steady State Check
  id: k8sSteadyStateCheck
  template:
    uses: k8sSteadyStateCheck
    with:
      managed_workloads: '<+steps.k8sApplyStep.output.outputVariables.managedWorkloads>'
      timeout: "10m"
```

To watch workloads from a manifest path:

```yaml
- name: Kubernetes Steady State Check
  id: k8sSteadyStateCheck
  template:
    uses: k8sSteadyStateCheck
    with:
      manifest_path: '<+steps.k8sApplyStep.output.outputVariables.manifest>'
      timeout: "10m"
```

***

### How the step works <a href="#how-the-step-works" id="how-the-step-works"></a>

When the step runs, Harness does the following:

1. Resolves the list of workloads from the manifest path, managed workloads, or custom workloads inputs.
2. Opens a watch connection to the Kubernetes API for each workload.
3. Waits until each workload reports all pods running and ready, or until the overall step timeout is reached.
4. On success, runs `kubectl describe` on each watched resource and logs the output.

The step uses Kubernetes Watch API calls with a 5-minute timeout per watch call. If a watch call times out, Harness opens a new watch call and continues waiting until the overall step timeout is reached.

***

### Read the step output <a href="#read-the-step-output" id="read-the-step-output"></a>

The step log shows each workload being watched and the final pod status for each resource.

The step exposes the following output variables you can reference in downstream steps.

| Output variable | Description                                                                                                                  |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `pods`          | Details of the pods after the steady-state check completes. Reference with `<+steps.[Step_Id].output.outputVariables.pods>`. |
| `skipped`       | Boolean indicating whether the steady-state check was skipped.                                                               |

***

### Advanced settings <a href="#advanced-settings" id="advanced-settings"></a>

The following advanced settings are available on the Kubernetes Steady State Check step.

* **Timeout duration**: Maximum time the step is allowed to run before being terminated.
* **On failure**: Define what happens if the step fails, such as retry, mark as success, or abort.
* **Strategy**: Configure a looping strategy to run this step over a list of values.
* **Conditional execution**: Run this step only when a specified condition is true.

***

### Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

**Step times out before workloads are ready**

The default timeout is `10m`. If your workloads take longer to reach steady state, for example, if image pulls are slow or init containers run long, increase the **Timeout** value on the step.

**Step fails with "KUBECONFIG\_PATH is required"**

The Kubeconfig Path field cannot be empty. Verify that your infrastructure connector is configured and that the kubeconfig path expression resolves correctly for your environment.

**Step fails with "at least one of manifest path, managed workloads, or custom workloads must be provided"**

You must specify at least one workload source. If you are using this step after a Kubernetes Apply step, pass the `managedWorkloads` output expression from the Apply step into the **Managed Workloads** field.

***

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

* Go to [Kubernetes Apply](/continuous-delivery/3.0/use-deployments/kubernetes/step-library/k8s-apply.md) to apply manifests before checking steady state.
* Go to [Kubernetes Scale](/continuous-delivery/3.0/use-deployments/kubernetes/step-library/k8s-scale.md) to scale workloads before verifying health.
* Go to [Failure strategies](/harness-ai/use-harness-platform/pipelines/failure-handling/define-a-failure-strategy-on-stages-and-steps.md) to configure what happens when the steady-state check fails.