GitHub Actions는 더 넓은 GitHub 생태계의 일부로 작동하는 인기 있는 CI/CD 플랫폼입니다. Teleport 머신 및 워크로드 아이덴티티를 사용하면 GitHub Actions가 장기 자격 증명 없이 Teleport로 보호된 리소스와 안전하게 상호 작용할 수 있습니다.

Teleport는 GitHub-호스팅 및 자체 호스팅 GitHub Actions 러너와 GitHub Enterprise Server에서 안전한 조인을 지원합니다.

가이드는 GitHub Actions 워크플로를 Teleport에 연결하고 등록된 리소스에 접근하는 데 필요한 권한을 부여하는 과정을 안내합니다.

Web UI에서 가이드를 찾으세요;<br />
**Add New** > **Integration** > "**GitHub Actions**" 검색

사전 조건#

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

• 사용자에게 토큰 리소스를 만들 수 있는 권한이 있어야 합니다.
• GitHub Actions가 활성화된 GitHub 저장소. 이 가이드에서는 예시로 gravitational/example 저장소를 사용하지만, 이 값은 자신의 고유한 저장소로 교체해야 합니다.

1단계/3단계. 봇 만들기#

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

2단계/3단계. GitHub Actions용 조인 토큰 만들기#

GitHub Actions 워크플로가 Teleport 클러스터에 인증할 수 있도록 하려면 먼저 조인 토큰을 만들어야 합니다. 이 토큰은 Auth Service가 봇 또는 노드의 조인을 허용할지 여부를 결정하는 기준을 설정합니다.

이 예시에서는 특정 GitHub 저장소 내의 모든 GitHub Actions 실행에 접근을 허용하는 조인 토큰을 만듭니다. 프로덕션에서는 CI가 특정 브랜치에 대해 실행될 때만 접근이 가능하도록 이 규칙을 더 제한할 수 있습니다. 조인 토큰 레퍼런스 페이지에서 사용 가능한 규칙의 전체 목록을 확인할 수 있습니다.

bot-token.yaml 파일을 만듭니다:

kind: token
version: v2
metadata:
  name: example-bot
spec:
  # Bot 역할은 이 토큰이 노드 조인이 아닌 봇 사용자에게 접근을 허용함을 나타냅니다.
  # 이 역할은 Teleport에 내장되어 있습니다.
  roles: [Bot]
  join_method: github
  # bot_name은 이 토큰이 접근을 허용할 봇 사용자를 나타냅니다.
  # 이전 단계에서 만든 봇의 이름과 일치해야 합니다.
  bot_name: example
  github:
    # allow는 어떤 GitHub Actions 실행이 접근을 허용받는지 제어하는 규칙을 지정합니다.
    # allow 규칙과 일치하지 않는 것은 거부됩니다.
    allow:
    # repository는 저장소 소유자의 이름을 포함해야 합니다.
    - repository: gravitational/example

gravitational/example을 tbot이 실행될 저장소 이름으로 교체합니다. 봇과 토큰의 이름을 사용 사례를 더 잘 설명하는 이름으로 변경할 수도 있습니다.

spec:
  github:
    enterprise_server_host: ghes.example.com

spec:
  github:
    enterprise_slug: my-enterprise

리소스 파일이 작성되면 tctl로 토큰을 만듭니다:

$ tctl create -f bot-token.yaml

다음 명령으로 토큰 example-bot이 만들어졌는지 확인합니다:

$ tctl tokens ls
Token       Type Labels Expiry Time (UTC)
----------- ---- ------ ----------------------------------------------
example-bot Bot         01 Jan 00 00:00 UTC (2562047h47m16.854775807s)

3단계/3단계. GitHub Actions 워크플로 설정#

봇이 성공적으로 만들어지면 이 봇으로 인증하고 tbot이 생성한 자격 증명을 사용하도록 GitHub Actions 워크플로를 설정해야 합니다. 이를 돕기 위해 Teleport는 워크플로 내에서 사용할 수 있는 여러 사용하기 쉬운 GitHub Actions를 게시합니다.

Teleport GitHub Actions 중 하나를 사용하는 대신 tbot을 수동으로 설정하는 것도 가능합니다. 이는 더 많은 설정이 필요하지만 tbot을 정밀하게 제어할 수 있으며 액션으로는 불가능한 구현을 허용합니다.

