이 가이드에서는 Bound Keypair 참여를 사용하여 임의의 호스트에 머신 및 워크로드 아이덴티티의 에이전트인 tbot을 설치합니다. 이 호스트는 베어메탈 머신, VM, 컨테이너 또는 다른 호스트가 될 수 있습니다. 유일한 요구 사항은 호스트에 영구 저장소가 있어야 한다는 것입니다.

Bound Keypair 참여는 시크릿 기반 참여 방법에 대한 개선된 대안이며 즉시 사용 가능한 교체재로 기능할 수 있습니다. 정적 토큰 참여보다 더 안전하고, 갱신 가능한 인증서를 사용하는 임시 토큰 참여보다 더 유연합니다. 인증서가 만료되면 자동 복구를 수행하여 장기 장애 후에도 bot이 재참여할 수 있도록 합니다.

플랫폼별 참여 방법이 환경에 더 적합할 수 있습니다. 전체 옵션 목록은 배포 가이드를 참조하세요.

작동 방식#

Bound Keypair 참여를 사용하면 머신 및 워크로드 아이덴티티 bot이 내부 데이터 디렉터리에 영구적으로 저장되는 고유한 키 쌍을 생성합니다. 그런 다음 Teleport는 향후 참여 시도를 위해 이 공개 키를 신뢰하도록 구성됩니다.

나중에 bot이 클러스터에 참여하려고 할 때, Teleport는 개인 키만으로 완료할 수 있는 챌린지를 bot에게 발행합니다. bot은 해결된 챌린지를 반환하여 자체 신원을 증명하고, 조건부로 클러스터에 참여할 수 있게 됩니다. 이 프로세스는 모든 참여 시도마다 반복되지만, bot이 인증서가 만료될 만큼 충분히 오래 오프라인 상태였다면 다시 참여하기 위해 추가적으로 자동 복구를 수행해야 합니다.

자체 증명은 AWS와 같은 클라우드 공급자나 전용 TPM에서 제공하는 외부 검증보다 본질적으로 덜 안전하기 때문에, Bound Keypair 참여는 남용을 방지하기 위한 다양한 추가 검사를 시행합니다:

• 키 쌍이 유용하게 공유되거나 복제될 수 없도록 하는 참여 상태 검증
• 정규 bot 인증서가 유용하게 공유되거나 복제될 수 없도록 하는 인증서 생성 카운터 검사
• bot이 이 키 쌍을 사용하여 자동으로 복구할 수 있는 빈도에 대한 구성 가능한 제한

Bound Keypair 참여의 중요한 이점은 모든 참여 제한이 언제든지 재구성될 수 있으며, 만료되거나 오프라인 상태가 된 bot은 클라이언트 측 개입 없이 서버 측 예외를 만들어 복구할 수 있다는 것입니다.

이 참여 방법이 어떻게 작동하고 프로덕션에서 사용하는 방법에 대한 자세한 내용은 참조 페이지를 참조하세요.

필수 조건#

• 버전 18.1.0 이상의 실행 중인 Teleport 클러스터.
• tsh 및 tctl 클라이언트.

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.

• 이 가이드는 bot 호스트에 내부 bot 데이터를 위한 변경 가능한 영구 저장소가 있다고 가정합니다. 변경 불가능한 호스트(예: CI 실행)에서 Bound Keypair 참여를 사용할 수도 있지만, 이렇게 하면 보안 보장이 줄어듭니다. 자세한 내용은 참조 페이지를 참조하세요.

1단계/5단계. tbot 설치#

이 단계는 bot 호스트에서 완료합니다.

먼저, 머신 및 워크로드 아이덴티티를 사용하려는 호스트에 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.

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단계/5단계. 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단계/5단계. 참여 토큰 생성#

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

