terraform 블록 참조

terraform 블록 참조 (terraform block reference)

이 주제는 terraform 블록에 대한 참조 정보를 제공해요. terraform 블록을 사용해 Terraform 버전, 백엔드, HCP Terraform 통합, 필요한 프로바이더를 포함한 Terraform 동작을 구성할 수 있어요.

출처: 문서

본문

구성 모델 (Configuration model)

다음 목록은 terraform 블록의 속성 계층, 데이터 타입, 요구 사항을 간략히 보여줘요. 자세한 내용은 속성을 클릭하세요.

terraform
- required_version 문자열
- required_providers 블록
  - <PROVIDER> 블록
    - version 문자열
    - source 문자열
- provider_meta "<LABEL>" 블록
- backend "<BACKEND_TYPE>" 블록 | cloud와 상호 배타적
- cloud 블록 | backend와 상호 배타적
  - organization 문자열 | HCP Terraform 연결 시 필수
  - workspaces 블록 | HCP Terraform 연결 시 필수
    - tags 리스트 | name과 상호 배타적
    - name 문자열 | tags와 상호 배타적
    - project 문자열
  - hostname 문자열 | app.terraform.io
  - token 문자열
- experiments 리스트

완전한 구성 (Complete configuration)

다음 terraform 블록은 설정할 수 있는 모든 지원 내장 인자를 정의해요:

terraform {
  required_version = "<version>"
  required_providers {
    <PROVIDER> {
      version = "<version-constraint>"
      source = "<provider-address>"
    }
  }
  provider_meta "<LABEL>" { 
    # Shown for completeness but only used for specific cases     
  }
  backend "<TYPE>" {        
    # `backend` is mutually exclusive with `cloud` 
    "<ARGUMENTS>"
  }
  cloud {                   
    # `cloud` is mutually exclusive with `backend` 
    organization = "<organization-name>"
    workspaces {
      tags = [ "<tag>" ]
      name = "<workspace-name>"
      project = "<project-name>"
    }
    hostname = "app.terraform.io"
    token = "<TOKEN>"
  }
  experiments = [ "<feature-name>" ]
}

명세 (Specification)

terraform 블록은 다음 구성을 지원해요.

`terraform` 블록

Terraform 동작을 정의하는 구성을 포함하는 부모 블록이에요. terraform 블록에서는 상수 값만 사용할 수 있어요. terraform 블록의 인자는 리소스 및 입력 변수 같은 명명된 객체를 참조할 수 없어요. 또한 블록에서 내장 Terraform 언어 함수를 사용할 수 없어요.

`required_version`

구성을 실행할 수 있는 Terraform CLI 버전을 지정해요.

terraform {
  required_version = "<Terraform version>"
  # . . .
}

버전 제약 지정의 지원 문법에 대한 자세한 내용은 버전 제약 (Version constraints)을 참고하세요.

협업 환경에서 Terraform 버전 제약을 사용해 모든 사람이 특정 Terraform 버전을 사용하거나, 구성이 기대하는 동작을 가진 최소 Terraform 버전 이상을 사용하도록 하세요.

버전 제약을 충족하지 않는 Terraform 버전으로 구성을 실행하면 Terraform은 오류를 출력하고 작업 없이 종료해요.

구성과 연결된 모듈도 버전 제약을 지정할 수 있어요. 작업을 수행하려면 모듈에 정의된 제약을 포함해 구성과 연결된 모든 버전 제약을 충족하는 Terraform 버전을 사용해야 해요. Terraform 모듈에 대한 자세한 내용은 모듈 (Modules)을 참고하세요.

required_version 구성은 Terraform CLI 버전에만 적용되며 프로바이더 플러그인 버전에는 적용되지 않아요. 자세한 내용은 프로바이더 요구 사항 (Provider Requirements)을 참고하세요.

요약

데이터 타입: 문자열.
기본값: 없음.
예제:프로바이더 추가

`required_providers`

구성에 지정된 리소스를 생성하고 관리하는 데 필요한 모든 프로바이더 플러그인을 지정해요.

terraform {
  required_providers {
    <PROVIDER> {}
  }
  # . . .
}

