이 가이드에서는 env zero에서 실행되는 작업에서 Teleport용 Terraform 프로바이더를 사용하는 방법을 설명합니다.

이 가이드는 Terraform 프로바이더를 로컬에서 실행하거나, 다른 CI/CD 환경 또는 단기간 클라우드 VM에서 실행하는 방법은 다루지 않습니다. 해당 경우에는 전용 가이드를 참조하세요:

• Terraform Cloud에서 Terraform 프로바이더 실행
• CI 또는 클라우드 VM에서 Terraform 프로바이더 실행
• 로컬에서 Terraform 프로바이더 실행

동작 방식#

env zero에서 Teleport Terraform 프로바이더를 실행할 때, 내장된 Machine & Workload ID 지원을 사용하여 공유 비밀 없이 Teleport 클러스터에 동적으로 인증할 수 있습니다.

이를 위해 Teleport는 env zero 플랫폼에서 실행되는 작업에 OIDC 토큰을 제공하는 env zero의 General OIDC Integrations 지원을 활용할 수 있습니다. 그런 다음 Teleport Terraform 프로바이더는 이 토큰을 사용하여 Teleport 클러스터에 자신의 ID를 증명합니다.

이 가이드를 따르면서 env zero 배포에서 참여 요청을 수락하도록 Teleport 클러스터를 구성하고, env0 참여 방법을 사용하여 인증하도록 프로바이더를 구성합니다.

사전 요구 사항#

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

• Terraform >= [terraform.version]+

  $ terraform version
  # Terraform v(=terraform.version=)
  

  기존 Teleport 리소스를 Terraform 리소스로 가져오려면 Terraform 버전 v1.5.0 이상이 필요합니다.

• env zero 계정 및 프로젝트

• Teleport Terraform 프로바이더 v18.4.0 이상

1/5단계: env zero에서 OIDC 활성화하기#

조직의 자격 증명 설정에서 OIDC 통합을 활성화해야 합니다. 이를 위해:

1. 조직 설정으로 이동합니다
2. "Policies" 탭을 선택합니다
3. "Third-Party Authentication" 헤더 아래에서 "Enable OIDC during deployments"가 체크되어 있는지 확인합니다
4. 필요한 경우 "Save"를 선택합니다

자세한 내용은 env zero 문서를 참조하세요.

2/5단계. 정보 수집하기#

배포 워크플로가 Teleport에 인증할 수 있도록 최소한 조직 및 프로젝트의 ID를 구성해야 합니다. 이 값들은 env zero UI에서 찾을 수 있습니다.

조직 ID를 확인하려면 조직 설정으로 이동하여 "General" 탭을 선택하고 ID 필드에 표시된 값을 메모하세요. 원하는 경우 조직 ID를 여기에 저장하세요: example-organization-id

그 다음 프로젝트 ID도 가져와야 합니다. 원하는 프로젝트의 설정으로 이동하여 표시된 ID를 메모하세요. 원하는 경우 여기에 입력할 수 있습니다: example-project-id

3/5단계. Teleport에서 env zero 참여 구성하기#

먼저, Teleport Auth Service가 env zero 실행에서 참여 요청을 수락하도록 구성해야 합니다. 이후 단계에서 Teleport Terraform 프로바이더가 사용할 terraform이라는 이름의 봇을 생성하여 이 작업을 수행합니다.

다음 내용을 terraform_bot.yaml에 작성합니다:

kind: bot
version: v1
metadata:
  name: terraform
spec:
  # terraform-provider 역할은 terraform 프로바이더가 지원하는 모든
  # 리소스에 대한 접근 권한을 부여하는 내장 역할입니다.
  roles: ["terraform-provider"]

그런 다음 새 YAML 매니페스트에서 봇을 생성합니다:

$ tctl create -f terraform_bot.yaml
bot 'terraform' has been created

다음으로, 새 봇이 env zero의 OIDC 자격 증명으로 인증할 수 있어야 합니다. 다음 내용으로 terraform_token.yaml이라는 파일을 생성합니다:

kind: token
version: v2
metadata:
  name: terraform
spec:
  roles: [Bot]
  join_method: env0
  bot_name: terraform
  env0:
    allow:
      - organization_id: example-organization-id
        project_id: example-project-id

추가 허용 규칙 필드를 사용하여 인증이 허용되는 작업을 더욱 제한할 수 있습니다. 전체 옵션 목록은 env0 참여 방법 참조를 참조하세요.

배포 작업이 참여할 수 있도록 허용되려면 지정된 모든 필드가 Teleport에 제시되는 값과 일치해야 합니다. 여러 프로젝트의 참여를 허용하려면 allow 필드에 추가 항목을 추가할 수 있습니다. 또한 각 항목은 최소한 organization_id와 프로젝트 식별자(project_id 또는 project_name)를 제공해야 합니다.

완료되면 토큰을 생성합니다:

$ tctl create -f terraform_token.yaml
token 'terraform' has been created

4/5단계. Terraform 프로바이더 구성하기#

provider.tf 또는 유사한 파일에서 teleport 프로바이더를 구성합니다:

provider "teleport" {
  addr = "example.teleport.sh:443"
  join_method = "env0"
  join_token = "terraform"
}

다음 매개변수를 설정해야 합니다:

• addr는 Teleport 클러스터의 공개 호스트명과 포트와 일치해야 합니다
• join_method는 env0이어야 합니다
• join_token은 2단계에서 생성한 token 리소스의 이름과 일치해야 합니다

기존 identity_file_path가 있다면 반드시 제거하세요. join_method와 join_token으로 대체됩니다.

완전한 예시로 이 최소한의 provider.tf를 참고하세요:

terraform {
  required_providers {
    teleport = {
      source  = "terraform.releases.teleport.dev/gravitational/teleport"
      version = "(=teleport.plugin.version=)"
    }
  }
}

provider "teleport" {
  addr = "example.teleport.sh:443"
  join_method = "env0"
  join_token = "terraform"
}

resource "teleport_role" "test" {
  version = "v7"
  metadata = {
    name        = "test"
    description = "Dummy role to validate Terraform Provider setup"
    labels = {
      test = "yes"
    }
  }
}

5/5단계. Terraform 실행하기#

이제 Terraform plan 또는 apply를 수행할 수 있습니다. CLI, API, Git 등 모든 유형의 트리거가 작동합니다.

로컬 terraform이 env zero에 인증되어 있고 Remote Plan이 구성된 경우 다음을 실행할 수 있습니다:

$ terraform plan

그렇지 않은 경우 일반적으로 사용하는 방법(수동, Git 훅 등)으로 작업 실행을 트리거할 수 있습니다.

트리거 방법에 관계없이, Terraform 구성에 따라 워크플로가 성공적으로 실행되어야 합니다. tctl을 사용하여 더미 역할이 생성되었는지 확인할 수 있습니다:

$ tctl get role/test

다음 단계#

• Terraform과 env zero로 Teleport 구성 리소스를 관리하는 방법을 알았다면, 구성을 구체화할 수 있도록 Terraform 리소스 참조를 읽어보세요.
• Machine & Workload ID가 Teleport 클러스터에 인증하는 데 사용하는 env zero의 OIDC 구현에 대해 자세히 알아보려면 env zero 문서를 읽어보세요.