Reference for the teleport-discovery-aws Terraform module

Report an Issue

Is this page helpful?

How can we improve this page?

View as Markdown

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 AWS resources.

• 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"
  }

  # Configure matchers to discover EC2 instances and EKS clusters.
  aws_matchers = [
    {
      types   = ["ec2"]
      # EC2 discovery supports wildcard to find instances in all regions.
      regions = ["*"]
      tags = {
        origin = ["example"]
      }
    },
    {
      types   = ["eks"]
      regions = ["*"]
      tags = {
        team = ["platform"]
      }
    }
  ]
}

aws_matchers fields

Field	Type	Default	Description
types	list(string)	(required)	AWS resource types to discover. Allowed values: ec2, eks.
regions	list(string)	(required)	AWS regions to search. Use "*" for all regions.
tags	map(list(string))	{ "*" : ["*"] }	AWS resource tags to match. The default matches all resources.
setup_access_for_arn	string	""	ARN to configure access for discovered EKS clusters. Only supported for EKS matchers.
kube_app_discovery	bool	null	Teleport's Kubernetes App Discovery will automatically identify and enroll to Teleport HTTP applications running inside a Kubernetes cluster.

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.8.3
tls	>= 4.0

Providers

Name	Version
aws	>= 5.0
http	>= 3.0
teleport	>= 18.8.3
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_policy.teleport_organization_account_enumeration	resource
aws_iam_policy.teleport_organization_join_validation	resource
aws_iam_role.teleport_discovery_service	resource
aws_iam_role_policy_attachment.teleport_discovery_service	resource
aws_iam_role_policy_attachment.teleport_organization_account_enumeration	resource
aws_iam_role_policy_attachment.teleport_organization_join_validation	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.allow_assume_role_for_child_accounts	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_iam_policy_document.teleport_organization_account_enumeration	data source
aws_iam_policy_document.teleport_organization_join_validation	data source
aws_organizations_organization.this	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_child_account_iam_role_name	Name for the AWS IAM role to assume in child accounts. This role must be created manually in each account. Check the module outputs aws_child_account_iam_role_template for the trust relationship and permissions required.	string	"teleport-organization-discovery-child-account-role"	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
aws_matchers	AWS resource discovery matchers. Valid values for aws_matchers.types are: ec2, eks, rds.	list(object({ types = list(string) regions = optional(list(string), ["*"]) tags = optional(map(list(string)), { "*" : ["*"] }) setup_access_for_arn = optional(string, "") kube_app_discovery = optional(bool) }))	[]	no
aws_organization_discovery	Discover resources in accounts under the organization, filtered by Organizational Units (the Organization's Root ID or * can be used to include the entire organization). A specific IAM role must be created in each account, to be assumed by the Discovery Service. Check the module outputs for the trust relationship and permissions required for the role. Limitations: only EC2 is supported.	object({ organizational_units = object({ include = list(string) exclude = optional(list(string), null) }) })	null	no
aws_organization_discovery_iam_principal_arn	ARN of the AWS IAM principal used by the Discovery Service when AWS Organization discovery is configured without an OIDC integration. Required only when aws_organization_discovery is set and discovery_service_iam_credential_source.use_oidc_integration is false; this ARN is used in the child-account IAM role trust policy template.	string	""	no
aws_organization_iam_policies	AWS IAM policy customizations for organization-wide discovery to be created in AWS management account.	object({ account_enumeration = optional(object({ name = optional(string, "teleport-organization-account-enumeration") use_name_prefix = optional(bool, true) document = optional(string, "") }), {}) join_validation = optional(object({ name = optional(string, "teleport-organization-join-validation") use_name_prefix = optional(bool, true) document = optional(string, "") }), {}) })	{}	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, true) trust_role = optional(object({ role_arn = string external_id = optional(string, "") })) })	{ "trust_role": null, "use_oidc_integration": true }	no
match_aws_regions	Deprecated legacy input. Use aws_matchers instead. AWS regions to discover. The default matches all AWS regions.	list(string)	[ "*" ]	no
match_aws_resource_types	Deprecated legacy input. Use aws_matchers instead. AWS resource types to match when discovering resources with Teleport.	list(string)	[]	no
match_aws_tags	Deprecated legacy input. Use aws_matchers instead. 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_child_account_iam_role_template	Create this AWS IAM Role in each Organization's account, so that the Discovery Service can assume it to discover resources in those accounts.
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_organization_account_enumeration_iam_policy_arn	AWS resource name (ARN) of the AWS IAM policy that grants the permissions needed for Teleport to enumerate accounts in the AWS organization. Only set when aws_organization_discovery is configured with the OIDC integration.
teleport_organization_account_enumeration_iam_role_template	When not using OIDC, attach this policy to the AWS principal used by the Discovery Service.
teleport_organization_join_validation_iam_policy_arn	AWS resource name (ARN) of the AWS IAM policy that grants the permissions needed for the Teleport Auth Service to validate IAM-method join attempts against the organization. Only set when aws_organization_discovery is configured with the OIDC integration.
teleport_organization_join_validation_iam_role_template	When not using OIDC, attach this policy to the AWS principal used by the Auth Service.
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>.