Connect Your Cloud Account
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 three ways for you to connect to your AWS account:
- Using AWS Assume Role
- Using IAM user credentials
- 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
- Click on Roles, then click on Create Role
- Under type of trusted entity, select AWS Account
- 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 - Select Require External ID
- Enter an External ID. The value must be equal to your Organization ID
- Click Next:Permissions
- Select AdministratorAccess or whatever policies are required by your IaC
- Click Next:Review
- Enter a name for the role, and click Create Role
- 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)
- Go to the Settings page, and pick the Credentials tab
- Under Cloud Credentials section, click + Add Credential
- Enter a name for the new credential
- Under Type, pick AWS Assumed Role
- Under Role ARN, enter your role ARN
- Note that your External ID is pre-filled with your env0 Organization ID
- Choose the duration for the deployment's assumed role (make sure it is equal or less than the duration you set in AWS)
- Click Add
- Go to the project for which you'd like to use this role, then click Project Settings and click Credentials
- 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 IDTo customize the duration per environment, create a variable called
ENV0_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
- 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.
- 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
- Go to Settings and click the Credentials tab
- Under Cloud Credentials, click + Add Credential
- Enter a name for the new credential
- Under Type, pick AWS Access Keys
- Under Access Key ID, enter your Access Key ID
- Under Secret Access Key, enter the value of your Secret Access Key
- 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
- Go to the project for which you'd like to use this role, then go to Project Settings and click Credentials
- 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
- Go to the Settings page and click the Credentials tab
- Under Cloud Credentials, click + Add Credential
- Enter a name for the new credential.
- Under Type, pick Google Cloud Service Account
- Under Project ID, enter your GCP project name (optional)
- Under Secret Account Key, copy and paste the JSON key contents directly into the value of this variable
- 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
- Go to the project for which you'd like to use this role, and then go to Project Settings and click Credentials
- 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.
-
First, make sure you are logged in:
az login
Follow the instructions to login
-
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" } } ]
-
Next, set your active subscription:
az account set --subscription="${id}"
-
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:
{ "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
- Go to the Settings page, and click on the Credentials tab
- Under the Cloud Credentials section, click + Add Credential
- Enter a name for the new credential
- Under Type, pick Azure Service Principal
- Under Client ID, enter your service principal app ID
- Under Client Secret, enter your service principal password
- Under Subscription ID, enter your subscription ID
- Under Tenant ID, enter your service principal tenant ID
- 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.
- Select the project for which you'd like to use this role, then go to Project Settings and click Credentials
- 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. Thecurrent-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.
Updated 2 months ago