다음은 사용 가능한 GitHub Actions 중 두 가지를 보여주는 예시와 GitHub Actions에서 사용하기 위해 tbot을 수동으로 설정하는 방법을 보여줍니다.

예시: teleport-actions/auth#

teleport-actions/auth 액션은 SSH 및 Teleport 클러스터에 대한 관리 작업에 사용할 수 있는 다목적 아이덴티티 출력을 생성합니다. 이 액션에 의해 환경 변수가 설정되며, 이를 통해 tsh 및 tctl이 이 아이덴티티를 사용하도록 자동으로 설정됩니다.

가이드는 GitHub Actions 워크플로를 Teleport에 연결하고 등록된 SSH 노드에 접근하는 데 필요한 권한을 부여하는 과정을 안내합니다.

Web UI에서 가이드를 찾으세요:<br />
**Add New** > **Integration** > **MWI: GitHub Actions + SSH**

이 예시는 다음에 자격 증명을 사용하는 방법을 보여줍니다:

• tsh를 사용하여 사용 가능한 SSH 노드 나열
• tctl을 사용하여 사용 가능한 SSH 노드 나열
• tsh를 사용하여 SSH 노드에 연결
• OpenSSH의 ssh를 사용하여 SSH 노드에 연결

먼저 봇에 할당한 역할을 조정하여 SSH 접근을 허용해야 합니다. 이 예시는 모든 노드의 root에 접근을 허용합니다. 프로덕션 설정에서는 봇이 접근해야 하는 노드로만 제한하는 것이 좋습니다.

1. 다음 명령을 실행하여 텍스트 편집기에서 example-bot 역할을 엽니다:

$ tctl edit role/example-bot

1. 역할에 다음이 포함되어 있는지 확인합니다:

   spec:
     allow:
       # Linux 사용자 'root' 로그인 허용.
       logins: ['root']
       # 모든 노드에 연결 허용. 이 레이블을 봇이 접근해야 하는
       # 노드만 일치하도록 조정하세요.
       node_labels:
         '*': '*'
   

이 권한이 부여되면 GitHub Actions 워크플로를 만들 수 있습니다. .github/workflows/example.yaml을 만듭니다:

# 시작하는 데 도움이 되는 기본 워크플로입니다.
# "main" 브랜치에 푸시가 발생할 때마다 다음 작업을 수행합니다.
on:
  push:
    branches:
    - main
jobs:
  demo:
    permissions:
      # "id-token: write" 권한이 필요하지 않으면 tbot이 클러스터에
      # 인증할 수 없습니다.
      id-token: write
      contents: read
    # 워크플로의 이름과 필요한 단계를 수행하는 데 사용할 Linux 배포판.
    name: example
    runs-on: ubuntu-latest
    steps:
    - name: Checkout repository
      uses: actions/checkout@v3
    - name: Fetch Teleport binaries
      uses: teleport-actions/setup@v1
      with:
        version: auto
        # Teleport Proxy Service의 주소로 교체하세요.
        proxy: example.teleport.sh:443
    - name: Fetch credentials using 머신 및 워크로드 아이덴티티
      id: auth
      uses: teleport-actions/auth@v2
      with:
        # Teleport Proxy Service의 주소로 교체하세요.
        proxy: example.teleport.sh:443
        # 1단계에서 만든 조인 토큰 리소스의 이름을 사용하세요.
        token: example-bot
        # 생성된 자격 증명의 유효 기간을 지정합니다.
        # 선택 사항이며 기본값은 "1h"입니다.
        certificate-ttl: 1h
        # 익명 사용 텔레메트리 제출을 활성화합니다.
        # 이는 `tbot`의 미래 개발을 형성하는 데 도움이 됩니다.
        # 이것을 생략하면 비활성화할 수 있습니다.
        anonymous-telemetry: 1
    - name: List nodes (tsh)
      # 이 경우 Machine ID 자격 증명을 사용하여 원격 SSH 노드를
      # 나열하기 위해 "tsh ls"를 실행합니다.
      run: tsh ls
    - name: List nodes (tctl)
      run: tctl nodes ls
    - name: Run hostname via SSH (tsh)
      # `root`가 원격 SSH 사용자명과 일치하고 hostname이
      # 접근을 위해 설정된 Teleport 클러스터의 SSH 호스트명과
      # 일치하는지 확인하세요.
      run: tsh ssh root@example-node hostname
    - name: Run hostname via SSH (OpenSSH)
      run: ssh -F ${{ steps.auth.outputs.ssh-config }} root@example-node.example.teleport.sh hostname

