이 가이드에서는 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 및 클라우드 가이드를 참조하세요.

사전 요구 사항#

• A running Teleport Enterprise cluster. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

• The tctl and tsh clients.

  Installing `tctl` and `tsh` clients

  1. Determine the version of your Teleport cluster. The tctl and tsh clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at /v1/webapi/find and use a JSON query tool to obtain your cluster version. Replace with the web address of your Teleport Proxy Service:

     $ TELEPORT_DOMAIN=
     $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"
     

  2. Follow the instructions for your platform to install tctl and tsh clients:

To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials.

For example, run the following command, assigning to the domain name of the Teleport Proxy Service in your cluster and to your Teleport username:

$ tsh login --proxy= --user=
$ tctl status
# Cluster  (=teleport.url=)
# Version  (=teleport.version=)
# CA pin   (=presets.ca_pin=)

If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

• 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) 값을 결정하거나 지원을 요청해야 할 때 유용할 수 있습니다.