이 가이드는 Google Cloud Platform GCE 인스턴스에 머신 및 워크로드 아이덴티티 에이전트 tbot을 배포하고 Teleport 클러스터에 연결하는 방법을 설명합니다.

작동 방식#

GCP에서 가상 머신에는 서비스 계정을 할당할 수 있습니다. 그러면 이 머신은 GCP에서 서명된 JSON 웹 토큰을 요청할 수 있어 제3자가 GCP 공개 키를 사용하여 서비스 계정을 포함한 해당 머신에 대한 정보를 검증할 수 있습니다. Teleport gcp 조인 방법은 tbot이 이 서비스 계정 JWT를 사용하여 Teleport Auth Service에 아이덴티티를 증명하고 장기 시크릿 없이 Teleport 클러스터에 조인하도록 지시합니다.

이 페이지의 가이드는 GCP 가상 머신에 tbot을 배포하는 것에 명시적으로 초점을 맞추지만, Google Kubernetes Engine에서 실행 중인 워크로드와 함께 gcp 조인 방법을 사용하는 것도 가능합니다. 이렇게 하려면 클러스터와 tbot 파드가 사용할 Kubernetes 서비스 계정에 대해 GCP 워크로드 아이덴티티를 설정해야 합니다. Kubernetes에서 워크로드로 tbot을 배포하는 추가 지침은 Kubernetes 플랫폼 가이드를 참조하세요.

사전 조건#

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

• GCP 기본 컴퓨팅 서비스 계정이 아닌 Teleport 클러스터에 접근을 허용하려는 GCP 서비스 계정.
• GCP 서비스 계정으로 설정된 tbot을 설치할 GCP Compute Engine VM.

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

이 단계는 GCP VM에서 완료합니다.

먼저 머신 및 워크로드 아이덴티티를 사용할 VM에 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단계. 봇 만들기#

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

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-token.yaml을 만듭니다:

kind: token
version: v2
metadata:
  # name은 이 토큰을 사용하는 `tbot`에서 지정됩니다.
  name: example-bot
spec:
  roles: [Bot]
  # bot_name은 이 가이드에서 이전에 만든 봇의 이름과 일치해야 합니다.
  bot_name: example
  join_method: gcp
  gcp:
    # allow는 Auth Service가 `tbot`의 조인 허용 여부를 결정하는 규칙을 지정합니다.
    allow:
    - project_ids:
        - my-project-123456
      service_accounts:
        # GCP 서비스 계정의 전체 "이름"이어야 합니다.
        # 기본 컴퓨팅 서비스 계정은 지원되지 않습니다.
        - my-service-account@my-project-123456.iam.gserviceaccount.com

교체:

• my-project-123456을 GCP 프로젝트 ID로.
• example을 두 번째 단계에서 만든 봇의 이름으로.
• my-service-account@my-project-123456.iam.gserviceaccount.com을 이전 단계에서 설정한 서비스 계정의 이메일로. 기본 컴퓨팅 서비스 계정은 지원되지 않습니다.

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

$ tctl create -f bot-token.yaml

4단계/5단계. tbot 설정#

이 단계는 GCP VM에서 완료합니다.

다음으로 tbot을 설정하는 파일을 만듭니다. 이 예시에서는 identity 서비스를 사용하도록 tbot을 설정합니다. 이렇게 하면 봇으로 Teleport 클러스터에 인증하기 위해 tsh 또는 tctl이 사용할 수 있는 단기 인증서 집합이 생성됩니다.

/etc/tbot.yaml을 만듭니다:

version: v2
proxy_server: example.teleport.sh:443
onboarding:
  join_method: gcp
  token: example-bot
storage:
  type: memory
# services는 접근 가이드를 완료하는 동안 채워집니다.
services:
- type: identity
  destination:
    type: directory
    path: /opt/machine-id

교체:

• example.teleport.sh:443을 Teleport Proxy 또는 Auth Service의 주소로. Teleport Proxy의 주소를 사용하는 것이 좋습니다.
• example-bot을 두 번째 단계에서 만든 토큰 이름으로.
• /opt/machine-id를 tbot이 단기 자격 증명을 기록할 디렉터리 경로로. tbot을 실행하는 사용자가 이 디렉터리를 만들 적절한 권한이 있는지 확인하세요.

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단계. tbot 설정 테스트#

tbot은 이제 /opt/machine-id 내에 단기 자격 증명을 생성하고 있습니다. 올바르게 작동하는지 확인하기 위해 tsh를 사용하여 이 자격 증명을 테스트합니다.

tbot을 배포한 호스트에서 다음을 실행하여 --proxy를 Teleport Proxy Service의 주소로, -i를 설정된 디렉터리 내의 identity 파일 경로로 교체합니다:

$ tsh --proxy example.teleport.sh:443 -i /opt/machine-id/identity status                                                                                                                                                                                                                                         127 ↵
> Profile URL:        https://example.teleport.sh:443
Logged in as:       bot-example
Cluster:            example.teleport.sh
Roles:              access
Logins:             support, ubuntu
Kubernetes:         disabled
Valid until:        2025-11-12 14:08:34 +0000 GMT [valid for 58m]
Extensions:         bot-instance-id@goteleport.com, bot-name@goteleport.com, disallow-reissue, impersonator, login-ip, permit-agent-forwarding, permit-port-forwarding, permit-pty, private-key-policy

이제 플랫폼에 대한 기본 tbot 배포를 준비하고 tsh 및 tctl과 함께 사용할 수 있는 간단한 출력을 생성할 수 있는지 확인했습니다. 사용 사례에 맞게 tbot을 설정하는 방법에 대한 지침은 접근 가이드 중 하나를 따르고 이 가이드에서 설정한 예시 identity 서비스를 교체하세요.

다음 단계#

• 접근 가이드를 따라 환경에 맞게 tbot을 마저 설정합니다.
• 사용 가능한 모든 설정 옵션을 확인하려면 설정 레퍼런스를 읽으세요.
• TELEPORT_ANONYMOUS_TELEMETRY에 대한 자세한 정보.