Connect Your Cloud Account

env0 applies your Terraform 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

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 to obtain credentials for Terraform.
It will require all permissions required by Terraform, 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 of your choosing - consider this like a password env0 will use in order to assume the role.
  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 and the External ID in subsequent steps.
  11. On the created Role screen, look for Maximum session duration and click Edit. Select Custom Duration and enter "18000" (5 hours) - that time matches the maximum allowed deployment time on env0.

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

You can use the following CloudFormation Template 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: 18000
      Tags: 
        - Key: Owner
          Value: Env0
Outputs:
  ExternalId:
    Value: !Ref ExternalId
    Description: "ExternalID for Env0"
  AssumeRoleArn:
    Value: !GetAtt AssumeRole.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_EXTERNAL_ID

The RoleArn and ExternalId Will be available in the Outputs Tab of your CloudFormation Stack.

🚧

The ExternalID is like setting a password, so please treat it with caution.

Add your Role ARN and External ID 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
28562856

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. Under "External ID", enter the value of your Role's External ID
  5. Click Add

πŸ“˜

External ID 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 external ID. Read more here

10261026

AWS Assumed Role

  1. Go to the project 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
28462846

Picking AWS credential for 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. Then, create another variable called ENV0_AWS_ROLE_EXTERNAL_ID, set its value to be the secret external ID, and mark the variable as sensitive

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
28562856

Cloud Credentials

  1. Enter a name for the new credential.
  2. Under "Type", pick "AWS Access Keys".
  3. Under "Access Key ID", enter your role ARN.
  4. Under "Secret Access Key", enter the value of your Role's External ID
  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

10241024

AWS Access Keys

  1. Go to the project 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
28542854

Picking AWS credential for project

Google Cloud

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
28562856

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

10241024

Google Cloud Service Account

  1. Go to the project 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
28342834

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
    }
    

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
28562856

Cloud Credentials

  1. Enter a name for the new credential.
  2. Under "Type", pick "Azure Service Principal".
  3. Under "Client ID", enter your service prinicipal 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

10181018

Azure Service Principal

  1. Go to the project 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
28602860

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 authorisation. Same as all above options, you'll be able to separate your credentials into project/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


What’s Next