교체:

• example.teleport.sh:443을 Teleport Proxy 또는 클라우드 테넌트의 주소로.
• example-bot을 이전 단계에서 만든 토큰 이름으로.
• example-node를 연결하려는 Teleport SSH 노드 이름으로.
• root를 연결하는 노드의 사용자 이름이자 봇에 접근을 허용한 사용자 이름으로.

변경 사항을 저장소의 main 브랜치에 추가, 커밋, 푸시합니다.

웹 브라우저에서 GitHub 저장소의 Actions 탭으로 이동합니다. 변경으로 인해 만들어지고 트리거된 Workflow를 선택하고 example 작업을 선택합니다. GitHub Actions 워크플로가 완료되는 데 시간이 걸릴 수 있으며, 성공하면 다음과 유사하게 보입니다.

액션의 List nodes 단계를 확장하면 tsh ls 명령을 사용하여 머신 및 워크로드 아이덴티티 봇의 관점에서 클러스터의 모든 노드가 나열된 출력이 표시됩니다.

예시: teleport-actions/auth-k8s#

teleport-actions/auth-k8s 액션은 Teleport에 등록된 Kubernetes 클러스터에 연결하기 위해 Kubernetes 클라이언트에 필요한 자격 증명과 설정이 포함된 Kubernetes 출력 서비스를 생성합니다. 액션은 이 클라이언트를 자동으로 설정하는 데 필요한 환경 변수를 내보냅니다.

이 예시에서 teleport-actions/auth-k8s 액션을 사용하여 클러스터 내의 모든 Pod를 나열하지만, 이는 kubectl 또는 helm을 사용하여 Kubernetes 클러스터에 배포하도록 쉽게 수정할 수 있습니다.

가이드는 GitHub Actions 워크플로를 Teleport에 연결하고 등록된 Kubernetes 클러스터에 접근하는 데 필요한 권한을 부여하는 과정을 안내합니다.

Web UI에서 가이드를 찾으세요:<br />
**Add New** > **Integration** > **MWI: GitHub Actions + Kubernetes**

먼저 봇에 할당한 역할을 조정하여 Kubernetes 클러스터에 대한 접근을 허용해야 합니다. 이 예시는 editor 그룹이 있는 모든 클러스터에 봇 접근을 허용합니다. Kubernetes RBAC 설정에 대한 자세한 지침은 Kubernetes 접근 가이드를 참조하세요.

1. 다음 명령을 실행하여 텍스트 편집기에서 example-bot 역할을 엽니다:

$ tctl edit role/example-bot

1. 역할에 다음이 포함되어 있는지 확인합니다:

   spec:
     allow:
       kubernetes_labels:
         '*': '*'
       kubernetes_resources:
       - kind: pod
         namespace: "*"
         name: "*"
       kubernetes_groups:
       - editor
   

이 권한이 부여되면 GitHub Actions 워크플로를 만들 수 있습니다. .github/workflows/example.yaml을 만듭니다:

# 시작하는 데 도움이 되는 기본 워크플로입니다. 필요에 맞게 수정하세요.
on:
  push:
    branches:
    - main
jobs:
  demo:
    permissions:
      # "id-token: write" 권한이 필요하지 않으면 tbot이 클러스터에
      # 인증할 수 없습니다.
      id-token: write
      contents: read
    name: example
    runs-on: ubuntu-latest
    steps:
    - name: Checkout repository
      uses: actions/checkout@v3
    - name: Fetch kubectl
      uses: azure/setup-kubectl@v3
    - name: Fetch Teleport binaries
      uses: teleport-actions/setup@v1
      with:
        version: auto
        # Teleport Proxy Service의 주소로 교체하세요.
        proxy: example.teleport.sh:443
    - name: Fetch credentials using Machine ID
      uses: teleport-actions/auth-k8s@v2
      with:
        # Teleport Proxy Service의 주소로 교체하세요.
        proxy: example.teleport.sh:443
        # 1단계에서 만든 조인 토큰 리소스의 이름을 사용하세요.
        token: example-bot
        # Kubernetes 클러스터의 이름을 사용하세요.
        kubernetes-cluster: my-kubernetes-cluster
        # 익명 사용 텔레메트리 제출을 활성화합니다. 이는
        # `tbot`의 미래 개발을 형성하는 데 도움이 됩니다.
        # 이것을 생략하면 비활성화할 수 있습니다.
        anonymous-telemetry: 1
    - name: List pods
      run: kubectl get pods -A

