Reference for the teleport-discovery-aws Terraform module

Report an Issue

Is this page helpful?

How can we improve this page?

Source Code: github.com/gravitational/teleport/tree/master/integrations/terraform-modules/teleport/discovery/aws

AWS Discovery Terraform module

This Terraform module creates the AWS and Teleport cluster resources necessary for a Teleport cluster to discover resources in AWS.

• AWS IAM role for Teleport Discovery Service to assume.
• AWS IAM policy attached to the IAM role that grants the AWS permissions necessary for Teleport to discover resources in AWS.
• AWS OIDC Provider for Teleport Discovery Service to assume an IAM role using OIDC. This resource is optional - creation can be disabled using create_aws_iam_openid_connect_provider = false. This resource is optional to support two scenarios:
  • When there is already an AWS IAM OIDC provider in the AWS account configured to use your Teleport cluster's proxy URL. AWS restricts AWS IAM OIDC providers to one per unique URL, so if you are managing that provider already then this module cannot create another one for the same Teleport cluster.
  • When AWS IAM OIDC federation is not possible because your Teleport cluster's proxy URL is not reachable. In this case you should configure AWS IAM role credentials for your Teleport Discovery Service instances and set discovery_service_iam_credential_source to trust that role.
• Teleport discovery_config cluster resource that configures Teleport for AWS resource discovery.
• Teleport integration cluster resource for AWS OIDC.
• Teleport token cluster resource that allows Teleport nodes to use AWS IAM credentials to join the cluster.

Prerequisites

• Configure Teleport Terraform Provider
• Configure AWS Terraform provider

Usage

module "aws_discovery" {
  source = "terraform.releases.teleport.dev/teleport/discovery/aws"

  # Your Teleport cluster public proxy address - host:port format is required.
  teleport_proxy_public_addr = "example.teleport.sh:443"
  # Teleport Discovery Service instances in this discovery group will be configured to discover AWS resources.
  # "cloud-discovery-group" is the group name of the discovery service instances running in Teleport Cloud clusters.
  teleport_discovery_group_name = "cloud-discovery-group"

  # apply additional tags to the AWS resources created by the module
  apply_aws_tags = {
    Terraform = "true"
    Env       = "dev"
  }
  # Match EC2 instances that have the AWS tag "origin=example"
  match_aws_resource_types = ["ec2"]
  match_aws_tags = {
    origin = ["example"]
  }
}

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	>= 5.0
http	>= 3.0
teleport	>= 18.5.1
tls	>= 4.0

Providers

Name	Version
aws	>= 5.0
http	>= 3.0
teleport	>= 18.5.1
tls	>= 4.0

Modules

No modules.

Resources

Name	Type
aws_iam_openid_connect_provider.teleport	resource
aws_iam_policy.teleport_discovery_service	resource
aws_iam_role.teleport_discovery_service	resource
aws_iam_role_policy_attachment.teleport_discovery_service	resource
teleport_discovery_config.aws	resource
teleport_integration.aws_oidc	resource
teleport_provision_token.aws_iam	resource
aws_caller_identity.this	data source
aws_iam_policy_document.teleport_discovery_service_iam_role_trust	data source
aws_iam_policy_document.teleport_discovery_service_single_account	data source
aws_partition.this	data source
http_http.teleport_ping	data source
tls_certificate.teleport_proxy	data source

Inputs

Name	Description	Type	Default	Required
apply_aws_tags	Additional AWS tags to apply to all created AWS resources.	map(string)	{}	no
apply_teleport_resource_labels	Additional Teleport resource labels to apply to all created Teleport resources.	map(string)	{}	no
aws_iam_policy_document	Override the AWS IAM policy document attached to the AWS IAM role for resource discovery.	string	""	no
aws_iam_policy_name	Name for the AWS IAM policy for discovery.	string	"teleport-discovery"	no
aws_iam_policy_use_name_prefix	Determines whether the name of the AWS IAM policy (aws_iam_policy_name) is used as a prefix.	bool	true	no
aws_iam_role_name	Name for the AWS IAM role for discovery.	string	"teleport-discovery"	no
aws_iam_role_use_name_prefix	Determines whether the name of the AWS IAM role (aws_iam_role_name) is used as a prefix.	bool	true	no
create	Toggle creation of all resources.	bool	true	no
create_aws_iam_openid_connect_provider	Toggle AWS IAM OIDC provider creation. If false and using OIDC, then the AWS IAM OIDC provider must already exist.	bool	true	no
discovery_service_iam_credential_source	Configure the AWS credential source for Teleport Discovery Service instances. The default uses AWS OIDC integration.	object({ use_oidc_integration = optional(bool) trust_role = optional(object({ role_arn = string external_id = optional(string, "") })) })	{ "trust_role": null, "use_oidc_integration": true }	no
match_aws_regions	AWS regions to discover. The default matches all AWS regions.	list(string)	[ "*" ]	no
match_aws_resource_types	AWS resource types to match when discovering resources with Teleport. Valid values are: ec2.	list(string)	n/a	yes
match_aws_tags	AWS resource tags to match when discovering resources with Teleport. The default matches all discovered AWS resources.	map(list(string))	{ "*": [ "*" ] }	no
teleport_discovery_config_name	Name for the teleport_discovery_config resource.	string	"discovery"	no
teleport_discovery_config_use_name_prefix	Determines whether the name of the Teleport discovery config (teleport_discovery_config_name) is used as a prefix.	bool	true	no
teleport_discovery_group_name	Teleport discovery group to use. For discovery configuration to apply, this name must match at least one Teleport Discovery Service instance's configured discovery_group. For Teleport Cloud clusters, use "cloud-discovery-group".	string	n/a	yes
teleport_integration_name	Name for the teleport_integration resource.	string	"discovery"	no
teleport_integration_use_name_prefix	Determines whether the name of the Teleport integration (teleport_integration_name) is used as a prefix.	bool	true	no
teleport_provision_token_name	Name for the teleport_provision_token resource.	string	"discovery"	no
teleport_provision_token_use_name_prefix	Determines whether the name of the Teleport provision token (teleport_provision_token_name) is used as a prefix.	bool	true	no
teleport_proxy_public_addr	Teleport cluster proxy public address host:port.	string	n/a	yes

Outputs

Name	Description
aws_oidc_provider_arn	AWS resource name (ARN) of the AWS OpenID Connect (OIDC) provider that allows Teleport Discovery Service to assume an AWS IAM role using OIDC.
teleport_discovery_config_name	Name of the Teleport dynamic discovery_config. Configuration details can be viewed with tctl get discovery_config/<name>. Teleport Discovery Service instances will use this discovery_config if they are in the same discovery group as the discovery_config.
teleport_discovery_service_iam_policy_arn	AWS resource name (ARN) of the AWS IAM policy that grants the permissions needed for Teleport to discover resources in AWS.
teleport_discovery_service_iam_role_arn	AWS resource name (ARN) of the AWS IAM role that Teleport Discovery Service will assume.
teleport_integration_name	Name of the Teleport integration resource. The integration resource configures Teleport Discovery Service instances to assume an AWS IAM role for discovery using AWS OIDC federation. Integration details can be viewed with tctl get integrations/<name> or by visiting the Teleport web UI under 'Zero Trust Access' > 'Integrations'.
teleport_provision_token_name	Name of the Teleport provision token that allows Teleport nodes to join the Teleport cluster using AWS IAM credentials. Token details can be viewed with tctl get token/<name>.

Was this page helpful?

How can we improve this page?