Teleport 머신 및 워크로드 아이덴티티(MWI)는 여러 플랫폼과 리소스 유형에 걸쳐 비인간 아이덴티티(Non-Human Identities)에 대한 안전한 접근을 제공하며, 인프라스트럭처-코드 워크플로부터 AI 에이전트 운영까지 모든 것을 지원합니다. 이 가이드는 널리 사용되는 구현 방식인 CI/CD 파이프라인을 통해 배포 대상에서 명령을 실행하는 것에 초점을 맞춥니다. 특정 사용 사례가 다르더라도, 이 가이드는 기본적인 MWI 설정 프로세스를 다루며, 이후 도구별 지침을 위한 전용 사용 사례 페이지를 참조할 수 있습니다.

이 가이드에서는 다음을 수행합니다:

• 대상 리소스로 Linux 서버 또는 Kubernetes 클러스터를 선택합니다.
• Bot을 위한 역할을 생성하거나 기존 역할을 선택합니다.
• 대상 리소스에 접근할 수 있는 역할을 가진 Bot을 Teleport에서 생성합니다.
• Bot을 위한 GitHub 조인 토큰을 생성합니다.
• tbot 바이너리를 사용하여 인증하고 명령을 실행하는 GitHub Actions 워크플로를 설정합니다.

이 가이드는 개발 및 학습 목적으로 MWI를 구성하는 방법을 다룹니다. 프로덕션 준비가 된 MWI 구성에 대해서는 Machine ID 배포하기 가이드를 참조하세요.

사전 요구사항#

이 시작 가이드에서는 GitHub Actions 워크플로에서 Linux 서버 또는 Kubernetes 클러스터로 명령을 전달하도록 MWI를 구성합니다. 이 가이드는 Linux 서버 또는 Kubernetes 클러스터가 이미 Teleport에 등록되어 있다고 가정합니다. 아직 등록하지 않았다면 리소스 등록 가이드를 참조하세요.

• GitHub Actions 워크플로를 생성할 권한이 있는 GitHub 리포지터리.

  GitHub Enterprise를 사용하고 계신가요?

  클라우드 또는 자체 호스팅 GitHub Enterprise 리포지터리를 사용할 경우 추가 구성이 필요합니다. 가능하다면 이 가이드에서는 개인 리포지터리를 사용하는 것을 권장합니다.

  GitHub Enterprise를 사용해야 하는 경우 다음을 확인하세요:

  • 클라우드
    • 조인 토큰에서 github 아래에 enterprise_slug 필드를 조직 이름과 같은 엔터프라이즈 슬러그 이름으로 설정합니다.
  • 자체 호스팅
    • Teleport Auth Service가 GitHub Enterprise 인스턴스에 도달할 수 있어야 합니다.
    • 조인 토큰에서 github 아래에 enterprise_server_host 필드를 GitHub Enterprise 인스턴스의 호스트 이름으로 설정합니다.

  
  조인 토큰 필드는 예제 조인 토큰 파일에 주석 처리된 상태로 제공됩니다.

• Teleport에 등록된 대상 리소스, 다음 중 하나:

  • Linux 서버
  • Kubernetes 클러스터
  • 사용할 수 있는 대상 리소스가 없다면 새 리소스를 등록하는 가이드 중 하나를 따르세요.

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

1단계/5. 대상 리소스 선택#

먼저, GitHub Actions 워크플로가 머신 및 워크로드 아이덴티티를 사용하여 접근할 대상 리소스를 선택합니다.

GitHub Actions 워크플로에 리소스에 대한 접근 권한을 부여하려면, 역할을 생성하고 그 역할 안에서 접근을 허용할 리소스의 라벨을 지정합니다. 라벨은 Teleport에서 리소스를 식별하고 분류하는 데 도움이 되는 키-값 쌍입니다.

$ tctl nodes ls --format=text

Host    UUID                                 Public Address Labels                              Version
------- ------------------------------------ -------------- ----------------------------------- -------
target1 8a50c8aa-c45f-403c-95ff-83f50561d64c                env=mwi-demo,hostname=ip-10-0-0-200 18.1.5

$ tctl kube ls --format=text

