이 가이드에서는 Bound Keypair 정적 키를 사용하여 임의의 상태 비저장 환경에 머신 및 워크로드 아이덴티티의 에이전트인 tbot을 설치합니다. 이는 Teleport의 전용 참여 방법이 아직 지원되지 않는 공급자에서의 CI/CD 작업, 임시 베어메탈 노드, 또는 쓰기 가능한 영구 저장소가 없는 다른 환경일 수 있습니다.

Bound Keypair 참여는 시크릿 기반 참여 방법에 대한 더 유연한 대안이며, 정적 키는 일부 기본 보안 요구 사항을 완화하여 임의의 노드가 참여할 수 있도록 합니다.

작동 방식#

Bound Keypair 참여는 일반적으로 추가 신원 증명을 저장하기 위한 쓰기 가능한 클라이언트 측 저장소에 접근할 수 있다고 가정하지만, Bound Keypair 정적 키를 사용하면 이 요구 사항이 해제됩니다.

일반적으로 실제 Bound Keypair 키는 tbot 클라이언트가 내부적으로 관리하므로 필요에 따라 생성하고 교체할 수 있습니다. 정적 키를 사용하면 개인 키의 직접적인 소유권을 갖고 플랫폼 키스토어처럼 원하는 방식으로 저장할 수 있습니다. tbot 클라이언트는 자동으로 관리하는 대신 사용자의 정적 개인 키를 사용하도록 구성됩니다.

필수 조건#

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

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.

1단계/7단계. 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단계/7단계. 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 호스트에서 사용 가능해야 하는 개인 키
• Teleport 참여 토큰에 구성해야 하는 공개 키

tbot 클라이언트의 헬퍼를 사용하여 정적 키 쌍을 생성합니다. 이 단계는 어디서든 실행할 수 있으며 구성이 필요하지 않지만, 환경이나 시크릿 저장소에 따라 달라질 수 있는 bot이 키에 접근하는 방법을 결정해야 합니다:

1. 환경 변수를 통해, 시크릿을 환경 변수로 주입하는 공급자나 환경에 유용합니다.
2. bot 호스트에 전송하는 표준 파일을 통해.

이를 염두에 두고, 환경 변수를 통해 tbot에 키를 제공하려면 다음을 실행합니다:

$ tbot keypair create --proxy-server :443 --static

그렇지 않고 파일을 사용한다면 다음을 실행합니다:

$ tbot keypair create --proxy-server :443 --static --static-key-path ./path/to/key

--static-key-path 값을 원하는 대로 조정합니다. 이 명령을 bot 호스트에서 직접 실행하지 않은 경우, 다음 단계에서 bot 호스트로 전송할 준비를 해두세요.

어느 경우든, 명령이 키 쌍을 생성하고 일부 지시사항을 출력합니다. 예를 들어, 환경 변수 키를 사용할 때 다음과 같이 표시됩니다:

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

	

이 토큰 예시를 참조로 사용하세요:

	kind: token
	metadata:
	  name: example-token
	spec:
	  bot_name: example
	  bound_keypair:
	    onboarding:
	      initial_public_key: 
	    recovery:
	      limit: 0
	      mode: insecure
	  join_method: bound_keypair
	  roles:
	  - Bot
	version: v2

이 정적 키를 사용하도록 bot을 구성하려면 아래의 개인 키 값을 bot의 환경에 삽입하세요. 가능한 경우 플랫폼별 키스토어를 통해 삽입하는 것이 좋습니다:

	export TBOT_BOUND_KEYPAIR_STATIC_KEY="<...인코딩된 개인 키...>"

정적 토큰으로 참여한 bot은 키 쌍 교체를 지원하지 않으며,
토큰의 'rotate_after' 필드를 통해 서버 측에서 교체가 요청되면 참여할 수 없게 됩니다.
또한 위에 표시된 것처럼 'insecure' 복구 모드를 사용해야 합니다. 자세한 내용:

	https://goteleport.com/docs/reference/machine-workload-identity/machine-id/bound-keypair/concepts/#recovery

이 명령은 공개 키, 참여 토큰 예시, bot을 구성하는 데 필요한 개인 키를 출력합니다. 다음 단계까지 이 출력을 사용 가능한 상태로 유지하세요.

