GitHub Actions에서 Machine ID 배포하기

GitHub Actions는 더 큰 GitHub 생태계의 일부로 작동하는 인기 있는 CI/CD 플랫폼입니다. Teleport Machine ID는 GitHub Actions가 장기 자격 증명 없이 Teleport 보호 리소스와 안전하게 상호 작용할 수 있도록 합니다.

Teleport는 GitHub-hosted 및 self-hosted GitHub Actions 러너는 물론 GitHub Enterprise Server에서 안전한 조인을 지원합니다.

전제 조건

실행 중인 Teleport 클러스터 버전 이상. Teleport를 시작하려면, 가입하기 위해 무료 평가판에 등록하거나 데모 환경 설정하기를 참조하세요.
tctl 관리 도구와 tsh 클라이언트 도구.

tctl과 tsh 다운로드에 대한 지침은 설치를 방문하세요.

당신의 Teleport 클러스터에 연결할 수 있는지 확인하려면, tsh login으로 로그인한 다음 현재 자격 증명을 사용하여 tctl 명령어를 실행할 수 있는지 확인하십시오. 예를 들어:
```
tsh login --proxy=teleport.example.com --user=email@example.com
tctl status
클러스터  teleport.example.com
버전  16.2.0
CA 핀   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
```
클러스터에 연결하고 tctl status 명령어를 실행할 수 있다면, 현재 자격 증명을 사용하여 작업대에서 후속 tctl 명령어를 실행할 수 있습니다. 자신의 Teleport 클러스터를 호스팅하는 경우, Teleport 인증 서비스를 호스팅하는 컴퓨터에서 전체 권한으로 tctl 명령어를 실행할 수도 있습니다.
사용자는 토큰 리소스를 생성할 수 있는 권한이 있어야 합니다.
GitHub Actions가 활성화된 GitHub 리포지토리. 이 가이드는 gravitational/example 리포지토리를 예시로 사용하지만, 이 값은 고유한 리포지토리 이름으로 교체해야 합니다.

단계 1/3. 봇 생성

다음으로, 봇을 생성해야 합니다. 봇은 기계 또는 기계 그룹에 대한 Teleport 아이덴티티입니다. 사용자와 마찬가지로, 봇은 액세스할 수 있는 내용을 정의하는 일련의 역할과 특성을 가지고 있습니다.

bot.yaml을 생성하세요:

kind: bot
version: v1
metadata:
  # name은 클러스터 내에서 봇의 고유 식별자입니다.
  name: example
spec:
  # roles는 봇에 부여할 역할의 목록입니다. 여기에 어떤 역할을 지정해야 할지 모르는 경우 걱정하지 마세요.
  # Access Guides가 이미 생성된 봇에 역할을 생성하고 할당하는 방법을 안내해 드립니다.
  roles: []

example을 봇에 대한 고유하고 설명적인 이름으로 교체하는 것을 잊지 마세요.

이 파일을 적용하려면 tctl을 사용하세요:

tctl create bot.yaml

단계 2/3. GitHub Actions용 조인 토큰 생성

GitHub Actions 워크플로우가 Teleport 클러스터에 인증할 수 있도록 조인 토큰을 먼저 생성해야 합니다. 이러한 토큰은 Auth Server가 봇이나 노드에 조인할 수 있는지 여부를 결정하는 기준을 설정합니다.

이 예제에서는 특정 GitHub 리포지토리 내에서 진행되는 모든 GitHub Actions에 접근을 허용하는 조인 토큰을 생성합니다. 프로덕션에서는 CI가 특정 브랜치에서 실행될 때만 접근할 수 있도록 이러한 규칙을 추가로 제한하는 것이 좋습니다. 사용 가능한 규칙의 전체 목록은 GitHub Actions 참조 페이지에서 확인할 수 있습니다.

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이 실행될 리포지토리의 이름으로 교체하세요. 또한 봇 및 토큰의 이름을 사용 사례에 맞게 변경할 수도 있습니다.

GitHub Enterprise를 사용하고 있습니까?

Enterprise Server

Teleport 11.1.4부터, Teleport Enterprise 사용자는 GitHub Enterprise Server 인스턴스 내에서 워크플로우가 GitHub 조인 방법을 사용하여 인증할 수 있도록 허용할 수 있습니다.

Teleport Auth Server는 GitHub Enterprise Server에 연결할 수 있어야 합니다.

이를 구성하려면 spec.github.enterprise_server_host를 GHES 인스턴스의 호스트 이름으로 설정하세요.

예를 들어:

spec:
  github:
    enterprise_server_host: ghes.example.com

Enterprise Cloud

GitHub Enterprise Cloud 구성에서 include_enterprise_slug를 사용하도록 설정한 경우, spec.github.enterprise_slug를 GitHub Enterprise 조직의 슬러그로 설정해야 합니다.

예를 들어:

spec:
  github:
    enterprise_slug: my-enterprise