Cluster  Labels                        Version
-------- ----------------------------- -------
staging  env=mwi-demo,region=us-west-2  18.1.5

이 예제에서는 env 라벨과 값 mwi-demo를 사용하여 GitHub Actions 워크플로가 접근할 수 있는 대상을 제어합니다.

2단계/5. 역할 선택 또는 생성#

이제 대상 리소스에 대한 접근을 허용하는 역할을 생성합니다. 대상 리소스에 대한 접근을 이미 허용하는 기존 역할이 있다면, 이 단계를 건너뛰고 그 역할을 대신 사용해도 됩니다.

kind: role
version: v7
metadata:
  name: github-bot
spec:
  allow:
    node_labels:
      env: mwi-demo
    logins:
      - ubuntu

$ tctl create -f ./role.yaml

kind: role
version: v7
metadata:
  name: github-bot
spec:
  allow:
    kubernetes_labels:
      env: mwi-demo
    kubernetes_groups:
      - system:masters
    kubernetes_resources:
      - kind: '*'
        name: '*'
        namespace: default
        verbs:
          - '*'

$ tctl create -f role.yaml

3단계/5. Bot 생성#

Teleport에서 Bot 사용자는 머신 또는 AI 에이전트의 아이덴티티를 나타냅니다. SSO 사용자 및 로컬 사용자와 마찬가지로 Bot에도 접근을 관리하기 위한 역할이 할당됩니다.

이제 GitHub Actions 워크플로를 나타내는 Bot을 생성합니다.

로컬 머신에서 다음 내용으로 bot.yaml이라는 파일을 생성합니다:

kind: bot
version: v1
metadata:
  name: github-bot
spec:
  roles:
    - github-bot

spec.roles 필드 안의 값이 방금 생성한 역할의 이름과 일치하는지 확인하세요.

tctl create를 사용하여 파일로부터 Bot을 생성합니다:

$ tctl create -f ./bot.yaml

4단계/5 조인 토큰 생성#

사용자와 달리, Bot은 사용자 이름과 비밀번호 또는 SSO를 사용하여 인증하지 않습니다. 대신 조인(joining)이라는 프로세스를 통해 인증합니다. Teleport는 CI 파이프라인의 OIDC 엔드포인트나 AWS EC2 인스턴스의 Assumed Role과 같이 Bot이 실행되는 플랫폼에 대한 메타데이터를 사용하여 프로세스의 아이덴티티를 증명하며, 이를 통해 승인된 Bot만 클러스터에 조인할 수 있도록 합니다. 즉, Bot은 단순한 공유 비밀이 아니라 검증된 아이덴티티를 갖게 됩니다.

Teleport는 Bot이 실행되는 플랫폼에 따라 다양한 안전한 조인 방법을 지원합니다. 여기서는 GitHub Actions를 사용하므로 github 조인 방법을 사용합니다.

조인 토큰 정의에서 repository 필드를 GitHub Actions 워크플로를 실행할 GitHub 리포지터리와 일치하도록 편집하세요. Bot이 해당 GitHub 조직 및 리포지터리에서 조인을 시도하면, Teleport는 이를 github-bot으로 식별하고 올바른 역할을 할당합니다. Bot이 다른 리포지터리에서 조인을 시도하면 거부됩니다.

로컬 머신에서 다음 내용으로 join_token.yaml이라는 파일을 생성합니다:

kind: token
version: v2
metadata:
  name: github-bot
spec:
  join_method: github
  roles:
  - Bot
  bot_name: github-bot
  github:
    allow:
    - repository: "your-github-username/my-repo"
    # enterprise_server_host: github.my-company.com # use for self-hosted GitHub Enterprise
    # enterprise_slug: my-company # use for GitHub Enterprise Cloud organization

다음을 확인하세요:

• your-github-username/my-repo를 GitHub Actions 워크플로가 실행될 GitHub 리포지터리 이름으로 교체합니다.
• spec.bot_name 필드가 이전 단계에서 생성한 Bot의 이름과 일치합니다.
• 필요한 경우 enterprise_server_host 또는 enterprise_slug를 설정했습니다.

