이 가이드에서는 다음 환경에서 Teleport Terraform Provider를 실행하는 방법을 설명합니다:

• 다음 CI/CD 파이프라인에서:
  • GitHub Actions (github 조인 메서드 사용)
  • GitlabCI (gitlab 조인 메서드 사용)
  • CircleCI (circleci 조인 메서드 사용)
• 다음 클라우드 VM에서:
  • AWS (aws 조인 메서드 사용)
  • GCP (gcp 조인 메서드 사용)

참고: Azure, Kubernetes 파드 내부 및 TPM(Trusted Platform Module)이 있는 서버에서도 기본 머신 & 워크로드 아이덴티티로 Terraform 공급자를 실행할 수 있습니다. 해당 설정은 이 가이드에서 자세히 설명하지 않지만, 일반적인 머신 & 워크로드 아이덴티티 가이드를 따르고 "tbot 구성" 단계를 공급자에게 조인 메서드와 토큰을 전달하는 것으로 대체할 수 있습니다.

• Azure 머신 & 워크로드 아이덴티티 가이드
• Kubernetes 머신 & 워크로드 아이덴티티 가이드
• TPM 머신 & 워크로드 아이덴티티 가이드

HCP Terraform (Terraform Cloud)과 자체 호스팅 Terraform Enterprise는 지원되지만 특별한 구성이 필요합니다. 전용 가이드를 참조하세요.

이 가이드는 Teleport를 로컬에서, 전용 서버에서 또는 특정 플랫폼에서 실행하는 것을 다루지 않습니다. 해당 경우에 대한 더 구체적인 가이드는 다음을 참조하세요:

• Terraform Provider 로컬에서 실행
• 서버에서 Teleport Terraform Provider 실행
• Spacelift에서 Teleport Terraform Provider 실행

작동 방식#

이 설정은 런타임(CI/CD 시스템, 클라우드 공급자, 컨테이너 엔진 등)에 아이덴티티 증명을 요청합니다. 이 증명은 Terraform 공급자가 Teleport에 연결하고 자격 증명을 얻기 위해 직접 사용됩니다. 이 설정에서는 Terraform 공급자가 기본적으로 아이덴티티 증명을 얻고 Teleport 클러스터에 조인할 수 있으므로 tbot 데몬이 필요하지 않습니다.

이 설정은 Teleport에 위임된 조인 메서드가 있는 선택적 런타임(예: GitHub Actions, GitLab CI 등)에서만 작동합니다.

사전 요구사항#

다음 중 하나가 필요합니다:

• Terraform이 설치된 GCP 또는 AWS VM
• GitHub Actions, GitLab CI 또는 CircleCI 작업을 실행할 수 있는 git 저장소

또한 다음이 필요합니다:

• A running Teleport 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:

1단계/4단계: Terraform 공급자 봇 생성#

이 단계에서는 terraform이라는 봇을 생성합니다.

terraform-bot.yaml이라는 파일을 생성합니다:

kind: bot
version: v1
metadata:
  name: terraform
spec:
  # The terraform-provider is a default role shipped in Teleport granting access
  # to every resource supported by the terraform provider.
  roles: ["terraform-provider"]

그런 다음 tctl로 적용합니다:

$ tctl create terraform-bot.yaml

This is an admin-level action and requires MFA to complete
Tap any security key
Detected security key tap
bot "terraform" has been created

이 시점에서 새 봇을 확인할 수 있습니다:

$ tctl bots ls

Bot       User          Roles
--------- ------------- ------------------
terraform bot-terraform terraform-provider

2단계/4단계: 봇 조인 토큰 생성#

이 단계에서는 이전에 생성한 terraform 봇으로 프로세스가 Teleport에 연결할 수 있도록 하는 토큰을 생성합니다.

토큰 유형과 구성은 Terraform 공급자가 실행되는 위치에 따라 다릅니다. 조인 프로세스, 다양한 조인 메서드, 토큰 유형 및 지원 필드에 대한 자세한 내용은 조인 참조를 참조하세요.

