이 가이드에서는 Teleport가 권한을 설정하여 클러스터에 EC2 인스턴스를 자동으로 등록하도록 Teleport를 설정하는 방법을 보여줍니다.

작동 방식#

Teleport Discovery Service는 EC2 인스턴스에서 실행되며 AWS API를 조회하여 AWS 계정의 인스턴스를 나열합니다. 배포하는 새 EC2 인스턴스에 대해 Discovery Service는 AWS Systems Manager를 사용하여 인스턴스에 Teleport를 설치하고 Teleport로 보호된 서버로 클러스터에 조인시킵니다. teleport 명령을 사용하면 Discovery Service가 Teleport 클러스터에 EC2 인스턴스를 서버로 등록할 수 있는 IAM 정책을 생성할 수 있습니다.

IAM 정책과 SSM 문서를 수동으로 설정하려면 수동 EC2 자동 검색 설정을 읽어보세요.

AWS 조직에서 여러 AWS 계정을 관리하는 경우 조직 수준 EC2 자동 검색 설정을 참조하세요.

사전 조건#

• A running Teleport cluster. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

• 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 with the web address of your Teleport Proxy Service:

     $ TELEPORT_DOMAIN=
     $ 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:

• EC2 인스턴스와 IAM 정책을 생성하고 연결할 권한이 있는 AWS 계정.
• 기본 Teleport 설치 스크립트를 사용하는 경우 Ubuntu/Debian/RHEL/Amazon Linux 2/Amazon Linux 2023을 실행하고 SSM 에이전트 버전 3.1 이상을 실행하는 EC2 인스턴스. (다른 Linux 배포판의 경우 Teleport를 수동으로 설치할 수 있습니다.)

To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials.

For example, run the following command, assigning to the domain name of the Teleport Proxy Service in your cluster and to your Teleport username:

$ tsh login --proxy= --user=
$ tctl status
# Cluster  (=teleport.url=)
# Version  (=teleport.version=)
# CA pin   (=presets.ca_pin=)

If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

Discovery Service가 Teleport 클러스터에 추가할 모든 EC2 인스턴스는 Discovery Service에서 명령을 수신하기 위해 AmazonSSMManagedInstanceCore IAM 정책을 포함해야 합니다. 정책에 포함된 권한 목록은 AWS 문서를 참조하세요.

1/6 단계. EC2 초대 토큰 생성#

When discovering EC2 instances, Teleport makes use of IAM invite tokens for authenticating joining Nodes.

Create a file called token.yaml:

# token.yaml
kind: token
version: v2
metadata:
  # the token name is not a secret because instances must prove that they are
  # running in your AWS account to use this token
  name: aws-discovery-iam-token
spec:
  # use the minimal set of roles required (e.g. Node, App, Kube, DB, WindowsDesktop)
  roles: [Node]

  # set the join method allowed for this token
  join_method: iam

  allow:
  # specify the AWS account which Nodes may join from
  - aws_account: "123456789"

Assign the aws_account field to your AWS account number. Add the token to the Teleport cluster with:

$ tctl create -f token.yaml

2/6 단계. IAM 정책 설정#

teleport discovery bootstrap 명령은 자동 검색을 작동시키는 데 필요한 IAM 정책을 정의하고 구현하는 프로세스를 자동화합니다. 명령을 실행하는 EC2 인스턴스에 연결된 단일 사전 정의 정책만 필요합니다:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iam:GetPolicy",
                "iam:TagPolicy",
                "iam:ListPolicyVersions",
                "iam:CreatePolicyVersion",
                "iam:CreatePolicy",
                "iam:GetRole",
                "ssm:CreateDocument",
                "iam:DeletePolicyVersion",
                "iam:AttachRolePolicy",
                "iam:PutRolePermissionsBoundary"
            ],
            "Resource": "*"
        }
    ]
}

이 정책을 생성하고 Discovery Service를 실행할 노드(EC2 인스턴스)에 적용합니다.

3/6 단계. Discovery 노드에 Teleport 설치#

Discovery Service를 실행할 EC2 인스턴스에 Teleport를 설치합니다:

To install a Teleport Agent on your Linux server:

The recommended installation method is the cluster install script. It will select the correct version, edition, and installation mode for your cluster.

