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

작동 방식#

teleport-discovery-aws Terraform 모듈은 Teleport EC2 자동 검색을 활성화하기 위해 Teleport 클러스터와 AWS 계정에 리소스를 생성합니다.

Teleport Discovery Service는 AWS API를 쿼리하여 계정의 EC2 인스턴스 목록을 가져옵니다. 검색된 각 EC2 인스턴스에 대해 Discovery Service는 AWS Systems Manager(SSM)를 사용하여 인스턴스에 Teleport를 설치하고 Teleport로 보호되는 서버로 클러스터에 참가시킵니다.

사전 요구 사항#

• 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:

• Ubuntu/Debian/RHEL/Amazon Linux 2/Amazon Linux 2023을 실행하고 SSM 에이전트 버전 3.1 이상을 갖춘 EC2 인스턴스

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 설치#

1/3단계. Teleport 설치#

다른 Teleport 서비스(예: Auth 또는 Proxy)를 이미 실행 중인 호스트에서 Discovery Service를 실행할 계획이라면 이 단계를 건너뛸 수 있습니다.

Discovery Service를 실행할 호스트 인스턴스에 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
   

2/3단계. Discovery Service 구성#

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

$ tctl tokens add --type=discovery

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

에 클러스터의 Teleport Proxy Service 호스트 및 포트를 지정하고, 에 등록할 리소스 그룹을 식별하는 이름을 지정하십시오:

# teleport.yaml
version: v3
teleport:
  join_params:
    # token_name은 리터럴 토큰 문자열 또는 파일 경로일 수 있습니다.
    # 구성 파일에 비밀을 포함하지 않으려면 파일 경로가 더 좋습니다.
    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.

teleport-discovery-aws Terraform 모듈 사용#
1/5단계. AWS Terraform 공급자 구성#
AWS Terraform 공급자와 Terraform이 AWS 리소스를 관리하기 위한 AWS IAM 권한을 구성하십시오.

AWS Terraform 공급자에 필요한 AWS IAM 권한
AWS Terraform 공급자는 teleport-discovery-aws 모듈이 생성한 AWS 리소스를 관리하기 위해 다음 AWS IAM 권한이 필요합니다:
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "TerraformIdentity",
      "Effect": "Allow",
      "Action": "sts:GetCallerIdentity",
      "Resource": "*"
    },
    {
      "Sid": "ManageIamRole",
      "Effect": "Allow",
      "Action": [
        "iam:CreateRole",
        "iam:DeleteRole",
        "iam:GetRole",
        "iam:ListInstanceProfilesForRole",
        "iam:ListRolePolicies",
        "iam:ListRoles",
        "iam:ListRoleTags",
        "iam:TagRole",
        "iam:UntagRole",
        "iam:UpdateAssumeRolePolicy"
      ],
      "Resource": "*"
    },
    {
      "Sid": "ManageIamPolicy",
      "Effect": "Allow",
      "Action": [
        "iam:CreatePolicy",
        "iam:CreatePolicyVersion",
        "iam:DeletePolicy",
        "iam:DeletePolicyVersion",
        "iam:GetPolicy",
        "iam:GetPolicyVersion",
        "iam:ListPolicies",
        "iam:ListPolicyTags",
        "iam:ListPolicyVersions",
        "iam:TagPolicy",
        "iam:UntagPolicy"
      ],
      "Resource": "*"
    },
    {
      "Sid": "ManageRolePolicyAttachments",
      "Effect": "Allow",
      "Action": [
        "iam:AttachRolePolicy",
        "iam:DetachRolePolicy",
        "iam:ListAttachedRolePolicies"
      ],
      "Resource": "*"
    },
    {
      "Sid": "ManageOidcProvider",
      "Effect": "Allow",
      "Action": [
        "iam:CreateOpenIDConnectProvider",
        "iam:DeleteOpenIDConnectProvider",
        "iam:GetOpenIDConnectProvider",
        "iam:ListOpenIDConnectProviders",
        "iam:TagOpenIDConnectProvider",
        "iam:UntagOpenIDConnectProvider",
        "iam:UpdateOpenIDConnectProviderThumbprint"
      ],
      "Resource": "*"
    }
  ]
}


2/5단계. Teleport Terraform 공급자 구성#
Teleport Terraform 공급자를 구성하는 방법은 Terraform을 실행하는 방식(예: CI, Spacelift, 기타 원격 환경)에 따라 여러 가지가 있지만, 빠른 시작을 위해서는 로컬 데모 가이드를 참조하십시오.
로컬 데모 가이드는 로컬 Teleport 자격 증명으로 Teleport Terraform 공급자를 구성하는 방법을 안내합니다. 일반적으로 tsh로 로그인하고 terraform 명령을 실행하는 동일한 셸에서 tctl 명령을 실행하면 됩니다:
$ tsh login
$ eval "$(tctl terraform env)"

