Skip to main content
Version: 18.x

Server Auto-Discovery for Amazon EC2

Report an Issue

This guide shows you how to configure Teleport to automatically enroll EC2 instances in your cluster.

How it works​

In the setup we describe in this guide, the Teleport Discovery Service connects to Amazon EC2 and reconciles the servers enrolled on the Auth Service backend with servers it lists from the EC2 API. If an EC2 instance matches a configured label and is not enrolled in your cluster, the Discovery Service executes a script on these discovered instances using AWS Systems Manager that installs Teleport, starts it and joins the cluster using the IAM join method.

The Teleport Discovery Service uses an IAM invite token with a long time-to-live (TTL), so that new instances can be discovered and added to the Teleport cluster for the lifetime of the token.

Discover EC2 instances in Auto Scaling groups​

Teleport supports discovering EC2 instances launched by Amazon EC2 Auto Scaling groups (ASGs). The Discovery Service discovers and enrolls ASG members as ordinary EC2 instances through the existing EC2 discovery process. No ASG-specific Teleport configuration is required.

When matching instances by AWS tags, configure the ASG tags with PropagateAtLaunch=true. Tags applied only to the ASG are not present on its EC2 instances and therefore cannot be used by the Discovery Service matcher. The Discovery Service enrolls newly launched instances during later discovery scans. It excludes terminated instances from discovery.

Choosing guided or manual EC2 auto-discovery configuration​

In the guided EC2 auto-discovery configuration process, Teleport generates its own policies and SSM documents for the Discovery Service to use.

If you want to have more control over the policies and SSM documents used, manual or Terraform configuration may be suitable for you.

Choosing single-account or organization-level EC2 auto-discovery​

If you want to discover EC2 instances in a single AWS account, follow either the Guided EC2 Auto-Discovery Configuration or Manual EC2 Auto-Discovery Configuration guides.

If you want to discover EC2 instances across multiple AWS accounts in an AWS Organization, follow one of the Organization-level guides.

Guides​