각 로컬 프로바이더 이름은 소스 주소와 버전 제약에 매핑돼요. required_providers 블록에서 속성을 구성하는 방법에 대한 지침은 공개 Terraform Registry의 각 Terraform 프로바이더 문서 또는 프라이빗 registry를 참고하세요.

요약

데이터 타입: 블록.
기본값: 없음.
예제:프로바이더 추가

프로바이더 특정 설정 (Provider-specific settings)

필수로 지정하려는 프로바이더의 이름을 지정해요. 프로바이더 구성 방법에 대한 지침은 구성 제공 (Provide Configuration)을 참고하세요.

terraform {
  required_providers {
    <PROVIDER> {
      version = "<version-constraint>"
      source = "<address>"      
    }
  }
  # . . .
}

다음 인자를 지정할 수 있어요:

인자	설명	데이터 타입	기본값
`version`	이 구성이 사용해야 하는 프로바이더 버전을 지정해요. 연산자를 사용해 버전 범위를 지정하도록 버전을 제한할 수 있어요. 자세한 내용은 버전 제약 (Version constraints)을 참고하세요.	문자열	Terraform은 기본적으로 최신 버전을 설치해요.
`source`	프로바이더의 전역 소스 주소를 지정해요. 자세한 내용은 프로바이더 요구 (Requiring Providers)을 참고하세요.	문자열	없음

요약

데이터 타입: 블록.
기본값: 없음.
예제:프로바이더 추가

`provider_meta "<LABEL>"`

프로바이더가 기대할 수 있는 메타데이터 필드를 지정해요.

terraform {
  provider_meta {
    <DATA>
  }
  # . . .
}

개별 모듈은 프로바이더 구성과 독립적으로 메타데이터 필드를 채울 수 있어요. 자세한 내용은 프로바이더 메타데이터 (Provider Metadata)를 참고하세요.

요약

데이터 타입: 블록.
기본값: 없음.

`backend "<BACKEND_TYPE>"`

Terraform state 파일을 저장하는 메커니즘을 지정해요.

terraform {
  backend "<TYPE>" {
    <backend-configuration>
  }
  # . . .
}

backend 블록은 인자로 백엔드 타입을 받아요. backend 블록 구성에 대한 자세한 내용은 백엔드 구성 (Backend Configuration)을 참고하세요.

구성이 state 데이터를 저장하는 cloud 구성도 포함할 때는 backend 블록을 구성할 수 없어요.

요약

데이터 타입: 블록.
기본값: local

`cloud`

Terraform 구성이 HCP Terraform 또는 Terraform Enterprise 설치에 연결할 수 있게 하는 일련의 속성을 지정해요.

terraform {
  cloud  {
    <cloud-configuration>
  }
  # . . .
}

HCP Terraform과 Terraform Enterprise는 state 저장, 원격 실행 및 기타 이점을 제공해요. 자세한 내용은 HCP Terraform 및 Terraform Enterprise 문서를 참고하세요.

구성당 cloud 블록은 하나만 제공할 수 있어요.

구성이 state 데이터를 저장하는 backend 구성도 포함할 때는 cloud 블록을 구성할 수 없어요.

cloud 블록은 입력 변수, 로컬 값, 데이터 소스 속성 같은 명명된 값을 참조할 수 없어요.

요약

데이터 타입: 블록.
기본값: 없음.
예제: HCP Terraform에 연결

`organization`

연결할 조직의 이름을 지정해요.

terraform {
  cloud  {
    organization = "<organization-name>"
  }
  # . . .
}

조직을 문자열로 하드코딩하는 대신 TF_CLOUD_ORGANIZATION 환경 변수를 사용할 수 있어요.

요약

데이터 타입: 문자열
HCP Terraform 연결 시 필수
예제: HCP Terraform에 연결

`workspaces`

HCP Terraform에서 워크스페이스 일치를 위한 메타데이터를 지정해요.

terraform {
  cloud  {
    workspaces {
      tags = [ "<workspace-tag>" ] # Mutually exclusive with `name`
      name = "<workspace-name>" # Mutually exclusive with `tags`
      project = "<project-name>"
    }            
  }
  # . . .
}

Terraform은 지정된 태그, 이름 또는 프로젝트와 일치하는 HCP Terraform에서 관리되는 워크스페이스와 구성을 연결해요. workspaces 블록에서 다음 메타데이터를 지정할 수 있어요:

속성	설명	데이터 타입
`tags`	키-값 태그의 문자열 맵 또는 단일 값의 키 전용 태그 목록을 지정해요. Terraform은 모든 태그와 일치하는 워크스페이스와 구성을 연결해요. 작업 디렉터리에서 만든 새 워크스페이스는 태그를 상속해요. 이 속성과 `name` 속성을 같은 구성에 설정할 수 없어요.	문자열 배열 또는 문자열 맵
`name`	Terraform 구성을 연결할 HCP Terraform 워크스페이스 이름을 지정해요. 작업 디렉터리는 구성에 명명된 워크스페이스에서만 사용할 수 있어요. Terraform CLI에서 워크스페이스를 관리할 수 없어요. 이 속성과 `tags` 속성을 같은 구성에 설정할 수 없어요. 단일 워크스페이스를 문자열로 하드코딩하는 대신 `TF_WORKSPACE` 환경 변수를 사용할 수 있어요.	문자열
`project`	HCP Terraform 프로젝트의 이름을 지정해요. Terraform은 이 구성을 사용하는 모든 워크스페이스를 프로젝트에 생성해요. 작업 디렉터리에서 `terraform workspace list` 명령을 사용하면 지정된 프로젝트의 워크스페이스만 반환해요. 프로젝트를 문자열로 하드코딩하는 대신 `TF_CLOUD_PROJECT` 환경 변수를 사용할 수 있어요.	문자열

요약

데이터 타입: 블록.
HCP Terraform 연결 시 필수
예제: HCP Terraform에 연결

`hostname`

Terraform Enterprise 배포의 호스트 이름을 지정해요.

terraform {
  cloud  {
    hostname = "app.terraform.io"
  }
  # . . .
}

Terraform Enterprise 배포의 호스트 이름을 하드코딩하는 대신 TF_CLOUD_HOSTNAME 환경 변수를 사용할 수 있어요.

요약

데이터 타입: 문자열.
Terraform Enterprise 연결 시 필수.
기본값: app.terraform.io
예제: Terraform Enterprise에 연결

`token`

HCP Terraform과 인증하기 위한 토큰을 지정해요.

terraform {
  cloud  {
    token = "<token>"
  }
  # . . .
}

구성에서 토큰을 생략하고 대신 terraform login 명령을 사용하거나 CLI 구성 파일에서 자격 증명을 수동으로 구성하는 것을 권장해요.

요약

데이터 타입: 문자열.
기본값: 없음.
예제: Terraform Enterprise에 연결

`experiments`

옵트인할 실험적 기능 이름 목록을 지정해요.

terraform {
  experiments = [ "<feature-name>" ]
  # . . .
}

실험적 기능을 사용할 수 있는 릴리스에서는 모듈별로 활성화할 수 있어요.

실험은 이후 릴리스에서 임의로 변경될 수 있으며, 실험 결과에 따라 최종 릴리스 전에 크게 변경되거나 안정적인 형태로 릴리스되지 않을 수도 있어요. 주요 변경 사항이 마이너 및 패치 릴리스에 나타날 수 있어요. 프로덕션용 Terraform 모듈에서 실험적 기능을 사용하는 것은 권장하지 않아요.

실험이 활성화된 모듈은 모든 terraform plan 또는 terraform apply 작업에서 경고를 생성해요. 공유 모듈에서 실험적 기능을 사용해 보려면 모듈의 알파 또는 베타 릴리스에서만 실험을 활성화하는 것을 권장해요.

실험에 대한 정보와 사용 가능한 실험 키워드에 대한 릴리스 노트를 모니터링하려면 Terraform 변경 로그를 참고하세요.

요약

데이터 타입: 리스트.
기본값: 없음.

`cloud` 블록용 환경 변수

환경 변수를 사용해 하나 이상의 cloud 블록 속성을 구성할 수 있어요. 이는 같은 Terraform 구성을 다른 HCP Terraform 조직 및 프로젝트에서 사용하려 할 때 유용해요. Terraform은 구성에 해당 속성을 정의하지 않은 경우에만 이 변수를 사용해요. cloud 블록을 전적으로 환경 변수로 구성하기로 했다면 구성 파일에 빈 cloud 블록을 여전히 추가해야 해요.

