Terraform Cloud Agent on Amazon ECS

This solution creates self-hosted HashiCorp Cloud Platform (HCP) Terraform agent on Amazon ECS cluster. HCP Terraform allows you to manage isolated, private, or on-premises infrastructure using self-hosted HCP Terraform agents. The agent polls HCP Terraform or HCP Terraform Enterprise for any changes to your configuration and executes the changes locally, so you do not need to allow public ingress traffic to your resources. Agents allow you to control infrastructure in private environments without modifying your network perimeter.

Architecture

Prerequisites

To use this module you need to have the following:

1. HashiCorp Cloud Platform (HCP) Terraform subscription
2. Terraform API token with permission to create Terraform agent pool
3. AWS account and credentials to provision resources as mentioned below.
4. VPC with private subnets

Getting Started

Please refer to the examples on how to get started.

Requirements

Name	Version
terraform	>= 1.5.0
aws	>= 5.0.0
tfe	>= 0.54

Providers

Name	Version
aws	>= 5.0.0
tfe	>= 0.54

Modules

Name	Source	Version
ecs_cluster	git::https://github.com/terraform-aws-modules/terraform-aws-ecs	6b52c965734d95767d8e20d965afcd0db29dae5e

Resources

Name	Type
aws_cloudwatch_log_group.cloudwatch	resource
aws_ecs_service.hcp_terraform_agent	resource
aws_ecs_task_definition.hcp_terraform_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.ssm_access_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_kms_key.log_ssm_key	resource
aws_security_group.hcp_terraform_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_caller_identity.current	data source
aws_iam_policy_document.agent_assume_role_policy	data source
aws_iam_policy_document.agent_init_policy	data source
aws_iam_policy_document.kms_key_policy	data source
aws_iam_policy_document.ssm_access_policy	data source
aws_region.current	data source

Inputs

Name	Description	Type	Default	Required
hcp_terraform_org_name	The name of the HCP Terraform or HCP Terraform Enterprise organization where the agent pool will be configured. The combination of hcp_terraform_org_name and name must be unique within an AWS account.	string	n/a	yes
name	A name to apply to resources. The combination of name and hcp_terraform_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	list(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_cidr_blocks	CIDR blocks to allow the agent to communicate with the HCP Terraform instance.	list(string)	[ "0.0.0.0/0" ]	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_egress_ports	Egress ports to allow the agent to communicate with the HCP Terraform instance.	set(string)	[ "443", "7146" ]	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
cloudwatch_log_group_name	The name of the CloudWatch log group where agent logs will be sent.	string	"/hcp/hcp-terraform-agent"	no
cloudwatch_log_group_retention	The number of days to retain logs in the CloudWatch log group.	number	365	no
create_cloudwatch_log_group	Whether the CloudWatch log group should be created.	bool	true	no
create_ecs_cluster	Whether to create a new ECS cluster for the agent.	bool	true	no
create_tfe_agent_pool	Whether to omit agent pool/token creation	bool	true	no
ecs_cluster_arn	ARN of the ECS cluster where the agent will be deployed.	string	"arn:aws:ecs:us-west-2:000000000000:cluster/ecs-basic"	no
extra_env_vars	Extra environment variables to pass to the agent container.	list(object({ name = string value = string }))	[]	no
hcp_terraform_address	The HTTPS address of the HCP Terraform or HCP Terraform Enterprise instance.	string	"https://app.terraform.io"	no
kms_key_arn	The ARN of the KMS key to create. If empty, a new key will be created.	string	""	no
num_agents	The number of agent containers to run.	number	1	no
tags	Map of tags to apply to resources deployed by this solution.	map(any)	null	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
tfe_agent_pool_name	Terraform agent pool name to be used when agent creation is omitted	string	""	no
tfe_agent_token	Terraform agent token to be used when agent creation is omitted	string	""	no
use_spot_instances	Whether to use Fargate Spot instances.	bool	false	no

Outputs

Name	Description
agent_pool_id	ID of the HCP Terraform agent pool.
agent_pool_name	Name of the HCP Terraform 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.
kms_key_arn	The ARN of the created KMS key
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.