GitHub Actions의 경우:

의 GitHub Actions 워크플로에서 Terraform Provider가 조인하도록 허용하려면 다음 terraform-bot-token.yaml을 생성합니다:

kind: token
version: v2
metadata:
  name: terraform-bot
spec:
  roles: [Bot]
  join_method: github
  bot_name: terraform
  github:
    # allow specifies rules that control which GitHub Actions runs will be
    # granted access. Those not matching any allow rule will be denied.
    allow:
    - repository:  name="organization/repository"/>

GitLab CI의 경우:

GitLab 인스턴스의 에 있는 GitLab CI 파이프라인에서 Terraform Provider가 조인하도록 허용하려면 다음 terraform-bot-token.yaml을 생성합니다:

kind: token
version: v2
metadata:
  name: terraform-bot
spec:
  roles: [Bot]
  join_method: gitlab
  bot_name: terraform
  gitlab:
    # domain should be the domain of your GitLab instance. If you are using
    # GitLab's cloud hosted offering, omit this field entirely.
    domain:  name="gitlab.example.com" />
    # allow specifies rules that control which GitLab tokens will be accepted
    # by Teleport. Tokens not matching any allow rule will be denied.
    allow:
      - project_path:  name="group/project"/>

CircleCI의 경우:

Teleport 클러스터에 연결이 허용될 CircleCI 워크플로에 대한 규칙을 구성하려면 CircleCI 조직 ID를 확인하고 CircleCI 컨텍스트를 생성해야 합니다.

CircleCI를 열고 내비게이션 바에서 "Organization settings"로 이동합니다. "Organization ID" 섹션이 있는 "Overview" 인터페이스가 표시됩니다. 이 값을 기록하고 구성 예시에서 를 대체합니다.

CircleCI에는 **컨텍스트(contexts)**라는 조직 수준 개념이 있으며, 이를 통해 워크플로 작업에 노출되어야 하는 일련의 시크릿을 구성할 수 있습니다. CircleCI는 컨텍스트와 관련된 작업을 트리거할 수 있는 행위자를 제어하도록 구성할 수 있습니다.

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

CircleCI에서 "Organization settings"를 열고 "Contexts"로 이동합니다. "Create Context"를 클릭하고 를 컨텍스트 이름으로 제공합니다. 이 값을 조직에 더 적합한 문자열로 대체할 수 있지만, 이 가이드의 이후 단계에서 를 사용자 값으로 교체해야 합니다.

방금 생성한 컨텍스트를 선택합니다. 컨텍스트를 구성할 수 있는 페이지에 있습니다. Teleport 구성에 사용할 컨텍스트 ID를 확인하려면 다음과 유사한 형식의 컨텍스트 설정 페이지 URL을 찾습니다:

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

이 경우 컨텍스트 ID는 00000000-0000-0000-0000-000000000000입니다.

이 값을 기록하고 구성 예시에서 를 컨텍스트 ID로 대체합니다.

그런 다음 를 컨텍스트 ID로 바꿔 다음 terraform-bot-token.yaml을 생성합니다:

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

AWS의 경우:

다음이 있는지 확인합니다:

• Teleport 클러스터에 대한 접근을 부여하려는 AWS IAM 역할. 이 역할에는 sts:GetCallerIdentity가 부여되어야 합니다. 이 가이드에서 이 역할은 로 이름이 지정됩니다.
• Terraform 공급자를 실행하려는 곳에 IAM 역할이 연결된 AWS EC2 가상 머신.
• AWS 계정 ID:

그런 다음 다음 terraform-bot-token.yaml을 생성합니다:

kind: token
version: v2
metadata:
  name: terraform-bot
spec:
  roles: [Bot]
  bot_name: terraform
  join_method: iam
  allow:
    - aws_account: "111111111111" />"
      aws_arn: "arn:aws:sts::organization-id" />:assumed-role/ name="instance-iam-role" />/i-*"

