이 가이드에서는 Bound Keypair 정적 키를 사용하여 임의의 상태 비저장 환경에 Machine & Workload Identity의 에이전트인 tbot을 설치합니다. 이는 Teleport의 전용 참여 방법 중 하나가 아직 지원되지 않는 공급자에서 실행되는 CI/CD 작업, 임시 베어메탈 노드, 또는 쓰기 가능한 영구 저장소가 없는 그 밖의 환경일 수 있습니다.

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

작동 방식#

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

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

필수 조건#

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

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

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

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

먼저, Machine & Workload Identity를 사용하려는 호스트에 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단계/7단계. 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단계/7단계. 키 쌍 및 참여 토큰 생성#

다음으로, 다음으로 구성된 키 쌍을 생성해야 합니다:

• 런타임에 bot 호스트에서 사용 가능해야 하는 개인 키
• Teleport 참여 토큰에 구성해야 하는 공개 키

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

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

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

$ tbot keypair create --proxy-server example.teleport.sh:443 --static

그렇지 않고 파일을 사용한다면 다음을 실행하세요:

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

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

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

To register the keypair with Teleport, include this public key in the token's
'spec.bound_keypair.onboarding.initial_public_key' field:

	public key

Refer to this token example as a reference:

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

Configure your bot to use this static key by inserting the following private key
value into the bot's environment, ideally via a platform-specific keystore if
available:

	export TBOT_BOUND_KEYPAIR_STATIC_KEY="<...encoded private key...>"

Note that bots joined with static tokens do not support keypair rotation and
will be unable to join if a rotation is requested server-side via the token's
'rotate_after' field. Additionally, 'insecure' recovery mode must be used, as
shown above. Read more at:

	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: 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: example.teleport.sh:443
onboarding:
  join_method: bound_keypair
  token: example-token
storage:
  type: directory
  path: /var/lib/teleport/bot
# outputs will be filled in during the completion of an access guide.
outputs: []

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

파일 키 사용#

키를 bot 환경에 복사하거나 그 밖의 방법으로 사용 가능하도록 한 다음, 다음 내용을 /etc/tbot.yaml에 작성합니다:

version: v2
proxy_server: 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 will be filled in during the completion of an access guide.
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단계. 출력 구성#

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

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

다음 단계#

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