env0 applies your infrastructure code to create resources in your own cloud account. It requires only the necessary permissions to manage your cloud resources on your behalf.

This includes permissions to create, update, and delete any type of cloud resource you want env0 to manage.

Here, you will learn how to grant env0 the required permissions.

Amazon Web Services (AWS)

env0 offers two ways for you to connect to your AWS account:

1. Using AWS Assume Role
2. Using IAM user credentials
3. Using OIDC

Using AWS Assume Role

This role will be assumed by env0 during a deployment.
It will require all permissions required including GetAccessKeyInfo.

Create an AWS IAM Role

1. Click on Roles, then click on Create Role
2. Under type of trusted entity, select AWS Account
3. Under An AWS account ID, select 'An AWS account' and enter 913128560467. If you have a self-hosted agent installation you should enter the AWS account ID where the agent is installed
4. Select Require External ID
5. Enter an External ID. The value must be equal to your Organization ID
6. Click Next:Permissions
7. Select AdministratorAccess or whatever policies are required by your IaC
8. Click Next:Review
9. Enter a name for the role, and click Create Role
10. Click on the role you just created. We will need the Role ARN in subsequent steps

📘

Assume Role Duration

To edit the duration of the Assume Role, go to the Created Role screen and locate Maximum Session Duration. Click Edit and select your relevant duration.

When you create the credentials in env0, please make sure to select the correct duration. It must be equal to or less than the selected duration in AWS.

Add your Role ARN and External ID configuration to env0 (via CloudFormation)

You can use the following CloudFormation Template or Terraform HCL to create the AssumeRole

AWSTemplateFormatVersion: '2010-09-09'
Parameters:
  ExternalId:
    Type: String
    Default: external-id
Resources:
  AssumeRole:
    Type: AWS::IAM::Role
    Properties: 
      RoleName: Env0-AssumeRole
      Description: |
        Used by Env0 to automate the deployment of Infrastructure from a Verison Control System
      AssumeRolePolicyDocument: !Sub |
        {"Version": "2012-10-17",
            "Statement": [
                {
                    "Effect": "Allow",
                    "Action": "sts:AssumeRole",
                    "Principal": {
                        "AWS": "913128560467"
                    },
                    "Condition": {
                        "StringEquals": {
                            "sts:ExternalId": "${ExternalId}"
                        }
                    }
                }
            ]
        }
      ManagedPolicyArns: 
        - arn:aws:iam::aws:policy/AdministratorAccess
      MaxSessionDuration: ${SessionDuration}
      Tags: 
        - Key: Owner
          Value: Env0
Outputs:
  ExternalId:
    Value: !Ref ExternalId
    Description: "ExternalID for Env0"
  AssumeRoleArn:
    Value: !GetAtt AssumeRole.Arn

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 4.36.0"
    }
    env0 = {
      source  = "env0/env0"
      version = ">= 1.15"
    }
  }
}

provider "env0" {
  # env0 Provider expects to find the environment variables defined.
  # to create an API key see:  https://docs.env0.com/docs/api-keys
  # ENV0_API_KEY    
  # ENV0_API_SECRET
  # or using tf provider variables
  # api_key = ""
  # api_secret = ""
}

provider "aws" {
  region = var.region
}

### VARIABLES

variable "region" {
  type    = string
  default = "us-east-1"
}

variable "assume_role_name" {
  type        = string
  default     = "env0-deployer-role"
  description = "name used for both env0 and AWS"
}

variable "managed_policy_arns" {
  type        = list(string)
  default     = ["arn:aws:iam::aws:policy/AdministratorAccess", ]
  description = "list of policy arns to assign to env0's deployer"
}

