Teleport 워크로드 아이덴티티는 워크로드에 단기 암호화 아이덴티티를 발급하여 다른 워크로드나 클라우드 공급자 API와 안전하게 인증하고 통신할 수 있게 합니다.

이 가이드에서는 Amazon EC2 인스턴스에 머신 및 워크로드 아이덴티티 에이전트 tbot을 배포하고 머신 및 워크로드 아이덴티티(MWI)를 설정합니다. 완료되면 EC2 인스턴스에서 실행 중인 워크로드에 SPIFFE 호환 자격 증명을 발급하는 tbot 서비스가 작동하게 됩니다.

사전 요구사항#

• 실행 중인 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
     ```
   

 

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 명령을 실행할 수도 있습니다.

• Teleport 클러스터에 접근 권한을 부여하려는 AWS IAM 역할. 이 역할에는 sts:GetCallerIdentity가 부여되어야 합니다. 이 가이드에서 이 역할은 teleport-bot-role이라는 이름으로 사용됩니다.
• MWI 에이전트 tbot을 설치할, IAM 역할이 연결된 AWS EC2 인스턴스.

1/6단계. tbot 설치#

이 단계는 AWS EC2 인스턴스에서 완료합니다.

머신 및 워크로드 아이덴티티를 사용할 EC2 인스턴스에 tbot을 설치합니다.

플랫폼에 맞는 Teleport 패키지를 다운로드하고 설치합니다:

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

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

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

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

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

2/6단계. Bot 생성#

이 단계는 로컬 머신에서 완료합니다.

다음으로 Bot을 생성해야 합니다. Bot은 머신 또는 머신 그룹을 위한 Teleport identity입니다. 사용자와 마찬가지로 bot에는 무엇에 액세스할 수 있는지 정의하는 role 및 trait 집합이 있습니다.

bot.yaml을 생성합니다:

kind: bot
version: v1
metadata:
  # name is a unique identifier for the Bot in the cluster.
  name: example
spec:
  # roles is a list of roles to grant to the Bot. Don't worry if you don't know
  # what roles you need to specify here, the Access Guides will walk you through
  # creating and assigning roles to the already created Bot.
  roles: []

example을 Bot에 대한 고유하고 설명적인 이름으로 반드시 교체하십시오.

tctl을 사용하여 이 파일을 적용합니다:

$ tctl create bot.yaml

3/6단계. 조인 토큰 생성#

이 단계는 로컬 머신에서 완료합니다.

bot-token.yaml을 생성합니다:

kind: token
version: v2
metadata:
  # name will be specified in the `tbot` to use this token
  name: example-bot
spec:
  roles: [Bot]
  # bot_name should match the name of the bot created earlier in this guide.
  bot_name: example
  join_method: iam
  # Restrict the AWS account and (optionally) ARN that can use this token.
  # This information can be obtained from running the
  # "aws sts get-caller-identity" command from the CLI.
  allow:
    - aws_account: "111111111111"
      aws_arn: "arn:aws:sts::111111111111:assumed-role/teleport-bot-role/i-*"

다음을 교체합니다:

• 111111111111을 사용자의 AWS 계정 ID로 교체합니다.
• teleport-bot-role을 EC2 인스턴스에 생성하고 할당한 AWS IAM 역할의 이름으로 교체합니다.
• example을 이 가이드의 두 번째 단계에서 생성한 봇의 이름으로 교체합니다.
• i-*는 지정된 역할을 가진 모든 인스턴스가 해당 조인 방법을 사용할 수 있음을 나타냅니다. 개별 인스턴스로 제한하고 싶다면 i-*를 전체 인스턴스 ID로 교체합니다.

이 파일을 적용하려면 tctl을 사용합니다:

$ tctl create bot-token.yaml

4/6단계. tbot 구성#

이 단계는 AWS EC2 인스턴스에서 완료합니다. tbot에서 workload-identity-api 서비스를 구성합니다. 워크로드에 SPIFFE 자격 증명을 발급하려면 tbot이 Workload API 엔드포인트를 노출해야 합니다. tbot 구성에 workload-identity-api 서비스를 추가하여 이를 구성합니다.

먼저 이 소켓을 생성할 위치를 결정합니다. 이 예제에서는 /opt/machine-id/workload.sock을 사용합니다. Workload API에 연결해야 하는 프로세스만 접근할 수 있는 디렉터리를 선택하는 것이 좋습니다.

/etc/tbot.yaml을 생성합니다:

version: v2
# Teleport proxy server address
proxy_server: example.teleport.sh:443
# Onboarding configuration
onboarding:
  join_method: iam
  token: example-bot
# Storage configuration for tbot state
storage:
  type: directory
  path: /var/lib/teleport/bot
# Services section - configures the workload-identity-api service
services:
  - type: workload-identity-api
    listen: unix:///opt/machine-id/workload.sock
    selector:
      name: example-workload-identity
    attestors:
      systemd:
        enabled: true

다음을 교체합니다:

• example.teleport.sh:443을 사용자의 Teleport Proxy Service 또는 Auth Service 주소로 교체합니다. 가능하면 Teleport Proxy Service 인스턴스의 주소를 사용하는 것이 좋습니다.
• example-bot을 세 번째 단계에서 생성한 토큰의 이름으로 교체합니다.

기본적으로 tbot은 데몬 모드로 실행됩니다. 다만 이 경우 Linux 호스트의 서비스 관리자 내에서 서비스로 구성해야 합니다. 서비스 관리자는 부팅 시 tbot을 시작하고 실패할 경우 재시작되도록 보장합니다.

tbot이 Teleport 설치 스크립트 또는 teleport-update 명령을 사용하여 설치된 경우, tbot systemd 서비스가 자동으로 생성됩니다.

tbot.yaml이 생성된 후, 서비스를 활성화하고 시작합니다.

$ sudo systemctl enable tbot --now

서비스가 성공적으로 시작되었는지 확인합니다.

$ sudo systemctl status tbot

User 및 Group과 같은 서비스 속성은 systemctl edit tbot을 사용하여 구성할 수 있습니다.`

