EC2 인스턴스를 자동으로 등록하도록 Teleport 구성하기

Teleport Discovery Service는 Amazon EC2에 연결하여 구성된 레이블과 일치하는 EC2 인스턴스를 자동으로 발견하고 등록할 수 있습니다. 그런 다음 AWS Systems Manager를 사용하여 설치 스크립트를 실행하여 발견된 인스턴스에 Teleport를 설치하고 시작하여 클러스터에 연결합니다.

이 경우 Teleport Discovery Service는 긴 수명(파라미터) IAM 초대 토큰을 사용하여 새 인스턴스를 발견하고 토큰의 수명 동안 Teleport 클러스터에 추가할 수 있습니다.

전제 조건

실행 중인 Teleport 클러스터 버전 이상. Teleport를 시작하려면, 가입하기 위해 무료 평가판에 등록하거나 데모 환경 설정하기를 참조하세요.
tctl 관리 도구와 tsh 클라이언트 도구.

tctl과 tsh 다운로드에 대한 지침은 설치를 방문하세요.

EC2 인스턴스 및 IAM 정책을 생성 및 첨부할 수 있는 권한이 있는 AWS 계정.
Ubuntu/Debian/RHEL/Amazon Linux 2/Amazon Linux 2023에서 실행되는 EC2 인스턴스와 기본 Teleport 설치 스크립트를 사용하려면 SSM 에이전트 버전 3.1 이상이 필요합니다. (기타 리눅스 배포판의 경우 Teleport를 수동으로 설치할 수 있습니다.)
당신의 Teleport 클러스터에 연결할 수 있는지 확인하려면, tsh login으로 로그인한 다음 현재 자격 증명을 사용하여 tctl 명령어를 실행할 수 있는지 확인하십시오. 예를 들어:
```
tsh login --proxy=teleport.example.com --user=email@example.com
tctl status
클러스터  teleport.example.com
버전  16.2.0
CA 핀   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
```
클러스터에 연결하고 tctl status 명령어를 실행할 수 있다면, 현재 자격 증명을 사용하여 작업대에서 후속 tctl 명령어를 실행할 수 있습니다. 자신의 Teleport 클러스터를 호스팅하는 경우, Teleport 인증 서비스를 호스팅하는 컴퓨터에서 전체 권한으로 tctl 명령어를 실행할 수도 있습니다.

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

EC2 인스턴스를 발견할 때 Teleport는
가입 노드를 인증하기 위해 IAM 초대 토큰을 사용합니다.

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 계정 지정
  - aws_account: "123456789"

aws_account 필드에 AWS 계정 번호를 할당합니다.
다음의 명령어로 토큰을 Teleport 클러스터에 추가합니다:

tctl create -f token.yaml

2단계/7. IAM 정책 정의

teleport discovery bootstrap 명령은 자동 발견을 작동시키기 위해 필요한 IAM 정책을 정의하고 구현하는 과정을 자동화합니다. 이는 단일 미리 정의된 정책만 필요하며, 이 정책은 명령을 실행하는 EC2 인스턴스에 첨부되어야 합니다:

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

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

3단계/7. Discovery Node에 Teleport 설치

Tip

Discovery Service를 이미 다른 Teleport 서비스(예: Auth 또는 Proxy)가 실행되고 있는 동일한 Node에서 실행할 계획이라면 이 단계를 건너뛰어도 됩니다.

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

Linux 서버에 Teleport 설치하기:

Teleport 에디션에 따라 edition을(를) 다음 중 하나로 지정합니다:

에디션 값
Teleport Enterprise Cloud cloud
Teleport Enterprise (자체 호스팅) enterprise
Teleport Community Edition oss

에디션	값
Teleport Enterprise Cloud	`cloud`
Teleport Enterprise (자체 호스팅)	`enterprise`
Teleport Community Edition	`oss`

설치할 Teleport의 버전을 확인합니다. 클러스터에서 자동 에이전트 업데이트가 활성화되어 있는 경우, 업데이터와 호환되는 최신 Teleport 버전을 쿼리합니다:

TELEPORT_DOMAIN=example.teleport.com
TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/automaticupgrades/channel/default/version | sed 's/v//')"

그렇지 않으면, Teleport 클러스터의 버전을 확인합니다:

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

Linux 서버에 Teleport를 설치합니다:
```
curl https://cdn.teleport.dev/install-v16.2.0.sh | bash -s ${TELEPORT_VERSION} edition
```
설치 스크립트는 Linux 서버에서 패키지 관리자를 감지하고 이를 사용하여 Teleport 바이너리를 설치합니다. 설치를 사용자 지정하려면 설치 가이드에서 Teleport 패키지 리포지토리에 대해 알아보세요.