클라우드 VM, 온프레미스 서버, CI/CD 파이프라인과 같은 원격 환경에서 Terraform을 실행하는 경우 Teleport Terraform 공급자 사용을 참조하여 사용 사례에 적합한 가이드를 찾으십시오.
3/5단계. Terraform 모듈 입력 구성#
Terraform 구성에 teleport-discovery-aws 모듈을 추가하십시오.
cloudself-hosted

module "aws_discovery" {
  source = "terraform.releases.teleport.dev/teleport/discovery/aws"
  version = "~> (=cloud.major_version=).0"

  # 필수 입력:
  # 에 Teleport 클러스터의 프록시 공개 주소(host:port 형식)를 지정하십시오.
  teleport_proxy_public_addr = "https://"
  # teleport_discovery_group_name은 Discovery Service 구성 파일의 discovery group 이름과 일치해야 합니다.
  # Teleport Cloud 클러스터는 그룹 이름 "cloud-discovery-group"으로 Discovery Service를 실행합니다.
  # 직접 Discovery Service를 실행하려는 경우가 아니면 이 입력을 수정하지 마십시오.
  teleport_discovery_group_name = "cloud-discovery-group"
  # EC2 인스턴스 검색
  match_aws_resource_types = ["ec2"]

  # 선택적 입력:
  # 이 모듈이 생성한 모든 AWS 리소스에 추가 AWS 태그 "origin=example" 적용
  apply_aws_tags = { origin = "example" }
  # 이 모듈이 생성한 모든 Teleport 리소스에 추가 Teleport 레이블 "origin=example" 적용
  apply_teleport_resource_labels = { origin = "example" }
  # match_aws_regions은 Discovery Service가 EC2 인스턴스를 매칭하고 검색할 리전 목록입니다.
  # 와일드카드 "*"가 기본값이며 모든 리전에 매칭됩니다.
  match_aws_regions = ["*"]
  # match_aws_tags는 EC2 인스턴스 검색 시 매칭할 AWS 태그입니다.
  # 일치하는 태그가 있는 EC2 인스턴스만 검색됩니다.
  # 와일드카드 {"*" : ["*"]}가 기본값이며 모든 태그에 매칭됩니다.
  match_aws_tags = { "*" : ["*"] }
}



module "aws_discovery" {
  source = "terraform.releases.teleport.dev/teleport/discovery/aws"
  version = "~> (=teleport.major_version=).0"

  # 필수 입력:
  # 클러스터의 Teleport Proxy Service 호스트 및 포트로 이 입력을 편집하십시오
  teleport_proxy_public_addr    = "https://"
  # Discovery Service 구성 파일의 discovery group 이름과 일치하도록 이 입력을 편집하십시오
  teleport_discovery_group_name = ""
  # EC2 인스턴스 검색
  match_aws_resource_types = ["ec2"]

  # 선택적 입력:
  # 이 모듈이 생성한 모든 AWS 리소스에 추가 AWS 태그 "origin=example" 적용
  apply_aws_tags = { origin = "example" }
  # 이 모듈이 생성한 모든 Teleport 리소스에 추가 Teleport 레이블 "origin=example" 적용
  apply_teleport_resource_labels = { origin = "example" }
  # match_aws_regions은 Discovery Service가 EC2 인스턴스를 매칭하고 검색할 리전 목록입니다.
  # 와일드카드 "*"가 기본값이며 모든 리전에 매칭됩니다.
  match_aws_regions = ["*"]
  # match_aws_tags는 EC2 인스턴스 검색 시 매칭할 AWS 태그입니다.
  # 일치하는 태그가 있는 EC2 인스턴스만 검색됩니다.
  # 와일드카드 {"*" : ["*"]}가 기본값이며 모든 태그에 매칭됩니다.
  match_aws_tags = { "*" : ["*"] }
}



모듈의 출력을 표시하기 위해 Terraform 출력을 추가하십시오:
output "aws_discovery" {
  value = module.aws_discovery
}

모듈 입력 및 출력의 전체 설명은 teleport-discovery-aws 참조를 참조하십시오.
4/5단계. Terraform 모듈 적용#
$ terraform init
$ terraform apply

Terraform은 다음 리소스를 생성하도록 계획해야 합니다:

Teleport Discovery Service가 수임할 AWS IAM 역할
Teleport가 AWS에서 리소스를 검색하는 데 필요한 AWS 권한을 부여하는 AWS IAM 정책
IAM 정책을 Discovery Service IAM 역할에 연결하는 AWS IAM 정책 연결
Teleport Discovery Service가 OIDC를 사용하여 IAM 역할을 수임하기 위한 AWS OIDC 공급자
AWS 리소스 검색을 위한 Teleport를 구성하는 Teleport discovery_config 클러스터 리소스
AWS OIDC를 위한 Teleport integration 클러스터 리소스
Teleport 노드가 AWS IAM 자격 증명을 사용하여 클러스터에 참가할 수 있도록 하는 Teleport token 클러스터 리소스

Terraform 계획을 검토하고 계획 작업을 확인하십시오.
Terraform이 계획 적용을 완료하면 모듈 출력이 표시됩니다:
aws_discovery = {
  "aws_oidc_provider_arn" = "arn:aws:iam::123456789012:oidc-provider/example.teleport.sh"
  "teleport_discovery_config_name" = "discovery-aws-account-123456789012"
  "teleport_discovery_service_iam_policy_arn" = "arn:aws:iam::123456789012:policy/teleport-discovery-<timestamp>"
  "teleport_discovery_service_iam_role_arn" = "arn:aws:iam::123456789012:role/teleport-discovery-<timestamp>"
  "teleport_integration_name" = "discovery-aws-account-123456789012"
  "teleport_provision_token_name" = "discovery-aws-account-123456789012"
}

AWS 리소스에는 다음 태그가 있어야 합니다:

origin=example
teleport.dev/cluster=<cluster-name>
teleport.dev/integration=discovery-aws-account-<account-id>
teleport.dev/iac-tool=terraform

Teleport 리소스에는 다음 레이블이 있어야 합니다:

origin=example
teleport.dev/iac-tool=terraform

5/5단계. 검색 상태 확인#
Terraform 모듈을 적용한 후 Teleport Discovery Service가 AWS 계정의 EC2 인스턴스 검색을 시작하고 클러스터에 보호된 리소스로 등록해야 합니다.
Note
EC2 인스턴스가 검색되고 등록되는 데 몇 분이 걸릴 수 있습니다.

Teleport Web UI로 이동하여 Zero Trust Access > Integrations를 선택하십시오.
기본적으로 teleport-discovery-aws Terraform 모듈이 생성한 통합의 이름은 discovery-aws-account-<aws-account-id>입니다.
AWS 계정에 대한 통합을 클릭하여 검색 상태를 검토하십시오.
통합 페이지에서는 검색된 EC2 인스턴스의 수와 검색 프로세스 중 발생한 문제에 대한 개요를 제공합니다.

위의 예시에서 인스턴스의 AWS SSM 에이전트에 문제가 있었음을 확인할 수 있습니다.
"issues" 탭으로 이동하여 "Details"를 클릭하면 문제에 대한 자세한 정보를 확인할 수 있습니다:

이 경우 EC2 인스턴스에 AmazonSSMManagedInstanceCore IAM 정책이 연결된 IAM 역할이 없어서 인스턴스가 SSM 명령을 받을 수 없다는 문제입니다.
EC2 인스턴스의 역할에 AmazonSSMManagedInstanceCore IAM 정책을 연결하고 Discovery Service가 SSM으로 설치를 재시도할 때까지 기다리면 이 문제를 해결할 수 있습니다. 다음 검색 스캔이 실행되어 인스턴스에 Teleport를 설치하는 데 몇 분이 걸릴 수 있습니다.
검색된 모든 EC2 인스턴스가 Teleport 클러스터에 성공적으로 참가하면 개요 페이지에 정상 상태가 표시됩니다:

모듈 구성 업데이트#
모듈 입력을 변경하고 재적용하여 AWS 검색 통합을 조정할 수 있습니다.
예를 들어 이전에 모든 리전의 기본 와일드카드 대신 특정 AWS 리전을 사용했다면 match_aws_regions를 조정하여 EC2 검색을 위한 추가 리전을 포함하고 모듈을 재적용하여 해당 리전의 인스턴스 등록을 시작할 수 있습니다.
-match_aws_regions = ["us-west-1"]
+match_aws_regions = ["us-west-1", "us-east-1"]

Terraform을 다시 적용하십시오:
$ terraform apply

변경 사항을 확인하기 전에 Terraform 계획을 검토하십시오.
Terraform이 계획 적용을 완료하면 Discovery Service가 동적 discovery_config의 변경 사항을 인식하고 us-east-1에서도 EC2 인스턴스 등록을 시작합니다.
문제 해결#

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.