variable "organization_id" {
  type        = string
  description = "env0 org id found under Organization > Settings"

### RESOURCES 

resource "aws_iam_role" "env0_deployer_role" {
  name = var.assume_role_name

  max_session_duration = 18000 # env0 requirement, 5 hours for SaaS

  # Change to your policy
  managed_policy_arns = var.managed_policy_arns

  # 913128560466 is env0's AWS Account ID
  # see: https://docs.env0.com/docs/connect-your-cloud-account#using-aws-assume-role
  assume_role_policy = jsonencode({
    "Version" : "2012-10-17",
    "Statement" : [
      {
        "Effect" : "Allow",
        "Principal" : {
          "AWS" : "arn:aws:iam::913128560467:root"
        },
        "Action" : "sts:AssumeRole",
        "Condition" : {
          "StringEquals" : {
            "sts:ExternalId" : "${var.organization_id}"
          }
        }
      }
    ]
  })

  tags = {
    note = "Created through env0 Bootstrap"
  }
}

# optional to manage your env0 resources using env0's terraform provider
resource "env0_aws_credentials" "credentials" {
  name        = aws_iam_role.env0_deployer_role.arn #easier to track in the UI which role exactly is being used
  arn         = aws_iam_role.env0_deployer_role.arn
}
  
output "role_arn" {
  value = aws_iam_role.env0_deployer_role.arn
}

Next, run the following AWS CLI command to deploy the CloudFormation Stack

aws cloudformation deploy \
--stack-name assume-role-env0 \
--template-file ./assume-role-env0.yml \
--capabilities CAPABILITY_NAMED_IAM \
--parameter-overrides ExternalId=YOUR_ORGANIZATION_ID SessionDuration=SESSION_DURATION

The RoleArn will be available in the Outputs tab of your CloudFormation stack.

📘

For security reasons, the ExternalID is resolved on the backend to be your organization ID.

Add your Role ARN configuration to env0 (via Manual Configuration)

1. Go to the Settings page, and pick the Credentials tab
2. Under Cloud Credentials section, click + Add Credential

3. Enter a name for the new credential
4. Under Type, pick AWS Assumed Role
5. Under Role ARN, enter your role ARN
6. Note that your External ID is pre-filled with your env0 Organization ID
7. Choose the duration for the deployment's assumed role (make sure it is equal or less than the duration you set in AWS)
8. Click Add
9. Go to the project for which you'd like to use this role, then click Project Settings and click Credentials
10. Pick the credential you would like to use in this project, this project, then click Add

📘

Change Assumed Role per Environment

If you'd like to override the project's Assumed Role and use a different Assumed Role for a specific environment, set the following environment variables:

• A variable called ENV0_AWS_ROLE_ARN- set its value to be the role ARN
• A variable called ENV0_AWS_ROLE_EXTERNAL_ID- its value to your Org ID

To customize the duration per environment, create a variable calledENV0_AWS_ROLE_DURATION, and set its value to the desired duration in seconds. AWS uses a default value of 3600s (1 hour), while env0 uses a default value of 18000s (5 hours).

Using AWS user credentials

Create IAM Role & Permissions

1. To connect your AWS account, you will need to create an IAM user with programmatic access. See this guide on how to do that. Make sure you save your Access Key ID and Secret Access Key.
2. You will need to grant this user the appropriate permissions in order to deploy the resources defined in your IaC code.

Add Your Credentials to env0

1. Go to Settings and click the Credentials tab
2. Under Cloud Credentials, click + Add Credential

3. Enter a name for the new credential
4. Under Type, pick AWS Access Keys
5. Under Access Key ID, enter your Access Key ID
6. Under Secret Access Key, enter the value of your Secret Access Key
7. Click Add

📘

Secret Access Key in a Self-Hosted Agent

If your organization is managed in a Kubernetes Self-Hosted Agent, you must reference an existing AWS, GCP or Azure secret manager variable instead of typing the actual secret Secret Access Key.

Read more here

8. Go to the project for which you'd like to use this role, then go to Project Settings and click Credentials
9. Pick the credential you would like to use in this project, and then click on Save

Google Cloud (GCP)

Create a Service Account

In order to connect your GCS account, you will need to create a Service Account Key. See this guide on how to create one. Make sure to save the JSON key contents.

Add Your Credentials to env0

1. Go to the Settings page and click the Credentials tab
2. Under Cloud Credentials, click + Add Credential

3. Enter a name for the new credential.
4. Under Type, pick Google Cloud Service Account
5. Under Project ID, enter your GCP project name (optional)
6. Under Secret Account Key, copy and paste the JSON key contents directly into the value of this variable
7. Click Add

📘

Secret Account Key in a Self-Hosted Agent

If your organization is managed in a Kubernetes Self-Hosted Agent, you must reference an existing AWS, GCP or Azure secret manager variable instead of typing the actual secret Secret Account Key.

Read more here

8. Go to the project for which you'd like to use this role, and then go to Project Settings and click Credentials
9. Pick the credential you would like to use in this project, then click Save

Using OIDC with GCP

See instructions here.

Azure

Create a Service Principal

In order to access resources a Service Principal needs to be created in your Tenant.
This is easiest to do via the AZ CLI.

1. First, make sure you are logged in:

   az login
   

   Follow the instructions to login

2. Once logged in, your subscriptions will be returned:

   json5

   [
     {
       "cloudName": "AzureCloud",
       "id": "2d7e700a-8793-45ff-ba0a-9d92d15edf56", // this is your Subscription ID
       "isDefault": "true",
       "name": "Pay-As-You-Go",
       "state": "Enabled",
       "tenantId": "e522969-635a-4327-8807-7f7aac328e82",
       "user": {
         "name": "[email protected]",
         "type": "user"
       }
     }
   ]
   

3. Next, set your active subscription:

   az account set --subscription="${id}"
   

4. Create a Service Principal for env0 to deploy your terraform stack:

   az ad sp create-for-rbac -n "${name-of-your-choice}"
   

   This will return the metadata for your Service Principal:

   json5

   {
     "appId": "2dc2b1b3-11dd-4eb5-845-84fc-5bda87620cea", // this is your Client ID
     "displayName": "who",
     "name": "http://who",
     "password": "ab735025-151e-4337-b154-b7833d6929a9",  // this is your Client Secret
     "tenant": "5c8c7547-dd3f-4750-a8d9-f2e04e6015ba"     // this is your Tenant ID
   }
   

📘

Don't forget to make sure that the new Service Principal has the required permissions.

Add Your Credentials to env0

1. Go to the Settings page, and click on the Credentials tab
2. Under the Cloud Credentials section, click + Add Credential

3. Enter a name for the new credential
4. Under Type, pick Azure Service Principal
5. Under Client ID, enter your service principal app ID
6. Under Client Secret, enter your service principal password
7. Under Subscription ID, enter your subscription ID
8. Under Tenant ID, enter your service principal tenant ID
9. Click Add

📘

Client Secret in a Self-Hosted Agent

If your organization is managed in a Kubernetes Self-Hosted Agent, you must reference an existing AWS, GCP, or Azure secret manager variable instead of typing the actual secret Client Secret.

Read more .`here.

10. Select the project for which you'd like to use this role, then go to Project Settings and click Credentials
11. Pick the credential you would like to use in this project, then click Save

Using OIDC with Azure

See instructions here.

Other Cloud Providers

If you are using Terraform to manage infrastructure in a different provider than the ones mentioned above, you will need to check the provider’s documentation to understand what authentication options are supported.

Generally, you should be able to use specific environment variables for authorization. Same as all the above options, you'll be able to separate your credentials into projects/environments as you see fit.

Customizing Cloud Authentication per Environment

Generally, Cloud Credentials are defined per env0 project. These are translated into environment variables at runtime (like AWS_ACCESS_KEY_ID and AWS_ACCESS_SECRET_KEY for AWS). If you'd like to give different credentials to a specific environment, you could simply override the desired environment variables during deployment.

Kubernetes

env0 applies your IaC to create resources in your own Kubernetes cluster. Here you will learn how to give env0 the required permissions to do just that.

We support major cloud provider managed clusters, as well as a general kubeconfig file.

👍

Easy Authentication for Terraform and Pulumi

While Helm and Kubernetes templates enjoy native support, env0 also enables seamless Kubernetes authentication integration within Terraform and Pulumi templates. These connect to your cluster by automatically creating the kubeconfig file in the deployment container.

Follow our code examples for Terraform and Pulumi for easy configuration.

Set Up Kubernetes Credential

Navigate into Organization Settings and click Credentials
Under Deployment Credentials, click + Add Credential

Inside the opened modal, select your desired Kubernetes Cluster authentication method.

Kubeconfig

If you want to allow connection to your custom cluster, you can do so by setting up a kubeconfig credential in env0's UI.

Select the Kubernetes Kubeconfig File credential from the Type dropdown menu and paste your validkubeconfig file.

📘

Constraints

Your kubeconfig hould contain exactly one cluster, context and user. The current-context field must be provided, and match the given context.

Next, you'll need to associate the created credential with your project.

Under Project Settings, click the Credentials tab. Then, check the Kubernetes checkbox and select the credential you created from the dropdown menu.

AWS EKS

Select the Kubernetes - AWS EKS Configuration credential from the Type dropdown menu, then enter your cluster name and region.

Next, you'll need to associate your EKS credential with your project.

In your Project Settings, click on the Credentials tab. Check the Kubernetes checkbox and select the credential you created from the dropdown menu.

📘

Credentials

In order to access your cluster, you'll also need to set valid AWS credentials.

GCP GKE

Select the Kubernetes - GCP GKE Configuration credential from the Type dropdown menu and enter your cluster name and region.

Next, you'll need to associate the GKE credential with your project.

In your Project Settings, click on the Credentials tab. Then, check the Kubernetes checkbox and select the credential you created from the dropdown menu.

📘

Credentials

In order to access your cluster, you'll also need to set valid GCP credentials.

Azure AKS

Select the Kubernetes - Azure AKS Configuration credential from the Type dropdown menu and enter your cluster name and resource group.

Next, you'll need to associate the AKS credential with your project.

In your Project Settings, click on the Credentials tab. Then, check the Kubernetes checkbox and select the credential you created from the dropdown menu.

📘

Credentials

In order to access your cluster, you'll also need to set valid Azure credentials.