include_enterprise_slug에 대한 자세한 내용은 GitHub 교육 자료를 참조하여 엔터프라이즈에 대한 발급자 값 사용자 정의.

리소스 파일이 작성되면 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 Action의 워크플로우를 구성해야 합니다. 이를 도와주기 위해, Teleport는 워크플로우 내에서 사용할 수 있는 여러 사용하기 쉬운 GitHub Actions를 제공합니다.

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

다음은 GitHub Actions에서 사용할 수 있는 두 가지 예제와 GitHub Actions용으로 tbot을 수동으로 구성하는 방법을 보여줍니다.

예제: `teleport-actions/auth`

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

이 예제에서는 다음 작업에 자격 증명을 사용합니다:

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

먼저, 봇에게 SSH에 접근할 수 있도록 할당한 역할을 조정해야 합니다. 이 예제에서는 모든 노드에서 root에 대한 접근을 허용합니다. 프로덕션 설정에서는 봇이 필요로 하는 노드로만 제한하는 것이 좋습니다.

tctl edit role/example-bot를 사용하여 다음을 역할에 추가합니다:

spec:
  allow:
    # Linux 사용자 'root'에 로그인 허용.
    logins: ['root']
    # 어떤 노드에도 연결 허용. 이러한 레이블을 조정하여 ansible이 접근해야 하는 노드로만 일치하도록 합니다.
    node_labels:
      '*': '*'

이렇게 권한이 부여되면 GitHub Actions 워크플로우를 생성할 수 있습니다. .github/workflows/example.yaml을 생성하세요:

# 이것은 시작하는 데 도움이 되는 기본 워크플로우입니다.
# "main" 브랜치에 푸시할 때마다 다음 작업을 수행합니다.
on:
  push:
    branches:
    - main
jobs:
  demo:
    permissions:
      # "id-token: write" 권한이 필요하며, 그렇지 않으면 Machine ID가 클러스터에 인증할 수 없습니다.
      id-token: write
      contents: read
    # 워크플로우의 이름과 요구 사항을 수행하기 위해 사용될 리눅스 배포판입니다.
    name: example
    runs-on: ubuntu-latest
    steps:
    - name: 리포지토리 체크아웃
      uses: actions/checkout@v3
    - name: Teleport 바이너리 가져오기
      uses: teleport-actions/setup@v1
      with:
        version: 16.2.0
    - name: Machine ID를 사용하여 자격 증명 가져오기
      id: auth
      uses: teleport-actions/auth@v2
      with:
        # 클러스터의 auth/proxy 서버 주소를 사용합니다.
        proxy: example.teleport.sh:443
        # 단계 1에서 생성한 조인 토큰 리소스의 이름을 사용합니다.
        token: example-bot
        # 생성된 자격 증명이 유효해야 할 시간의 길이를 지정합니다. 
        # 선택사항이며 기본값은 "1h"입니다.
        certificate-ttl: 1h
        # 익명 사용 통계를 제출할 수 있도록 활성화합니다. 
        # 이는 `tbot`의 미래 개발에 도움이 됩니다. 
        # 이를 생략하면 비활성화됩니다.
        anonymous-telemetry: 1
    - name: 노드 나열 (tsh)
      # 클러스터에서 명령을 입력하며, 여기서 "tsh ls"를 사용하여 Machine ID 자격 증명으로 원격 SSH 노드를 나열합니다.
      run: tsh ls
    - name: 노드 나열 (tctl)
      run: tctl nodes ls
    - name: SSH를 통해 호스트 이름 실행 (tsh)
      # `root`가 원격 SSH 사용자 이름과 일치하고, 
      # hostname이 Teleport 클러스터의 액세스용 호스트 이름과 일치해야 합니다.
      run: tsh ssh root@example-node hostname
    - name: 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를 연결할 노드의 사용자 이름으로 교체합니다. 이 사용자는 봇에 대한 접근을 허용했습니다.

변경 사항을 .github/workflows/example.yaml에 추가하고 커밋하고 main 브랜치에 푸시하세요.

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

작업의 노드 나열 단계를 확장하고 출력이 Machine ID 봇의 tsh ls 명령을 사용하여 클러스터의 모든 노드를 나열합니다.

예제: `teleport-actions/auth-k8s`

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

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

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

