📣 Teleport의 공식 파트너 인포그랩에서 OpenAI 기술 기반으로 자체 개발한 자동화 번역 프로그램을 통해 Teleport 공식 문서(v17.0.0)의 한글판을 국내 최초로 제공합니다.
Infograb logo
EC2 인스턴스를 자동으로 등록하도록 Teleport 구성하기

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

이러한 시나리오에서 Teleport Discovery Service는 장기 유효 기간(TTL)을 가진 IAM 초대 토큰을 사용하여 새 인스턴스를 발견하고 Teleport 클러스터에 추가할 수 있습니다.

전제 조건

  • 실행 중인 Teleport 클러스터 버전 17.0.0-dev 이상. Teleport를 시작하려면 가입하여 무료 평가판을 이용하거나 데모 환경 설정 방법을 확인하십시오.

  • tctl 관리자 도구와 tsh 클라이언트 도구.

    tctl 및 tsh 다운로드 방법에 대한 지침은 설치를 방문하십시오.

  • EC2 인스턴스와 IAM 정책을 생성 및 첨부할 수 있는 권한이 있는 AWS 계정.
  • 기본 Teleport 설치 스크립트를 사용하는 경우 Ubuntu/Debian/RHEL/Amazon Linux 2/Amazon Linux 2023에서 SSM 에이전트 버전 3.1 이상이 실행 중인 EC2 인스턴스. (기타 Linux 배포판의 경우, Teleport를 수동으로 설치할 수 있습니다.)
  • 연결이 가능한지 확인하기 위해 tsh login 으로 로그인한 다음, 현재 자격 증명을 사용하여 tctl 명령어를 실행할 수 있는지 확인하십시오. 예를 들어: 
    tsh login --proxy=teleport.example.com --user=email@example.com
    tctl status
    클러스터  teleport.example.com
    버전  17.0.0-dev
    CA 핀   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
    클러스터에 연결할 수 있고 tctl status 명령어를 실행할 수 있다면, 현재 자격 증명을 사용하여 워크스테이션에서 후속 tctl 명령어를 실행할 수 있습니다.
    자신의 Teleport 클러스터를 호스팅하는 경우, Teleport Auth Service를 호스팅하는 컴퓨터에서 전체 권한으로 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를 실행할 노드(EC2 인스턴스)에 적용하십시오.

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

Tip

Discovery Service를 다른 Teleport 서비스(Auth 또는 Proxy 등)가 이미 실행 중인 동일한 노드에서 실행할 계획이라면 이 단계를 건너뛸 수 있습니다.

Discovery Service를 실행할 EC2 인스턴스에 Teleport를 설치하십시오:

Linux 서버에 Teleport 설치하기:

  1. Teleport 에디션에 따라 edition를 다음 중 하나로 할당합니다:

    에디션값
    Teleport Enterprise Cloudcloud
    Teleport Enterprise (자가 호스팅)enterprise
    Teleport Community Editionoss

  2. 설치할 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')"

  3. Linux 서버에 Teleport를 설치합니다:

    curl https://cdn.teleport.dev/install-v15.4.11.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를 실행할 노드(EC2 인스턴스)의 /tmp/token 에 저장하십시오.

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

Discovery Service는 발견된 리소스를 서로 다른 집합으로 그룹화할 수 있는 구성 매개변수 - discovery_service.discovery_group - 를 노출합니다. 이 매개변수는 서로 다른 클라우드 리소스 집합을 감시하는 Discovery Agents들이 충돌하여 다른 서비스에 의해 생성된 리소스를 삭제하는 것을 방지하는 데 사용됩니다.

여러 Discovery Services를 실행할 때, 동일한 클라우드 리소스를 감시하는 경우 각 서비스가 동일한 discovery_group 값으로 구성되어야 하며, 서로 다른 클라우드 리소스를 감시하는 경우에는 다른 값으로 구성해야 합니다.

