Install the agent with Terraform

• A VPC, an EKS cluster with a managed node group, and the cluster autoscaler
• An agent pool and an agent secret in env zero
• The env0-agent Helm release, configured with env zero hosted encrypted state, so the cluster needs no persistent volume

​

Prerequisites

• Terraform 1.3.2 or later, or OpenTofu
• AWS credentials that can create a VPC, an EKS cluster, IAM roles, and Auto Scaling group settings
• AWS CLI v2 and bash on the machine that runs Terraform or OpenTofu. The Helm provider authenticates with aws eks get-token, and the aws module runs aws autoscaling commands.
• The Helm CLI, to run the chart tests in Verify the installation
• An env zero API key, exported as environment variables:

export ENV0_API_KEY=<YOUR_API_KEY_ID>
export ENV0_API_SECRET=<YOUR_API_KEY_SECRET>

​

Create the configuration

terraform {
  required_providers {
    env0 = {
      source  = "env0/env0"
      version = "~> 1.33"
    }
    helm = {
      source  = "hashicorp/helm"
      version = ">= 2.13.0, < 3.0.0"
    }
    random = {
      source  = "hashicorp/random"
      version = "~> 3.6"
    }
  }
}

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

variable "cluster_name" {
  default = "env0-agent"
}

module "cluster" {
  source = "github.com/env0/k8s-modules//aws?ref=v1.2.0"

  region       = var.region
  cluster_name = var.cluster_name

  create_efs_storage = false
}

provider "env0" {}

provider "helm" {
  kubernetes {
    host                   = module.cluster.cluster_endpoint
    cluster_ca_certificate = base64decode(module.cluster.cluster_certificate_authority_data)
    exec {
      api_version = "client.authentication.k8s.io/v1beta1"
      command     = "aws"
      args        = ["eks", "get-token", "--cluster-name", module.cluster.cluster_name, "--region", var.region]
    }
  }
}

resource "env0_agent_pool" "this" {
  name = var.cluster_name
}

resource "env0_agent_secret" "this" {
  agent_id = env0_agent_pool.this.id
}

# Encrypts the deployment state and working directory before the agent uploads them.
resource "random_password" "state_encryption_key" {
  length  = 32
  special = false
}

resource "helm_release" "env0_agent" {
  repository = "https://env0.github.io/self-hosted"
  chart      = "env0-agent"
  # Latest chart: https://github.com/env0/self-hosted/releases
  version = "v5.5.6"

  # Wait for the node group and the addons, so the agent pods can start
  depends_on = [module.cluster]

  name             = "env0-agent"
  namespace        = "env0-agent"
  create_namespace = true
  timeout          = 600

  set_sensitive {
    name  = "agentAccessToken"
    value = env0_agent_secret.this.secret
  }

  set_sensitive {
    name  = "env0StateEncryptionKey"
    value = base64encode(random_password.state_encryption_key.result)
  }
}

​

Apply the configuration

1. Initialize the working directory:
   terraform init
   
2. Apply the configuration:
   terraform apply
   

​

Verify the installation

1. Configure kubectl for the new cluster. If you changed cluster_name or region, use your values:
   aws eks update-kubeconfig --name env0-agent --region us-east-1
   
2. Run the chart tests:
   helm test env0-agent --namespace env0-agent --logs --timeout 1m
   
3. In env zero, go to Organization Settings > Agents. The agent pool named after cluster_name (env0-agent by default) shows Active.

​

Assign the agent to a project

resource "env0_agent_project_assignment" "this" {
  agent_id   = env0_agent_pool.this.id
  project_id = "<YOUR_PROJECT_ID>"
}

​

Use an existing EKS cluster

1. Remove the module "cluster" block, and the depends_on line from helm_release.
2. Add the aws provider to required_providers:
   main.tf

   aws = {
     source  = "hashicorp/aws"
     version = ">= 5.95.0"
   }
   
3. Replace the provider "helm" block with:
   main.tf

   provider "aws" {
     region = var.region
   }
   
   data "aws_eks_cluster" "this" {
     name = var.cluster_name
   }
   
   provider "helm" {
     kubernetes {
       host                   = data.aws_eks_cluster.this.endpoint
       cluster_ca_certificate = base64decode(data.aws_eks_cluster.this.certificate_authority[0].data)
       exec {
         api_version = "client.authentication.k8s.io/v1beta1"
         command     = "aws"
         args        = ["eks", "get-token", "--cluster-name", data.aws_eks_cluster.this.name, "--region", var.region]
       }
     }
   }
   
4. Set the cluster_name variable default to the name of your cluster.

​

Keep the state in your AWS account

1. In module "cluster", remove create_efs_storage = false. The module then creates an EFS file system, the EFS CSI driver, and the env0-state-sc StorageClass.
2. Remove the random_password resource and the env0StateEncryptionKey block from helm_release. Without the key, the agent chart creates a persistent volume claim on env0-state-sc.

​

Next steps

• Custom/optional configuration - Add Helm values to helm_release.env0_agent.
• Authenticating the agent on AWS EKS - Give deployments an IAM role. The oidc_provider_arn module output feeds the IAM role trust policy.
• Hosting deployment logs - Store deployment logs in your AWS account.