GCP의 경우:

다음이 있는지 확인합니다:

• 공급자를 실행하려는 VM에 연결된 GCP 서비스 계정(SA). 기본 컴퓨팅 SA일 수 없습니다. 이 가이드에서 이 SA는 로 이름이 지정됩니다.
• GCP 프로젝트 ID:

그런 다음 다음 terraform-bot-token.yaml을 생성합니다:

kind: token
version: v2
metadata:
  name: terraform-bot
spec:
  roles: [Bot]
  bot_name: terraform
  join_method: gcp
  gcp:
    allow:
    - project_ids:
        - "my-project-123456" />"
      service_accounts:
        - "my-service-account" />@ name="my-project-123456" />.iam.gserviceaccount.com"

terraform-bot-token.yaml 매니페스트에 설명된 봇 토큰을 생성합니다:

$ tctl create -f terraform-bot-token.yaml

This is an admin-level action and requires MFA to complete
Tap any security key
Detected security key tap
provision_token "terraform-bot" has been created

3단계/4단계: Terraform 공급자 구성#

이 단계에서는 공급자가 Teleport 클러스터에 연결하고 이전에 생성한 토큰으로 조인하도록 구성하는 최소한의 Terraform 코드를 작성합니다.

이를 위해 다음이 필요합니다:

• 포트를 포함한 Teleport 클러스터 도메인: . Web UI에 접근할 때 URL에서 찾을 수 있습니다.
• 생성한 토큰의 조인 메서드. 이는 terraform-bot-token.yaml의 spec.join_method 필드입니다: .

다음 최소한의 main.tf 파일을 생성합니다:

terraform {
  required_providers {
    teleport = {
      source  = "terraform.releases.teleport.dev/gravitational/teleport"
      version = "~> (=teleport.major_version=).0"
    }
  }
}

provider "teleport" {
  addr        = ""
  join_method = ""
  join_token  = "terraform-bot"
}

# We must create a test role, if we don't declare resources, Terraform won't try to
# connect to Teleport and we won't be able to validate the setup.
resource "teleport_role" "test" {
  version = "v7"
  metadata = {
    name        = "test"
    description = "Dummy role to validate Terraform Provider setup"
    labels = {
      test = "yes"
    }
  }

  spec = {}
}

• GitHub Actions의 경우: main.tf 파일을 GitHub Actions 파이프라인을 실행하는 GitHub 저장소에 복사합니다.
• GitLab CI의 경우: main.tf 파일을 GitLab CI 파이프라인을 실행하는 GitLab 저장소에 복사합니다.
• CircleCI의 경우: main.tf 파일을 CircleCI 파이프라인을 실행하는 Git 저장소에 복사합니다.
• AWS의 경우: main.tf 파일을 Terraform을 실행할 AWS VM에 복사합니다.
• GCP의 경우: main.tf 파일을 Terraform을 실행할 GCP VM에 복사합니다.

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

이 단계에서는 환경에 따라 Terraform을 실행하는 최소한의 예시를 보여줍니다. 이 코드는 프로덕션 용도에 적합하지 않은 기본 로컬 백엔드를 사용합니다. 특히 CI에서는 CI 파이프라인 간에 Terraform 상태가 유지되도록 비로컬 Terraform 백엔드를 사용해야 합니다.

GitHub Actions의 경우:

Terraform 코드가 포함된 저장소에서 다음 내용으로 .github/workflows/teleport-terraform.yaml 파일을 생성합니다:

name: Teleport Terraform Demo
# This is a basic workflow to help you get started.
# It will take the following action whenever a push is made to the "main" branch.
on:
  push:
    branches:
    - main
