Harness Governance Quickstart

Updated 1 week ago by Michael Cretzman

Currently, this feature is behind the Feature Flag OPA_PIPELINE_GOVERNANCE and is in Beta. Contact Harness Support to enable the feature.

Harness provides governance using Open Policy Agent (OPA), Policy Management, and Rego policies. You can use Harness Governance to ensure that Harness entities like Pipelines meet specific compliance requirements when specific events happen (On Save, On Run, etc).

This quickstart shows you how to use Harness OPA integration to enforce Pipeline governance.

We'll show you how to use OPA's Rego policy language to create policies, test them against Pipelines, enforce them when saving and running Pipelines, and reviewing all of the policy evaluations for a Pipeline.

Let's get started.

Objectives

You'll learn how to:

  1. Create and test Rego policies in Harness.
  2. Create a Policy Set using your new policy.
  3. Run a Pipeline that fails a policy evaluation.
  4. Run a Pipeline that passes a policy evaluation.
  5. Review policy evaluations for a Pipeline.

Before You Begin

  • What you don't need: this quickstart is only intended to show you how Pipeline governance works and so we use a simple Pipeline that only contains an Approval stage. You do not need a Kubernetes cluster or other host as a CD deployment target or CI build farm. You do not need a running Harness Delegate.
  • Review Harness Key Concepts to establish a general understanding of Harness.
  • The Harness Governance Overview provides a concise overview of Harness Governance.
  • New to OPA Policy Authoring? OPA policies are written in OPA's Rego policy language. We'll provide the policy you need for this quickstart, but it's also helpful to have some familiarity with Rego before writing and reading policies.
When you create Policy Sets they are applied to all matching entities (for example, Pipelines). Be careful that you do not create a Policy Set that might impact existing Pipelines unintentionally.

For this quickstart, we'll create a new Harness Project and only apply Policy Sets to its Pipelines. We will not impact Pipelines outside of this Project.

How does Harness use OPA?

The Harness OPA server is an OPA server managed by Harness.

In Harness, you add Rego policies to a Policy Set and select the Harness entities for evaluation (e.g. Pipelines). At that point, the policies are configured on the Harness OPA Server via a Kubernetes ConfigMap.

When certain events happen (e.g. saving or running a Pipeline), Harness reaches out to the Harness OPA server to evaluate the action using the Policy Set.

For more details, see Harness Governance Overview.

Step 1: Create a Project

In your Harness account, click Home.

Click Projects, and then click New Project.

Name the Project Quickstart, and click Save and Continue.

In Invite Collaborators, click Save and Continue. You automatically be added as a Project Admin.

Your new Project is created.

Next we'll add a Pipeline that we'll evaluate later using OPA policies.

Step 2: Create a Pipeline

For this quickstart, we'll use a very simple Pipeline that only contains an Approval stage.

Open the new Harness Project you created and click Deployments.

Click Pipelines, and then click Create a Pipeline.

Name the Pipeline Policy Example and click Start.

In Pipeline Studio, click YAML to switch to the YAML editor.

Click Edit YAML.

Replace the existing YAML with the following YAML:

pipeline:
name: Policy Example
identifier: Policy_Example
projectIdentifier: Quickstart
orgIdentifier: default
tags: {}
stages:
- stage:
name: Test
identifier: Test
description: ""
type: Approval
spec:
execution:
steps:
- step:
type: ShellScript
name: Echo
identifier: Echo
spec:
shell: Bash
onDelegate: true
source:
type: Inline
spec:
script: echo "hello"
environmentVariables: []
outputVariables: []
executionTarget: {}
timeout: 10m
serviceDependencies: []
tags: {}

We use the Quickstart projectIdentifier and the default orgIdentifier. If you are in a different org, you can replace default with the current org Id. You can get Ids from the URL in your browser: .../orgs/<Org Id>/projects/<Project Id>/....

Click Save. The Pipeline is now saved.

Click Visual and you can see it's a simple Pipeline with a manual Approval stage and one Shell Script step that echoes hello.

Next, we'll create a policy that requires any Pipeline with an Approval stage to also contain an Approval step in that stage.

Step 2: Create and Test a Policy

In this step, we'll quickly review a Rego policy, add the policy in Harness, and then test our Pipeline using the policy.

Review: Rego Policies

Harness uses the Rego policy language for defining rules that are evaluated by the OPA engine. Basically, you use Rego to answer queries such as "does the Pipeline have an Approval step?" and so on.

Your Harness Pipelines and entities might be created using the Harness UI or YAML, but your Rego policies will validate the JSON of your Pipelines or other entities.

Let's look at a simple example:

package pipeline_approval

# Deny pipelines that don't have an Approval step
deny[sprintf("deployment stage '%s' does not have a HarnessApproval step", [input.pipeline.stages[i].stage.name])] {
input.pipeline.stages[i].stage.type == "Deployment" # Find all Deployment stages...
not stages_with_approval[i] # ...that are not in the set of stages with HarnessApproval steps
}

# Find the set of stages that contain a Harness Approval step
stages_with_approval[i] {
input.pipeline.stages[i].stage.spec.execution.steps[_].step.type == "HarnessApproval"
}

Basically, this policy checks whether a Pipeline has an Approval stage containing Approval steps. If the Pipeline does not, then the policy deny is enforced.