4단계/7. EC2 인스턴스를 발견하도록 Teleport 구성

Discovery Service를 별도의 호스트에서 실행하는 경우, 이 서비스는 클러스터에 연결하기 위한 유효한 초대 토큰이 필요합니다. 아래 명령어를 실행하여 Teleport Auth Service에 대해 하나를 생성합니다:

tctl tokens add --type=discovery

생성된 토큰을 Discovery Service를 실행할 Node(EC2 인스턴스)의 /tmp/token에 저장합니다.

EC2 인스턴스 발견을 활성화하기 위해 teleport.yaml의 discovery_service.aws 섹션에는 최소한 하나의 항목이 포함되어야 합니다:

version: v3
teleport:
  join_params:
    token_name: "/tmp/token"
    method: token
  proxy_server: "teleport.example.com:443"
auth_service:
  enabled: off
proxy_service:
  enabled: off
ssh_service:
  enabled: off
discovery_service:
  enabled: "yes"
  aws:
   - types: ["ec2"]
     regions: ["us-east-1","us-west-1"]
     install:
        join_params:
          token_name: aws-discovery-iam-token
          method: iam
     tags:
       "env": "prod" # 태그:env=prod인 EC2 인스턴스와 일치

teleport.auth_servers 키를 해당 Auth Service 또는 Proxy Service의 URI와 포트에 맞게 조정합니다.
discovery_service.aws 아래의 키를 EC2 환경에 맞게 조정합니다.
특히 Discovery Service와 연관시키고자 하는 지역 및 태그를 조정합니다.

5단계/7. Discovery Service AWS 구성 부트스트랩

위에서 설명한 Node에서 teleport discovery bootstrap을 실행합니다. 이 명령은 Discovery Service를 활성화하는 데 필요한 추가 IAM 정책 및 AWS Systems Manager(SSM) 문서를 생성하고 표시합니다:

sudo teleport discovery bootstrap
Reading configuration at "/etc/teleport.yaml"...
AWS1. IAM 정책 "TeleportEC2Discovery" 생성:{    "Version": "2012-10-17",    "Statement": [        {            "Effect": "Allow",            "Action": [                "ec2:DescribeInstances",                "ssm:DescribeInstanceInformation",                "ssm:GetCommandInvocation",                "ssm:ListCommandInvocations",                "ssm:SendCommand"            ],            "Resource": [                "*"            ]        }    ]}
2. IAM 정책 "TeleportEC2DiscoveryBoundary" 생성:{    "Version": "2012-10-17",    "Statement": [        {            "Effect": "Allow",            "Action": [                "ec2:DescribeInstances",                "ssm:DescribeInstanceInformation",                "ssm:GetCommandInvocation",                "ssm:ListCommandInvocations",                "ssm:SendCommand"            ],            "Resource": [                "*"            ]        }    ]}
3. SSM 문서 "TeleportDiscoveryInstaller" 생성:
schemaVersion: '2.2'description: aws:runShellScriptparameters:  token:    type: String    description: "(Required) 클러스터에 조인할 때 사용할 Teleport 초대 토큰."  scriptName:    type: String    description: "(Required) 클러스터에 조인할 때 사용할 Teleport 설치 스크립트."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:      - /bin/sh /tmp/installTeleport.sh "{{ token }}"
4. "yourUser-discovery-role"에 IAM 정책을 첨부합니다.
확인하시겠습니까? [y/N]: y

정책을 검토하고 확인합니다:

확인하시겠습니까? [y/N]: y✅[AWS] IAM 정책 "TeleportEC2Discovery" 생성 완료.✅[AWS] IAM 정책 "TeleportEC2DiscoveryBoundary" 생성 완료.✅[AWS] SSM 문서 "TeleportDiscoveryInstaller" 생성 완료.✅[AWS] IAM 정책을 "alex-discovery-role"에 첨부 완료.

Discovery Service에 의해 Teleport 클러스터에 추가될 모든 EC2 인스턴스는 Discovery Service로부터 명령을 받기 위해 AmazonSSMManagedInstanceCore IAM 정책을 포함해야 합니다.

이 정책에는 다음 권한이 포함됩니다:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ssm:DescribeAssociation",
                "ssm:GetDeployablePatchSnapshotForInstance",
                "ssm:GetDocument",
                "ssm:DescribeDocument",
                "ssm:GetManifest",
                "ssm:GetParameter",
                "ssm:GetParameters",
                "ssm:ListAssociations",
                "ssm:ListInstanceAssociations",
                "ssm:PutInventory",
                "ssm:PutComplianceItems",
                "ssm:PutConfigurePackageResult",
                "ssm:UpdateAssociationStatus",
                "ssm:UpdateInstanceAssociationStatus",
                "ssm:UpdateInstanceInformation"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "ssmmessages:CreateControlChannel",
                "ssmmessages:CreateDataChannel",
                "ssmmessages:OpenControlChannel",
                "ssmmessages:OpenDataChannel"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "ec2messages:AcknowledgeMessage",
                "ec2messages:DeleteMessage",
                "ec2messages:FailMessage",
                "ec2messages:GetEndpoint",
                "ec2messages:GetMessages",
                "ec2messages:SendReply"
            ],
            "Resource": "*"
        }
    ]
}

