Overview

env0 enables applying approval policies for the environments managed using the app.

env0 uses the Open Policy Agent engine for enforcing policies when an environment is deployed.

Open Policy Agent uses rego files to define the required policies. env0 expects the user's files to be within a repository, not necessarily the deployed environment repository.

During the deployment, after the plan and cost estimation steps, a step for policy approval will be run, and the deployment may continue, wait for further approval, or get canceled, according to the output of previous steps and other data such as the type of deployment, users involved, or IaC.

Enable approval policies step

In the project settings page, go to the POLICIES tab and click the Configure button next to Apply custom approval policy to all environments in this project

Repository Configuration

Configure the repository for the repository that contains the rego files for the desired policy. If the files are located within a directory, specify the folder path too.

All the environments under the project will have a deployment step for validating that the plan isn't violating the chosen policy.

📘

Actions that enforce policies

Policies are enforced only when an environment is about to get deployed or destroyed. Tasks, PR plans and other actions are not enforcing policies.

Input by env0

The input env0 generates based on the deployment is of the following structure:

{
  deploymentRequest: {
    type: string;
    triggerName: string;
    revision: string;
  };
  template: {
    type: string;
    repository: string;
  	path: string;
  	revision: string;
  	id: string;
  	name: string;
  };
  costEstimation: {
    totalMonthlyCost: number;
    monthlyCostDiff: number;
  };
  plan: object;
  deployerUser: {
 	  name: string;
    email: string;
  };
  approvers: {
 	  name: string;
    email: string;
  }[]
}

• deploymentRequest:
  • type: The action that caused the deployment. Can be deploy, destroy, deployResume or destroyResume
  • triggerName: The trigger for the deployment. Can be cd, user, ttl, scheduled, workflow or comment
  • revision: The revision that this specific deployment uses to clone the data from. May be missing if no revision is stated for the deployment or as a default for the template.
• template
  • id: The template's unique id.
  • name: The template's name.
  • type: The type of the template, i.e. what IaC tool is used to deploy the resources. The value can be one of the following: terraform - terragrunt - pulumi - cloudformation - k8s - helm
  • repository: The repository URL of the template.
  • path: The path within the repository to the relevant files.
  • revision: The revision that the repository's code will be cloned from. It may be missing if no revision is set for the template.
• costEstimation: An object that describes the projected changes in the cost once the changes are approved. Cost estimation must be enabled and the template type supported to have correct values.
• plan: An object representing the speculated changes that the deployment will cause once approved. Contents are in the same format as the content of the plan phase during the deployment run. note: plan is only supported in Terraform and Terragrunt environments.
• deployerUser: An object containing the name and email of the user that created the environment and made the first deployment
• approvers: An array of users that approved the changes to the environment

🚧

Supported IaC Frameworks

Currently on Terraform deployments we will populate the plan field.

For other IaC tools the object will be empty, and only the other fields should be used.

Expected rules format

The approval flow expects at least one of three options in the output for the Open Policy Agent run: allow, pending, deny. If there is at least one rule within the deny option, the deployment is canceled. Otherwise, if there is at least one rule within the pending option, the deployment will wait for manual user approval. Otherwise, there must be at least one rule within the allow option so the deployment will continue automatically. If no rules are met, the default behavior is to wait for approval.

Examples

Policies

There are many cases where approval policies may be useful:

• Requiring more than a certain threshold of approvers
• Deny any change that its expected cost cross a predefined limit
• Prevent removing critical resources from an environment
• Allowing only a sub-set of users to change specific resources within an environment

And the list can go on and on.

Examples may be found in our GitHub repository

Full input example

{
  "deploymentRequest": {
    "type": "deploy",
    "triggerName": "user",
    "revision": "null-module"
  },
  "template": {
    "id": "some id",
    "name": "template name",
    "type": "terraform",
    "repository": "https://github.com/env0/templates",
    "path": "misc/null-resource",
    "revision": "master"
  },
  "costEstimation": {
    "totalMonthlyCost": 0,
    "monthlyCostDiff": 0
  },
  "plan": {
    "format_version": "1.1",
    "terraform_version": "1.2.2",
    "planned_values": {
      "root_module": {
        "resources": [
          {
            "address": "null_resource.null",
            "mode": "managed",
            "type": "null_resource",
            "name": "null",
            "provider_name": "registry.terraform.io/hashicorp/null",
            "schema_version": 0,
            "values": {
              "triggers": null
            },
            "sensitive_values": {}
          }
        ]
      }
    },
    "resource_changes": [
      {
        "address": "null_resource.null",
        "mode": "managed",
        "type": "null_resource",
        "name": "null",
        "provider_name": "registry.terraform.io/hashicorp/null",
        "change": {
          "actions": [
            "create"
          ],
          "before": null,
          "after": {
            "triggers": null
          },
          "after_unknown": {
            "id": true
          },
          "before_sensitive": false,
          "after_sensitive": {}
        }
      }
    ],
    "configuration": {
      "provider_config": {
        "null": {
          "name": "null",
          "full_name": "registry.terraform.io/hashicorp/null"
        }
      },
      "root_module": {
        "resources": [
          {
            "address": "null_resource.null",
            "mode": "managed",
            "type": "null_resource",
            "name": "null",
            "provider_config_key": "null",
            "schema_version": 0
          }
        ]
      }
    }
  },
  "deployerUser": {
    "name": "deployer user",
    "email": "[email protected]"
  },
  "approvers": [
    {
      "name": "Other User",
      "email": "[email protected]"
    }
  ]
}

Deployment Pending Approval

Here the user's deployment stopped as the Open Policy Agent evaluated one of the rules as pending. Once the deployment is approved twice, this step will be passed and the apply step can start.

🚧

Changing policy during a deployment

Note that changing or removing a policy during a deployment (for example while it's pending approval) is not supported and might result in an error. In such a case, you should cancel the deployment and re-deploy the environment.