The Pipeline fails the policy if:

  • deny is true.
  • deny is a non-empty string.
  • deny is a non-empty array of strings.

The Pipeline passes the policy if:

  • deny is undefined.
  • deny is false.
  • deny is an empty string.
  • deny is an empty array of strings.

You also must consider severity, but that is discussed later.

Create the Policy

In the Harness Project, in Project Setup, click Governance.

Click Policies, and then click New Policy.

Name the new policy Quickstart, and click Apply. The policy editor appears.

Paste the following policy into the editor:

package pipeline_approval

# Deny pipelines that don't have an Approval step
deny[sprintf("deployment stage '%s' does not have a HarnessApproval step", [input.pipeline.stages[i].stage.name])] {
input.pipeline.stages[i].stage.type == "Approval" # Find all Deployment stages...
not stages_with_approval[i] # ...that are not in the set of stages with HarnessApproval steps
}

# Find the set of stages that contain a Harness Approval step
stages_with_approval[i] {
input.pipeline.stages[i].stage.spec.execution.steps[_].step.type == "HarnessApproval"
}

Click Save.

Test the Policy

Now we can test the policy using the Pipeline we added.

In Input, click Select Input. The Select Input settings appear.

Here we'll select the Pipeline we created.

In Entity Type, select Pipeline.

In Event Type, select Pipeline Evaluation.

In Action, select On Save.

Click Apply.

The JSON for the Pipeline is added to Input.

Harness Pipelines can be created in YAML, but Rego evaluates JSON.

The JSON is useful for viewing the Fully Qualified Names (FQNs) of the labels your Rego references.

At the bottom of the JSON you can see the user that created the Pipeline.

...
"user": {
"name": "john.doe@harness.io",
"email": "john.doe@harness.io"
},
"action": "onsave",
"date": "2021-11-10T20:42:14.789+0000"
...

This can be used for policies where you want to evaluate users.

Click Test.

In Output, you can see that the Pipeline failed the policy because it is missing an Approval step.

We tested the policy, but we still need to enforce it. To enforce a policy, you add it to a Policy Set.

Step 3: Create a Policy Set

OPA evaluates rules using Policy Sets. Policy Sets are groups of related policies. A single policy can be a member of many Policy Sets.

For this quickstart, we'll just create a Policy Set using our single policy.

Click Policy Sets.

In Policy Sets, click New Policy Set.

Name the new Policy Set Quickstart.

Now we can select the Harness entity for the Policy Set, and the event that triggers evaluation.

In Entity Type that this policy set applies to, select Pipeline.

In On what event should the policy set be evaluated, select On Run.

Click Continue.

Now we can select the policies for this Policy Set.

In Policy evaluation criteria, click Add.

In Policy to Evaluate, select the Quickstart policy you created.

Policies can be created at the Account, Org, and Project level. You can tell which level the policy belongs to by the way it is formatted. Let's look at an example using a policy named Quickstart:

  • Account-level: Quickstart
  • Org-level: <org_name>/Quickstart
  • Project-level: <org_name>/<project_name> - Quickstart

In What should happen if a policy fails?, select Error and exit.

Click Finish. The new Policy Set is listed.

This Policy Set will be evaluated on every Pipeline.

When you create Policy Sets they are applied to all matching entities (for example, Pipelines). Be careful that you do not create a Policy Set that might impact existing Pipelines unintentionally.

Step 4: Evaluate a Pipeline on Run

Now that we have a Policy Set, let's see it in action.

Click Pipelines to navigate back to the Pipeline you created earlier. Remember, it does not have an Approval step and it will fail the Policy Set evaluation.

Click Run, and then Run Pipeline.

The Policy Set is evaluated and the Pipeline execution fails.

You can see the Policy Set that failed the Pipeline failed and the reason for the failure.

Let's fix the Pipeline and try again.

Step 5: Conform a Failed Pipeline and Rerun

Open the Pipeline in Pipeline Studio.

Switch to the YAML editor and click Edit YAML.

Add a new line before the - step: for the Shell Script step.

On the new line, paste the YAML for a Manual Approval step:

                          - step:
type: HarnessApproval
name: Approval
identifier: Approval
spec:
approvalMessage: Please review the following information and approve the pipeline progression
includePipelineExecutionHistory: true
approvers:
userGroups:
- account.admin
minimumCount: 1
disallowPipelineExecutor: false
approverInputs: []
timeout: 1d

Click Save.

Click Run, and then Run Pipeline.

The Pipeline runs. It passed the Policy Set successfully.

The new Approval step appears during execution.

Click Approve to finish running the Pipeline.

Step 6: Review Policy Evaluations

You can review policy evaluations in a few places.

Review in Pipeline Execution

On the Pipeline deployment summary (Execution History), click Policy Evaluations.

You can see Policy Set evaluations listed.

Review in Governance Overview

Click Project Setup, and then click Governance.

Click Evaluations.

You can see the evaluation you just performed:

Summary

In this tutorial, you:

  1. Created and tested a Rego policy in Harness.
  2. Created a Policy Set from your new policy.
  3. Ran a Pipeline that failed a policy evaluation.
  4. Ran a Pipeline that passed a policy evaluation.
  5. Reviewed policy evaluations for a Pipeline.

See Also


Please Provide Feedback