tbot이 수동으로 설치된 경우, 서비스 구성도 수동으로 수행해야 합니다.

이 가이드에서는 systemd를 예로 들지만, tbot은 일반적인 모든 대안과 호환됩니다.

tbot install systemd를 사용하여 systemd 서비스 파일을 생성합니다.

$ sudo tbot install systemd \
   --write \
   --config /etc/tbot.yaml \
   --user teleport \
   --group teleport \
   --anonymous-telemetry

다음 항목을 반드시 변경하십시오.

• teleport를 tbot을 실행할 Linux 사용자 이름으로 변경합니다.
• /etc/tbot.yaml을 생성한 구성 파일의 경로로 변경합니다.

--write를 생략하면 systemd 서비스 파일을 디스크에 쓰는 대신 콘솔에 출력할 수 있습니다.

--anonymous-telemetry는 익명 사용 텔레메트리 제출을 활성화합니다. 이는 tbot의 향후 개발 방향을 정하는 데 도움이 됩니다. 이를 생략하여 비활성화할 수 있습니다.

다음으로, 부팅 시 서비스가 시작되도록 서비스를 활성화한 후 서비스를 시작합니다.

$ sudo systemctl daemon-reload
$ sudo systemctl enable tbot --now

서비스가 성공적으로 시작되었는지 확인합니다.

$ sudo systemctl status tbot

새 구성을 적용하려면 tbot 인스턴스를 재시작합니다.

5/6단계. 워크로드 아이덴티티 구성#

다음으로, 방금 생성한 대상 리소스에서 워크로드 아이덴티티를 구성합니다. 봇이 구성되어 Teleport에 연결되면, 이제 이를 사용하여 Teleport의 워크로드 아이덴티티 시스템을 통해 워크로드에 SPIFFE 호환 자격 증명을 발급할 수 있습니다.

다음을 수행합니다:

• 워크로드의 SPIFFE ID를 정의하는 워크로드 아이덴티티 리소스를 생성합니다.
• Bot이 해당 아이덴티티에 대한 자격 증명을 발급할 수 있도록 RBAC를 구성합니다.
• 워크로드가 연결하여 SPIFFE SVID 호환 자격 증명을 받을 수 있도록 SPIFFE Workload API 엔드포인트를 노출하도록 tbot 인스턴스를 업데이트합니다.