동일한 Teleport 클러스터 내에서 혼합된 구성을 실행하는 것이 가능하므로 일부 Discovery Services는 동일한 클라우드 리소스를 감시하도록 구성할 수 있고, 다른 서비스는 서로 다른 리소스를 감시하도록 할 수도 있습니다. 예를 들어, 두 개의 서로 다른 클라우드 계정에서 데이터를 분석하는 4-agent 고가용성 구성은 다음과 같이 구성됩니다.

  • Production 계정에서 데이터를 폴링하기 위해 discovery_group: "prod" 로 구성된 2개의 Discovery Services.
  • Staging 계정에서 데이터를 폴링하기 위해 discovery_group: "staging" 로 구성된 2개의 Discovery Services.
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"
  discovery_group: "aws-prod"
  aws:
   - types: ["ec2"]
     regions: ["us-east-1","us-west-1"]
     install:
        join_params:
          token_name: aws-discovery-iam-token
          method: iam
     tags:
       "env": "prod" # EC2 인스턴스에서 tag:env=prod와 일치하는 태그 설정
  • teleport.auth_servers 키를 귀하의 Auth Service 또는 Proxy Service의 URI 및 포트에 맞게 수정하십시오.
  • discovery_service.aws 아래의 키를 귀하의 EC2 환경에 맞게 조정하십시오. 특히 Discovery Service와 연관시키려는 지역 및 태그를 조정하십시오.

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

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

sudo teleport discovery bootstrap
"/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: "(필수) 클러스터에 조인할 때 사용할 Teleport 초대 토큰."  scriptName:    type: String    description: "(필수) 클러스터에 조인할 때 사용할 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. IAM 정책을 "yourUser-discovery-role"에 연결합니다.
확인하시겠습니까? [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
role 'installer-manager' 가 생성되었습니다

프리셋 editor 역할은 기본적으로 필수 권한을 갖추고 있습니다.

기본 설치 스크립트를 사용자 정의하려면, 작업 공간에서 다음 명령을 실행하세요:

tctl edit installer/default-installer

기본 설치 프로그램에 원하는 변경을 한 후, 텍스트 편집기에서 파일을 저장하고 닫으세요.

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

discovery_service:
  # ...
  { { matcher } }:
    - types: { { matchTypes } }
      tags:
        - "env": "prod"
      install: # 기본 설치 프로그램이 사용될 때 선택적 섹션.
        script_name: "default-installer"
    - types: { { matchTypes } }
      tags:
        - "env": "devel"
      install:
        script_name: "devel-installer"

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

  • {{ .MajorVersion }}: 저장소에서 설치할 Teleport의 주요 버전.
  • {{ .PublicProxyAddr }}: 연결할 Teleport Proxy Service의 공개 주소.
  • {{ .RepoChannel }}: 선택적 패키지 저장소 (apt/yum) 채널 이름. 형식은 <channel>/<version>입니다. 예: stable/v17. 자세한 내용은 설치를 참조하세요.
  • {{ .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-17.0.0-dev
echo Repository Channel: stable/v17.0.0-dev

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

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

7/7단계. Teleport 시작

the Discovery Service 가 AWS에 인증하는 데 사용할 수 있는 자격 증명에 대한 액세스를 부여하십시오.

  • the Discovery Service 를 EC2 인스턴스에서 실행 중인 경우, EC2 인스턴스 메타데이터 서비스 방법을 사용할 수 있습니다.
  • the Discovery Service 를 Kubernetes에서 실행 중인 경우, IAM Roles for Service Accounts (IRSA)를 사용할 수 있습니다.
  • 그렇지 않은 경우, 환경 변수를 사용해야 합니다.

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

EC2 인스턴스는 EC2 인스턴스 프로필을 사용하도록 구성되어야 합니다. 자세한 내용은 인스턴스 프로필 사용을 참조하십시오.

AWS의 IAM Roles for Service Accounts (IRSA)를 참조하여 AWS에서 OIDC 공급자를 설정하고 포드의 서비스 계정이 해당 역할을 맡을 수 있도록 하는 AWS IAM 역할을 구성하십시오.

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가 자동으로 시작되도록 systemd 서비스를 생성하여 구성합니다. 지침은 the Discovery Service를 설치한 방법에 따라 다릅니다.

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

sudo systemctl enable teleport
sudo systemctl start teleport

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 System Manager -> Node Management -> Run Command의 명령 기록을 확인하십시오. 오류를 검토하려면 대상의 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 정책이 포함되어 있는지 확인하십시오.

더 많은 세부 정보를 보려면 AWS 문서에서 SSM RunCommand 오류 코드 및 문제 해결 정보를 참조하십시오:

다음 단계

Teleport 원문 보기
인포레터에서 최신 DevOps 트렌드를 격주로 만나보세요!