1. Assign to your Teleport cluster hostname and port, but not the scheme (https://).

2. Run your cluster's install script:

   $ curl "https:///scripts/install.sh" | sudo bash
   

4/6 단계. EC2 인스턴스를 검색하도록 Teleport 설정#

If you are running the Discovery Service on its own host, the service requires a valid invite token to connect to the cluster. Generate one by running the following command against your Teleport Auth Service:

$ tctl tokens add --type=discovery

Save the generated token in /tmp/token on the Node (EC2 instance) that will run the Discovery Service.

(!docs/pages/includes/discovery/discovery-group.mdx!)

Assign to the host and port of the Teleport Proxy Service in your cluster, and to a name that identifies a group of resources that you will enroll:

# teleport.yaml
version: v3
teleport:
  join_params:
    token_name: "/tmp/token"
    method: token
  proxy_server: "





5/6 단계. Discovery Service AWS 설정 부트스트랩#
위와 동일한 노드에서 teleport discovery bootstrap을 실행합니다. 이 명령은 Discovery Service를 활성화하는 데 필요한 추가 IAM 정책 및 AWS Systems Manager(SSM) 문서를 생성하고 표시합니다:
$ sudo teleport discovery bootstrap
Reading configuration at "/etc/teleport.yaml"...
# ...

이 명령은 Discovery Service의 역할에 다음과 같은 추가 권한을 추가합니다:

account:ListRegions
ec2:DescribeInstances
ssm:DescribeInstanceInformation
ssm:GetCommandInvocation
ssm:ListCommandInvocations
ssm:SendCommand

정책을 검토하고 확인합니다:
# ...
Confirm? [y/N]: y
✅[AWS] Create IAM Policy "TeleportEC2Discovery"... done.
✅[AWS] Create IAM Policy "TeleportEC2DiscoveryBoundary"... done.
✅[AWS] Create IAM SSM Document "AWS-RunShellScript"... done.
✅[AWS] Attach IAM policies to "alex-discovery-role"... done.

6/6 단계. Teleport 시작#

Grant the Discovery Service access to credentials that it can use to authenticate to
AWS.

If you are running the Discovery Service on an EC2 instance, you may use the EC2
Instance Metadata Service method
If you are running the Discovery Service in Kubernetes, you can use IAM Roles for
Service Accounts (IRSA)
Otherwise, you must use environment variables






Have multiple sources of AWS credentials?
Teleport's AWS client loads credentials from different sources in the following
order:

Environment Variables
Shared credentials file
Shared configuration file (Teleport always enables shared configuration)
EC2 Instance Metadata (credentials only)

While you can provide AWS credentials via a shared credentials file or shared
configuration file, you will need to run the Discovery Service with the AWS_PROFILE
environment variable assigned to the name of your profile of choice.
If you have a specific use case that the instructions above do not account for,
consult the documentation for the AWS SDK for
Go for a detailed
description of credential loading behavior.



Configure the Discovery Service to start automatically when the host boots up by
creating a systemd service for it. The instructions depend on how you installed
the Discovery Service.



You can check the status of the Discovery Service with systemctl status teleport
and view its logs with journalctl -fu teleport.

Discovery Service를 시작하면 이전에 지정한 태그와 일치하는 EC2 인스턴스가 Teleport 클러스터에 자동으로 추가되기 시작합니다.
여러 AWS 계정에서 인스턴스 검색#
Teleport Discovery Service가 실행 중인 계정 이외의 AWS 계정에서 EC2 인스턴스를 검색하려면 Teleport가 각 계정의 IAM 역할을 위임할 수 있는 권한이 있어야 합니다. 이 가이드는 위의 주요 EC2 검색 가이드를 완료했다고 가정하며 검색하려는 각 AWS 계정에 대해 반복해야 합니다.
1/5 단계. EC2 초대 토큰 업데이트#

Add a new entry to spec.allow in token.yaml and set aws_account to the
account number of the new account, including the
:
# token.yaml
kind: token
version: v2
metadata:
  name: aws-discovery-iam-token
spec:
  roles: [Node]
  join_method: iam
  allow:
  - aws_account: "123456789012"
    # Existing entry...
+ - aws_account: ""


2/5 단계. IAM 권한 설정#
대상 계정에서 새 역할을 생성하고 ARN을 기록합니다. 다음 IAM 정책을 생성하고 새 역할에 연결합니다:
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iam:GetPolicy",
                "iam:TagPolicy",
                "iam:ListPolicyVersions",
                "iam:CreatePolicyVersion",
                "iam:CreatePolicy",
                "iam:GetRole",
                "ssm:CreateDocument",
                "iam:DeletePolicyVersion",
                "iam:AttachRolePolicy",
                "iam:PutRolePermissionsBoundary"
            ],
            "Resource": "*"
        }
    ]
}

을 추가하여 Discovery Service가 위임할 수 있도록 새 역할의 신뢰 정책을 편집합니다:
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "



4/5 단계. Discovery Service AWS 설정 부트스트랩#
모든 계정이 준비되면 teleport discovery bootstrap을 다시 실행하여 나머지 IAM 정책과 SSM 문서를 생성합니다. 각 고유한 assume_role_arn/external_id에 대해 Teleport는 해당 역할을 위임하고 새 정책을 연결합니다(--attach-to-user 또는 --attach-to-role로 재정의하지 않는 경우).
$ sudo teleport discovery bootstrap