tctl create를 사용하여 파일로부터 조인 토큰을 생성합니다:

$ tctl create -f join_token.yaml

5단계/5 GitHub Actions에서 리소스에 접근하기#

편의를 위해 게시된 여러 Actions가 있지만, 이 가이드에서는 이해를 돕기 위해 명시적으로 살펴봅니다.

GitHub 리포지터리 내에서 두 가지 다른 파일을 생성합니다:

• .github/workflows/teleport.yaml: GitHub Actions 워크플로의 구성으로, 어떤 트리거에 대해 어떤 작업이 수행되어야 하는지를 지정합니다.
• tbot.yaml: 머신 및 워크로드 아이덴티티 에이전트인 tbot의 구성 파일로, Bot이 어떻게 인증해야 하는지와 어떤 종류의 아이덴티티를 요청해야 하는지를 지정합니다.

version: v2
proxy_server: example.teleport.sh:443
onboarding:
  join_method: github
  token: github-bot
certificate_ttl: 5m
storage:
  type: memory
services:
  - type: identity
    destination:
      type: directory
      path: ./ssh_out

on:
  workflow_dispatch:

jobs:
  check_resource_usage:
    permissions:
      # The "id-token: write" permission is required, or MWI will not be
      # able to authenticate with the cluster.
      id-token: write
      contents: read
    name: Check resource usage on server
    runs-on: ubuntu-latest
    steps:
    - name: Checkout repository
      uses: actions/checkout@v3
    - name: Fetch Teleport binaries
      uses: teleport-actions/setup@v1
      with:
        proxy: example.teleport.sh:443
        version: auto
    - name: Export ssh config
      run: tbot start --oneshot -c ./tbot.yaml
    - name: Run mpstat
      run: |
        ssh -F ./ssh_out/ssh_config ubuntu@myinstance.example.teleport.sh mpstat

version: v2
proxy_server: example.teleport.sh:443
onboarding:
  join_method: github
  token: github-bot
certificate_ttl: 5m
storage:
  type: memory
services:
  - type: kubernetes/v2
    selectors:
      - name: my-kubernetes-cluster
    destination:
      type: directory
      path: ./k8s_out

on:
  workflow_dispatch:

jobs:
  list_pods:
    permissions:
      # The "id-token: write" permission is required, or MWI will not be
      # able to authenticate with the cluster.
      id-token: write
      contents: read
    name: List pods in default namespace
    runs-on: ubuntu-latest
    steps:
    - name: Checkout repository
      uses: actions/checkout@v3
    - name: Fetch Teleport binaries
      uses: teleport-actions/setup@v1
      with:
        proxy: example.teleport.sh:443
        version: auto
    - name: Export kubectl config
      run: tbot start --oneshot -c ./tbot.yaml
    - name: Run kubectl get pods
      run: |
        kubectl --kubeconfig=./k8s_out/kubeconfig.yaml get pods -n default

워크플로 실행#

생성한 워크플로를 실행합니다:

$ gh workflow run teleport.yaml --ref main

워크플로가 완료되면 작업이 성공적으로 완료된 것을 확인할 수 있으며, 로그에서 명령의 출력을 볼 수 있습니다.

요약#

이제 여러분은 장기 자격 증명을 배포하지 않고도 Teleport 프록시를 통해 안전하게 리소스에 접근할 수 있는 GitHub Actions 워크플로를 성공적으로 설정했으며, 이를 통해 개발 팀의 프로세스가 더 안전하고 효율적이게 되었습니다.

다음 단계#

• 플랫폼에 맞게 프로덕션 준비가 된 방식으로 tbot을 구성하는 방법을 알아보려면 배포 가이드를 확인하세요.
• SSH 및 Kubernetes 외의 다른 사용 사례에 맞게 tbot을 구성하는 방법을 알아보려면 접근 가이드를 확인하세요.
• 사용 가능한 모든 구성 옵션을 살펴보려면 구성 참조를 읽어보세요.
• Teleport 프록시로 보호할 수 없는 클라우드 API와 같은 리소스에 대해서도 워크로드 아이덴티티가 동일한 기능을 제공하는 방법을 알아보세요.