Runs one Depot controller ECS service for Depot Managed.
module "controller" {
source = "depot/controller/aws"
version = "x.x.x"
name = "acme"
token = "/depot/controller/acme-token"
# Optional when the token SecureString uses a customer-managed KMS key.
token-kms-key-arn = "arn:aws:kms:us-east-1:123456789012:key/00000000-0000-0000-0000-000000000000"
ecs-cluster-name = "cluster"
subnet-ids = ["subnet-abc123", "subnet-def456"]
security-group-ids = ["sg-abc123"]
}This module starts the Depot controller service only. It expects:
- a Depot controller token to already be stored in SSM Parameter Store
- an ECS cluster, subnets, and security group to already exist
For customer-managed Depot controllers, create the token from the Depot organization
settings page and store it in SSM under the value passed to token. Use a
SecureString parameter for the token. When the SecureString uses a
customer-managed KMS key, pass that key ARN as token-kms-key-arn so the ECS
execution role can decrypt the secret at task startup.
By default, the task role can assume target account roles matching:
arn:<current AWS partition>:iam::*:role/depot-connection-*-controller
Pass assume-role-arns when the Depot controller should be restricted to a narrower set of
target connection role ARNs.
Pass this module's controller-role-arn output into each depot/connection/aws
module in the same AWS partition. For GovCloud, run this module with an
aws-us-gov provider/account so the controller role ARN originates from the
GovCloud partition.
Auto-update is enabled by default. When Depot reports a newer active Depot controller
version for the configured auto-update-channel, the Depot controller asks ECS to
force a new deployment of this service. This lets ECS resolve mutable image tags,
such as ghcr.io/depot/cloudd:stable, to fresh image digests for the new
deployment.
This only upgrades automatically when controller-image uses a mutable tag. If the
image is pinned to a digest, ECS will keep deploying that digest until Terraform
or another external release process updates the task definition image.
The default channel is stable, matching the default
controller-image = "ghcr.io/depot/cloudd:stable". Depot-owned staging
controllers can set both controller-image = "ghcr.io/depot/cloudd:main" and
auto-update-channel = "main" to follow merges to main.
Set auto-update-enabled = false for customer-hosted or high-compliance
installations that manage upgrades externally. In that mode, the module sets
CLOUDD_AUTO_UPDATER_ENABLED=false, omits the
CLOUDD_AUTO_UPDATER_CLUSTER_ARN and CLOUDD_AUTO_UPDATER_SERVICE_NAME
environment variables, and does not grant the Depot controller ECS update permissions.
| Name | Description | Type | Default | Required |
|---|---|---|---|---|
| name | Name used to namespace AWS resources for this Depot controller. | string |
n/a | yes |
| security-group-ids | Existing security group IDs for the Depot controller ECS service. | list(string) |
n/a | yes |
| subnet-ids | Existing subnet IDs for the Depot controller ECS service. | list(string) |
n/a | yes |
| token | SSM parameter name containing DEPOT_API_TOKEN for the Depot controller. | string |
n/a | yes |
| assign-public-ip | Whether ECS should assign public IPs to Depot controller tasks. | bool |
true |
no |
| assume-role-arns | Target account role ARNs the Depot controller may assume. Defaults to the standard Depot connection controller role name in any account. | list(string) |
[] |
no |
| availability-zone-rebalancing | Availability zone rebalancing setting for the ECS service. | string |
"ENABLED" |
no |
| auto-update-enabled | Whether the Depot controller should force a new ECS service deployment when Depot reports a newer active Depot controller version. | bool |
true |
no |
| auto-update-channel | Depot controller release channel to use for auto-update checks. | string |
"stable" |
no |
| controller-image | Container image to run for the Depot controller. | string |
"ghcr.io/depot/cloudd:stable" |
no |
| ecs-cluster-name | Existing ECS cluster name where the Depot controller should run. | string |
"cluster" |
no |
| extra-env | Extra environment variables for the Depot controller. | list(object({ name = string, value = string })) |
[] |
no |
| log-retention | Number of days to keep CloudWatch logs for the Depot controller. | number |
30 |
no |
| service-name | ECS service name. Defaults to depot-controller-. | string |
null |
no |
| tags | A map of tags to apply to supported resources. | map(string) |
{} |
no |
| task-count | Desired count of Depot controller tasks. | number |
1 |
no |
| task-cpu | CPU units for the Depot controller Fargate task. | number |
1024 |
no |
| task-memory | Memory in MiB for the Depot controller Fargate task. | number |
2048 |
no |
| token-kms-key-arn | Customer-managed KMS key ARN used to encrypt the DEPOT_API_TOKEN SecureString parameter. Leave null when using the AWS-managed SSM key. | string |
null |
no |
| Name | Description | Value | Sensitive |
|---|---|---|---|
| execution-role-arn | ARN of the Depot controller ECS execution role. | "arn:aws:iam::123456789012:role/depot-controller-acme-ecs" |
no |
| controller-role-arn | ARN of the Depot controller role for connection modules to trust. | "arn:aws:iam::123456789012:role/depot-controller-acme" |
no |
| controller-role-name | Name of the Depot controller role. | "depot-controller-acme" |
no |
| log-group-name | CloudWatch log group name for the Depot controller. | "depot-controller-acme" |
no |
| partition | AWS partition for this controller. | "aws" |
no |
| service-name | Name of the Depot controller ECS service. | "depot-controller-acme" |
no |
| task-role-arn | ARN of the Depot controller task role. | "arn:aws:iam::123456789012:role/depot-controller-acme" |
no |
| token | SSM parameter name used as DEPOT_API_TOKEN for the Depot controller. | "/depot/controller/acme-token" |
no |