> 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/use-continuous-delivery/deploy-services-on-different-platforms/kubernetes/kubernetes-executions/k8s-diff-step.md). # K8s Diff step Compare the live state of deployed Kubernetes resources with changes defined in a YAML file using the K8s Diff step {% hint style="info" %} This feature is in Beta[^1] and requires enablement. [View all early access features.](/release-notes/features.md) {% @harness-feature-flag-access/request-feature-flag-access module="continuous-delivery" pagePath="continuous-delivery/use-continuous-delivery/deploy-services-on-different-platforms/kubernetes/kubernetes-executions/k8s-diff-step" featureFlags="%5B%7B%22name%22%3A%22K8s%20diff%20tab%22%2C%22key%22%3A%22CDS\_K8S\_DIFF\_VIEW%22%2C%22status%22%3A%22BETA%22%2C%22description%22%3A%22Adds%20a%20K8s%20diff%20tab%20to%20the%20K8s%20Diff%20step%20that%20shows%20a%20searchable%20list%20of%20the%20changed%20resources%2C%20with%20a%20line-by-line%2C%20color-coded%20diff%20for%20the%20selected%20file.%22%7D%5D" %} {% endhint %} Use the `kubectl diff` command to compare the current live state of deployed Kubernetes resources with changes defined in a YAML file. This preview helps catch unintended modifications and prevent misconfigurations before deployment. The command used in this step is `kubectl diff -f `. *** ## What you will learn from this topic * How to [add a K8s Diff step](#add-the-k8s-diff-step) to a Kubernetes Deploy stage * How to configure the step [parameters and advanced settings](#configure-step-parameters) * How to read the [execution logs](#read-execution-output) produced by the step * How to review the [K8s diff tab](#view-the-k8s-diff-tab) for a searchable, file-by-file diff * How to [link directly to the K8s diff tab](#link-directly-to-the-k8s-diff-tab) from an approval message or another step * How to troubleshoot [delegate selector errors](#troubleshooting) and understand the step [limitations](#limitations) *** ## Before you begin * **diffutils package**: Install the **diffutils** package on the system where the delegate runs `kubectl diff`. This package provides the utilities required to compare file differences. * **Kubernetes Deploy stage**: Add a step to a Harness Kubernetes Deploy stage that includes the step in a Harness Kubernetes Deploy stage that has a service with Kubernetes or Helm chart manifests. Go to [Kubernetes deployments](/continuous-delivery/use-continuous-delivery/deploy-services-on-different-platforms/kubernetes/kubernetes-cd-quickstart.md) to set up a stage. *** ## When to use the K8s Diff step You can add the K8s Diff step anywhere in the Deploy stage. It runs before changes are applied, so it is useful for reviewing potential modifications to Kubernetes resources. Here is an example of a K8s Diff step added before the Kubernetes rolling deployment: ![Pipeline execution view with a K8s Diff step placed before a Kubernetes rolling deployment step](https://3694223630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fy1JhZ4oKIppwY7d5AhPj%2Fuploads%2Fgit-blob-e37f1ee255b5cb6e0f0a4384ea1f64ff2f2d45ee%2Fk8s-diff-1.png?alt=media) *** ## Add the K8s Diff step Perform the following steps to add the K8s Diff step to your stage: 1. In your Harness Kubernetes Deploy stage execution view, click **Add Step**. 2. Select **K8s Diff** from the list of available steps. ![Add Step menu showing the K8s Diff step](https://3694223630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fy1JhZ4oKIppwY7d5AhPj%2Fuploads%2Fgit-blob-26d97093afdedd21c83050a8c8ef546ed309b668%2Fk8s-diff-2.png?alt=media) *** ## Configure step parameters Configure the following parameters for the K8s Diff step. * **Name**: Enter a name for the step. * **Timeout**: Enter a timeout duration. You can use the following timeout units: * `w` for weeks * `d` for days * `h` for hours * `m` for minutes * `s` for seconds * `ms` for milliseconds The maximum is `53w`. Save the step. No additional configuration is needed. The step automatically fetches the manifest resources from the configured **Service**. ### Advanced settings The **Advanced** tab provides the following options: * [Delegate Selector](https://developer.harness.io/docs/platform/delegates/manage-delegates/select-delegates-with-selectors) * [Conditional Execution](https://developer.harness.io/docs/platform/pipelines/step-skip-condition-settings) * [Failure Strategy](https://developer.harness.io/docs/platform/pipelines/failure-handling/define-a-failure-strategy-on-stages-and-steps) * [Looping Strategy](https://developer.harness.io/docs/platform/pipelines/looping-strategies/looping-strategies-matrix-repeat-and-parallelism) * [Policy Enforcement](https://developer.harness.io/docs/platform/governance/policy-as-code/harness-governance-overview)
YAML example ```yaml - step: type: K8sDiff name: K8sDiff identifier: K8sDiff spec: {} timeout: 10m ```
*** ## Read execution output After the K8s Diff step runs, review the execution logs for the computed difference. ![Execution logs for a completed K8s Diff step](https://3694223630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fy1JhZ4oKIppwY7d5AhPj%2Fuploads%2Fgit-blob-cd4c58f0156fa7f521d081cdfae24c16fad44020%2Fk8s-diff-3.png?alt=media) You can also find the difference in the output of the step: ![Step output panel showing the Kubernetes resource diff](https://3694223630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fy1JhZ4oKIppwY7d5AhPj%2Fuploads%2Fgit-blob-ccfdad23bf8b69ba4d66451b096ae7547593dce1%2Fk8s-diff-4.png?alt=media) *** ## View the K8s diff tab {% hint style="info" %} This tab is behind the feature flag `CDS_K8S_DIFF_VIEW`. Contact [Harness Support](mailto:support@harness.io) to enable the feature. {% endhint %} The step details panel for a K8s Diff step includes a **K8s diff** tab. This tab lists every changed manifest in a searchable file tree on the left, with a badge showing how many lines changed in each file. Select a file to see its line-by-line, color-coded diff on the right, which makes it easier to scan a large set of manifest changes than reading the raw execution output.
Open the **K8s diff** tab from the step details panel after the step runs, next to the other step tabs such as **Input** and **Output**. *** ## Link directly to the K8s diff tab You can construct a URL that opens a pipeline execution with a specific step tab already selected. This is useful when you want to send someone, such as an approver, straight to the K8s diff tab instead of asking them to navigate there manually. Append a `tab` query parameter to the step's execution URL, set to the tab identifier `K8S_DIFF_VIEW`: ``` <+<+execution.steps.STEP_ID.executionUrl>.concat("&tab=K8S_DIFF_VIEW")> ``` Replace `STEP_ID` with the K8s Diff step's identifier. If the tab identifier in the URL does not match an available tab for that step, Harness opens the step's default tab instead and removes the invalid `tab` value from the URL.
Example: Link an approver directly to the K8s diff tab Consider a pipeline where a K8s Diff step runs before a Harness Approval step, so an approver can review the computed diff before approving the deployment. Add the expression to the approval message so the approver's notification includes a direct link to the diff, instead of a link to the pipeline execution's default view. 1. Add a **Harness Approval** step after the K8s Diff step. 2. In the approval step's **Approval Message** field, include the expression: ``` Review the Kubernetes diff before approving: <+<+execution.steps.K8sDiff_1.executionUrl>.concat("&tab=K8S_DIFF_VIEW")> ``` 3. Replace `K8sDiff_1` with the identifier of your K8s Diff step. When the approval step triggers a notification, the approver gets a link that opens the pipeline execution with the K8s diff tab already active.
*** ## Troubleshooting
NoEligibleDelegatesInAccountException or delegate selector mismatch The K8s Diff step first fetches manifests from your Git or Helm connector before running the diff. If the delegate selector configured at the step or pipeline level differs from the one on the manifest connector, Harness merges (ANDs) all selectors by default. This means a single delegate must carry every tag, and the task fails with a `NoEligibleDelegatesInAccountException` if no delegate matches all of them. To enable priority-based selector behavior, where the step-level selector overrides the connector-level selector instead of merging, ask [Harness Support](mailto:support@harness.io) to enable the `CDS_CONTAINER_STEP_DELEGATE_SELECTOR_PRECEDENCE` feature flag on your account. Go to [Delegate selector priority](https://developer.harness.io/docs/platform/delegates/manage-delegates/select-delegates-with-selectors#delegate-selector-priority) to review how Harness resolves selector conflicts.
*** ## Limitations The following limitations apply to the K8s Diff step: * The `kubectl diff` command requires **server-side Apply**, which is available in Kubernetes version 1.18 and above. * `kubectl diff` may not work correctly with third-party **Custom Resource Definitions (CRDs)**, because they are not always fully supported by the diff command. * The command does not display changes for secrets, due to security restrictions designed to protect sensitive data. * The K8s Diff step is only available for the **Kubernetes Deployment** swimlane. It supports Helm chart manifests with the Kubernetes Deployment type, but not the Native Helm deployment type. ### Sample application To try the K8s Diff step with a sample application and configuration files, go to the [Harness Community Repository](https://github.com/harness-community/harnesscd-example-apps/tree/master/kubernetes-steps/diff-step). *** ## Next steps * [Delegate selector priority](https://developer.harness.io/docs/platform/delegates/manage-delegates/select-delegates-with-selectors#delegate-selector-priority): Understand how Harness resolves delegate selector conflicts. * [Harness Community Repository](https://github.com/harness-community/harnesscd-example-apps/tree/master/kubernetes-steps/diff-step): Try the K8s Diff step with a sample application. {% @harness-feedback/feedback %} [^1]: Beta features are feature-complete but still being validated. Available on request.