교체:

• example.teleport.sh:443을 Teleport Proxy Service의 주소로.
• example-bot을 이전 단계에서 만든 토큰 이름으로.
• my-kubernetes-cluster를 Kubernetes 클러스터의 이름으로.

auth-k8s 액션은 이후 단계의 KUBECONFIG를 Teleport에서 가져온 자격 증명으로 설정합니다. 즉, Kubernetes용 대부분의 기존 도구(예: kubectl 및 helm)가 추가 설정 없이 클러스터를 사용할 수 있습니다.

이 새 워크플로 파일을 저장소의 기본 브랜치에 추가, 커밋, 푸시합니다.

웹 브라우저에서 GitHub 저장소의 Actions 탭으로 이동합니다. 변경으로 인해 만들어지고 트리거된 Workflow를 선택하고 example 작업을 선택합니다.

액션의 List pods 단계를 확장하여 출력이 Kubernetes 클러스터 내의 모든 Pod 목록을 표시하는지 확인합니다.

예시: teleport-actions/database-tunnel#

teleport-actions/database-tunnel 액션은 Machine & Workload ID의 database-tunnel 서비스를 사용하여 Teleport로 보호된 데이터베이스에 터널을 제공하는 백그라운드 tbot 클라이언트를 실행합니다.

이 예시에서는 psql 클라이언트를 사용하여 Postgres 데이터베이스에서 간단한 쿼리를 실행하지만, 호환되는 클라이언트와 함께 지원되는 모든 데이터베이스 유형을 사용할 수 있습니다. 앱에서 Teleport로 보호된 데이터베이스에 접근하는 방법에 대한 자세한 내용은 일반 데이터베이스 가이드를 참조하세요.

1. 다음 명령을 실행하여 텍스트 편집기에서 example-bot 역할을 엽니다:

$ tctl edit role/example-bot

1. 역할에 다음이 포함되어 있는지 확인합니다:

   spec:
     allow:
       db_labels:
         '*': '*'
       db_names: [demo-db]
       db_users: [demo-user]
       rules:
         - resources: [db_server, db]
           verbs: [read, list]
   

원하는 데이터베이스와 일치하도록 레이블, 이름, 사용자를 필요에 따라 조정하세요.

데이터베이스 권한이 부여되면 GitHub Actions 워크플로를 만들 수 있습니다. .github/workflows/example.yaml을 만듭니다:

# 시작하는 데 도움이 되는 기본 워크플로입니다. 필요에 맞게 수정하세요.
on:
  push:
    branches:
    - main
jobs:
  demo:
    permissions:
      # "id-token: write" 권한이 필요하지 않으면 tbot이 클러스터에
      # 인증할 수 없습니다.
      id-token: write
      contents: read
    name: example
    runs-on: ubuntu-latest
    steps:
    - name: Checkout repository
      uses: actions/checkout@v3
    - name: Fetch Teleport binaries
      uses: teleport-actions/setup@v1
      with:
        version: auto
        # Teleport Proxy Service의 주소로 교체하세요.
        proxy: example.teleport.sh:443
    - name: Fetch credentials using Machine ID
      uses: teleport-actions/database-tunnel@v1
      with:
        # Teleport Proxy Service의 주소로 교체하세요.
        proxy: example.teleport.sh:443
        # 1단계에서 만든 조인 토큰 리소스의 이름을 사용하세요.
        token: example-bot
        # 터널의 리스너 주소를 설정합니다. 기본 데이터베이스
        # 클라이언트(예: `psql`)는 이 소켓 주소를 사용하여 연결합니다.
        listen: tcp://localhost:5432
        # 데이터베이스 서비스 이름, 보통 `tsh db ls`에 표시되는
        # 데이터베이스 서버 이름입니다.
        service: postgres
        # 연결할 특정 데이터베이스의 이름.
        database: demo-db
        # 연결할 데이터베이스 사용자의 사용자명.
        username: demo-user
        # 백그라운드에서 봇과 조율하는 데 사용되는 tbot 진단
        # 서비스의 포트를 설정합니다. 여러 백그라운드 봇(앱
        # 터널/프록시, 데이터베이스 터널 등)을 실행하는 경우
        # 각각 고유한 포트를 지정해야 합니다. 설정하지 않으면
        # 아래에 표시된 기본값이 사용됩니다.
        diag-port: 57263
        # 익명 사용 텔레메트리 제출을 활성화합니다. 이는
        # `tbot`의 미래 개발을 형성하는 데 도움이 됩니다.
        # 이것을 생략하면 비활성화할 수 있습니다.
        anonymous-telemetry: 1

    - name: Run a database command
      run: |
        psql postgres://demo-user@localhost:5432/demo-db -c 'select 1;'

