Manage Approval Policies

Enforce deployment approval workflows using Open Policy Agent (OPA) rego policies in env zero

Overview

env zero enables applying approval policies for the environments managed using the app.

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

Template approval policies

You can assign multiple approval policies to a single template. In the template settings page, under the advanced section, click the + Add Approval Policy button:

Environments that will be deployed from templates with approval policies, will have their Approve plan automatically checkbox disabled.

Project approval policies

You can assign multiple approval policies to a single project. Those approval policies will be inherited by sub projects.

In the project settings page, go to the POLICIES tab and click the + Add Approval Policy button:

Environments that will be deployed in projects with approval policies or projects with parent projects that have approval policies assigned, will have their Approve plan automatically checkbox disabled. In those cases, the Approve plans automatically for new environments checkbox in project policies settings page will also be disabled.

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 env zero

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

Text Input 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;
    teams: {id: string; name: string;}[]
  };
  approvers: {
 	  name: string;
    email: string;
    teams: {id: string; name: string;}[]
  }[];
  variables: {
    environment: Record<string, string>;
    terraform: Record<string, string>;
    env0: Record<string, string>;
  };
  policyData: any
}

• 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, driftRemediation, terraform-cli 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: opentofu - 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. See Plan format by IaC type for details.
• deployerUser: An object containing the name, email and teams of the user that created the environment and made the first deployment
• approvers: An array of users and their teams that approved the changes to the environment
• variables: The variables used by deployment, divided by type. (e.g. variables.environment.MY_VAR_1
  • .env0 will contain the environment variables automatically added by env0. Listed in Custom Flows.
• policyData: Any custom data provided by the user (see Adding custom data)

Plan format by IaC type

The plan field format depends on the IaC tool used by the template:

IaC Type	Plan Format
OpenTofu / Terraform	Standard plan JSON — see OpenTofu JSON plan representation
Terragrunt (single module)	Same as OpenTofu/Terraform
Terragrunt (run-all)	A modules map — see Terragrunt run-all plan format below
Pulumi	Requires version >= 3.105.0. For deploy: Pulumi update plan format. For destroy: same as pulumi destroy --preview-only --json output
CloudFormation	For deploy: DescribeChangeSet. For destroy: ListStackResources
Other (k8s, helm, etc.)	null — only the other input fields should be used

Terragrunt run-all plan format

For Terragrunt templates configured with run-all, the plan field contains a map of each module’s plan:

{
  "plan": {
    "is_run_all": true,
    "modules": {
      "module-a": { /* standard terraform show -json output */ },
      "module-b": { /* standard terraform show -json output */ }
    }
  }
}

• is_run_all: Always true, indicating this is a run-all plan. Use this flag to distinguish from single-module plans.
• modules: A map where each key is the module’s relative path and each value is the full OpenTofu/Terraform JSON plan for that module.

Modules that failed to produce a plan output will be excluded from the modules map. A warning will appear in the deployment logs if this happens.

Print the full input

If you need to debug your policy, env0 will print the full input to the approval flow logs by using ENV0_PRINT_POLICY_INPUT=true environment variable.

Adding custom data to the policy input

Additional input can be provided by the user, by supplying the ENV0_POLICY_DATA_PATH environment variable with the path to a JSON file.

• The file can be in the cloned repository, or created dynamically by a custom flow.
• The contents of the JSON file will be available in the input under the key policyData.
• In case there is an error reading the file, the policyData will be undefined

Expected rules format

Rego Files

Your Rego files should be under the env0 package. In addition, Please make sure that your rego files are using “package env0” in order for approval flow to work correctly.

The approval flow expects at least one of these options in the output for the Open Policy Agent If several options are received, the strictest will take place

• deny: The deployment will be cancelled.

• pending: The deployment will stop and wait for user approval.

• warn: The deployment will continue with a warning.

• allow: The deployment will continue.

  If no rules are met, the default behavior is pending.

When handling multiple approval policies, we will still use the same logic, if one approval policy outputs deny and another outputs pending, the deny will take place and we will cancel the deployment.

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 examples

You can print the full input to the approval flow logs by setting ENV0_PRINT_POLICY_INPUT=true as an environment variable.

OpenTofu / Terraform

{
  "deploymentRequest": {
    "type": "deploy",
    "triggerName": "user",
    "revision": "main"
  },
  "template": {
    "id": "abc-123",
    "name": "my-terraform-template",
    "type": "terraform",
    "repository": "https://github.com/example/templates",
    "path": "misc/null-resource",
    "revision": "main"
  },
  "costEstimation": {
    "totalMonthlyCost": 120.5,
    "monthlyCostDiff": 15.0
  },
  "plan": {
    "format_version": "1.2",
    "terraform_version": "1.5.7",
    "resource_changes": [
      {
        "address": "aws_s3_bucket.example",
        "type": "aws_s3_bucket",
        "name": "example",
        "provider_name": "registry.terraform.io/hashicorp/aws",
        "change": {
          "actions": ["create"],
          "before": null,
          "after": { "bucket": "my-bucket" }
        }
      }
    ]
  },
  "deployerUser": {
    "name": "deployer user",
    "email": "[e-mail]",
    "teams": [{ "id": "teamId", "name": "deployers team" }]
  },
  "approvers": [
    {
      "name": "Other User",
      "email": "[e-mail]",
      "teams": [
        { "id": "approversTeamId", "name": "approvers team" },
        { "id": "securityTeamId", "name": "security team" }
      ]
    }
  ],
  "variables": {
    "environment": { "AWS_REGION": "us-east-1" },
    "terraform": { "instance_type": "t3.medium" },
    "env0": { "ENV0_ENVIRONMENT_NAME": "production" }
  }
}

For the full plan schema, see the OpenTofu JSON plan representation.

Terragrunt run-all

{
  "deploymentRequest": {
    "type": "deploy",
    "triggerName": "user"
  },
  "template": {
    "id": "def-456",
    "name": "my-tg-run-all-template",
    "type": "terragrunt",
    "repository": "https://github.com/example/infra",
    "path": "live/production"
  },
  "costEstimation": {
    "totalMonthlyCost": 250.0,
    "monthlyCostDiff": 30.0
  },
  "plan": {
    "is_run_all": true,
    "modules": {
      "vpc": {
        "format_version": "1.2",
        "terraform_version": "1.5.7",
        "resource_changes": [
          {
            "address": "aws_vpc.main",
            "type": "aws_vpc",
            "name": "main",
            "provider_name": "registry.terraform.io/hashicorp/aws",
            "change": {
              "actions": ["create"],
              "before": null,
              "after": { "cidr_block": "10.0.0.0/16" }
            }
          }
        ]
      },
      "eks": {
        "format_version": "1.2",
        "terraform_version": "1.5.7",
        "resource_changes": [
          {
            "address": "aws_eks_cluster.main",
            "type": "aws_eks_cluster",
            "name": "main",
            "provider_name": "registry.terraform.io/hashicorp/aws",
            "change": {
              "actions": ["create"],
              "before": null,
              "after": { "name": "my-cluster" }
            }
          }
        ]
      }
    }
  },
  "deployerUser": {
    "name": "deployer user",
    "email": "[e-mail]",
    "teams": [{ "id": "teamId", "name": "deployers team" }]
  },
  "approvers": [],
  "variables": {
    "environment": {},
    "terraform": {},
    "env0": { "ENV0_ENVIRONMENT_NAME": "production" }
  }
}

CloudFormation

For CloudFormation deployments, the plan field contains:

• Deploy: The DescribeChangeSet response
• Destroy: The ListStackResources response

Terragrunt run-all policy example

Use input.plan.is_run_all to detect run-all plans in your policies. For example, to deny if any module creates a public S3 bucket:

package env0

deny["Public S3 bucket detected in run-all module"] {
  input.plan.is_run_all
  module_plan := input.plan.modules[_]
  resource := module_plan.resource_changes[_]
  resource.type == "aws_s3_bucket"
  resource.change.after.acl == "public-read"
}

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.

Using a specific OPA version

You can choose a specific OPA version to use with the ENV0_OPA_VERSION variable.