이 가이드에서는 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 Organization에서 여러 AWS 계정을 관리하는 경우 조직 수준 EC2 자동 검색 구성을 참고하세요.

사전 요구 사항#

• 실행 중인 Teleport 클러스터. Teleport를 시작하려면 무료 체험판에 가입하거나 데모 환경을 구성하세요.

• tctl and tsh clients.

  Installing `tctl` and `tsh` clients

  1. Teleport 클러스터의 버전을 확인합니다. tctl and tsh clients는 Teleport 클러스터 버전보다 최대 한 개의 메이저 버전까지만 뒤처질 수 있습니다. Proxy Service의 /v1/webapi/find로 GET 요청을 보내고 JSON 쿼리 도구를 사용하여 클러스터 버전을 확인합니다. teleport.example.com:443를 Teleport Proxy Service의 웹 주소로 바꿉니다:

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

  2. 사용 중인 플랫폼에 대한 지침에 따라 tctl and tsh clients를 설치합니다:

Mac

     `tctl` and `tsh` clients가 포함된, 서명된 Teleport macOS .pkg 설치 프로그램을 다운로드합니다:
 
     ```code
     $ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg
     ```

     Finder에서 `pkg` 파일을 더블 클릭하여 설치를 시작합니다.
 
     

       Homebrew를 사용하여 Teleport를 설치하는 것은 지원되지 않습니다. Homebrew의
       Teleport 패키지는 Teleport에서 유지 관리하지 않으므로 신뢰성이나 보안을
       보장할 수 없습니다.
     