jobs:
  demo:
    permissions:
      # The "id-token: write" permission is required or Machine & Workload
      # Identity will not be able to authenticate with the cluster.
      id-token: write
      contents: read
    name: terraform-plan
    runs-on: ubuntu-latest

    # You can find more advanced TF workflows at https://github.com/hashicorp/setup-terraform
    steps:
    - uses: actions/checkout@v4
    - uses: hashicorp/setup-terraform@v3
    - name: Terraform Init
      id: init
      run: terraform init
    - name: Terraform Plan
      id: plan
      run: terraform plan -no-color

변경 사항을 커밋하고 main 브랜치에 푸시하여 GitHub Actions 워크플로를 트리거합니다. 워크플로 로그에서 성공적인 Terraform 계획을 볼 수 있습니다.

GitLab CI의 경우:

클러스터 이름을 검색합니다:

$ tctl status

Cluster       
Version       16.2.0
# ...

Terraform 코드가 포함된 저장소에서 .gitlab-ci.yaml 파일이 없으면 생성하고 다음 내용을 추가합니다:

stages:
  - plan
image:
  name: hashicorp/terraform:1.9
  entrypoint: [""]
terraform-job:
  stage: plan
  # id_tokens configures ID Tokens that GitLab will automatically inject into
  # the environment of your GitLab run.
  #
  # See https://docs.gitlab.com/ee/ci/secrets/id_token_authentication.html
  # for further explanation of the id_tokens configuration in GitLab.
  id_tokens:
    TBOT_GITLAB_JWT:
      # aud for TBOT_GITLAB_JWT must be configured with the name of your
      # Teleport cluster. This is not necessarily the address of your Teleport
      # cluster and will not include a port or scheme (http/https)
      #
      # This helps the Teleport Auth Service know that the token is intended for
      # it, and not a different service or Teleport cluster.
      aud: "teleport.example.com"/>"
  script:
    - terraform init
    - terraform plan

변경 사항을 커밋하고 아무 브랜치에 푸시하여 GitLab CI 파이프라인을 트리거합니다. 파이프라인 로그에서 성공적인 Terraform 계획을 볼 수 있습니다.

CircleCI의 경우:

Terraform 코드가 포함된 저장소에서 .circleci/config.yml에 다음 CircleCI 구성을 추가합니다:

version: '2.1'
orbs:
  terraform: circleci/terraform@3.1
workflows:
  deploy_infrastructure:
    jobs:
      - terraform/init:
          tag: 1.9.5
          checkout: true
          context:  name="teleport-access" />
      - terraform/plan:
          tag: 1.9.5
          context:  name="teleport-access" />
          requires:
            - terraform/init

변경 사항을 커밋하고 아무 브랜치에 푸시하여 CircleCI 파이프라인을 트리거합니다. 파이프라인 로그에서 성공적인 Terraform 계획을 볼 수 있습니다.

AWS의 경우:

EC2 인스턴스에서 Terraform 명령을 실행합니다:

$ terraform init
Initializing the backend...

Initializing provider plugins...
- Finding terraform.releases.teleport.dev/gravitational/teleport versions matching ...

$ terraform plan
Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # teleport_role.test will be created
  + resource "teleport_role" "test" {
      + id       = (known after apply)
      + kind     = (known after apply)
      + metadata = {
          + name      = "test"
          + namespace = (known after apply)
        }
      + spec     = {}
      + version  = "v7"
    }

Plan: 1 to add, 0 to change, 0 to destroy.

GCP의 경우:

GCP VM에서 Terraform 명령을 실행합니다:

$ terraform init
Initializing the backend...

Initializing provider plugins...
- Finding terraform.releases.teleport.dev/gravitational/teleport versions matching ...

$ terraform plan
Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # teleport_role.test will be created
  + resource "teleport_role" "test" {
      + id       = (known after apply)
      + kind     = (known after apply)
      + metadata = {
          + name      = "test"
          + namespace = (known after apply)
        }
      + spec     = {}
      + version  = "v7"
    }

Plan: 1 to add, 0 to change, 0 to destroy.