6단계/7. [선택 사항] 기본 설치 스크립트 사용자 정의

설치 프로그램을 맞춤 설정하려면 사용자가 installer 리소스에 대해 list, create, read 및 update 동사를 허용하는 역할을 가져야 합니다.

installer-manager.yaml이라는 파일을 다음 내용으로 생성하세요:

kind: role
version: v5
metadata:
  name: installer-manager
spec:
  allow:
    rules:
      - resources: [installer]
        verbs: [list, create, read, update]

역할을 생성합니다:

tctl create -f installer-manager.yaml
역할 'installer-manager' 가 생성되었습니다

기본적으로 editor 프리셋 역할은 필요한 권한을 가지고 있습니다.

기본 설치 프로그램 스크립트를 맞춤 설정하려면, 워크스테이션에서 다음 명령을 실행하세요:

tctl get installer/default-installer > teleport-default-installer.yaml

결과로 생성된 teleport-default-installer.yaml 파일은 발견된 인스턴스를 등록할 때 실행될 내용을 변경하기 위해 편집할 수 있습니다.

기본 설치 프로그램에 원하는 변경 사항을 적용한 후, 해당 리소스는 다음을 실행하여 업데이트할 수 있습니다:

tctl create -f teleport-default-installer.yaml

여러 installer 리소스가 존재할 수 있으며 teleport.yaml의 discovery_service.aws 목록 항목의 aws.install.script_name 섹션에서 지정할 수 있습니다:

discovery_service:
  aws:
    - types: ["ec2"]
      tags:
       - "env": "prod"
      install: # 기본 설치 프로그램이 사용될 때의 선택적 섹션.
        script_name: "default-installer"
    - types: ["ec2"]
      tags:
       - "env": "devel"
      install:
        script_name: "devel-installer"

installer 리소스는 다음과 같은 템플릿 옵션을 가지고 있습니다:

{{ .MajorVersion }}: 저장소에서 설치할 Teleport의 주요 버전입니다.
{{ .PublicProxyAddr }}: 연결할 Teleport Proxy 서비스의 공용 주소입니다.
{{ .RepoChannel }}: 선택적 패키지 저장소 (apt/yum) 채널 이름입니다.
형식은 <channel>/<version>입니다. 예: stable/v16. 자세한 내용은 설치를 참조하세요.
{{ .AutomaticUpgrades }}: 자동 업데이트가 활성화되었는지 비활성화되었는지를 나타냅니다.
그 값은 true 또는 false입니다. 자세한 정보는 자동 에이전트 업데이트를 참조하세요.
{{ .TeleportPackage }}: 사용할 Teleport 패키지입니다.
그 값은 클러스터가 엔터프라이즈인지 여부에 따라 teleport-ent 또는 teleport입니다.

다음과 같이 사용할 수 있습니다:

kind: installer
metadata:
  name: default-installer
spec:
  script: |
    echo {{ .PublicProxyAddr }}
    echo Teleport-{{ .MajorVersion }}
    echo Repository Channel: {{ .RepoChannel }}
version: v1

설치 시 검색되면 다음과 같은 내용을 가진 스크립트로 평가됩니다:

echo teleport.example.com
echo Teleport-16.2.0
echo Repository Channel: stable/v16.2.0

기본 설치 프로그램은 다음과 같은 작업을 수행합니다:

지원되는 Linux 배포판에 공식 Teleport 저장소를 추가합니다.
apt 또는 yum을 통해 Teleport를 설치합니다.
Teleport 구성 파일을 생성하고 /etc/teleport.yaml에 기록합니다.
Teleport 서비스를 활성화하고 시작합니다.

7단계/7. Teleport 시작하기

the Discovery Service에 AWS에 인증하는 데 사용할 수 있는 자격 증명에 대한 액세스를 부여합니다.

the Discovery Service를 EC2 인스턴스에서 실행하는 경우 EC2 인스턴스 메타데이터 서비스 방법을 사용할 수 있습니다. 그렇지 않은 경우 환경 변수를 사용해야 합니다:

Teleport는 EC2 인스턴스에서 실행될 때 이를 감지하고 인스턴스 메타데이터 서비스를 사용하여 자격 증명을 가져옵니다.