위 명령이 출력한 예시 토큰을 템플릿으로 사용하여, 다음 내용을 포함하는 token.yaml을 생성합니다:

kind: token
metadata:
  name: example-token
spec:
  bot_name: example
  bound_keypair:
  onboarding:
    initial_public_key:  name="public key"/>
  recovery:
    limit: 0
    mode: insecure
  join_method: bound_keypair
  roles:
  - Bot
version: v2

bot_name을 이전 단계에서 생성한 bot과 일치하도록 설정하고, 공개 키가 tbot keypair create ...가 출력한 값과 일치하는지 확인하세요.

준비가 되면 tctl을 사용하여 Teleport 클러스터에서 참여 토큰을 생성합니다:

$ tctl create -f token.yaml

4단계/7단계. 개인 키 저장#

개인 키를 생성했으므로 이제 작업에서 사용 가능하도록 저장해야 합니다. 이를 수행하는 방법은 공급자와 환경에 따라, 그리고 환경 변수나 파일을 통해 제공할지 여부에 따라 다릅니다.

파일로 bot 호스트에 키 저장#

생성한 개인 키 파일이 bot 호스트에서 사용 가능한지 확인하세요. 로컬 머신에서 생성한 경우, scp를 통해 복사하거나, Ansible을 통해 키를 프로비저닝하거나, 원하는 방법으로 bot 호스트에 전송하세요.

bot 호스트의 결과 파일이 tbot 프로세스를 실행하는 계정만 읽을 수 있도록 주의하세요.

환경 변수에 키 저장#

환경 변수를 사용하는 경우, 플랫폼과 환경에 따라 bot 호스트에 직접 저장하는 것보다 플랫폼별 키스토어에 키를 저장하는 것이 좋습니다. 이렇게 하면 bot 호스트가 시작될 때 환경 변수가 설정됩니다.

백엔드에 관계없이 다음과 같이 변수를 설정합니다:

• 이름: TBOT_BOUND_KEYPAIR_STATIC_KEY
• 값: tbot keypair create --static ...에서 출력된 base64 인코딩 값

이 값은 tbot keypair create ... --static --static-key-path /path/to/key를 사용했을 때 파일에 기록되는 것과 동일한 내용이지만, 환경 변수 값으로 사용하기 쉽도록 base64 인코딩되어 있습니다.

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

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

환경 변수 키 사용#

환경 변수를 통해 시크릿을 노출하는 경우, $TBOT_BOUND_KEYPAIR_STATIC_KEY 변수에서 사용 가능한지 확인하세요.

다음 내용으로 /etc/tbot.yaml을 생성합니다:

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

join_method 및 token을 지정하는 것 외에도 추가 구성이 필요하지 않습니다. 키는 참여 프로세스 중에 필요에 따라 환경에서 읽힙니다.

파일 키 사용#

키를 bot 환경에 복사하거나 사용 가능한지 확인하고, 다음을 /etc/tbot.yaml에 작성합니다:

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

static_private_key_path가 키가 사용 가능한 위치를 가리키도록 설정하고 파일을 저장합니다.

6단계/7단계. tbot이 Teleport에 인증할 수 있는지 확인#

생성한 tbot.yaml을 사용하여 tbot을 실행하고, 개인 키가 예상대로 사용 가능한지 확인합니다. 파일(이전에 구성한 경로에서)이나 $TBOT_BOUND_KEYPAIR_STATIC_KEY 환경 변수를 통해 사용 가능해야 합니다:

$ tbot start -c /etc/tbot.yaml --oneshot

모든 것이 올바르게 설정되었다면, tbot이 실행되고 Teleport에 인증하고 정상적으로 종료됩니다. 프로덕션에서는 더 오래 실행되는 작업에 대해 지속적으로 업데이트된 인증서를 제공하도록 tbot을 원할 경우 --oneshot 플래그를 제거할 수 있습니다. 그렇지 않으면 발행된 인증서는 결국 만료됩니다(기본적으로 1시간).

7단계/7단계. 서비스 구성#

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.

다음 단계#

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