이 가이드에서는 Machine & Workload Identity의 에이전트 tbot을 CircleCI 워크플로 내에서 실행하도록 설정합니다. 봇은 장기 시크릿의 필요성을 없애기 위해 circleci 위임 조인 방법을 사용하도록 설정됩니다.

사전 요구사항#

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

• 푸시할 수 있는 Git 리포지터리에 연결된 CircleCI 프로젝트.

Step 1/4. CircleCI 설정#

어떤 CircleCI 워크플로가 Teleport 클러스터에 연결할 수 있도록 허용할지에 대한 규칙을 설정하려면, CircleCI 조직의 ID를 확인하고 CircleCI 컨텍스트를 생성해야 합니다.

조직 ID 확인하기#

CircleCI를 열고 내비게이션 바에서 "Organization settings"로 이동합니다. "Organization ID"라는 섹션이 있는 "Overview"라는 제목의 인터페이스가 표시됩니다. 이 값을 기록해 두고, 설정 예제에서 organization-id을 이 값으로 대체하세요.

컨텍스트 생성하기#

CircleCI에는 조직 수준의 개념인 **컨텍스트(contexts)**가 있으며, 이를 통해 워크플로 작업에 노출되어야 하는 일련의 시크릿을 설정할 수 있습니다. CircleCI를 설정하여 어떤 액터가 컨텍스트와 연결된 작업을 트리거할 수 있는지 제어할 수 있습니다.

워크플로 작업에 할당된 컨텍스트는 CircleCI가 해당 작업을 위해 생성하는 아이덴티티 토큰에도 인코딩됩니다. 이는 Teleport가 어떤 CircleCI 작업이 Teleport 클러스터에 대한 접근 권한을 부여받아야 하는지 판단하는 데 이상적인 방법이 됩니다.

이 예제에서는 teleport-access라는 이름의 CircleCI 컨텍스트를 생성합니다. 그런 다음 이 컨텍스트에 Teleport 클러스터에 대한 접근 권한을 부여합니다.

CircleCI 컨텍스트를 생성하려면, CircleCI에서 "Organization settings"를 열고 "Contexts"로 이동합니다. "Create Context"를 클릭하고 생성하려는 컨텍스트의 이름으로 teleport-access를 입력합니다. 이 값은 조직에 더 적합한 문자열로 대체할 수 있지만, 이 가이드의 이후 단계에서 teleport-access를 사용한 부분을 자신의 값으로 대체해야 한다는 점을 유의하세요.

방금 생성한 컨텍스트를 선택합니다. 이제 컨텍스트를 설정할 수 있는 페이지가 표시됩니다. Teleport를 설정할 때 사용할 컨텍스트의 ID를 확인하려면 컨텍스트 설정 페이지의 URL을 확인하세요. URL 형식은 다음과 비슷합니다:

https://app.circleci.com/settings/organization/github/gravitational/contexts/00000000-0000-0000-0000-000000000000

이 경우 컨텍스트 ID는 다음과 같습니다: 00000000-0000-0000-0000-000000000000.

이 값을 기록해 두고, 설정 예제에서 context-id를 이 값으로 대체하세요.

Step 2/4. 봇 생성#

다음으로 Bot을 생성해야 합니다. Bot은 머신 또는 머신 그룹을 위한 Teleport identity입니다. 사용자와 마찬가지로 bot에는 무엇에 액세스할 수 있는지 정의하는 role 및 trait 집합이 있습니다.

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: []

example을 Bot에 대한 고유하고 설명적인 이름으로 반드시 교체하십시오.

tctl을 사용하여 이 파일을 적용합니다:

$ tctl create bot.yaml

Step 3/4. CircleCI용 조인 토큰 생성#

CircleCI 워크플로가 Teleport 클러스터로 인증할 수 있도록 하려면 먼저 조인 토큰을 생성해야 합니다. 이 토큰은 Auth 서비스가 봇이나 노드의 조인을 허용할지 여부를 결정하는 기준을 설정합니다.

bot-token.yaml이라는 파일을 생성하고, Step 1에서 확인한 값으로 organization-id와 context-id를 반드시 대체하세요.

kind: token
version: v2
metadata:
  name: example-bot
spec:
  roles: [Bot]
  join_method: circleci
  bot_name: example
  circleci:
    organization_id: organization-id
    # allow specifies the rules by which the Auth Service determines if `tbot`
    # should be allowed to join.
    allow:
    - context_id: context-id

토큰 리소스의 필드를 좀 더 자세히 살펴보겠습니다:

• metadata.name은 토큰의 이름을 정의합니다. 이 값은 이후 설정의 다른 부분에서도 사용해야 한다는 점을 유의하세요.
• spec.bot_name은 이 토큰이 접근 권한을 부여할 Machine ID 봇의 이름입니다. 이 값은 이후 설정의 다른 부분에서도 사용해야 한다는 점을 유의하세요.
• spec.roles는 이 토큰이 접근 권한을 부여할 역할을 정의합니다. [Bot] 값은 이 토큰이 Machine & Workload Identity 봇에 대한 접근 권한을 부여함을 나타냅니다.
• spec.join_method는 토큰이 적용되는 조인 방법을 정의합니다. 이 가이드는 CircleCI에만 초점을 맞추므로, 이 값을 circleci로 설정합니다.
• spec.circleci.allow는 이 토큰을 사용하여 어떤 CircleCI 실행이 인증할 수 있는지에 대한 규칙을 설정하는 데 사용됩니다.

tctl을 사용하여 이를 Teleport 클러스터에 적용합니다:

$ tctl create -f bot-token.yaml

Step 4/4. CircleCI 워크플로 설정#

봇과 조인 토큰을 생성했으니, 이제 Teleport 클러스터에 연결할 수 있는 CircleCI 워크플로를 설정할 수 있습니다.

tbot을 설정하려면 YAML 파일을 사용합니다. 이 예제에서는 이 파일을 리포지터리 자체에 저장하지만, CI 파이프라인 자체에서 생성하거나 만들 수도 있습니다.

리포지터리 내에 tbot.yaml을 생성합니다:

version: v2
proxy_server: example.teleport.sh:443
onboarding:
  join_method: circleci
  token: example-bot
oneshot: true
storage:
  type: memory
# services will be filled in during the completion of an access guide.
services: []

다음을 대체하세요:

• example.teleport.sh를 Teleport 프록시 또는 Auth 서비스의 주소로 대체합니다. Teleport 프록시의 주소를 사용하는 것이 좋습니다.
• example-bot을 세 번째 단계에서 생성한 토큰의 이름으로 대체합니다.

이제 CircleCI 파이프라인을 정의할 수 있습니다. 파이프라인에서 tbot을 사용하려면 먼저 환경 내에서 사용할 수 있어야 합니다. 이 예제에서는 tbot을 CI 단계의 일부로 다운로드하는 방법을 보여주지만, 운영 환경에서는 Teleport CDN에 대한 의존성을 피하기 위해 이 바이너리를 포함하는 Docker 이미지를 빌드하는 것이 좋습니다.

Git 리포지터리를 열고 .circleci라는 디렉터리를 생성합니다. 그런 다음 config.yml이라는 파일을 열고 다음 설정을 입력합니다:

# See: https://circleci.com/docs/configuration-reference
version: 2.1
jobs:
  write-run-log:
    docker:
      - image: cimg/base:stable
    steps:
      - checkout
      - run:
          name: "Install Teleport"
          command: |
            curl "https://example.teleport.sh:443/scripts/install.sh" | sudo bash
      - run:
          name: "Run Machine & Workload Identity"
          command: |
            export TELEPORT_ANONYMOUS_TELEMETRY=1
            tbot start -c tbot.yaml
workflows:
  write-run-log:
    jobs:
      - write-run-log:
          context:
            - teleport-access

example.teleport.sh를 Teleport 프록시 서비스의 주소로 대체하세요.

TELEPORT_ANONYMOUS_TELEMETRY는 익명 사용 텔레메트리 제출을 활성화합니다. 이는 tbot의 향후 개발 방향을 정하는 데 도움이 됩니다. 이 항목을 생략하면 이 기능을 비활성화할 수 있습니다.

이 두 설정 파일을 리포지터리에 추가하고 커밋한 다음 푸시하세요.

CircleCI를 열고 작업의 상태를 확인하여, 작업이 완료될 때까지 기다린 후 오류가 발생하지 않았는지 확인하세요.

보안 영향 및 위험에 대한 참고 사항#

작업에서 tbot start가 사용되고 나면, 해당 작업의 이후 모든 단계는 tbot이 생성한 자격 증명에 접근할 수 있게 됩니다. 이러한 자격 증명에 접근할 수 있는 단계의 수를 줄이려면 워크플로를 여러 작업으로 나누세요.

CircleCI 봇에 할당하는 역할이 CI/CD가 상호작용해야 하는 Teleport 클러스터 내 리소스에만 접근 권한을 갖도록 하세요.

다음 단계#

이제 tbot에 대한 기본 설정을 준비했습니다. 현재 시점에서 tbot은 Teleport 클러스터에 자신을 식별시키고 자체 자격 증명을 갱신하지만, 다른 애플리케이션이 사용할 자격 증명은 아직 출력하지 않습니다.

• 접근 가이드를 따라 사용자의 환경에 맞게 tbot 설정을 완료하세요.
• 설정 참조를 읽고 사용 가능한 모든 설정 옵션을 살펴보세요.
• CircleCI 자체에 대한 자세한 내용은 해당 문서를 참조하세요.
• TELEPORT_ANONYMOUS_TELEMETRY에 대한 자세한 정보.