GitHub Actions에서 Machine ID 배포

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

Teleport는 GitHub 호스팅 및 셀프 호스팅 GitHub Actions 러너와 함께 GitHub Enterprise Server에서의 안전한 조인을 지원합니다.

사전 요구 사항

실행 중인 Teleport 클러스터 버전 17.0.0-dev 이상. Teleport를 시작하려면 가입하여 무료 평가판을 이용하거나 데모 환경 설정 방법을 확인하십시오.
tctl 관리자 도구와 tsh 클라이언트 도구.

tctl 및 tsh 다운로드 방법에 대한 지침은 설치를 방문하십시오.

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

1/3단계. 봇 만들기

다음으로, Bot을 생성해야 합니다. Bot은 기계 또는 기계 그룹에 대한 Teleport ID입니다. 사용자와 마찬가지로 Bot도 액세스할 수 있는 권한을 정의하는 역할과 특성을 가지고 있습니다.

bot.yaml 을 생성합니다:

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

example 을 Bot에 대한 고유하고 설명적인 이름으로 교체했는지 확인하세요.

다음과 같이 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:
      # repository는 리포지토리 소유자의 이름을 포함해야 합니다.
      - repository: gravitational/example

gravitational/example 을 tbot 이 실행될 리포지토리의 이름으로 바꿉니다. 봇과 토큰의 이름을 변경하여 사용 사례를 보다 정확하게 설명할 수도 있습니다.

GitHub Enterprise 사용 중인가요?

Enterprise Server

셀프 호스팅 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

GitHub 엔터프라이즈에 대한 발급자 값 사용자 지정에 대한 가이드는 customizing the issuer value for an 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 워크플로 구성하기

이제 봇이 성공적으로 생성되었으므로, 이제 이 봇으로 인증할 수 있도록 GitHub Action의 워크플로를 구성하고 tbot 이 생성한 자격 증명을 사용해야 합니다. 이를 돕기 위해 Teleport는 워크플로 내에서 사용할 수 있는 여러 가지 사용하기 쉬운 GitHub Actions를 게시합니다.

Teleport GitHub Actions 중 하나를 사용하지 않고 tbot 을 수동으로 구성하는 것도 가능합니다. 이는 더 많은 구성이 필요하지만 tbot 에 대한 정확한 제어를 허용하며, Actions로는 불가능한 구현도 가능합니다.

다음은 사용 가능한 두 가지 GitHub Actions의 예를 보여주고, GitHub Actions에서 tbot 을 수동으로 구성하는 방법을 보여줍니다.

예제: `teleport-actions/auth`

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

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

tsh 를 사용하여 사용 가능한 SSH 노드 목록 보기
tctl 을 사용하여 사용 가능한 SSH 노드 목록 보기
tsh 를 사용하여 SSH 노드에 연결
OpenSSH의 ssh 를 사용하여 SSH 노드에 연결

먼저, 봇에 할당한 역할을 조정하여 SSH에 대한 액세스를 부여해야 합니다. 이 예제는 모든 노드에서 root에 대한 액세스를 부여합니다. 생산 설정에서는 봇이 필요한 노드로만 제한하는 것이 좋습니다.

다음과 같이 역할에 추가하려면 tctl edit role/example-bot 를 사용하세요:

spec:
  allow:
    # 'root'라는 Linux 사용자에게 로그인 허용.
    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
    # 워크플로의 이름과 필요한 단계를 수행할 Linux 배포판.
    name: example
    runs-on: ubuntu-latest
    steps:
      - name: 리포지토리 체크아웃
        uses: actions/checkout@v3
      - name: Teleport 바이너리 가져오기
        uses: teleport-actions/setup@v1
        with:
          version: 17.0.0-dev
      - 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)
        # 클러스터의 명령어를 입력하며, 이 경우에는 Machine ID 자격 증명을 사용하여 원격 SSH 노드를 나열하는 "tsh ls".
        run: tsh ls
      - name: 노드 목록 보기 (tctl)
        run: tctl nodes ls
      - name: SSH를 통한 호스트 이름 실행 (tsh)
        # `root` 가 원격 SSH 사용자 이름과 일치하도록 하고, hostname이 액세스에 대한 Teleport 클러스터의 일부인 SSH 호스트 이름과 일치해야 합니다.
        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 를 연결하려는 노드에서 사용자에게 부여한 이름으로 바꾸세요.

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

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

작업의 노드 목록 보기 단계를 확장하면 해당 출력이 클러스터의 모든 노드를 나열하며, tsh ls 명령을 사용하는 Machine ID 봇의 관점에서 나열됩니다.

예제: `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

Note

이 예제는 역할이 v6 버전이라고 가정합니다. v7 이상의 역할을 사용하는 경우 kubernetes_resources 의 kind: pod 섹션에 verbs: ["get", "list"]를 포함해야 합니다. 그렇지 않으면 예제의 kubectl get pods -A 실행이 거부됩니다.

권한이 부여되면 이제 GitHub Actions 워크플로를 생성할 수 있습니다. .github/workflows/example.yaml 파일을 생성하십시오:

# 이는 시작하는 데 도움이 되는 기본 워크플로입니다. 필요에 맞게 수정하십시오.
on:
  push:
    branches:
      - main
jobs:
  demo:
    permissions:
      # 클러스터와 인증할 수 없도록 "id-token: write" 권한이 필요합니다.
      id-token: write
      contents: read
    name: 예제
    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: 17.0.0-dev
      - name: 머신 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 액션은 향후 단계에 대해 Teleport에서 가져온 자격 증명으로 KUBECONFIG 를 설정합니다. 이는 대부분의 기존 Kubernetes 도구(예: kubectl 및 helm )가 추가 구성 없이 클러스터를 사용할 수 있음을 의미합니다.

이 새로운 워크플로 파일을 리포지토리의 기본 브랜치에 추가, 커밋 및 푸시하십시오.

웹 브라우저에서 GitHub 리포지토리의 Actions 탭으로 이동하십시오. 이제 변경 사항으로 인해 생성되고 트리거된 Workflow를 선택하고 example 작업을 선택하십시오.

액션의 파드 목록 나열 단계를 확장하면 출력에 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: 17.0.0-dev
      - 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 클러스터에 대한 접근을 허용하는 자격 증명에 접근할 수 있습니다. 가능한 한 이 작업이 사용된 이후로 필요한 최소한의 단계만 실행하는 것이 좋습니다. CI/CD 파이프라인에서 실행되는 다른 코드와 자격 증명을 분리하기 위해 여러 작업으로 워크플로를 분리하는 것이 좋습니다.

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