tctl은 Teleport 클러스터 관리 CLI 도구입니다. 일반적으로는 로컬에 로그인한 사용자의 자격 증명을 사용하지만, Machine & Workload Identity에서 발급한 자격 증명을 사용하는 것도 가능합니다. 이를 통해 비대화형 환경(예: CI/CD)에 배포된 커스텀 자동화 워크플로의 일부로 tctl을 활용할 수 있습니다.

이 가이드에서는 tbot을 구성하여 tctl용 자격 증명을 생성한 다음, tctl을 사용하여 파일에 정의된 Teleport 역할을 배포합니다.

사전 요구 사항#

• 실행 중인 Teleport 클러스터. Teleport를 시작하려면 무료 체험판에 가입하거나 데모 환경을 구성하세요.

• tctl and tsh clients.

  Installing `tctl` and `tsh` clients

  1. Teleport 클러스터의 버전을 확인합니다. tctl and tsh clients는 Teleport 클러스터 버전보다 최대 한 개의 메이저 버전까지만 뒤처질 수 있습니다. Proxy Service의 /v1/webapi/find로 GET 요청을 보내고 JSON 쿼리 도구를 사용하여 클러스터 버전을 확인합니다. teleport.example.com:443를 Teleport Proxy Service의 웹 주소로 바꿉니다:

     $ TELEPORT_DOMAIN=teleport.example.com:443
     $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"
     

  2. 사용 중인 플랫폼에 대한 지침에 따라 tctl and tsh clients를 설치합니다:

Mac

     `tctl` and `tsh` clients가 포함된, 서명된 Teleport macOS .pkg 설치 프로그램을 다운로드합니다:
 
     ```code
     $ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg
     ```

     Finder에서 `pkg` 파일을 더블 클릭하여 설치를 시작합니다.
 
     

       Homebrew를 사용하여 Teleport를 설치하는 것은 지원되지 않습니다. Homebrew의
       Teleport 패키지는 Teleport에서 유지 관리하지 않으므로 신뢰성이나 보안을
       보장할 수 없습니다.
     

Windows - Powershell

     ```code
     $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip
     # Unzip the archive and move the `tctl` and `tsh` clients to your %PATH%
     # NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP.
     # Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\<username>) instead.
     ```
 
   

 
   

Linux

     Linux 설치판의 모든 Teleport 바이너리에는 `tctl` and `tsh` clients가 포함되어 있습니다.  RPM/DEB
     패키지 및 i386/ARM/ARM64용 다운로드를 포함한 더 많은 옵션은
     [설치 페이지](../installation/installation.mdx)를 참조하세요.
 
     ```code
     $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ cd teleport
     $ sudo ./install
     # Teleport binaries have been copied to /usr/local/bin
     ```
   

 

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

• tctl을 사용할 머신에 tbot이 이미 설치되어 구성되어 있어야 합니다. 자세한 내용은 배포 가이드를 참조하세요.

1/3단계. RBAC 구성#

먼저, tbot이 생성한 자격 증명으로 Teleport 설정을 수정할 수 있도록 Teleport를 구성해야 합니다. 이는 필요한 권한을 부여하는 역할을 생성한 다음 이 역할을 Bot에 할당하는 방식으로 수행합니다.

공격의 피해 범위를 제한하기 위해 가능한 한 적은 권한만 부여하는 것이 중요합니다. 따라서 이 예시에서는 역할을 생성하고 업데이트하는 권한만 부여합니다.

다음 내용으로 role.yaml 파일을 만듭니다:

kind: role
version: v6
metadata:
  name: example-role
spec:
  allow:
    rules:
    - resources:
      # tctl로 관리할 리소스의 이름을 지정합니다.
      # 이 가이드에서는 역할만 관리합니다.
      - role
      verbs:
      - create
      - read
      - update
      - delete
      - list

example-role을 사용 사례에 맞는 설명적인 이름으로 바꾸세요.

tctl create -f ./role.yaml을 사용하여 역할을 생성합니다.

이제 tctl bots update를 사용하여 Bot에 역할을 추가합니다. example은 배포 가이드에서 생성한 Bot의 이름으로, example-role은 방금 생성한 역할의 이름으로 바꾸세요:

$ tctl bots update example --add-roles example-role

2/3단계. tbot 출력 서비스 구성#

이제 tctl에 필요한 자격 증명을 생성할 서비스로 tbot을 구성해야 합니다. tctl은 Teleport API에 접근하므로 사용할 올바른 서비스 유형은 identity입니다.

이 가이드에서는 directory 대상을 사용합니다. 이는 자격 증명을 디스크의 지정된 디렉터리에 씁니다. 이 디렉터리는 tbot을 실행하는 Linux 사용자가 쓸 수 있어야 하며, tctl을 실행하는 Linux 사용자가 읽을 수 있어야 합니다.

tbot 구성을 수정하여 identity 출력을 추가합니다:

services:
- type: identity
  destination:
    type: directory
    # 이 가이드에서는 /opt/machine-id를 대상 디렉터리로 사용합니다.
    # 원하는 대로 변경할 수 있습니다. 여러 출력 서비스는 동일한 대상을 공유할 수 없습니다.
    path: /opt/machine-id

이제 /opt/machine-id 아래에 identity 파일이 표시되어야 합니다. 여기에는 tctl이 Teleport Auth 서비스에 인증하는 데 필요한 개인 키와 서명된 인증서가 포함되어 있습니다.

3/3단계. identity 출력 서비스와 함께 tctl 사용하기#

예시로, tctl을 사용하여 Teleport 역할을 정의하는 YAML 파일 디렉터리를 적용합니다. 이 파일들이 버전 관리 시스템(예: git)에 저장되어 있고 변경 시 이 작업이 실행된다면, 이는 GitOps 방식으로 Teleport 역할을 관리하는 토대가 될 수 있습니다.

이 예시 역할은 여러분의 Teleport 클러스터 맥락에서는 유용하지 않으므로, 이 가이드를 완료한 후에는 수정해야 합니다.

roles/라는 디렉터리를 만들고 그 안에 example.yaml을 생성합니다:

kind: role
version: v6
metadata:
  name: tctl-test
spec:
  # 예시 역할이므로 이 역할은 아무 작업도 수행하지 않습니다.
  allow: {}

tctl이 identity 파일을 사용하도록 구성하려면 -i 플래그를 사용합니다. identity 파일에는 Teleport의 주소가 지정되어 있지 않으므로, Teleport 프록시 또는 Teleport Auth 서버의 주소와 함께 --auth-server도 지정해야 합니다.

tctl을 실행하되, example.teleport.sh:443을 여러분의 Teleport 프록시 또는 Auth 서비스 주소로, /opt/machine-id/identity를 이를 수정한 경우 생성된 identity 파일의 경로로 바꾸세요:

$ tctl --auth-server example.teleport.sh:443 -i /opt/machine-id/identity create -f roles/*.yaml

Teleport 클러스터를 확인하여 역할이 생성되었는지 확인합니다.

$ tctl get role/tctl-test

다음 단계#

• tctl 참조를 살펴보고 tctl이 수행할 수 있는 모든 작업을 확인하세요.
• 구성 참조를 읽고 사용 가능한 모든 tbot 구성 옵션을 살펴보세요.