AWS에서 워크로드 아이덴티티를 사용하여 tbot 배포

요약

Teleport 워크로드 아이덴티티는 워크로드에 단기 암호화 아이덴티티를 발급하여 다른 워크로드나 클라우드 공급자 API와 안전하게 인증하고 통신할 수 있게 합니다. 이 가이드는 Amazon EC2 인스턴스에 머신 및 워크로드 아이덴티티 에이전트 tbot을 배포하고 머신 및 워크로드 아이덴티티 (MWI)를 설정하는 방법을 안내합니다.

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

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

사전 요구 사항#

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:

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.

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

1/7단계. `tbot` 설치#

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

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

플랫폼에 맞는 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.

Assign to your Teleport cluster hostname and port, but not the scheme (https://).

Run your cluster's install script:

$ curl "https:///scripts/install.sh" | sudo bash

2/8단계. Bot 생성#

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

Next, you need to create a Bot. A Bot is a Teleport identity for a machine or group of machines. Like users, bots have a set of roles and traits which define what they can access.

Create 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: []

Make sure you replace example with a unique, descriptive name for your Bot.

Use tctl to apply this file:

$ tctl create bot.yaml

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

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

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/7단계. `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을 두 번째 단계에서 생성한 토큰의 이름으로.

By default, tbot will run in daemon mode. However, this must then be configured as a service within the service manager on the Linux host. The service manager will start tbot on boot and ensure it is restarted if it fails.

If tbot was installed using the Teleport install script or teleport-update command, the tbot systemd service is automatically created for you.

After tbot.yaml is created, enable and start the service::

$ sudo systemctl enable tbot --now

Check the service has started successfully:

$ sudo systemctl status tbot

Service properties like User and Group may be configured using systemctl edit tbot.`

If tbot was installed manually, service configuration will need to be performed manually as well.

For this guide, systemd will be demonstrated but tbot should be compatible with all common alternatives.

Use tbot install systemd to generate a systemd service file:

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

Ensure that you replace:

teleport with the name of Linux user you wish to run tbot as.
/etc/tbot.yaml with the path to the configuration file you have created.

You can omit --write to print the systemd service file to the console instead of writing it to disk.

--anonymous-telemetry enables the submission of anonymous usage telemetry. This helps us shape the future development of tbot. You can disable this by omitting this.

Next, enable the service so that it will start on boot and then start the service:

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

Check the service has started successfully:

$ sudo systemctl status tbot

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

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

다음으로 방금 생성한 대상 리소스에서 워크로드 아이덴티티를 구성합니다. 봇이 구성되고 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에 my-app이라는 서비스의 경우 /svc/my-app과 같이 systemd 서비스 이름이 자동으로 포함됩니다.

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

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

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

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

$ 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 호환 자격증명을 받을 수 있음을 확인합니다.

7/7단계. Workload API를 사용하도록 워크로드 구성#

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

다음 단계#

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

AWS에서 워크로드 아이덴티티를 사용하여 tbot 배포

원문 보기

번역일: 2026-04-04

요약

사전 요구 사항#

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:

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=)

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

1/7단계. `tbot` 설치#

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

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

플랫폼에 맞는 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.

Assign to your Teleport cluster hostname and port, but not the scheme (https://).

Run your cluster's install script:

$ curl "https:///scripts/install.sh" | sudo bash

2/8단계. Bot 생성#

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

Next, you need to create a Bot. A Bot is a Teleport identity for a machine or group of machines. Like users, bots have a set of roles and traits which define what they can access.

Create 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: []

Make sure you replace example with a unique, descriptive name for your Bot.

Use tctl to apply this file:

$ tctl create bot.yaml

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

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

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/7단계. `tbot` 구성#

/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을 두 번째 단계에서 생성한 토큰의 이름으로.

If tbot was installed using the Teleport install script or teleport-update command, the tbot systemd service is automatically created for you.

After tbot.yaml is created, enable and start the service::

$ sudo systemctl enable tbot --now

Check the service has started successfully:

$ sudo systemctl status tbot

Service properties like User and Group may be configured using systemctl edit tbot.`

If tbot was installed manually, service configuration will need to be performed manually as well.

For this guide, systemd will be demonstrated but tbot should be compatible with all common alternatives.

Use tbot install systemd to generate a systemd service file:

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

Ensure that you replace:

teleport with the name of Linux user you wish to run tbot as.
/etc/tbot.yaml with the path to the configuration file you have created.

You can omit --write to print the systemd service file to the console instead of writing it to disk.

--anonymous-telemetry enables the submission of anonymous usage telemetry. This helps us shape the future development of tbot. You can disable this by omitting this.

Next, enable the service so that it will start on boot and then start the service:

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

Check the service has started successfully:

$ sudo systemctl status tbot

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

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

다음을 수행합니다:

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

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을 사용하여 워크로드 아이덴티티를 생성합니다.

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

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에 my-app이라는 서비스의 경우 /svc/my-app과 같이 systemd 서비스 이름이 자동으로 포함됩니다.

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

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

$ 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 호환 자격증명을 받을 수 있음을 확인합니다.

7/7단계. Workload API를 사용하도록 워크로드 구성#

다음 단계#

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

AWS에서 워크로드 아이덴티티를 사용하여 tbot 배포

사전 요구 사항#

1/7단계. tbot 설치#

2/8단계. Bot 생성#

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

4/7단계. tbot 구성#

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

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

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

7/7단계. Workload API를 사용하도록 워크로드 구성#

다음 단계#

사전 요구 사항#

1/7단계. tbot 설치#

2/8단계. Bot 생성#

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

4/7단계. tbot 구성#

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

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

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

7/7단계. Workload API를 사용하도록 워크로드 구성#

다음 단계#

1/7단계. `tbot` 설치#

4/7단계. `tbot` 구성#

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

1/7단계. `tbot` 설치#

4/7단계. `tbot` 구성#

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