5/5 단계. Teleport 재시작#
새 인스턴스 검색을 시작하려면 Teleport 서비스를 다시 시작합니다:
$ sudo systemd restart teleport

systemctl status teleport로 Discovery Service의 상태를 확인하고 journalctl -fu teleport로 로그를 볼 수 있습니다.
자동 검색 레이블#

Teleport applies a set of default labels to resources on AWS, Azure, and Google
Cloud that join a cluster via auto-discovery. See the auto-discovery labels
reference

고급 설정#

(!docs/pages/includes/auto-discovery/server-advanced-config.mdx matcher="aws"!)
Use a custom installation script#
(!docs/pages/includes/server-access/custom-installer.mdx matcher="aws"!)
Use a custom SSM Document#
When executing the installation script on discovered EC2 instances, the Discovery Service uses an SSM document.
The default AWS-RunShellScript SSM document works in most cases and is always available in AWS.
However, if you need to customize the installation process for your environment, you can create a custom SSM Document and configure the Discovery Service to use it during installation.
The custom document's parameters must include env, scriptName and token.
The recommended approach is to use the following document and customize it as needed:
schemaVersion: '2.2'
description: aws:runShellScript
parameters:
  token:
    type: String
    description: "(Required) The Teleport invite token to use when joining the cluster."
  scriptName:
    type: String
    description: "(Required) The Teleport installer script to use when joining the cluster."
  env:
    type: String
    description: "Environment variables exported to the script. Format 'ENV=var FOO=bar'"
    default: "X=$X"
mainSteps:
- action: aws:downloadContent
  name: downloadContent
  inputs:
    sourceType: "HTTP"
    destinationPath: "/tmp/installTeleport.sh"
    sourceInfo:
      url: "https://teleport.example.com:443" />/webapi/scripts/installer/{{ scriptName }}"
- action: aws:runShellScript
  name: runShellScript
  inputs:
    timeoutSeconds: '300'
    runCommand:
      - export {{ env }}; /bin/sh /tmp/installTeleport.sh "{{ token }}"

Create this document using AWS Systems Manager in each region where you plan to discover instances.
Edit your Discovery Service configuration to use the custom SSM Document, by setting the ssm.document_name key:
# teleport.yaml
version: v3
# ...
discovery_service:
  enabled: true
  aws:
   - ssm:
       document_name: "TeleportDiscoveryInstaller"

Discover instances in all active regions#
The Discovery Service can be configured to scan all active AWS regions for EC2 instances.
Edit the AWS matcher and set the regions key to wildcard (*):
# teleport.yaml
version: v3
# ...
discovery_service:
  enabled: true
  aws:
   - regions: ["*"]
     # other fields

Add the necessary IAM permissions to allow the Discovery Service to list regions:
{
    "Effect": "Allow",
    "Action": [
        // existing permissions
        "account:ListRegions"
    ],
    "Resource": "*"
}


문제 해결#

If Installs are showing failed or instances are failing to appear check the
Command history in AWS System Manager -> Node Management -> Run Command.
Select the instance-id of the Target to review Errors.
cannot unmarshal object into Go struct field#
If you encounter an error similar to the following:
invalid format in plugin properties map[destinationPath:/tmp/installTeleport.sh sourceInfo:map[url:[https://example.teleport.sh:443/webapi/scripts/installer/preprod-installer](https://example.teleport.sh/webapi/scripts/installer/preprod-installer)] sourceType:HTTP];
error json: cannot unmarshal object into Go struct field DownloadContentPlugin.sourceInfo of type string

It is likely that you're running an older SSM agent version. Upgrade to SSM agent version 3.1 or greater to resolve.
InvalidInstanceId: Instances [[i-123]] not in a valid state for account 456#
The following problems can cause this error:

The Discovery Service doesn't have permission to access the managed node.
AWS Systems Manager Agent (SSM Agent) isn't running. Verify that SSM Agent is running.
SSM Agent isn't registered with the SSM endpoint. Try reinstalling SSM Agent.
The discovered instance does not have permission to receive SSM
commands, verify the instance includes the AmazonSSMManagedInstanceCore IAM policy.

See SSM RunCommand error codes and troubleshooting information in AWS documentation for more details:

https://docs.aws.amazon.com/systems-manager/latest/userguide/troubleshooting-managed-instances.html
https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_SendCommand.html#API_SendCommand_Errors


다음 단계#


Read Joining Nodes via AWS IAM
Role
for more information on IAM Invite Tokens.
Information on IAM best practices on EC2 instances managed by Systems
Manager can be found in the AWS Cloud Operations & Migrations Blog
.
Full documentation on EC2 discovery configuration can be found through the 
config file reference documentation.