📣 Teleport의 공식 파트너 인포그랩에서 OpenAI 기술 기반으로 자체 개발한 자동화 번역 프로그램을 통해 Teleport 공식 문서(v17.0.0)의 한글판을 국내 최초로 제공합니다.
Infograb logo
Terraform Cloud에서 Teleport Terraform 제공자를 실행하는 방법

이 가이드는 HCP Terraform 또는 Terraform Enterprise를 사용하여 Teleport를 위한 Terraform 제공자를 사용하는 방법을 보여줍니다.

이 가이드는 로컬에서 Terraform 제공자를 실행하는 것, 다른 CI/CD 환경에서 실행하는 것 또는 단기 클라우드 VM에서 실행하는 것을 다루지 않습니다. 이러한 경우에는 전용 가이드를 참조하십시오:

작동 방식

Enterprise

자체 호스팅된 Terraform Enterprise에 가입하는 Terraform Cloud는 Teleport Enterprise가 필요합니다. 공용 HCP Terraform (https://app.terraform.io)에 가입하는 Terraform Cloud는 Teleport Community Edition에서 지원됩니다.

Terraform Cloud에서 Teleport Terraform 제공자를 실행할 때, 공유 비밀 없이 Teleport 클러스터에 동적으로 인증하기 위해 내장된 Machine ID 지원을 사용할 수 있습니다. 이 구성에서 Terraform 제공자는 Terraform Cloud의 Workload Identity 토큰을 사용하여 Teleport Auth 서비스에 자신의 신원을 증명합니다.

이 가이드를 따르면서, Terraform Cloud 실행으로부터의 조인 요청을 수락하도록 Teleport 클러스터를 구성하고, Terraform Cloud 조인 방법을 사용하여 인증하도록 제공자를 구성할 것입니다.

이 가이드는 공용 HCP Terraform 또는 자체 호스팅된 Terraform Enterprise 모두에 적용됩니다. 이는 Spacelift와 같은 다른 CI/CD 플랫폼에서 실행되는 Terraform 또는 OpenTofu에는 적용되지 않습니다. 이러한 환경에서 제공자를 구성하려면 일반 CI 및 클라우드 가이드를 참조하십시오.

전제 조건

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

  • Terraform >= 1.0.0+

    terraform version
    Terraform v1.0.0

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

  • 공용 Terraform Cloud SaaS 또는 Terraform Enterprise 인스턴스에서 계정 및 프로젝트가 필요합니다.

  • Teleport Terraform 제공자, v16.4.0 이상이 필요합니다.

1/4 단계: Teleport에서 Terraform Cloud 조인 구성

시작하려면, Teleport Auth 서비스가 Terraform Cloud 실행으로부터의 조인 요청을 수락하도록 구성해야 합니다. 이를 위해 terraform 이라는 봇을 생성할 것입니다. 이는 나중에 Teleport Terraform 제공자가 사용할 것입니다.

kind: bot
version: v1
metadata:
  name: terraform
spec:
  # terraform-provider 역할은 terraform 제공자가 지원하는 모든 리소스에 대한 액세스 권한을 부여하는 내장 역할입니다.
  roles: ["terraform-provider"]

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

tctl create -f terraform_bot.yaml
봇 'terraform'이 생성되었습니다.

다음으로, 새 봇이 Terraform Cloud Workload Identity 자격 증명으로 인증할 수 있도록 허용해야 합니다. 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
Enterprise

Terraform Enterprise 조인을 사용하려면 Teleport Enterprise가 필요합니다.

자체 호스팅된 Terraform Enterprise 설치는 추가적으로 hostname 매개변수를 구성해야 합니다:

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

이 hostname 값은 Terraform Enterprise 실행에 발급된 JWT의 iss 매개변수와 일치해야 하며, https:// 접두사는 제외합니다. 자세한 내용은 Terraform Enterprise 문서를 참조하십시오. hostname 이 구성되지 않으면 Terraform Cloud 발급자로 기본 설정되어 조인 시도가 실패합니다.

이 terraform 이라는 이름의 토큰은 Terraform Cloud 실행이 Teleport와 인증할 수 있도록 허용합니다. 이 토큰의 세 값이 Terraform Cloud에서 실행되는 작업의 값과 일치해야 합니다.

조직, 프로젝트 및 작업 공간 이름은 귀하의 Terraform Cloud 프로젝트와 일치하도록 변경해야 합니다. 원하는 경우, organization_id , project_id 및 workspace_id 필드도 사용하여 정확한 리소스 ID를 지정할 수 있습니다. 해당 값은 Terraform Cloud 대시보드에 표시된 것과 정확히 일치해야 합니다.

각 allow 규칙은 최소한 organization_name 또는 organization_id 를 지정해야 하며, 최소한 하나 이상의 다른 옵션(작업 공간 및/또는 프로젝트)을 지정해야 합니다. 원하는 경우, 작업 공간 이름(workspace_name 또는 workspace_id )을 설정하지 않으면 프로젝트 내의 모든 작업 공간을 허용할 수 있습니다. 원하는 만큼 많은 allow 규칙을 지정할 수 있으며, 최소 한 개가 일치해야 실행이 조인할 수 있습니다.

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

tctl create -f terraform_token.yaml
토큰 'terraform'이 생성되었습니다.

2단계/4: Terraform Cloud에서 Workload Identity 토큰 발행 구성

Terraform Cloud는 실행 중에 JWT를 발행하도록 구성되어야 합니다. 이를 위해서는 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. 원하신다면 설명을 입력합니다. 예: "Teleport에 대한 Workload identity token 요청"

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

이 변수가 설정되면, 이 작업 공간에서의 모든 후속 실행은 변숫값에 구성된 audience와 함께 JWT를 발급받게 됩니다. 즉, 여기서 보여주는 example.teleport.sh 입니다.

3단계/4: Terraform Provider 구성

provider.tf 또는 유사한 파일에서 teleport provider를 구성하세요:

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 = "13.3.7"
    }
  }
}

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 = "Terraform Provider 설정을 검증하기 위한 더미 역할"
    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 ) 값을 결정하거나 지원 요청이 필요할 경우 유용할 수 있습니다.

Teleport 원문 보기
인포레터에서 최신 DevOps 트렌드를 격주로 만나보세요!