Windows - Powershell

     ```code
     $ 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

     Linux 설치판의 모든 Teleport 바이너리에는 `tctl` and `tsh` clients가 포함되어 있습니다.  RPM/DEB
     패키지 및 i386/ARM/ARM64용 다운로드를 포함한 더 많은 옵션은
     [설치 페이지](../installation/installation.mdx)를 참조하세요.
 
     ```code
     $ 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
     ```
   

 

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

Teleport cluster에 연결할 수 있는지 확인하려면 tsh login으로 로그인한 다음, 현재 자격 증명으로 tctl 명령을 실행할 수 있는지 확인합니다.

예를 들어, teleport.example.com에 cluster 내 Teleport Proxy Service의 도메인 이름을, email@example.com에 Teleport 사용자 이름을 지정하여 다음 명령을 실행합니다:

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

cluster에 연결하여 tctl status 명령을 실행할 수 있다면, 현재 자격 증명을 사용하여 워크스테이션에서 이후의 tctl 명령을 실행할 수 있습니다. 자체 Teleport cluster를 호스팅하는 경우, 전체 권한을 얻기 위해 Teleport Auth Service를 호스팅하는 컴퓨터에서 tctl 명령을 실행할 수도 있습니다.

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

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

EC2 인스턴스를 검색할 때 Teleport는 조인하는 Node를 인증하기 위해 IAM 초대 토큰을 사용합니다.

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"

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

$ 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 Node에 Teleport 설치#

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

Linux 서버에 Teleport Agent를 설치하려면:

권장 설치 방법은 클러스터 설치 스크립트입니다. 이 스크립트는 클러스터에 맞는 올바른 버전, 에디션, 설치 모드를 선택합니다.

1. teleport.example.com:443에 Teleport 클러스터의 호스트명과 포트를 할당하되, 스킴(https://)은 포함하지 마십시오.

2. 클러스터의 설치 스크립트를 실행하십시오:

   $ curl "https://teleport.example.com:443/scripts/install.sh" | sudo bash
   

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

Discovery Service를 자체 호스트에서 실행하는 경우, 이 서비스는 클러스터에 연결하기 위해 유효한 초대 토큰이 필요합니다. Teleport Auth Service에 대해 다음 명령을 실행하여 토큰을 생성하십시오:

$ tctl tokens add --type=discovery

생성된 토큰을 Discovery Service를 실행할 Node(EC2 인스턴스)의 /tmp/token에 저장하십시오.

teleport.example.com:443을 클러스터의 Teleport Proxy Service 호스트 및 포트로, aws-prod을 등록할 리소스 그룹을 식별하는 이름으로 지정하십시오:

# teleport.yaml
version: v3
teleport:
  join_params:
    token_name: "/tmp/token"
    method: token
  proxy_server: "teleport.example.com:443"
auth_service:
  enabled: false
proxy_service:
  enabled: false
ssh_service:
  enabled: false
discovery_service:
  enabled: true
  discovery_group: aws-prod

등록하려는 리소스에 대한 매처를 생성하십시오.

Dynamic configuration (recommended)

EC2 인스턴스 검색을 활성화하려면, 앞서 구성한 것과 동일한 discovery group을 가진 Discovery Config 리소스를 생성하십시오.

다음 내용으로 discovery-aws-prod.yaml이라는 파일을 생성하십시오:

kind: discovery_config
version: v1
metadata:
  name: example-discovery-config
spec:
  discovery_group: aws-prod
  aws:
  - types: ["ec2"]
    regions: ["us-east-1", "us-west-1"]
    tags:
      "env": "prod" # Match EC2 instances where tag:env=prod
    ssm:
      document_name: "AWS-RunShellScript"
    install:
      enroll_mode: 1
      install_teleport: true
      join_method: iam
      join_token: aws-discovery-iam-token

spec.aws 아래의 키를 EC2 환경에 맞게, 특히 Discovery Service와 연결하려는 리전 및 태그에 맞게 조정하십시오.

다음 명령을 실행하여 Discovery Config를 생성하십시오:

$ tctl create -f discovery-aws-prod.yaml

일치하는 인스턴스가 Teleport 클러스터에 자동으로 추가됩니다.

Discovery Config는 언제든지 업데이트할 수 있으며, 서비스가 변경 사항을 자동으로 다시 적용합니다.

Static configuration

EC2 인스턴스 검색을 활성화하려면 teleport.yaml의 discovery_service.aws 섹션에 항목이 하나 이상 포함되어야 합니다:

# teleport.yaml
# ...
discovery_service:
  enabled: true
  discovery_group: aws-prod
  aws:
  - types: ["ec2"]
    regions: ["us-east-1", "us-west-1"]
    tags:
      "env": "prod" # Match EC2 instances where tag:env=prod
    ssm:
      document_name: "AWS-RunShellScript"
    install:
      enroll_mode: script
      install_teleport: true
      join_params:
        token_name: aws-discovery-iam-token
        method: iam

discovery_service.aws 아래의 키를 EC2 환경에 맞게, 특히 Discovery Service와 연결하려는 리전 및 태그에 맞게 조정하십시오.

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 시작#

the Discovery Service이(가) AWS에 인증하는 데 사용할 수 있는 자격 증명에 대한 접근 권한을 부여합니다.

• the Discovery Service을(를) EC2 인스턴스에서 실행하는 경우 EC2 Instance Metadata Service 방식을 사용할 수 있습니다
• the Discovery Service을(를) Kubernetes에서 실행하는 경우 IAM Roles for Service Accounts (IRSA)를 사용할 수 있습니다
• 그 외의 경우에는 환경 변수를 사용해야 합니다

Instance Metadata Service

Teleport는 EC2 인스턴스에서 실행 중일 때를 감지하고 Instance Metadata Service를 사용하여 자격 증명을 가져옵니다.

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

Kubernetes IRSA

AWS에서 OIDC provider를 설정하고 pod의 서비스 계정이 role을 assume할 수 있도록 허용하는 AWS IAM role을 구성하려면 IAM Roles for Service Accounts (IRSA)를 참고하세요.

Environment Variables

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=

systemd 서비스를 생성하여 호스트가 부팅될 때 the Discovery Service이 자동으로 시작되도록 구성합니다. 지침은 the Discovery Service을 어떻게 설치했는지에 따라 다릅니다.

Package Manager

the Discovery Service을 실행할 호스트에서 Teleport를 활성화하고 시작합니다:

$ sudo systemctl enable teleport
$ sudo systemctl start teleport

TAR Archive

the Discovery Service을 실행할 호스트에서 Teleport용 systemd 서비스 구성을 생성하고, Teleport 서비스를 활성화한 후 Teleport를 시작합니다:

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

systemctl status teleport로 the Discovery Service의 상태를 확인하고 journalctl -fu teleport로 로그를 볼 수 있습니다.

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

여러 AWS 계정에서 인스턴스 검색#

Teleport Discovery Service가 실행 중인 계정 이외의 AWS 계정에서 EC2 인스턴스를 검색하려면 Teleport가 해당 각 계정의 IAM 역할을 수임(assume)할 수 있는 권한을 가지고 있어야 합니다. 이 가이드는 위의 기본 EC2 검색 가이드를 완료했다고 가정하며, 인스턴스를 검색하려는 각 AWS 계정에 대해 반복해야 합니다.

1/5단계. EC2 초대 토큰 업데이트#

token.yaml의 spec.allow에 새 항목을 추가하고, aws_account를 새 계정의 계정 번호(destination AWS account ID 포함)로 설정하십시오:

# 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: "destination AWS account ID"

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가 이를 수임할 수 있도록 허용하고, Discovery Service role을 추가합니다.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "Discovery Service role"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

Discovery Service의 계정에 다음 정책을 생성하여 Discovery Service의 역할에 연결하고, new role ARN을 추가합니다.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "sts:AssumeRole",
            "Resource": "new role ARN"
        }
    ]
}

3/5단계. Teleport 구성 업데이트#

Dynamic configuration (recommended)

앞에서 생성한 Discovery Config를 편집하여 spec.aws 섹션에 항목을 추가하고, role ARN에는 가정(assume)할 IAM 역할의 ARN을 지정하며 optional external ID에는 선택적 external ID를 지정합니다:

kind: discovery_config
# ...
spec:
  aws:
  - types: ["ec2"]
    ssm:
      document_name: "AWS-RunShellScript"
    # Add new entry after existing entries
  - types: ["ec2"]
    regions: ["us-east-1", "us-west-1"]
    tags:
      "env": "prod" # Match EC2 instances where tag:env=prod
    install:
      enroll_mode: 1
      install_teleport: true
      join_method: iam
      join_token: aws-discovery-iam-token
    ssm:
      document_name: "AWS-RunShellScript"
    assume_role:
      role_arn: "role ARN"
      external_id: "optional external ID"
  - types: ["ec2"]
    ssm:
      document_name: "AWS-RunShellScript"
    # Add a new entry for each account.
    # ...

Static configuration

teleport.yaml 파일의 discovery_service.aws 섹션에 항목을 추가하고, role ARN에는 가정(assume)할 IAM 역할의 ARN을 지정하며 optional external ID에는 선택적 external ID를 지정합니다:

# teleport.yaml
# ...
discovery_service:
  enabled: true
  discovery_group: "aws-prod"
  aws:
  - types: ["ec2"]
    ssm:
      document_name: "AWS-RunShellScript"
    # Add new entry after existing entries
  - types: ["ec2"]
    regions: ["us-east-1", "us-west-1"]
    tags:
      "env": "prod" # Match EC2 instances where tag:env=prod
    install:
      enroll_mode: script
      install_teleport: true
      join_method: iam
      join_token: aws-discovery-iam-token
    ssm:
      document_name: "AWS-RunShellScript"
    assume_role_arn: "role ARN"
    external_id: "optional external ID"
  - types: ["ec2"]
    ssm:
      document_name: "AWS-RunShellScript"
    # Add a new entry for each account.
    # ...

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 systemctl restart teleport

systemctl status teleport로 Discovery Service의 상태를 확인하고 journalctl -fu teleport로 로그를 볼 수 있습니다.

자동 검색 라벨#

Teleport는 자동 검색을 통해 클러스터에 조인하는 AWS, Azure, Google Cloud의 리소스에 기본 레이블 집합을 적용합니다. 자동 검색 레이블 레퍼런스를 참조하십시오.

고급 구성#

이 섹션에서는 서버를 발견하고 등록하기 위한 구성 옵션을 다룹니다.

동일한 인스턴스에 여러 Teleport 에이전트 설치#

블루-그린 배포나 기타 다중 클러스터 구성을 사용할 때, 서로 다른 클러스터에서 인스턴스에 접근하고 싶을 수 있습니다.

Teleport는 접미사가 붙은 설치(suffixed installation)를 사용하여 동일한 인스턴스에서 여러 에이전트를 설치하고 실행하는 것을 지원하며, 이를 통해 각 설치를 격리할 수 있습니다.

Dynamic configuration (recommended)

Discovery Service가 접미사가 붙은 설치를 사용하도록 구성하려면, Discovery Config를 편집하여 spec.aws.install.suffix 키를 설정합니다.

kind: discovery_config
# ...
spec:
  aws:
   - install:
       suffix: "blue-cluster"

Static configuration

Discovery Service가 접미사가 붙은 설치를 사용하도록 구성하려면, Discovery Service 설정에서 install.suffix 키를 지정합니다.

# teleport.yaml
version: v3
# ...
discovery_service:
  enabled: true
  aws:
   - install:
       suffix: "blue-cluster"

에이전트 관리형 업데이트가 활성화되어 있어야 합니다.

Managed Updates를 위한 그룹 정의#

Teleport 에이전트 관리형 업데이트를 사용하는 경우, 업데이트 그룹을 구성하여 어떤 인스턴스가 함께 업데이트되는지 제어할 수 있습니다.

Dynamic configuration (recommended)

업데이트 그룹을 설정하려면, Discovery Config를 편집하여 spec.aws.install.update_group 키를 설정합니다.

kind: discovery_config
# ...
spec:
  aws:
   - install:
       update_group: "update-group-1"

Static configuration

업데이트 그룹을 설정하려면, Discovery Service 설정에서 install.update_group 키를 지정합니다.

# teleport.yaml
version: v3
# ...
discovery_service:
  enabled: true
  aws:
   - install:
       update_group: "update-group-1"

Configure HTTP Proxy during installation#

설치 파일에 접근하기 위해 프록시가 필요한 인스턴스의 경우, Discovery Service에서 HTTP 프록시 설정을 구성할 수 있습니다.

Dynamic configuration (recommended)

HTTP 프록시 설정을 지정하려면, Discovery Config를 편집하여 spec.aws.install.http_proxy_settings 키를 설정합니다.

kind: discovery_config
# ...
spec:
  aws:
   - install:
       http_proxy_settings:
         https_proxy: http://172.31.5.130:3128
         http_proxy: http://172.31.5.130:3128
         no_proxy: my-local-domain

Static configuration

설정에서 install.http_proxy_settings 키를 설정해야 합니다.

# teleport.yaml
version: v3
# ...
discovery_service:
  enabled: true
  aws:
   - install:
       http_proxy_settings:
         https_proxy: http://172.31.5.130:3128
         http_proxy: http://172.31.5.130:3128
         no_proxy: my-local-domain

사용자 지정 설치 스크립트 사용#

설치 스크립트를 커스터마이즈하려면, 사용자에게 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
# role 'installer-manager' has been created

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

기본 설치 스크립트를 커스터마이즈하려면, 워크스테이션에서 다음 명령을 실행합니다.

$ tctl edit installer/default-installer

기본 설치 스크립트를 원하는 대로 변경한 뒤, 텍스트 편집기에서 파일을 저장하고 닫습니다.

여러 개의 installer 리소스가 존재할 수 있으며, aws.install.script_name 섹션에서 지정할 수 있습니다.

Dynamic configuration (recommended)

Discovery Config를 편집하여 커스텀 설치 스크립트를 지정합니다.

<!-- INCLUDE:ENGLISH:docs/pages/includes/server-access/custom-installer-aws-dynamic.yaml -->
kind: discovery_config
# ...
spec:
  aws:
    - types: ["ec2"]
      tags:
       - "env": "prod"
      regions: ["us-west1", "us-east1"]
      install:
        enroll_mode: 1
        install_teleport: true
        script_name: "default-installer"
      ssm:
        document_name: "AWS-RunShellScript"
    - types: ["ec2"]
      tags:
       - "env": "devel"
      regions: ["us-west1", "us-east1"]
      install:
        enroll_mode: 1
        install_teleport: true
        script_name: "devel-installer"
      ssm:
        document_name: "AWS-RunShellScript"
<!-- /INCLUDE:ENGLISH -->

Static configuration

teleport.yaml 설정을 편집하여 커스텀 설치 스크립트를 지정합니다.

<!-- INCLUDE:ENGLISH:docs/pages/includes/server-access/custom-installer-aws.yaml -->
discovery_service:
  # ...
  aws:
    - types: ["ec2"]
      tags:
       - "env": "prod"
      regions: ["us-west1", "us-east1"]
      install:
        enroll_mode: script
        install_teleport: true
        script_name: "default-installer"
      ssm:
        document_name: "AWS-RunShellScript"
    - types: ["ec2"]
      tags:
       - "env": "devel"
      regions: ["us-west1", "us-east1"]
      install:
        enroll_mode: script
        install_teleport: true
        script_name: "devel-installer"
      ssm:
        document_name: "AWS-RunShellScript"
<!-- /INCLUDE:ENGLISH -->

installer 리소스에는 다음과 같은 템플릿 옵션이 있습니다.

• {}: 리포지토리에서 설치할 때 사용할 Teleport의 메이저 버전입니다.
• {}: 연결할 Teleport Proxy Service의 공용 주소입니다.
• {}: 선택적 패키지 리포지토리(apt/yum) 채널 이름입니다. <channel>/<version> 형식이며 예를 들어 stable/v(=teleport.major_version=)와 같습니다. 자세한 내용은 설치를 참고하세요.
• {}: 자동 업데이트가 활성화되었는지 비활성화되었는지를 나타냅니다. 값은 true 또는 false입니다. 자세한 내용은 자동 에이전트 업데이트를 참고하세요.
• {}: 사용할 Teleport 패키지입니다. 클러스터가 엔터프라이즈인지 여부에 따라 값이 teleport-ent 또는 teleport가 됩니다.

이들은 다음과 같이 사용할 수 있습니다.

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

이는 설치를 위해 조회될 때 다음과 같은 내용의 스크립트로 평가됩니다.

echo teleport.example.com
echo Teleport-(=teleport.version=)
echo Repository Channel: stable/v(=teleport.version=)

기본 설치 스크립트는 다음 작업을 수행합니다.

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

사용자 지정 SSM Document 사용#

발견된 EC2 인스턴스에서 설치 스크립트를 실행할 때, Discovery Service는 SSM document를 사용합니다.

기본 AWS-RunShellScript SSM document는 대부분의 경우에 동작하며 AWS에서 항상 사용할 수 있습니다.

그러나 환경에 맞게 설치 과정을 사용자 지정해야 하는 경우, 사용자 지정 SSM Document를 생성하고 설치 중에 이를 사용하도록 Discovery Service를 구성할 수 있습니다.

사용자 지정 document의 파라미터에는 반드시 env, scriptName, token이 포함되어야 합니다.

권장하는 방식은 다음 document를 사용하고 필요에 따라 사용자 지정하는 것입니다:

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 }}"

인스턴스를 발견하려는 각 리전에서 AWS Systems Manager를 사용하여 이 document를 생성합니다.

ssm.document_name 키를 설정하여 사용자 지정 SSM Document를 사용하도록 Discovery Service 구성을 편집합니다:

# teleport.yaml
version: v3
# ...
discovery_service:
  enabled: true
  aws:
   - ssm:
       document_name: "TeleportDiscoveryInstaller"

모든 활성 리전에서 인스턴스 발견#

Discovery Service는 모든 활성 AWS 리전에서 EC2 인스턴스를 스캔하도록 구성할 수 있습니다.

AWS matcher를 편집하고 regions 키를 와일드카드(*)로 설정합니다:

# teleport.yaml
version: v3
# ...
discovery_service:
  enabled: true
  aws:
   - regions: ["*"]
     # other fields

Discovery Service가 리전을 나열할 수 있도록 필요한 IAM 권한을 추가합니다:

{
    "Effect": "Allow",
    "Action": [
        // existing permissions
        "account:ListRegions"
    ],
    "Resource": "*"
}

문제 해결#

설치가 실패로 표시되거나 인스턴스가 나타나지 않는 경우, AWS System Manager -> Node Management -> Run Command에서 Command 이력을 확인하십시오. Target의 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 agent를 실행하고 있을 가능성이 높습니다. 이 문제를 해결하려면 SSM agent 버전 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 정책이 포함되어 있는지 확인하십시오.

자세한 내용은 AWS 문서의 SSM RunCommand 오류 코드 및 문제 해결 정보를 참조하십시오:

• 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

다음 단계#

• IAM Invite Token에 대한 자세한 내용은 AWS IAM Role을 통한 노드 참여를 참고하십시오.
• Systems Manager로 관리되는 EC2 인스턴스의 IAM 모범 사례에 대한 정보는 AWS Cloud Operations & Migrations Blog 에서 확인할 수 있습니다.
• EC2 디스커버리 구성에 대한 전체 문서는 구성 파일 레퍼런스 문서에서 확인할 수 있습니다.