경고

환경 변수를 사용해 Terraform 작업을 자동화할 수 있으며, 이는 특정 보안 고려 사항이 있어요. 자세한 내용은 비대화형 워크플로우 (Non-Interactive Workflows)를 참고하세요.

cloud 블록을 구성하려면 다음 환경 변수를 사용하세요:

TF_CLOUD_ORGANIZATION - 조직의 이름. Terraform은 cloud 블록에서 organization이 생략될 때 이 변수를 읽어요. 둘 다 지정되면 구성이 우선해요.
TF_CLOUD_HOSTNAME - Terraform Enterprise 설치의 호스트 이름. Terraform은 cloud 블록에서 hostname이 생략될 때 이를 읽어요. 둘 다 지정되면 구성이 우선해요.
TF_CLOUD_PROJECT - HCP Terraform 프로젝트의 이름. Terraform은 cloud 블록에서 workspaces.project가 생략될 때 이를 읽어요. 둘 다 지정되면 클라우드 블록 구성이 우선해요.
TF_WORKSPACE - 단일 HCP Terraform 워크스페이스의 이름. Terraform은 cloud 블록에서 workspaces가 생략될 때 이를 읽어요. HCP Terraform은 이 변수에서 새 워크스페이스를 만들지 않아요. 워크스페이스는 지정된 조직에 존재해야 해요. cloud 블록이 태그를 사용하면 TF_WORKSPACE를 설정할 수 있어요. 그러나 TF_WORKSPACE의 값은 태그 집합에 포함되어야 해요. 이 변수는 로컬 환경에서 워크스페이스도 선택해요. 자세한 내용은 TF_WORKSPACE를 참고하세요.

예제 (Examples)

다음 예제는 일반적인 사용 사례에 대한 구성을 작성하는 방법을 보여줘요.

프로바이더 추가 (Add a provider)

다음 구성은 공개 Terraform registry에서 aws 프로바이더 버전 2.7.0 이상을 요구해요:

terraform {
  required_providers {
    aws = {
      version = ">= 2.7.0"
      source = "hashicorp/aws"
    }
  }
}

HCP Terraform에 연결 (Connect to HCP Terraform)

다음 예제에서 구성은 example_corp 조직에서 layer=app 태그를 포함하는 워크스페이스에 작업 디렉터리를 연결해요:

terraform {
  cloud {
    organization = "example_corp"
    workspaces {
      tags = {
        layer = "app"
      }
    }
  }
}

Terraform Enterprise에 연결 (Connect to Terraform Enterprise)

다음 예제에서 구성은 example_corp 조직에서 app 키 전용 태그를 포함하는 워크스페이스에 작업 디렉터리를 연결해요. 키 전용 태그는 v202411-1 이전 버전의 Terraform Enterprise 또는 v1.10 이전 버전의 Terraform에서 사용해야 해요. TF_CLOUD_HOSTNAME 환경 변수를 사용하지 않는 한 구성에서 hostname 필드가 필요해요:

terraform {
  cloud {
    organization = "example_corp"
    hostname = "my.terraform-enterprise.host"
    workspaces {
      tags = ["app"]
    }
  }
}

환경 변수를 사용해 Terraform Enterprise에 연결

다음 예제에서 Terraform은 TF_CLOUD_ORGANIZATION과 TF_CLOUD_HOSTNAME 환경 변수를 확인하고 organization 및 hostname 인자를 자동으로 채워요. 초기화 중에 로컬 Terraform CLI는 그 값을 사용해 작업 디렉터리를 Terraform Enterprise에 연결해요. 결과적으로 Terraform은 구성을 HCP Terraform 또는 Terraform Enterprise에 연결하고 팀이 다른 지속적 통합 파이프라인에서 구성을 재사용할 수 있게 해요:

terraform {
  cloud {
    workspaces {
      tags = ["app"]
    }
  }
}

더 알아보기 (Learn more)

버전 제약 (Version constraints): 버전 지정
프로바이더 요구 사항 (Provider Requirements): 프로바이더 지정
백엔드 구성 (Backend Configuration): state 저장
HCP Terraform: 클라우드 연결

terraform 블록 참조