# EC2 Tags as Teleport Node Labels

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` is present, its value (must be lower case) 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
```

---

NOTE

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. If you want to get started with Teleport, [sign up](https://goteleport.com/signup) for a free trial or [set up a demo environment](https://goteleport.com/docs/get-started/deploy-community.md).

- The `tctl` and `tsh` clients.

  Installing `tctl` and `tsh` clients

  1. Determine the version of your Teleport cluster. The `tctl` and `tsh` clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at `/v1/webapi/find` and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service:

     ```
     $ TELEPORT_DOMAIN=teleport.example.com:443
     $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"
     ```

  2. Follow the instructions for your platform to install `tctl` and `tsh` clients:

     **Mac**

     Download the signed macOS .pkg installer for Teleport, which includes the `tctl` and `tsh` clients:

     ```
     $ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg
     ```

     In Finder double-click the `pkg` file to begin installation.

     ---

     DANGER

     Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security.

     ---

     **Windows - Powershell**

     ```
     $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip
     Unzip the archive and move the `tctl` and `tsh` clients to your %PATH%
     NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP.
     Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\<username>) instead.
     ```

     **Linux**

     All of the Teleport binaries in Linux installations include the `tctl` and `tsh` clients. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our [installation page](https://goteleport.com/docs/installation.md).

     ```
     $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ cd teleport
     $ sudo ./install
     Teleport binaries have been copied to /usr/local/bin
     ```

* One Teleport Agent running on an Amazon EC2 instance. See [our guides](https://goteleport.com/docs/enroll-resources/agents.md) 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](https://docs.aws.amazon.com/awsec2/latest/userguide/using_tags.html#allow-access-to-tags-in-imds) for more details.

---

NOTE

Only instances that are running on the [Nitro system](https://docs.aws.amazon.com/awsec2/latest/userguide/instance-types.html#ec2-nitro-instances) will update their tags while running. All other instance types [must be restarted](https://docs.aws.amazon.com/awsec2/latest/userguide/using_tags.html#work-with-tags-in-imds) 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](/docs/assets/images/launch-instance-advanced-options-9806e9ce74b0f1477cdf9231e797e387.png)

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`.

![Instance Settings](/docs/assets/images/instance-settings-7568bf149deebb81249906edf273b7a6.png)

1. Enable `Allow`.

![Allow Tags](/docs/assets/images/allow-tags-4cdc71fd89977e771c191fc4d642b87d.png)

### 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
```