Terraform module aws-ecs-tfc-agent

This module creates an HCP Terraform agent pool in a TFC org, and deploys a task definition and service into an existing ECS Fargate cluster. It includes the required security group and IAM roles for a basic deployment. For all options, see variables.tf

Prerequisites:

• An existing VPC with at least one public subnet
• An existing ECS Fargate cluster and CloudWatch log group
• An HCP Terraform organization or a Terraform Enterprise instance

Hat tip to Andy Assareh for his excellent examples.

Minimal example using the standard agent image (hashicorp/tfc-agent):

module "agent_standard" {
  source  = "github.com/danbarr/terraform-aws-ecs-tfc-agent?ref=v1.0.0"

  name                      = "ecs"
  tfc_org_name              = "My-TFC-Org"
  ecs_cluster_arn           = "arn:aws:ecs:us-east-1:111111111111:cluster/my-ecs-cluster"
  cloudwatch_log_group_name = "/ecs/tfc-agents"
  vpc_id                    = var.vpc_id
  subnet_ids                = var.subnet_ids
}

Example using a customized tfc-agent image hosted in ECR, plus my aws-ecs-fargate-cluster module to also create the ECS cluster:

module "agent_cluster" {
  source       = "github.com/danbarr/terraform-aws-ecs-fargate-cluster?ref=v1.0.1"
  cluster_name = "terraform-agent-cluster"
}

resource "aws_cloudwatch_log_group" "example" {
  name = "/ecs/tfc-agents-module-test"
}

module "agent_standard" {
  source  = "github.com/danbarr/terraform-aws-ecs-tfc-agent?ref=v1.0.0"

  name                      = "ecs-custom"
  tfc_org_name              = "My-Terraform-Org"
  agent_image               = "111111111111.dkr.ecr.us-east-1.amazonaws.com/tfc-custom-agent"
  ecs_cluster_arn           = module.agent_cluster.cluster_arn
  use_spot_instances        = true
  cloudwatch_log_group_name = "/ecs/tfc-agents"
  vpc_id                    = var.vpc_id
  subnet_ids                = var.subnet_ids
}

Requirements

Name	Version
terraform	>= 1.1.0
aws	>= 4.24
tfe	>= 0.36

Providers

Name	Version
aws	>= 4.24
tfe	>= 0.36

Resources

Name	Type
aws_ecs_service.tfc_agent	resource
aws_ecs_task_definition.tfc_agent	resource
aws_iam_role.ecs_task_execution_role	resource
aws_iam_role.ecs_task_role	resource
aws_iam_role_policy.agent_init_policy	resource
aws_iam_role_policy_attachment.ecs_task_execution_role_policy_attachment	resource
aws_iam_role_policy_attachment.ecs_task_role_policy_attachment	resource
aws_security_group.tfc_agent	resource
aws_security_group_rule.allow_egress	resource
aws_ssm_parameter.agent_token	resource
tfe_agent_pool.ecs_agent_pool	resource
tfe_agent_token.ecs_agent_token	resource
aws_iam_policy_document.agent_assume_role_policy	data source
aws_iam_policy_document.agent_init_policy	data source
aws_region.current	data source

Inputs

Name	Description	Type	Default	Required
cloudwatch_log_group_name	The name of the CloudWatch log group where agent logs will be sent. The log group must already exist.	string	n/a	yes
ecs_cluster_arn	ARN of the ECS cluster where the agent will be deployed.	string	n/a	yes
name	A name to apply to resources. The combination of name and tfc_org_name must be unique within an AWS account.	string	n/a	yes
subnet_ids	IDs of the subnet(s) where agents can be deployed (public subnets required)	list(string)	n/a	yes
tfc_org_name	The name of the TFC/TFE organization where the agent pool will be configured. The combination of tfc_org_name and name must be unique within an AWS account.	string	n/a	yes
vpc_id	ID of the VPC where the cluster is running.	string	n/a	yes
agent_auto_update	Whether the agent should auto-update. Valid values are minor, patch, and disabled.	string	"minor"	no
agent_cpu	The CPU units allocated to the agent container(s). See https://docs.aws.amazon.com/AmazonECS/latest/developerguide/AWS_Fargate.html#fargate-tasks-size	number	256	no
agent_image	The Docker image to launch.	string	"hashicorp/tfc-agent:latest"	no
agent_log_level	The logging verbosity for the agent. Valid values are trace, debug, info (default), warn, and error.	string	"info"	no
agent_memory	The amount of memory, in MB, allocated to the agent container(s).	number	512	no
agent_single_execution	Whether to use single-execution mode.	bool	true	no
extra_env_vars	Extra environment variables to pass to the agent container.	list(object({ name = string value = string }))	[]	no
num_agents	The number of agent containers to run.	number	1	no
task_policy_arns	ARN(s) of IAM policies to attach to the agent task. Determines what actions the agent can take without requiring additional AWS credentials.	list(string)	[]	no
tfc_address	The HTTPS address of the TFC or TFE instance.	string	"https://app.terraform.io"	no
use_spot_instances	Whether to use Fargate Spot instances.	bool	false	no

Outputs

Name	Description
agent_pool_id	ID of the TFC agent pool.
agent_pool_name	Name of the TFC agent pool.
ecs_service_arn	ARN of the ECS service.
ecs_task_arn	ARN of the ECS task definition.
ecs_task_revision	Revision number of the ECS task definition.
log_stream_prefix	Prefix for the CloudWatch log stream.
security_group_id	ID of the VPC security group attached to the service.
security_group_name	Name of the VPC security group attached to the service.
task_role_arn	ARN of the IAM role attached to the task containers.
task_role_name	Name of the IAM role attached to the task containers.