tctl edit role/example-bot를 사용하여 Teleport 역할에 다음 규칙을 추가합니다:

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" 권한이 필요하며, 그렇지 않으면 Machine ID가 클러스터에 인증할 수 없습니다.
      id-token: write
      contents: read
    name: example
    runs-on: ubuntu-latest
    steps:
    - name: 리포지토리 체크아웃
      uses: actions/checkout@v3
    - name: kubectl 가져오기
      uses: azure/setup-kubectl@v3
    - name: Teleport 바이너리 가져오기
      uses: teleport-actions/setup@v1
      with:
        version: 16.2.0
    - name: Machine ID로 자격 증명 가져오기
      uses: teleport-actions/auth-k8s@v2
      with:
        # 클러스터의 auth/proxy 서버 주소를 사용합니다.
        proxy: example.teleport.sh:443
        # 단계 1에서 생성한 조인 토큰 리소스의 이름을 사용합니다.
        token: example-bot
        # Kubernetes 클러스터의 이름을 사용합니다.
        kubernetes-cluster: my-kubernetes-cluster
        # 익명 사용 통계를 제출할 수 있도록 활성화합니다. 이는 `tbot`의 미래 개발에 도움이 됩니다.
        # 이를 생략하여 비활성화할 수 있습니다.
        anonymous-telemetry: 1
    - name: 파드 목록
      run: kubectl get pods -A

다음과 같이 교체하세요:

example.teleport.sh:443을 Teleport Proxy 또는 클라우드 테넌트의 주소로 교체합니다.
example-bot을 이전 단계에서 생성한 토큰의 이름으로 교체합니다.
my-kubernetes-cluster를 Kubernetes 클러스터의 이름으로 교체합니다.

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

변경 사항을 제출하고 기본 브랜치에 새 워크플로 파일을 푸시하세요.

웹 브라우저에서 GitHub 리포지토리의 Actions 탭으로 이동합니다. 이제 생성되고 변경으로 인해 트리거된 워크플로우를 선택하고 example job을 선택합니다.

작업의 파드 목록 단계를 확장하여 출력이 Kubernetes 클러스터 내의 모든 파드를 나열하는지 확인합니다.

예제: 수동 구성

tbot을 수동으로 구성하기 위해 YAML 파일을 사용할 것입니다. 이 예제에서는 이를 리포지토리에 커밋하겠지만, CI 파이프라인에서 생성하거나 생성할 수도 있습니다.

리포지토리 내에 tbot.yaml을 생성하세요:

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

다음과 같이 교체하세요:

example.teleport.sh:443을 Teleport Proxy 또는 Auth Server의 주소로 교체합니다. Teleport Proxy의 주소를 사용하는 것이 좋습니다.
example-bot을 첫 번째 단계에서 생성한 토큰의 이름으로 교체합니다.

이제 이 구성을 사용하여 tbot을 시작할 GitHub Actions 워크플로를 정의할 수 있습니다.

.github/workflows/example-action.yaml을 생성하세요:

# 이것은 시작하는 데 도움이 되는 기본 워크플로우입니다.
# "main" 브랜치에 푸시할 때마다 다음 작업을 수행합니다.
on:
  push:
    branches:
    - main
jobs:
  demo:
    permissions:
      # "id-token: write" 권한이 필요하며, 그렇지 않으면 Machine ID가 클러스터에 인증할 수 없습니다.
      id-token: write
      contents: read
    # 워크플로우의 이름과 요구 사항을 수행하기 위해 사용될 리눅스 배포판입니다.
    name: guide-demo
    runs-on: ubuntu-latest
    steps:
    - name: 리포지토리 체크아웃
      uses: actions/checkout@v3
    - name: Teleport 바이너리 가져오기
      uses: teleport-actions/setup@v1
      with:
        version: 16.2.0
    - name: Machine ID 실행
      env:
        # TELEPORT_ANONYMOUS_TELEMETRY는 익명 사용 통계 제출을 활성화합니다. 
        # 이는 tbot의 미래 개발에 도움이 됩니다. 
        # 이를 생략하여 비활성화할 수 있습니다.
        TELEPORT_ANONYMOUS_TELEMETRY: 1
      run: tbot start -c ./tbot.yaml --oneshot

이 두 파일을 리포지토리에 추가하고 커밋한 후 푸시하세요. GitHub Actions UI를 확인하여 워크플로가 성공했는지 확인하세요.

당신은 이제 tbot의 기본 설정을 완료했습니다. 현재 이 시점에서 tbot은 Teleport 클러스터에 자신을 식별하고 자체 자격 증명을 갱신하지만 다른 애플리케이션에서 사용할 수 있는 자격 증명을 출력하지는 않습니다.

액세스 가이드 중 하나를 따라 귀하의 액세스 요구 사항을 충족하는 출력을 구성하세요.

보안 권고사항 및 위험에 대한 주의

teleport-actions/auth가 워크플로우 작업에서 사용된 후, 해당 작업의 모든 후속 단계는 봇으로서 Teleport 클러스터에 접근할 수 있는 자격 증명에 접근할 수 있습니다. 가능한 경우, 이 액션이 사용된 이후로 필요한 최소한의 단계만 실행하는 것이 좋습니다. 이러한 자격 증명을 다른 코드와 분리하기 위해 워크플로를 여러 작업으로 분할하는 것이 좋습니다.

무엇보다도, GitHub Actions 봇에 할당하는 역할이 Teleport 클러스터에서 CI/CD가 상호작용하는 데 필요한 리소스에만 접근할 수 있도록 보장해야 합니다.