교체:

• example.teleport.sh:443을 Teleport Proxy Service의 주소로.
• example-bot을 이전 단계에서 만든 토큰 이름으로.
• postgres를 Teleport에 설정된 데이터베이스 서버 이름으로.
• demo-db를 접근할 데이터베이스 이름으로.
• demo-user를 연결할 데이터베이스 사용자명으로.

teleport-actions/database-tunnel 액션이 완료되면 설정된 포트(이 경우 localhost:5432)에서 데이터베이스 터널이 실행됩니다. 그런 다음 psql 또는 데이터베이스에 따라 다른 호환 클라이언트를 사용하여 접근할 수 있습니다.

이 새 워크플로 파일을 저장소의 기본 브랜치에 추가, 커밋, 푸시합니다.

웹 브라우저에서 GitHub 저장소의 Actions 탭으로 이동합니다. 변경으로 인해 만들어지고 트리거된 Workflow를 선택하고 example 작업을 선택합니다.

액션의 Run a database command 단계를 확장하여 데이터베이스 명령이 성공적으로 실행되었는지 확인합니다.

예시: teleport-actions/application-tunnel#

teleport-actions/application-tunnel 액션은 Machine & Workload ID의 application-tunnel 서비스를 사용하여 Teleport로 보호된 HTTP 또는 TCP 앱에 터널을 제공하는 백그라운드 tbot 클라이언트를 실행합니다.

1. 다음 명령을 실행하여 텍스트 편집기에서 example-bot 역할을 엽니다:

$ tctl edit role/example-bot

1. 역할에 다음이 포함되어 있는지 확인합니다:

   spec:
     allow:
       # `env=dev` 레이블이 있는 앱에 대한 접근을 허용합니다.
       app_labels:
         env: dev
   

봇이 접근할 수 있는 애플리케이션을 제한하도록 역할의 레이블 셀렉터를 조정하세요. 자세한 내용은 전용 애플리케이션 접근 가이드를 참조하세요.

권한이 부여되면 GitHub Actions 워크플로를 만들 수 있습니다. .github/workflows/example.yaml을 만듭니다:

# 시작하는 데 도움이 되는 기본 워크플로입니다. 필요에 맞게 수정하세요.
on:
  push:
    branches:
    - main
jobs:
  demo:
    permissions:
      # "id-token: write" 권한이 필요하지 않으면 tbot이 클러스터에
      # 인증할 수 없습니다.
      id-token: write
      contents: read
    name: example
    runs-on: ubuntu-latest
    steps:
    - name: Checkout repository
      uses: actions/checkout@v3
    - name: Fetch Teleport binaries
      uses: teleport-actions/setup@v1
      with:
        version: auto
        # Teleport Proxy Service의 주소로 교체하세요.
        proxy: example.teleport.sh:443
    - name: Fetch credentials using Machine ID
      uses: teleport-actions/application-tunnel@v1
      with:
        # Teleport Proxy Service의 주소로 교체하세요.
        proxy: example.teleport.sh:443
        # 1단계에서 만든 조인 토큰 리소스의 이름을 사용하세요.
        token: example-bot
        # 접근할 앱의 이름.
        app: my-application
        # 앱 터널의 리스너 주소를 설정합니다.
        listen: tcp://localhost:1234
        # 익명 사용 텔레메트리 제출을 활성화합니다. 이는
        # `tbot`의 미래 개발을 형성하는 데 도움이 됩니다.
        # 이것을 생략하면 비활성화할 수 있습니다.
        anonymous-telemetry: 1

    - name: Access the app
      run: curl http://localhost:1234

