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

수행할 작업의 개요는 다음과 같습니다:

• 대상 리소스로 Linux 서버 또는 Kubernetes 클러스터를 선택합니다.
• 봇을 위한 역할을 생성하거나 기존 역할을 선택합니다.
• 대상 리소스에 접근할 수 있는 역할을 가진 봇을 Teleport에 생성합니다.
• 봇을 위한 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 클러스터
  • 사용할 수 있는 대상 리소스가 없다면 새 리소스를 등록하는 가이드를 따르십시오.

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

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단계. 봇 생성#

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

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

로컬 머신에서 다음 내용으로 bot.yaml 파일을 만듭니다:

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

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

tctl create를 사용하여 파일에서 봇을 생성합니다:

$ tctl create -f ./bot.yaml

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

사용자와 달리 봇은 사용자 이름과 비밀번호 또는 SSO를 사용하여 인증하지 않습니다. 대신, 조인이라는 프로세스를 통해 인증합니다. Teleport는 봇이 실행 중인 플랫폼에 대한 메타데이터(예: CI 파이프라인의 OIDC 엔드포인트 또는 AWS EC2 인스턴스의 가정된 역할)를 사용하여 프로세스의 아이덴티티를 증명하고, 인가된 봇만 클러스터에 조인할 수 있도록 합니다. 이는 봇이 단순한 공유 비밀이 아닌 검증된 아이덴티티를 가짐을 의미합니다.

Teleport는 봇이 실행 중인 플랫폼에 특화된 여러 가지 안전한 조인 방법을 지원합니다. GitHub Actions를 사용하므로 github 조인 방법을 사용합니다.

조인 토큰 정의에서 repository 필드를 GitHub Actions 워크플로를 실행할 GitHub 저장소와 일치하도록 편집하십시오. 봇이 해당 GitHub 조직 및 저장소에서 조인을 시도하면, Teleport는 이를 github-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 # 자체 호스팅 GitHub Enterprise에 사용
    # enterprise_slug: my-company # GitHub Enterprise Cloud 조직에 사용

다음을 확인하십시오:

• your-github-username/my-repo를 GitHub Actions 워크플로가 실행될 GitHub 저장소 이름으로 교체합니다.
• spec.bot_name 필드가 이전 단계에서 생성한 봇 이름과 일치해야 합니다.
• 적절한 경우 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의 구성 파일로, 봇이 인증하는 방법과 요청해야 할 아이덴티티 종류를 지정합니다.

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:
      # "id-token: write" 권한이 필요합니다. 그렇지 않으면 MWI가
      # 클러스터에 인증할 수 없습니다.
      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:
      # "id-token: write" 권한이 필요합니다. 그렇지 않으면 MWI가
      # 클러스터에 인증할 수 없습니다.
      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

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

요약#

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

다음 단계#

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