Connect Your Cloud Account

env0 applies your infrastructure code to create resources in your own cloud account. Here you will learn how to give env0 the required permissions for that.

The exact steps depend on which cloud provider you are using.

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

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 -> 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 policy required by your Terraform
  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

If you like to edit the Duration of the Assume role, on the created Role screen, look for Maximum session duration and click Edit and select the relevant duration you would like.

When you create the credentials in env0, please make sure you select the correct duration as it need to be equal 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
}

and 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 the Cloud Credentials section, click + Add Credential
2856

Cloud Credentials

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

Picking AWS credential for the project

๐Ÿ“˜

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, you can create environment variables when deploying the environment, which will allow you to assume a different role.
Create a variable called ENV0_AWS_ROLE_ARN, and set its value to be the role.

To customize the duration per environment create a variable called ENV0_AWS_ROLE_DURATION, and set its value to be the duration in seconds.

Using AWS user credentials

Create IAM Role & Permissions

  1. In order 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 Terraform code.

Add Your Credentials to env0

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

Cloud Credentials

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

๐Ÿ“˜

Secret Access Key in a Self-Hosted Agent

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

1024

AWS Access Keys

  1. Go to the project for which you'd like to use this role, and then go to "Project Settings" -> Credentials" tab
  2. Pick the credential you would like to use in this project, and then click on Save
2854

Picking AWS credential for the project

Google Cloud (GCP)

Create a Service Account

  1. 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 pick the "Credentials" tab
  2. Under the Cloud Credentials section, click + Add Credential
2856

Cloud Credentials

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

๐Ÿ“˜

Secret Account Key in a Self-Hosted Agent

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

1024

Google Cloud Service Account

  1. Go to the project for which you'd like to use this role, and then go to "Project Settings" -> Credentials" tab
  2. Pick the credential you would like to use in this project, and then click on Save
2834

Picking GCP credential for project

Azure

Create a Service Principal

In order to access resources a Service Principal needs to be created in your Tenant.
It is easiest to do this 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:

    [
      {
        "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. Then create a Service Principal for env0 to be able to deploy your terraform stack:

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

    That will return the metadata for your Service Principal:

    {
      "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 the new Service Principal has the required permissions

Add Your Credentials to env0

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

Cloud Credentials

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

๐Ÿ“˜

Client Secret in a Self-Hosted Agent

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

1018

Azure Service Principal

  1. Go to the project for which you'd like to use this role, and then go to "Project Settings" -> Credentials" tab
  2. Pick the credential you would like to use in this project, and then click on Save
2860

Picking Azure credential for project

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 documentation to understand what authentication options the provider supports

Generally, you'll likely be able to simply 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. Please See XXX for more info

Customising Cloud Authentication Per Environment

Generally, Cloud Credentials are defined per env0 project. Those are translated to environment variables at runtime (like AWS_ACCESS_KEY_ID and AWS_ACCESS_SECRET_KEY for AWS). If you'd like to specify different credentials for a specific environment, you could simply override those environment variables when deploying that environment

Kubernetes

env0 applies your Terraform code to create resources in your own Kubernetes cluster. Here you will learn how to give env0 the required permissions for that.

We support the 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 that connect to your cluster, as we are creating the kubeconfig file in the deployment container automatically.

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

Set Up Kubernetes Credential

Navigate into Organization Settings > Credentials
Under Deployment Credentials, click the + Add Credential button

Inside the opened modal, select the desired Kubernetes Cluster authentication method you like

Kubeconfig

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

Select the Kubernetes - Kubeconfig File credential from the Type dropdown, and paste your valid kubeconfig file.

๐Ÿ“˜

Constraints

Your kubeconfig should 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.

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

AWS EKS

Select the Kubernetes - AWS EKS Configuration credential from the Type dropdown. Then, insert your cluster name and region.

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

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

๐Ÿ“˜

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. Then, insert your cluster name and region.

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

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

๐Ÿ“˜

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. Then, insert 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 Credentialstab. Then, check the Kubernetes checkbox and select the credential you created from the dropdown.

๐Ÿ“˜

Credentials

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