교체:

• example.teleport.sh:443을 Teleport Proxy Service의 주소로.
• example-bot을 이전 단계에서 만든 토큰 이름으로.
• my-application을 Teleport에 설정된 앱 이름으로.

실행되면 application-tunnel 액션은 설정된 호스트 및 포트(이 경우 localhost:1234)에서 선택한 애플리케이션에 터널을 엽니다.

이 새 워크플로 파일을 저장소의 기본 브랜치에 추가, 커밋, 푸시합니다.

웹 브라우저에서 GitHub 저장소의 Actions 탭으로 이동합니다. 변경으로 인해 만들어지고 트리거된 Workflow를 선택하고 example 작업을 선택합니다.

액션의 Access the app 단계를 확장하여 출력이 애플리케이션의 유효한 응답을 표시하는지 확인합니다.

예시: teleport-actions/application-proxy#

teleport-actions/application-proxy 액션은 Machine & Workload ID의 application-proxy 서비스를 사용하여 Teleport로 보호된 임의의 HTTP 앱에 접근하는 데 사용할 수 있는 로컬 HTTP 프록시 서버를 제공하는 백그라운드 tbot 클라이언트를 실행합니다.

이 액션은 HTTP 애플리케이션만 지원하지만, 봇에게 적절한 RBAC 권한이 부여되어 있고 클라이언트 앱이 HTTP 프록시(예: $HTTP_PROXY 환경 변수)를 사용할 수 있다면 임의의 앱에 접근할 수 있습니다.

1. 다음 명령을 실행하여 텍스트 편집기에서 example-bot 역할을 엽니다:

$ tctl edit role/example-bot

1. 역할에 다음이 포함되어 있는지 확인합니다:

   spec:
     allow:
       # `env=dev` 레이블이 있는 앱에 대한 접근을 허용합니다.
       app_labels:
         env: dev
   

봇이 접근할 수 있는 애플리케이션을 제한하도록 역할의 레이블 셀렉터를 조정하세요. 자세한 내용은 전용 애플리케이션 접근 가이드를 참조하세요.

권한이 부여되면 GitHub Actions 워크플로를 만들 수 있습니다. .github/workflows/example.yaml을 만듭니다:

# 시작하는 데 도움이 되는 기본 워크플로입니다. 필요에 맞게 수정하세요.
on:
  push:
    branches:
    - main
jobs:
  demo:
    permissions:
      # "id-token: write" 권한이 필요하지 않으면 tbot이 클러스터에
      # 인증할 수 없습니다.
      id-token: write
      contents: read
    name: example
    runs-on: ubuntu-latest
    steps:
    - name: Checkout repository
      uses: actions/checkout@v3
    - name: Fetch Teleport binaries
      uses: teleport-actions/setup@v1
      with:
        version: auto
        # Teleport Proxy Service의 주소로 교체하세요.
        proxy: example.teleport.sh:443
    - name: Fetch credentials using Machine ID
      uses: teleport-actions/application-proxy@v1
      with:
        # Teleport Proxy Service의 주소로 교체하세요.
        proxy: example.teleport.sh:443
        # 1단계에서 만든 조인 토큰 리소스의 이름을 사용하세요.
        token: example-bot
        # HTTP 프록시 서버의 리스너 주소를 설정합니다.
        listen: tcp://localhost:1235
        # 백그라운드에서 봇과 조율하는 데 사용되는 tbot 진단
        # 서비스의 포트를 설정합니다. 여러 백그라운드 봇(앱
        # 터널/프록시, 데이터베이스 터널 등)을 실행하는 경우
        # 각각 고유한 포트를 지정해야 합니다. 설정하지 않으면
        # 아래에 표시된 기본값이 사용됩니다.
        diag-port: 57263
        # 익명 사용 텔레메트리 제출을 활성화합니다. 이는
        # `tbot`의 미래 개발을 형성하는 데 도움이 됩니다.
        # 이것을 생략하면 비활성화할 수 있습니다.
        anonymous-telemetry: 1

    - name: Perform a request over the application tunnel
      run: |
        http_proxy=http://localhost:1235 curl http://httpbin/get

교체:

• example.teleport.sh:443을 Teleport Proxy Service의 주소로.
• example-bot을 이전 단계에서 만든 토큰 이름으로.