EC2 인스턴스는 EC2 인스턴스 프로파일을 사용하도록 구성되어 있어야 합니다. 자세한 내용은 인스턴스 프로파일 사용하기를 참조하세요.

Teleport의 내장 AWS 클라이언트는 다음 환경 변수에서 자격 증명을 읽습니다:

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_DEFAULT_REGION

the Discovery Service를 시작하면 서비스는 /etc/default/teleport 경로의 파일에서 환경 변수를 읽습니다. 이 자격 증명은 귀하의 조직에서 가져오십시오. /etc/default/teleport에 다음 내용을 포함하고 각 변수의 값을 대체해야 합니다:

AWS_ACCESS_KEY_ID=00000000000000000000
AWS_SECRET_ACCESS_KEY=0000000000000000000000000000000000000000
AWS_DEFAULT_REGION=<YOUR_REGION>

Teleport의 AWS 클라이언트는 자격 증명을 다음 순서로 다양한 출처에서 로드합니다:

환경 변수
공유 자격 증명 파일
공유 구성 파일 (Teleport는 항상 공유 구성을 활성화합니다)
EC2 인스턴스 메타데이터 (자격 증명 전용)

공유 자격 증명 파일 또는 공유 구성 파일을 통해 AWS 자격 증명을 제공할 수 있지만, the Discovery Service를 실행할 때 AWS_PROFILE 환경 변수를 선택한 프로파일의 이름으로 지정해야 합니다.

위의 지침이 고려하지 않은 특정 사용 사례가 있는 경우, 자격 증명 로딩 동작에 대한 자세한 설명을 보려면 AWS SDK for Go의 문서를 참조하십시오.

호스트가 부팅될 때 the Discovery Service가 자동으로 시작되도록 시스템 데몬 서비스를 생성하여 구성합니다. 지침은 the Discovery Service를 설치한 방법에 따라 다릅니다.

the Discovery Service를 실행할 호스트에서 Teleport를 활성화하고 시작하십시오:

sudo systemctl enable teleport
sudo systemctl start teleport

the Discovery Service를 실행할 호스트에서 Teleport에 대한 시스템 데몬 서비스 구성을 생성하고, Teleport 서비스를 활성화한 후 Teleport를 시작하십시오:

sudo teleport install systemd -o /etc/systemd/system/teleport.service
sudo systemctl enable teleport
sudo systemctl start teleport

the Discovery Service의 상태는 systemctl status teleport로 확인할 수 있으며, 로그는 journalctl -fu teleport로 볼 수 있습니다.

Discovery Service를 시작하면, 앞서 지정한 태그와 일치하는 EC2 인스턴스가 자동으로 Teleport 클러스터에 추가되기 시작합니다.

문제 해결

설치가 실패하거나 인스턴스가 나타나지 않는 경우, AWS Systems Manager -> 노드 관리 -> 명령 실행에서 명령 기록을 확인하십시오. 대상 인스턴스의 instance-id를 선택하여 오류를 검토합니다.

`cannot unmarshal object into Go struct field`

다음과 유사한 오류가 발생하는 경우:

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

이는 이전 SSM 에이전트 버전을 실행하고 있을 가능성이 높습니다. 문제를 해결하려면 SSM 에이전트 버전을 3.1 이상으로 업그레이드하십시오.

`InvalidInstanceId: Instances [[i-123]] not in a valid state for account 456`

다음 문제들이 이 오류를 유발할 수 있습니다:

Discovery Service가 관리 노드에 접근할 수 있는 권한이 없음.
AWS Systems Manager Agent (SSM Agent)가 실행되고 있지 않음. SSM Agent가 실행 중인지 확인합니다.
SSM Agent가 SSM 엔드포인트에 등록되어 있지 않음. SSM Agent를 재설치해보십시오.
발견된 인스턴스가 SSM 명령을 받을 수 있는 권한이 없음. 인스턴스에
AmazonSSMManagedInstanceCore IAM 정책이 포함되어 있는지 확인합니다.

자세한 사항은 SSM RunCommand 오류 코드 및 문제 해결 정보를
AWS 문서에서 확인하십시오:

다음 단계

IAM 초대 토큰에 대한 자세한 내용은 AWS IAM Role을 통해 노드에 가입하기를
읽어보세요.
Systems Manager에서 관리하는 EC2 인스턴스에 대한 IAM 모범 사례에 대한 정보는
AWS Cloud Operations & Migrations Blog에서 확인할 수 있습니다.
EC2 발견 구성을 포함한 전체 문서는 구성 파일 참조 문서를 통해 찾을 수 있습니다.

Teleport 원문 보기