Get StartedContact Sales
Fork me on GitHub

Teleport

Sync EC2 Tags and Teleport Node Labels

Version 14.x
  • Available for:
  • OpenSource
  • Team
  • Cloud
  • Enterprise

When running on an AWS EC2 instance, Teleport will automatically detect and import EC2 tags as Teleport labels for SSH nodes, Applications, Databases, and Kubernetes clusters. Labels created this way will have the aws/ prefix. When the Teleport process starts, it fetches all tags from the instance metadata service and adds them as labels. The process will update the tags every hour, so newly created or deleted tags will be reflected in the labels.

If the tag TeleportHostname (case-sensitive) is present, its value will override the node's hostname.

$ tsh ls
Node Name            Address        Labels                                                                                                                  
-------------------- -------------- ----------------------------------------------------------------------------------------------------------------------- 
fakehost.example.com 127.0.0.1:3022 env=example,hostname=ip-172-31-53-70,aws/Name=atburke-dev,aws/TagKey=TagValue,aws/TeleportHostname=fakehost.example.com

For services that manage multiple resources (such as the Database Service), each resource will receive the same labels from EC2.

Prerequisites

  • A running Teleport cluster. For details on how to set this up, see the Getting Started guide.

  • The tctl admin tool and tsh client tool version >= 14.2.0.

    See Installation for details.

To check version information, run the tctl version and tsh version commands. For example:

tctl version
Teleport v14.2.0 git:api/14.0.0-gd1e081e go1.21
  
tsh version
Teleport v14.2.0 go1.21
Proxy version: 14.2.0Proxy: teleport.example.com

  • A Teleport Team account. If you don't have an account, sign up to begin your free trial.

  • The Enterprise tctl admin tool and tsh client tool, version >= 14.1.3.

    You can download these tools from the Cloud Downloads page.

To check version information, run the tctl version and tsh version commands. For example:

tctl version
Teleport Enterprise v14.1.3 git:api/14.0.0-gd1e081e go1.21
  
tsh version
Teleport v14.1.3 go1.21
Proxy version: 14.1.3Proxy: teleport.example.com

  • A running Teleport Enterprise cluster. For details on how to set this up, see the Enterprise Getting Started guide.

  • The Enterprise tctl admin tool and tsh client tool version >= 14.2.0.

    You can download these tools by visiting your Teleport account workspace.

To check version information, run the tctl version and tsh version commands. For example:

tctl version
Teleport Enterprise v14.2.0 git:api/14.0.0-gd1e081e go1.21
  
tsh version
Teleport v14.2.0 go1.21
Proxy version: 14.2.0Proxy: teleport.example.com

  • A Teleport Enterprise Cloud account. If you don't have an account, sign up to begin a free trial of Teleport Team and upgrade to Teleport Enterprise Cloud.

  • The Enterprise tctl admin tool and tsh client tool version >= 14.1.3.

    You can download these tools from the Cloud Downloads page.

To check version information, run the tctl version and tsh version commands. For example:

tctl version
Teleport Enterprise v14.1.3 git:api/14.0.0-gd1e081e go1.21
  
tsh version
Teleport v14.1.3 go1.21
Proxy version: 14.1.3Proxy: teleport.example.com
  • One Teleport agent running on an Amazon EC2 instance. See our guides for how to set up Teleport agents.

Enable tags in instance metadata

To allow Teleport to import EC2 tags, tags must be enabled in the instance metadata. This can be done via the AWS console or the AWS CLI. See the AWS documentation for more details.

Note

Only instances that are running on the Nitro system will update their tags while running. All other instance types must be restarted to update tags.

AWS EC2 Console

To launch a new instance with instance metadata tags enabled:

  1. Open Advanced Options at the bottom of the page.
  2. Ensure that Metadata accessible is not disabled.
  3. Enable Allow tags in metadata.
Advanced Options
Advanced Options

To modify an existing instance to enable instance metadata tags:

  1. From the instance summary, go to Actions > Instance Settings > Allow tags in instance metadata.
  2. Enable Allow.
Instance Settings
 Allow Tags
Allow Tags

AWS CLI

To modify the instance at launch:

aws ec2 run-instances \    --image-id <image-id> \    --instance-type <instance-type> \    --metadata-options "InstanceMetadataTags=enabled"
    ...

To modify a running instance:

aws ec2 modify-instance-metadata-options \    --instance-id i-123456789example \    --instance-metadata-tags enabled