이 가이드에서는 등록 시크릿을 사용하여 bot을 참여시키는 방법을 설명합니다. 이 시크릿은 bot의 첫 번째 참여를 인증하기 위해 제공할 수 있는 일회용 시크릿입니다. 인증되면, bot은 자동으로 키 쌍을 생성하고 향후 모든 참여 시도에 사용하기 위해 공개 키를 Teleport에 등록합니다.

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

kind: token
version: v2
metadata:
  # 이 이름은 tbot의 `onboarding.token` 필드에 사용됩니다.
  name: example
spec:
  roles: [Bot]
  # bot_name은 이 가이드의 앞서 생성한 bot 이름과 일치해야 합니다.
  bot_name: example
  join_method: bound_keypair
  bound_keypair:
    recovery:
      mode: standard
      limit: 1

spec.bot_name의 example을 두 번째 단계에서 생성한 bot 이름으로 교체합니다.

이 예시에서는 bound keypair 토큰에 추가 옵션을 설정할 필요가 없습니다. bot의 초기 참여에 사용될 단일 복구 시도를 허용했으며, 사전 등록된 공개 키가 없으므로 Teleport는 토큰이 생성될 때 자동으로 등록 시크릿을 생성합니다.

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

$ tctl create -f token-example.yaml

다음으로, 생성된 등록 시크릿을 검색합니다. 다음 단계에서 필요합니다:

$ tctl get token/example --format=json | jq -r '.[0].status.bound_keypair.registration_secret'

이는 jq가 설치되어 있다고 가정합니다. 설치되지 않은 경우 tctl get token/example을 실행하고 .status.bound_keypair.registration_secret 필드를 검사하세요.

4단계/5단계. tbot 구성#

이 단계는 bot 호스트에서 완료합니다.

저장소 디렉터리 준비#

Create the bot data directory and grant permissions to access it to the Linux user (in our example, teleport) which tbot will run as.

# Make the bot directory and assign ownership to teleport user
$ sudo mkdir -p /var/lib/teleport/bot
$ sudo chown teleport:teleport /var/lib/teleport/bot
# Allow teleport user to open directory
$ sudo chmod +x /var/lib/teleport /var/lib/teleport/bot

구성 파일 생성#

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

version: v2
proxy_server: example.teleport.sh:443
onboarding:
  join_method: bound_keypair
  token: example
  bound_keypair:
    registration_secret: SECRET
storage:
  type: directory
  path: /var/lib/teleport/bot
# 서비스는 접근 가이드 완료 중에 채워집니다.
services: []

다음을 교체합니다:

• example.teleport.sh:443을 Teleport Proxy 주소로.
• example을 이전 단계에서 생성한 토큰 이름으로 (example에서 변경한 경우).
• SECRET을 이전 단계에서 검색한 등록 시크릿으로.

Now, you must decide if you want to run tbot as a daemon or in one-shot mode.

In daemon mode, tbot runs continually, renewing the short-lived credentials for the configured outputs on a fixed interval. This is often combined with a service manager (such as systemd) in order to run tbot in the background. This is the default behaviour of tbot.

In one-shot mode, tbot generates short-lived credentials and then exits. This is useful when combining tbot with scripting (such as in CI/CD) as it allows further steps to be dependent on tbot having succeeded. It is important to note that the credentials will expire if not renewed and to ensure that the TTL for the certificates is long enough to cover the length of the CI/CD job.

Configuring tbot as a daemon#

(!docs/pages/includes/machine-id/daemon.mdx!)

Configuring tbot for one-shot mode#

To use tbot in one-shot mode, modify /etc/tbot.yaml to add oneshot: true:

version: v2
oneshot: true
auth_server: ...

Now, you should test your tbot configuration. When started, several log messages will be emitted before it exits with status 0:

$ export TELEPORT_ANONYMOUS_TELEMETRY=1
$ tbot start -c /etc/tbot.yaml

TELEPORT_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.

5단계/5단계. 출력 구성#

You have now prepared the base configuration for tbot. At this point, it identifies itself to the Teleport cluster and renews its own credentials but does not output any credentials for other applications to use.

