이 가이드에서는 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 클라이언트.

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

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

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

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

먼저, 머신 및 워크로드 아이덴티티를 사용하려는 호스트에 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단계/4단계. 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단계/4단계. 참여 토큰 생성#

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

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

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

kind: token
version: v2
metadata:
  # This name will be used in tbot's `onboarding.token` field.
  name: example
spec:
  roles: [Bot]
  # bot_name should match the name of the bot created earlier in this guide.
  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단계/4단계. tbot 구성#

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

저장소 디렉터리 준비#

봇 데이터 디렉터리를 생성하고 tbot이 실행될 Linux 사용자(예제에서는 teleport)에게 해당 디렉터리에 접근할 권한을 부여하십시오.

# 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 will be filled in during the completion of an access guide.
services: []

다음을 교체합니다:

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

이제 tbot을 데몬으로 실행할지 아니면 원샷(one-shot) 모드로 실행할지 결정해야 합니다.

데몬 모드에서 tbot은 지속적으로 실행되며, 구성된 출력에 대한 단기 자격 증명을 일정한 간격으로 갱신합니다. 이는 tbot을 백그라운드에서 실행하기 위해 서비스 관리자(예: systemd)와 함께 사용하는 경우가 많습니다. 이것이 tbot의 기본 동작입니다.

원샷 모드에서 tbot은 단기 자격 증명을 생성한 후 종료합니다. 이는 (CI/CD와 같이) tbot을 스크립팅과 결합할 때 유용하며, 후속 단계가 tbot의 성공 여부에 의존할 수 있도록 합니다. 자격 증명은 갱신되지 않으면 만료되므로, 인증서의 TTL이 CI/CD 작업 시간을 충분히 커버할 만큼 긴지 확인하는 것이 중요합니다.

tbot을 데몬으로 구성하기#

기본적으로 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을 원샷 모드로 구성하기#

tbot을 원샷 모드로 사용하려면 /etc/tbot.yaml을 수정하여 oneshot: true를 추가하십시오:

version: v2
oneshot: true
auth_server: ...

이제 tbot 구성을 테스트해야 합니다. 시작되면 상태 0으로 종료되기 전에 여러 개의 로그 메시지가 출력됩니다:

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

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

다음 단계: 출력 구성#

이제 tbot의 기본 구성을 준비했습니다. 이 시점에서 tbot은 Teleport 클러스터에 자신을 식별하고 자체 자격 증명을 갱신하지만 다른 애플리케이션이 사용할 자격 증명은 출력하지 않습니다.

액세스 요구 사항을 충족하는 서비스를 구성하려면 액세스 가이드 중 하나를 따르십시오.

대안: 사전 등록된 키#

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

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

## If needed, create the bot's storage directory
$ 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

To register the keypair with Teleport, include this public key in the token's
`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 will be filled in during the completion of an access guide.
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에 대한 자세한 정보.