진행하기 전에 워크로드가 사용할 SPIFFE ID 경로를 결정해야 합니다. 이 예제에서는 /svc/foo를 사용합니다. SPIFFE ID 구조를 선택하는 방법에 대한 자세한 안내는 모범 사례 가이드에서 제공합니다.

workload-identity.yaml이라는 새 파일을 생성합니다:

kind: workload_identity
version: v1
metadata:
  name: example-workload-identity
  labels:
    example: getting-started
spec:
  spiffe:
    id: /svc/foo

다음을 교체합니다:

• example-workload-identity를 사용 사례를 설명하는 이름으로 교체합니다.
• /svc/foo를 발급하기로 결정한 SPIFFE ID 경로로 교체합니다.

워크로드 아이덴티티를 생성합니다:

$ tctl create ./workload-identity.yaml

워크로드 어테스테이션 사용#

SPIFFE ID에 값을 하드코딩하는 대신, 워크로드 어테스테이션을 사용하여 워크로드 속성을 기반으로 동적으로 값을 채울 수도 있습니다. 예를 들어 아이덴티티를 요청하는 systemd 서비스의 이름을 포함할 수 있습니다.

systemd 어테스터를 활성화하려면 tbot.yaml 구성에 다음을 추가합니다:

services:
  - type: workload-identity-api
    listen: unix:///opt/machine-id/workload.sock
    selector:
      name: example-workload-identity
    attestors:
      systemd:
        enabled: true

그런 다음, 어테스트된 서비스 이름을 참조하는 워크로드 아이덴티티를 정의합니다:

kind: workload_identity
version: v1
metadata:
  name: example-workload-identity
  labels:
    example: getting-started
spec:
  spiffe:
    id: "/svc/{{workload.systemd.service}}"

이 구성을 사용하면 SPIFFE ID에 systemd 서비스 이름이 자동으로 포함됩니다. 예를 들어 my-app이라는 이름의 서비스라면 /svc/my-app이 됩니다.

6/6단계. tbot spiffe-inspect로 Workload API 테스트#

tbot spiffe-inspect를 사용하여 Workload API 엔드포인트가 SPIFFE 자격 증명을 올바르게 발급하고 있는지 확인합니다. 이 명령은 엔드포인트에 연결하여 SVID를 요청하고, 상세한 디버그 정보를 출력합니다.

워크로드가 Workload API를 사용하도록 구성하기 전에, 이 명령을 사용하여 Workload API가 예상대로 동작하는지 확인하는 것이 좋습니다.

--path와 함께 spiffe-inspect 명령을 사용하여 Workload API 소켓의 경로를 지정합니다. 이때 /opt/machine-id/workload.sock을 이전 단계에서 구성한 경로로 교체합니다:

$ tbot spiffe-inspect --path unix:///opt/machine-id/workload.sock
INFO [TBOT]      Inspecting SPIFFE Workload API Endpoint unix:///opt/machine-id/workload.sock tbot/spiffe.go:31
INFO [TBOT]      Received X.509 SVID context from Workload API bundles_count:1 svids_count:1 tbot/spiffe.go:46
SVIDS
- spiffe://teleport.example.com/svc/foo
  - Expiry: 2025-03-20 10:55:52 +0000 UTC
Trust Bundles
- teleport.example.com

이는 워크로드가 Workload API에 성공적으로 연결하여 Teleport가 발급한 SPIFFE 호환 자격 증명을 받을 수 있음을 확인해 줍니다.

이제 Workload API가 예상대로 동작한다는 것을 확인했으므로, 워크로드가 이를 사용하도록 구성할 수 있습니다. 정확한 단계는 워크로드에 따라 달라집니다. SPIFFE SDK를 사용한 경우, SPIFFE_ENDPOINT_SOCKET 환경 변수가 tbot이 생성한 소켓을 가리키도록 구성할 수 있습니다.

다음 단계#

• 구성 참조를 읽고 사용 가능한 모든 구성 옵션을 살펴보세요.
• 워크로드 어테스테이션을 사용하여 워크로드의 특성을 기반으로 발급되는 SVID를 제한하세요.
• 워크로드 어테스테이션을 통해 확인된 속성을 기반으로 WorkloadIdentity 규칙을 구성하세요.
• TELEPORT_ANONYMOUS_TELEMETRY에 대한 자세한 정보.