Follow one of the access guides to configure a service that meets your access needs.

대안: 사전 등록된 키#

이 가이드는 등록 시크릿을 사용합니다. 등록 시크릿은 첫 번째 bot 참여 시 소비되는 일회용 공유 시크릿으로, bot이 공개 키를 Teleport에 자동으로 등록할 수 있게 합니다. 공유 시크릿을 사용하지 않으려면, bot의 키 쌍을 미리 생성하고 직접 Teleport에 공개 키를 알려주는 방법을 선택할 수도 있습니다.

공개 키를 생성하려면 bot 호스트에서 다음 명령을 실행합니다:

## 필요한 경우 bot의 저장소 디렉터리 생성
$ mkdir -p /var/lib/teleport/bot
$ tbot keypair create --storage /var/lib/teleport/bot --proxy-server=example.teleport.sh:443
2025-07-08T16:31:48.000-00:00 INFO [TBOT]      keypair has been written to storage storage:directory: /var/lib/teleport/bot tbot/keypair.go:135

Teleport에 키 쌍을 등록하려면 토큰의
`spec.bound_keypair.onboarding.initial_public_key`에 이 공개 키를 포함하세요:

	ssh-ed25519 <data>

콘솔에 기록된 SSH 스타일 공개 키를 기록해두세요. 다음 단계에서 이 값이 필요합니다.

프록시 서버 주소를 제공해야 하지만, 이는 구성된 서명 알고리즘을 결정하기 위해 클러스터에 ping을 보내는 데만 사용됩니다. 키 쌍이 생성되면, 공개 키가 콘솔에 출력됩니다.

다음으로, 로컬 머신에서 token-example.yaml이라는 파일을 생성합니다:

kind: token
version: v2
metadata:
  name: example
spec:
  roles: [Bot]
  join_method: bound_keypair
  bot_name: example
  bound_keypair:
    onboarding:
      initial_public_key: "ssh-ed25519 <data>"
    recovery:
      mode: standard
      limit: 1

bot이 생성한 SSH 스타일 공개 키를 initial_public_key 필드에 복사해야 합니다. 위와 같이 YAML이 유효하게 유지되도록 값을 따옴표로 감싸야 합니다.

tctl로 토큰을 생성합니다:

$ tctl create -f token-example.yaml

bot 머신으로 돌아가서, 원래 가이드와 같이 bot을 구성하지만 이번에는 registration_secret 필드 없이 구성합니다. 다음 내용으로 tbot.yaml을 생성합니다:

version: v2
proxy_server: example.teleport.sh:443
onboarding:
  join_method: bound_keypair
  token: example
storage:
  type: directory
  path: /var/lib/teleport/bot
# 출력은 접근 가이드 완료 중에 채워집니다.
outputs: []

원래 예시와 마찬가지로 다음을 교체합니다:

• example.teleport.sh:443을 Teleport Proxy 주소로.
• example을 이전 단계에서 생성한 토큰 이름으로 (example에서 변경한 경우).

storage.path는 위에서 tbot keypair create에 전달한 저장소 디렉터리와 동일한 경로를 가리켜야 합니다.

구성 파일이 생성되면 일반적으로 bot을 시작할 수 있습니다:

$ tbot start -c tbot.yaml

Bound Keypair 참여로 새 bot을 온보딩하는 방법에 대한 추가 정보는 온보딩 참조를 참조하세요.

다음 단계#

• 참여 방법과 사용 가능한 구성 옵션에 대한 자세한 내용은 Bound Keypair 참여 참조를 읽어보세요.
• tbot의 환경 구성을 완료하려면 접근 가이드를 따르세요.
• 사용 가능한 모든 구성 옵션을 탐색하려면 구성 참조를 읽어보세요.
• TELEPORT_ANONYMOUS_TELEMETRY에 대한 자세한 정보.