Example for discovering AWS resources in all accounts under an organization
This page lists the configuration fields in a usage example of the teleport-discovery-aws Terraform module: organization.
Teleport AWS Organization Discovery Example
Configuration in this directory creates AWS and Teleport resources necessary for Teleport to discover resources in multiple AWS accounts under the same Organization.
Currently, only EC2 discovery is supported when doing organization-wide discovery.
Run Terraform with credentials from the AWS Organization management account or a delegated administrator account. The Discovery Service and Auth Service must use credentials from one of these accounts to call the required AWS Organizations APIs.
After applying, you have to manually create an IAM Role in each target account using the details provided in the aws_child_account_iam_role_template output, which you can get by running terraform output. When the root or * is included, this also includes the management or delegated administrator account.
Use the following template, obtained from terraform output, to create the IAM role in each target account.
{
"aws_child_account_iam_role_template" = {
"assume_role_policy" = <<-EOT
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Principal": {
"AWS": "arn:aws:iam::<aws-root-account-id>:role/teleport-discovery-<timestamp>"
},
"Condition": {
"StringEquals": {
"aws:PrincipalOrgID": "<aws-organization-id>"
}
}
}
]
}
EOT
"policy" = <<-EOT
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:SendCommand",
"ssm:ListCommandInvocations",
"ssm:GetCommandInvocation",
"ssm:DescribeInstanceInformation",
"ec2:DescribeInstances",
"account:ListRegions"
],
"Resource": "*"
}
]
}
EOT
"role_name" = "teleport-organization-discovery-child-account-role"
}
# ...
}
When not using the AWS OIDC integration, you also have to create two extra IAM Roles in a management or delegated administrator account:
teleport_organization_account_enumeration_iam_role_template: must be accessible from the Discovery Service and is used to enumerate all the accounts under the Organization and to assume the role created in each target account.teleport_organization_join_validation_iam_role_template: must be accessible from the Auth Service and is used to accept join attempts from target EC2 instances.
You must also set aws_organization_discovery_iam_principal_arn to the ARN of the AWS IAM principal used by the Discovery Service. The child account IAM role template uses this ARN in its trust policy.
You can get the role details by running terraform output.
Requirements
| Name | Version |
|---|---|
| terraform | >= 1.5.7 |
| aws | >= 5.0 |
| teleport | >= 18.8.3 |
| tls | >= 4.0 |
Providers
No providers.
Modules
| Name | Source | Version |
|---|---|---|
| aws_discovery | ../.. | n/a |
Resources
No resources.
Inputs
No inputs.
Outputs
| Name | Description |
|---|---|
| aws_discovery | n/a |
Source Code
View the organization example source code for the teleport-discovery-aws module on GitHub.
################################################################################
# teleport/discovery/aws/examples/organization/main.tf
################################################################################
module "aws_discovery" {
source = "terraform.releases.teleport.dev/teleport/discovery/aws"
version = "~> 18.0"
teleport_proxy_public_addr = "example.teleport.sh:443"
teleport_discovery_group_name = "cloud-discovery-group"
# Enroll resources from all AWS Accounts in the Organization
# Only EC2 resource discovery is supported for organization-wide discovery.
aws_organization_discovery = {
organizational_units = {
# Include accounts under any Organizational Unit.
# At least one organizational unit must be included. You can use the root ID or the `*` to include the entire organization.
include = ["*"]
# Exclude the Organizational Unit's accounts and all their descendants.
# Takes precedence over the include rule, so accounts under this OU will not be enrolled even if the include rule matches them.
# Only exact matches are supported for exclusion, wildcards are not allowed.
exclude = ["ou-1234-abcdwxyz"]
}
}
# Each child account in the organization must have an IAM role with this name.
# This role is assumed by the discovery service to enroll resources from that account.
# The required trust relationship and permissions for this role can be found in the module outputs and documentation.
aws_child_account_iam_role_name = "teleport-organization-discovery-child-account-role"
# Discover EC2 instances using matching rules.
# Accepts "*" to discover across all enabled regions.
# The module adds account:ListRegions to the IAM policy automatically when "*" is used.
aws_matchers = [
{
types = ["ec2"]
# EC2 discovery supports a wildcard to find instances in all regions.
regions = ["*"]
tags = {
env = ["prod"]
}
}
]
# Apply the additional Teleport label "origin=example" to all Teleport resources created by this module
apply_teleport_resource_labels = { origin = "example" }
# Apply the additional AWS tag "origin=example" to all AWS resources created by this module
apply_aws_tags = { origin = "example" }
}
################################################################################
# teleport/discovery/aws/examples/organization/outputs.tf
################################################################################
output "aws_discovery" {
value = module.aws_discovery
}
################################################################################
# teleport/discovery/aws/examples/organization/versions.tf
################################################################################
terraform {
required_version = ">= 1.5.7"
required_providers {
aws = {
source = "hashicorp/aws"
version = ">= 5.0"
}
tls = {
source = "hashicorp/tls"
version = ">= 4.0"
}
teleport = {
source = "terraform.releases.teleport.dev/gravitational/teleport"
version = ">= 18.8.3"
}
}
}