애플리케이션 프록시에 대한 특정 앱 이름을 설정할 필요가 없습니다.

액션이 완료되면 설정된 포트(이 경우 http://localhost:1235)에서 HTTP 프록시 서버가 실행됩니다. HTTP 프록시를 사용할 수 있는 모든 애플리케이션은 http://APP_NAME/에서 역할을 통해 봇에게 부여된 모든 앱에 접근할 수 있습니다.

이 새 워크플로 파일을 저장소의 기본 브랜치에 추가, 커밋, 푸시합니다.

웹 브라우저에서 GitHub 저장소의 Actions 탭으로 이동합니다. 변경으로 인해 만들어지고 트리거된 Workflow를 선택하고 example 작업을 선택합니다.

액션의 Perform a request... 단계를 확장하여 출력이 프록시를 통해 성공적인 curl 요청을 표시하는지 확인합니다.

예시: 수동 설정#

tbot을 수동으로 설정하기 위해 YAML 파일이 사용됩니다. 이 예시에서는 저장소에 커밋하지만, CI 파이프라인 자체에서 생성하거나 만들 수 있습니다.

이 예시는 tbot의 "oneshot" 모드를 사용하여 자격 증명을 출력하고 즉시 종료합니다. 장기 실행 백그라운드 서비스를 사용해야 하는 경우 맞춤 예시는 아래를 참조하세요.

저장소 내에 tbot.yaml을 만듭니다:

version: v2
proxy_server: example.teleport.sh:443
onboarding:
  join_method: github
  token: example-bot
oneshot: true
storage:
  type: memory
# services는 접근 가이드를 완료하는 동안 채워집니다.
services: []

교체:

• example.teleport.sh:443을 Teleport Proxy Service의 주소로.
• example-bot을 두 번째 단계에서 만든 토큰 이름으로.

이제 이 설정으로 tbot을 시작하는 GitHub Actions 워크플로를 정의할 수 있습니다.

.github/workflows/example-action.yaml을 만듭니다:

# 시작하는 데 도움이 되는 기본 워크플로입니다.
# "main" 브랜치에 푸시가 발생할 때마다 다음 작업을 수행합니다.
on:
  push:
    branches:
    - main
jobs:
  demo:
    permissions:
      # "id-token: write" 권한이 필요하지 않으면 tbot이 클러스터에
      # 인증할 수 없습니다.
      id-token: write
      contents: read
    # 워크플로의 이름과 필요한 단계를 수행하는 데 사용할 Linux 배포판.
    name: guide-demo
    runs-on: ubuntu-latest
    steps:
    - name: Checkout repository
      uses: actions/checkout@v3
    - name: Fetch Teleport binaries
      uses: teleport-actions/setup@v1
      with:
        version: auto
        # Teleport Proxy Service의 주소로 교체하세요.
        proxy: example.teleport.sh:443
    - name: Execute Machine ID
      env:
        # TELEPORT_ANONYMOUS_TELEMETRY는 익명 사용 텔레메트리 제출을
        # 활성화합니다. 이는 tbot의 미래 개발을 형성하는 데 도움이 됩니다.
        # 이것을 생략하면 비활성화할 수 있습니다.
        TELEPORT_ANONYMOUS_TELEMETRY: 1
      run: tbot start -c ./tbot.yaml --oneshot

이 두 파일을 저장소에 추가, 커밋, 푸시합니다. GitHub Actions UI에서 워크플로가 성공했는지 확인합니다.

You have now prepared the base configuration for tbot. At this point, it identifies itself to the Teleport cluster and renews its own credentials but does not output any credentials for other applications to use.

Follow one of the access guides to configure a service that meets your access needs.

예시: 백그라운드 서비스를 사용한 수동 설정#

전용 액션에서 직접 지원하지 않는 서비스(예: ssh-multiplexer 또는 workload-identity-api 서비스)를 제공하거나 장기 실행 작업에 대해 인증서를 지속적으로 갱신하기 위해 백그라운드에서 tbot 클라이언트가 실행되어야 하는 경우, 몇 가지 추가 단계를 통해 안전하게 백그라운드에서 tbot을 실행할 수 있습니다.

표준 수동 설정 단계에서와 같이 저장소 내에 tbot.yaml을 만듭니다:

version: v2
proxy_server: example.teleport.sh:443
onboarding:
  join_method: github
  token: example-bot
storage:
  type: memory
# services는 접근 가이드를 완료하는 동안 채워집니다.
services: []

교체:

• example.teleport.sh:443을 Teleport Proxy Service의 주소로.
• example-bot을 첫 번째 단계에서 만든 토큰 이름으로.

이제 이 설정으로 tbot을 시작하는 GitHub Actions 워크플로를 정의할 수 있습니다.

.github/workflows/example-action.yaml을 만듭니다:

# 시작하는 데 도움이 되는 기본 워크플로입니다.
# "main" 브랜치에 푸시가 발생할 때마다 다음 작업을 수행합니다.
on:
  push:
    branches:
    - main
jobs:
  demo:
    permissions:
      # "id-token: write" 권한이 필요하지 않으면 tbot이 클러스터에
      # 인증할 수 없습니다.
      id-token: write
      contents: read
    # 워크플로의 이름과 필요한 단계를 수행하는 데 사용할 Linux 배포판.
    name: guide-demo
    runs-on: ubuntu-latest
    steps:
    - name: Checkout repository
      uses: actions/checkout@v3
    - name: Fetch Teleport binaries
      uses: teleport-actions/setup@v1
      with:
        version: auto
        # Teleport Proxy Service의 주소로 교체하세요.
        proxy: example.teleport.sh:443
    - name: Start tbot in the background
      env:
        # TELEPORT_ANONYMOUS_TELEMETRY는 익명 사용 텔레메트리 제출을
        # 활성화합니다. 이는 tbot의 미래 개발을 형성하는 데 도움이 됩니다.
        # 이것을 생략하면 비활성화할 수 있습니다.
        TELEPORT_ANONYMOUS_TELEMETRY: 1
      run: nohup tbot start -c ./tbot.yaml --diag-addr localhost:57264 > ./tbot.log 2>&1 &
    - name: Wait for tbot to become ready
      run: tbot wait --timeout=30s --diag-addr localhost:57264

    # tbot 자격 증명 또는 서비스를 사용하는 다른 단계를 여기에 삽입합니다.

    # 작업 마지막에 이 단계는 디버깅 목적으로 기록된 tbot 로그를
    # 출력합니다(tbot.log에 저장됨).
    - name: Print tbot logs
      # 다른 작업 단계의 실패 여부와 관계없이 로그가 출력되어야 합니다.
      if: always()
      run: |
        if [ -f ./tbot.log ]; then
          cat ./tbot.log
        else
          echo "No tbot logs found"
        fi

이 두 파일을 저장소에 추가, 커밋, 푸시합니다. GitHub Actions UI에서 워크플로가 성공했는지 확인합니다.

You have now prepared the base configuration for tbot. At this point, it identifies itself to the Teleport cluster and renews its own credentials but does not output any credentials for other applications to use.

Follow one of the access guides to configure a service that meets your access needs.

보안 의미 및 위험에 대한 참고 사항#

teleport-actions/auth가 워크플로 작업에서 사용되면 해당 작업의 모든 후속 단계가 봇으로 Teleport 클러스터에 대한 접근을 허용하는 자격 증명에 접근할 수 있습니다. 가능하면 이 액션이 사용된 후 최소한의 단계만 실행하세요. CI/CD 파이프라인에서 실행 중인 다른 코드로부터 이 자격 증명을 격리하기 위해 워크플로를 여러 작업으로 분리하는 것이 좋습니다.

가장 중요한 것은 GitHub Actions 봇에 할당하는 역할이 CI/CD가 상호 작용해야 하는 Teleport 클러스터의 리소스에만 접근할 수 있는지 확인하는 것입니다.

다음 단계#

• 더 많은 사용 정보는 GitHub Actions를 확인하세요:
  • teleport-actions/setup
  • teleport-actions/auth
  • teleport-actions/auth-k8s
  • teleport-actions/auth-application
  • teleport-actions/database-tunnel
  • teleport-actions/application-tunnel
  • teleport-actions/application-proxy
• github 조인 방법에 대한 자세한 내용은 조인 토큰 레퍼런스 페이지를 읽으세요.
• GitHub Actions 자체에 대한 자세한 내용은 해당 문서를 읽으세요.
• anonymous-telemetry에 대한 자세한 정보.