이 가이드에서는 HCP Terraform 또는 Terraform Enterprise를 사용하여 Teleport용 Terraform 프로바이더를 사용하는 방법을 설명합니다.

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

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

동작 방식#

Terraform Cloud에서 Teleport Terraform 프로바이더를 실행할 때, 내장된 머신 및 워크로드 아이덴티티 지원을 사용하여 공유 비밀 없이 Teleport 클러스터에 동적으로 인증할 수 있습니다. 이 구성으로 실행할 때, Terraform 프로바이더는 Terraform Cloud의 워크로드 아이덴티티 토큰을 사용하여 Teleport Auth Service에 자신의 ID를 증명합니다.

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

이 가이드는 공개 HCP Terraform(Terraform Cloud라고도 함)과 자체 호스팅 Terraform Enterprise 모두에 적용됩니다. Spacelift와 같은 다른 CI/CD 플랫폼에서 실행되는 Terraform 또는 OpenTofu에는 적용되지 않으므로, 이러한 환경에서 프로바이더를 구성하려면 일반 CI 및 클라우드 가이드를 참조하세요.

사전 요구 사항#

• 실행 중인 Teleport Enterprise 클러스터. 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 이상이 필요합니다.

• 공개 Terraform Cloud SaaS 또는 Terraform Enterprise 인스턴스의 계정 및 프로젝트

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

1/4단계: Teleport에서 Terraform Cloud 참여 구성하기#

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

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

다음으로, 새 봇이 Terraform Cloud 워크로드 아이덴티티 자격 증명으로 인증할 수 있어야 합니다. Terraform Cloud 또는 자체 호스팅 Terraform Enterprise 중 어느 것을 사용하는지에 따라 다음 내용으로 terraform_token.yaml이라는 파일을 생성합니다:

kind: token
version: v2
metadata:
  name: terraform
spec:
  roles: [Bot]
  join_method: terraform_cloud
  bot_name: terraform
  terraform_cloud:
    allow:
      - organization_name: ExampleOrganization
        project_name: example-project
        workspace_name: example-workspace

kind: token
version: v2
metadata:
  name: terraform
spec:
  roles: [Bot]
  join_method: terraform_cloud
  bot_name: terraform
  terraform_cloud:
    hostname: terraform.example.com
    allow:
      - organization_name: ExampleOrganization
        project_name: example-project
        workspace_name: example-workspace

terraform이라는 이름의 이 토큰은 토큰에 허용된 3개 값이 모두 Terraform Cloud가 실행하는 작업의 값과 일치할 때 Terraform Cloud 실행이 Teleport에 인증할 수 있도록 합니다.

Terraform Cloud 프로젝트 또는 프로젝트와 일치하도록 조직, 프로젝트, 워크스페이스 이름을 교체해야 합니다. 원하는 경우 정확한 리소스 ID를 지정하기 위해 organization_id, project_id, workspace_id 필드를 사용할 수도 있습니다. 값은 Terraform Cloud 대시보드에 표시된 것과 정확히 일치해야 합니다.

각 allow 규칙은 최소한 organization_name 또는 organization_id 중 하나와 다른 옵션(워크스페이스 및/또는 프로젝트) 중 하나를 지정해야 합니다. 원하는 경우 workspace_name(또는 workspace_id)을 설정하지 않아 프로젝트 아래의 모든 워크스페이스를 허용할 수 있습니다. 원하는 만큼 allow 규칙을 지정할 수 있으며, 실행이 참여할 수 있으려면 최소한 하나가 일치해야 합니다.

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

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

2/4단계: 워크로드 아이덴티티 토큰을 발급하도록 Terraform Cloud 구성하기#

실행 중에 JWT를 발급하도록 Terraform Cloud를 구성해야 합니다. 이를 위해 Terraform Cloud 대시보드에 환경 변수만 설정하면 됩니다. 방법은 다음과 같습니다:

1. https://app.terraform.io/으로 이동합니다
2. 원하는 조직, 프로젝트, 워크스페이스로 이동합니다
3. 워크스페이스 사이드바에서 "Variables"를 선택합니다
4. "Workspace Variables" 아래에서 "Add variable" 버튼을 클릭합니다
5. "Environment variable"("env") 카테고리를 선택합니다
6. 키로 TFC_WORKLOAD_IDENTITY_AUDIENCE_TELEPORT를 입력합니다
7. 값으로 Teleport 클러스터 이름을 입력합니다. Teleport Enterprise (Cloud)를 사용하는 경우 example.teleport.sh와 같이 표시됩니다.
8. 원하는 경우 설명을 입력합니다. 예를 들어 "Workload identity token request for Teleport"

최종 결과는 다음과 같아야 합니다:

이 변수가 설정되면 이 워크스페이스의 모든 후속 실행에 변수 값에 구성된 대상, 즉 여기 표시된 것처럼 example.teleport.sh로 JWT가 발급됩니다.

3/4단계: Terraform 프로바이더 구성하기#

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

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

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

• addr는 Teleport 클러스터의 공개 호스트명과 포트와 일치해야 합니다
• join_method는 terraform_cloud이어야 합니다. Terraform Enterprise도 1단계에서 구성된 호스트명으로 동일한 참여 방법을 사용합니다.
• join_token은 2단계에서 생성한 token 리소스의 이름과 일치해야 합니다
• audience_tag는 Terraform Cloud 대시보드에서 생성한 변수 키의 접미사와 일치해야 합니다. 예를 들어 변수 키가 TFC_WORKLOAD_IDENTITY_AUDIENCE_TELEPORT인 경우 audience_tag는 teleport이어야 합니다.

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

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

terraform {
  cloud {
    organization = "ExampleOrganization"

    workspaces {
      name = "example-workspace"
    }
  }

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

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

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

4/4단계: Terraform 실행하기#

이제 Terraform plan 또는 apply를 수행할 수 있습니다. CLI, API, Git 등 모든 유형의 트리거가 작동합니다. 단, 실행이 Terraform Cloud에 의해 조율되어야 합니다.

로컬 terraform이 Terraform Cloud에 인증되어 있다고 가정하고 다음을 시도해 보세요:

$ terraform plan

Terraform 구성에 따라 워크플로가 성공적으로 실행됩니다.

문제 해결#

디버깅 목적으로 JWT 추출하기#

디버깅 목적으로 JWT 샘플을 보아야 하는 경우, 실행에 대한 JWT를 출력하는 null_resource를 생성할 수 있습니다:

resource "null_resource" "print_token" {
  provisioner "local-exec" {
    command = "echo TFC_WORKLOAD_IDENTITY_TOKEN_TELEPORT: $TFC_WORKLOAD_IDENTITY_TOKEN_TELEPORT"
  }
}

적용되면 Terraform 로그에 인코딩된 JWT가 출력됩니다. 이 값은 수동으로 또는 jwt-cli와 같은 다양한 도구를 사용하여 디코딩할 수 있습니다.

이 JWT는 일반적으로 2시간 동안 유효하며 Teleport 클러스터에 인증하는 데 잠재적으로 사용될 수 있으므로 이 값을 신중하게 다뤄야 합니다. 완전히 인코딩된 토큰은 공유하지 마세요.

이는 Terraform Enterprise 참여 토큰을 구성하는 데 필요한 정확한 발급자(iss) 값을 결정하거나 지원을 요청해야 할 때 유용할 수 있습니다.