이 가이드는 클러스터에서 AWS 조직의 EC2 인스턴스를 자동으로 등록하도록 Teleport를 구성하는 방법을 설명합니다.

작동 방식#

Teleport Discovery Service는 EC2 인스턴스에서 실행되며 AWS API를 쿼리하여 AWS 조직 내 모든 계정의 인스턴스 목록을 가져옵니다. 새로 배포하는 EC2 인스턴스에 대해 Discovery Service는 AWS Systems Manager(SSM)를 사용하여 인스턴스에 Teleport를 설치하고 Teleport로 보호되는 서버로 클러스터에 참가시킵니다.

단일 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/7단계. Teleport에서 EC2 초대 토큰 생성#

EC2 인스턴스를 검색할 때 Teleport는 참가 노드 인증을 위해 IAM 초대 토큰을 사용합니다.

조직 ID는 "o-"로 시작하고 일련의 영숫자 문자가 뒤따르며, AWS 조직 콘솔의 왼쪽에서 확인할 수 있습니다.

에 조직 ID를 지정하십시오.

token.yaml 파일을 생성하십시오:

# token.yaml
kind: token
version: v2
metadata:
  # 토큰 이름은 비밀이 아닙니다. 인스턴스는 이 토큰을 사용하기 위해
  # AWS 조직에서 실행 중임을 증명해야 합니다
  name: aws-discovery-iam-token
spec:
  # 필요한 최소한의 역할 집합 사용 (예: Node, App, Kube, DB, WindowsDesktop)
  roles: [Node]

  # 이 토큰에 허용되는 참가 방법 설정
  join_method: iam

  allow:
  # 노드가 참가할 수 있는 AWS 조직 ID 지정
  - aws_organization_id: 



에 클러스터의 Teleport Proxy Service 호스트 및 포트를 지정하고,
에 등록할 리소스 그룹을 식별하는 이름을 지정하십시오:
# teleport.yaml
version: v3
teleport:
  join_params:
    token_name: "/tmp/token"
    method: token
  proxy_server: "




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 클러스터에 추가되기 시작합니다.
자동 검색 레이블#

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.