Reference for the teleport-agent-aws Terraform module
This page lists the input fields and output values of the teleport-agent-aws Terraform module.
Teleport Agent Services Deployment on AWS ECS
This module deploys a Teleport Database Service to AWS as an ECS task. It can generate the configuration, IAM permissions, and Teleport IAM join token for the Database Service. It is not intended to deploy a Teleport cluster or its Auth Service and Proxy Service control plane. This module does not provision the persistent backend and audit event storage, load balancing, DNS, or TLS certificates required to operate a self-hosted Teleport cluster.
Set var.region on each module instance to deploy Database Services across
multiple Regions using a single AWS provider configuration.
By default, the module creates an outbound security group for the Database
Service and a database-access security group that allows traffic from the
outbound group. The database-access group is returned as
database_security_group_id so it can be attached to databases. As an
alternative, set database_service.database_security_group_ids to have the
module add ingress rules to existing database security groups, sourced from
the outbound Database Service security group.
For an existing VPC, the module discovers its subnets and classifies them by their effective route tables' IPv4 default routes. It deploys to up to 16 private subnets whose default routes target AWS NAT gateways when available; otherwise, it deploys to up to 16 public subnets whose default routes target an AWS internet gateway and assigns public IP addresses to the ECS tasks. The deployment fails when neither class provides internet access.
When creating a VPC in the same Terraform apply, pass its private_subnet_ids
or public_subnet_ids outputs to bypass subnet discovery. Private subnets are always
preferred when both are provided.
Prerequisites
- An existing Teleport cluster with Auth Service and Proxy Service
- A reachable Teleport Proxy Service endpoint
- A supported join method and credentials that the agent can use to join the cluster. Database Service deployments create an IAM join token by default. See the Join Methods and Token Reference for other supported join methods and creating tokens.
Examples
Refer to the examples for example usage of this module.
How to get help
If you're having trouble, check out our GitHub Discussions.
For bugs related to this code, please open an issue.
Requirements
| Name | Version |
|---|---|
| terraform | >= 1.5.7 |
| aws | >= 6.0 |
| http | >= 3.0 |
| random | >= 3.0 |
| teleport | >= 18.8.0 |
Providers
| Name | Version |
|---|---|
| aws | >= 6.0 |
| http | >= 3.0 |
| random | >= 3.0 |
| teleport | >= 18.8.0 |
Modules
No modules.
Resources
Inputs
| Name | Description | Type | Default | Required |
|---|---|---|---|---|
| apply_aws_tags | Additional AWS tags to apply to all created AWS resources. | map(string) | {} | no |
| create | Toggle creation of all resources. | bool | true | no |
| create_security_group | Whether to create the Teleport instance outbound security group and the shared database-access security group. | bool | true | no |
| database_service | Teleport Database Service configuration. Set enabled to true to run the Teleport Database Service. Set allow_database_modification to true to add RDS permissions that allow the service to modify database configuration. Set default_iam_policy_database_types to the database types for which default IAM policy statements should be added to the ECS task role's inline policy. Supported default IAM policy database types are rds and rdsproxy. Statements in the default IAM policy can be overridden by a statement with a matching SID in var.ecs_task_role_inline_policy. When resources is null, a default resource matcher is used that matches databases in the same account, region, and VPC. Set database_security_group_ids to database security groups that should allow traffic from the Teleport Database Service. Setting database_security_group_ids requires create_security_group to be true. When ecs_task_role_self_assumption_allowed is true, each matcher's aws.assume_role_arn defaults to the ECS task role ARN, including custom matchers. Set aws.assume_role_arn to another role ARN to override this default, or to an empty string to disable role assumption for that matcher. | object({ allow_database_modification = optional(bool, false) database_security_group_ids = optional(list(string), []) default_iam_policy_database_types = optional(list(string), []) enabled = optional(bool, false) resources = optional(list(object({ labels = map(list(string)) aws = optional(object({ assume_role_arn = optional(string) external_id = optional(string, "") })) })), null) }) | {} | no |
| ecs_cluster_name | Name of the ECS cluster. | string | "teleport" | no |
| ecs_cluster_use_name_prefix | Determines whether var.ecs_cluster_name is used as a prefix of the ECS cluster name. | bool | true | no |
| ecs_execution_role_inline_policy | Optional JSON policy document to merge into the inline policy attached to the ECS execution IAM role. | string | null | no |
| ecs_service_name | Name of the ECS service. | string | "teleport" | no |
| ecs_task_cloudwatch_log_group_kms_key_id | KMS key ID or ARN used to encrypt the ECS task CloudWatch log group. When null, CloudWatch Logs uses its default encryption key. | string | null | no |
| ecs_task_cloudwatch_log_group_name | Name for the ECS task CloudWatch log group. | string | "ecs-teleport" | no |
| ecs_task_cloudwatch_log_group_region | AWS Region for the ECS task CloudWatch log group. Defaults to var.region, then the AWS provider's configured Region. | string | null | no |
| ecs_task_cloudwatch_log_group_retention_days | Number of days to retain logs in the ECS task CloudWatch log group. | number | 30 | no |
| ecs_task_cloudwatch_log_group_skip_destroy | Whether to preserve the ECS task CloudWatch log group when destroying module resources. Set to true if you do not wish the log group (and any logs it may contain) to be deleted at destroy time, and instead just remove the log group from the Terraform state. | bool | false | no |
| ecs_task_cloudwatch_log_group_use_name_prefix | Determines whether var.ecs_task_cloudwatch_log_group_name is used as a prefix of the ECS task CloudWatch log group name. | bool | true | no |
| ecs_task_cpu | Number of cpu units used by the ECS task. | number | 2048 | no |
| ecs_task_definition_name | Name of the ECS task. | string | "teleport" | no |
| ecs_task_definition_use_name_prefix | Determines whether var.ecs_task_definition_name is used as a prefix of the ECS task definition name. | bool | true | no |
| ecs_task_desired_count | Desired number of Teleport ECS tasks to run. | number | 2 | no |
| ecs_task_force_new_deployment | Set to true to force the ECS service to redeploy tasks without configuration changes. | bool | false | no |
| ecs_task_memory | Amount (in MiB) of memory used by the ECS task. | number | 4096 | no |
| ecs_task_role_inline_policy | Optional JSON policy document to merge into the inline policy attached to the ECS task IAM role. | string | null | no |
| ecs_task_role_self_assumption_allowed | Whether the ECS task IAM role can assume itself. | bool | true | no |
| environment_vars | Environment variables to set on the Teleport ECS container. | map(string) | {} | no |
| join_params | Override the Teleport join parameters. When null and var.database_service.enabled is true, the module creates an IAM join token automatically. Set this to use a pre-existing token or a different join method. | object({ token_name = string method = string }) | null | no |
| log_level | Teleport log level. Only used when var.database_service.enabled is true. | string | "INFO" | no |
| managed_updates_enabled | Whether to resolve the Teleport version from the configured Managed Updates endpoint when applying this module. | bool | true | no |
| managed_updates_group | Update group to query through the v2 Managed Updates endpoint. | string | "default" | no |
| private_subnet_ids | Private subnet IDs where Teleport can be deployed. Private subnets must have a default route through an AWS NAT gateway. Set this or public_subnet_ids to bypass automatic subnet discovery, such as when the VPC is created in the same Terraform apply. When both variables are null, the module discovers and classifies all subnets in vpc_id from their effective route tables. | list(string) | null | no |
| public_subnet_ids | Public subnet IDs where Teleport can be deployed. Public subnets must have a default route through an AWS internet gateway. Set this or private_subnet_ids to bypass automatic subnet discovery, such as when the VPC is created in the same Terraform apply. When both variables are null, the module discovers and classifies all subnets in vpc_id from their effective route tables. | list(string) | null | no |
| region | AWS Region where regional resources are created. When null, the AWS provider's configured Region is used. | string | null | no |
| security_group_ids | Additional security group IDs to attach to the Teleport ECS tasks. These groups are not modified by the module. | list(string) | [] | no |
| teleport_container_image | Container image used for Teleport ECS tasks. | string | "public.ecr.aws/gravitational/teleport-ent-distroless" | no |
| teleport_provision_token_name | Name for the Teleport provision token resource. | string | "iam-agent" | no |
| teleport_provision_token_use_name_prefix | Determines whether the name of the Teleport provision token is used as a prefix. | bool | true | no |
| teleport_proxy_public_addr | Teleport cluster proxy public address host:port. Required when var.database_service.enabled is true. | string | null | no |
| teleport_version_override | teleport_version_override is intended for development and MUST NOT be used to control the Teleport version in a typical deployment. This module is designed to run a specific Teleport version. You will face compatibility issues trying to run a different Teleport version with it. If you want to run Teleport version X.Y.Z, you should adjust the module version to X.Y.Z instead. | string | null | no |
| vpc_id | VPC ID where Teleport will be deployed. | string | n/a | yes |
Outputs
| Name | Description |
|---|---|
| assign_public_ip | Whether the Teleport ECS tasks are assigned public IP addresses. |
| database_security_group_id | Shared security group ID to attach to databases to allow ingress from the Teleport Database Service. Null when create_security_group is false. |
| ecs_cluster_arn | ARN of the ECS cluster for the Teleport ECS service. |
| ecs_cluster_name | Name of the ECS cluster for the Teleport ECS service. |
| ecs_execution_role_arn | The ARN of the execution IAM role for the Teleport ECS task. |
| ecs_execution_role_name | The name of the execution IAM role for the Teleport ECS task. |
| ecs_service_arn | ARN of the Teleport ECS service. |
| ecs_service_name | Name of the Teleport ECS service. |
| ecs_service_subnet_ids | Subnet IDs selected for the Teleport ECS service, up to the AWS limit of 16. Private subnets are preferred over public subnets. |
| ecs_task_cloudwatch_log_group_arn | ARN of the CloudWatch log group for the Teleport ECS task. |
| ecs_task_cloudwatch_log_group_name | Name of the CloudWatch log group for the Teleport ECS task. |
| ecs_task_definition_arn | ARN of the Teleport ECS task definition. |
| ecs_task_role_arn | The ARN of the task IAM role for the Teleport ECS task. |
| ecs_task_role_name | The name of the task IAM role for the Teleport ECS task. |
| intra_subnet_ids | Subnet IDs discovered without a default route through an AWS NAT gateway or internet gateway. Empty when subnet classification is provided by the caller. |
| private_subnet_ids | Private subnet IDs provided by the caller or discovered from default routes through AWS NAT gateways. |
| public_subnet_ids | Public subnet IDs provided by the caller or discovered from default routes through AWS internet gateways. |
| security_group_id | Security group ID created for the Teleport ECS service. Null when create_security_group is false. |
| teleport_provision_token_allow_aws_arn | A value that can be used with a Teleport IAM join token to allow the ECS cluster to join the Teleport cluster using its IAM credentials. |
| teleport_provision_token_name | Name of the Teleport provision token that allows the Teleport instance to join the cluster using AWS IAM credentials. |
Source Code
Was this page helpful?