Skip to main content
env zero 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 env zero to manage. Here, you will learn how to grant env zero the required permissions.

​
Credentials Management

When creating a credential in env zero, it can be assigned to one of two scopes: Organization or Project.
  • Organization Scope: When a credential is created via the organization credentials page (Organization Settings > Credentials), it is assigned to the Organization scope. This makes it available to all projects within the organization.
  • Project Scope: When a credential is created via the project credentials page (Project Settings > Credentials), it is assigned to the Project scope. This makes it available to that specific project and any of its sub-projects.
All credentials, regardless of scope, are visible on the organization credentials page. To create or update credentials in a specific scope, you must have the MANAGE_CREDENTIALS permission at that scope level (organization or project). By default, both Project Admin and Organization Admin roles include this permission.
For example, to create or edit credentials in the project “My Project,” you need the MANAGE_CREDENTIALS permission for that project.

​
Use case example

A common reason to scope credentials is to separate access between environments. For instance, if you have distinct development and production projects, you can ensure that users in the development project do not have access to production credentials.

​
Amazon Web Services (AWS)

env zero offers three 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 env zero 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 DurationTo 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 env zero, 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 env zero (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
  SessionDuration:
    Type: Number
    Default: 300
Resources:
  AssumeRole:
    Type: AWS::IAM::Role
    Properties: 
      RoleName: Env0-AssumeRole
      Description: |
        Used by env zero 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: env zero
Outputs:
  ExternalId:
    Value: !Ref ExternalId
    Description: "ExternalID for env zero"
  AssumeRoleArn:
    Value: !GetAtt AssumeRole.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
Cloud Credentials interface showing Add Credential button and credential management options

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 assumed 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, then click Project Settings and click Credentials
  8. Pick the credential you would like to use in this project, this project, then click Add
Project credentials interface showing how to pick AWS credential for the project
Project settings interface showing credential selection for AWS assumed role

Picking AWS credential for the project

Change Assumed Role per EnvironmentIf 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 env zero 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 env zero

  1. Go to Settings and click the Credentials tab
  2. Under Cloud Credentials, click + Add Credential
Cloud Credentials interface showing credential management options

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 AgentIf 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
AWS Access Keys configuration interface

AWS Access Keys

  1. Go to the project for which you’d like to use this role, then go to Project Settings and click Credentials
  2. Pick the credential you would like to use in this project, and then click on Save
Project credentials interface showing AWS credential selection

Picking AWS credential for the project

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

  1. Go to the Settings page and click the Credentials tab
  2. Under Cloud Credentials, click + Add Credential
Cloud Credentials interface showing credential management options

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 and paste the JSON key contents directly into the value of this variable
  5. Click Add
Secret Account Key in a Self-Hosted AgentIf 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
AWS Access Keys configuration interface

Google Cloud Service Account

  1. Go to the project for which you’d like to use this role, and then go to Project Settings and click Credentials
  2. Pick the credential you would like to use in this project, then click Save
Project credentials interface showing GCP credential selection

Picking GCP credential for a project

​
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: 
    [
  {
    "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": "who@outlook.com",
      "type": "user"
    }
  }
]
  3. Next, set your active subscription: 
    az account set --subscription="${id}"
  4. Create a Service Principal for env zero 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
}
Make sure the new Service Principal has the necessary permissions. Learn how to assign a role in Azure.

​
Add Your Credentials to env zero

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

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 AgentIf 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.
Azure Service Principal configuration interface

Azure Service Principal

  1. Select the project for which you’d like to use this role, then go to Project Settings and click Credentials
  2. Pick the credential you would like to use in this project, then click Save
Project credentials interface showing Azure credential selection

Picking Azure credential for project

Change Credentials per EnvironmentIf you’d like to override the project’s Credentials and use a different Credentials for a specific environment, set the following environment variables:
  • A variable called ARM_TENANT_ID- set its value to be the “service principal tenant ID”
  • A variable called ARM_SUBSCRIPTION_ID- set its value to be the “subscription ID”
  • A variable called ARM_CLIENT_SECRET - set its value to be the “service principal password”
  • A variable called ARM_CLIENT_ID - set its value to be the “service principal app ID”

​
Using OIDC with Azure

See instructions here.

​
Oracle Cloud Infrastructure (OCI)

​
Create an OCI API Key

To create a personal API Key in OCI:
  1. Login to OCI
  2. Click on your profile pic, and go to User Settings
  3. Under the Resources section, click on API Keys, and the Add API Key
  4. When you create an API Key, you will be prompted to download a Private RSA Key. Download it and save it for later, you’re going to need it
  5. Finally, click Save
  6. After you create the API key, you’ll be prompted with a Configuration file preview. Save it as well

​
Add Your Credentials to env zero

  1. Go to the Settings page and click the Credentials tab
  2. Under Cloud Credentials, click + Add Credential
Organization credentials interface showing credential management options
  1. Enter a name for the new credential
  2. Under Type, pick OCI API Key
  3. Under Tenancy OCID, copy the tenancy from the configuration file preview
  4. Under User OCID, copy the user from the configuration file preview
  5. Under OCI Region, pick the region that matches the one in the configuration file preview
  6. Under API Key Fingerprint, copy the fingerprint from the configuration file preview
  7. Under API Key Private Key, copy the private RSA key you downloaded
When generating a private RSA key via OCI, it’s followed by OCI_API_KEY after the key ends.
Remove that section.

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

env zero applies your IaC to create resources in your own Kubernetes cluster. Here you will learn how to give env zero 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 PulumiWhile Helm and Kubernetes templates enjoy native support, env zero 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
Organization credentials interface showing credential management options
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 env zero’s UI. Select the Kubernetes Kubeconfig File credential from the Type dropdown menu and paste your validkubeconfig file.
ConstraintsYour 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.
CredentialsIn 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.
CredentialsIn 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.
CredentialsIn order to access your cluster, you’ll also need to set valid Azure credentials.