`component` 블록 참조

component 블록 참조 (component block reference)

component 블록을 사용해 Stack을 구성하는 개별 모듈을 소스로 사용해요. component 블록은 Stack의 컴포넌트 구성 파일인 .tfcomponent.hcl 파일에 정의할 수 있어요. 각 컴포넌트는 프로비저닝하고 관리할 수 있는 재사용 가능한 인프라 조각을 나타내요. 이 페이지에서는 component 블록의 구성 모델과 지원 인자를 다룰게요.

출처: 문서

본문

component 블록을 사용해 Stack을 구성하는 개별 모듈을 소스로 사용해요. component 블록은 Stack의 컴포넌트 구성 파일인 .tfcomponent.hcl 파일에 정의할 수 있어요. 각 컴포넌트는 프로비저닝하고 관리할 수 있는 재사용 가능한 인프라 조각을 나타내요.

배경 (Background)

component 블록은 Stack에 포함할 인프라를 정의해요. 각 Stack은 적어도 하나의 component 블록을 요구하며, Stack에 포함하려는 모든 모듈에 대해 구성에 component 블록을 추가해야 해요.

각 컴포넌트는 Terraform 모듈을 소스로 사용하고, 입력 변수를 받을 수 있으며, Stack 수준에서 선언한 프로바이더를 받아들여요. tfcomponent.hcl 파일에서 다음 구성 블록을 정의할 수 있어요:

• required_providers 블록을 사용해 컴포넌트 구성이 요구하는 프로바이더를 선언해 Terraform이 그들을 설치하고 사용할 수 있게 해요.
• provider 블록을 사용해 프로바이더를 구성한 다음 그 구성을 컴포넌트에 전달해요.
• removed 블록을 사용해 Stack에서 제거하려는 컴포넌트를 정의해요.
• variable 블록을 사용해 Stack의 입력 변수를 정의해요.
• output 블록을 사용해 HCP Terraform UI에서 참조하려는 출력을 정의해요.
• locals 블록을 사용해 컴포넌트 구성 안에서 사용할 수 있는 로컬 값을 정의해요.

구성 모델 (Configuration model)

component 블록은 다음 인자를 지원해요:

• component "<NAME>" 블록
  • source 문자열
  • version 문자열
  • inputs 맵
  • providers 맵
  • depends_on 참조 리스트
  • for_each 메타-인자

완전한 구성 (Complete configuration)

사용 가능한 모든 인자는 다음 component 블록에 정의돼 있어요. source, inputs, providers 인자는 필수예요.

component "<NAME>" {
  for_each = <FOR_EACH>
  source   = "<SOURCE>"
  version  = "<VERSION>"
  inputs = {
    <KEY> = <VALUE>
  }
  providers = {
    <PROVIDER> = provider.<PROVIDER>.<ALIAS>
  }
  depends_on = [component.<NAME>]
}

사양 (Specification)

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

component "<NAME>"

component 키워드 뒤의 레이블은 컴포넌트의 이름이며, 같은 컴포넌트 구성의 모든 컴포넌트 사이에서 고유해야 해요. 컴포넌트의 이름은 유효한 식별자라면 무엇이든 될 수 있어요.

component 블록에서 다음 인자가 지원돼요:

인자	설명	타입	필수?
source	이 컴포넌트에 소스로 사용할 Terraform 모듈이에요.	문자열	필수
version	공개 Terraform 레지스트리에서 소스를 가져올 때 사용할 모듈 버전이에요.	문자열	선택
inputs	모듈 입력 변수 이름을 값에 매핑한 것이에요.	맵	필수
providers	프로바이더 이름을 컴포넌트 구성에 선언된 프로바이더에 매핑한 것이에요.	맵	필수
depends_on	HCP Terraform이 이 컴포넌트 전에 실행해야 하는 다른 컴포넌트의 리스트예요.	리스트	선택
for_each	값의 맵이나 집합에 기반해 컴포넌트의 여러 인스턴스를 만들어요.	맵 또는 집합	선택

source

source 인자는 이 컴포넌트에 사용할 Terraform 모듈을 지정해요. 로컬 경로, Git 저장소, Terraform 레지스트리, HCP Terraform 개인 레지스트리를 포함한 다양한 소스에서 모듈을 참조할 수 있어요.

component "<NAME>" {
  source = "<NAMESPACE>/<NAME>/<PROVIDER>"
  # ...
}

source 인자는 전통적인 Terraform 구성의 module 블록과 같은 모듈 소스를 받아들여요.

요약 (Summary)

• 데이터 타입: 문자열
• 기본값: 없음
• 필수: 예

version

version 인자를 사용해 공개 Terraform 레지스트리나 개인 HCP Terraform 레지스트리에서 소스를 가져올 때 사용할 모듈의 버전을 지정해요.

component "<NAME>" {
  source  = "<NAMESPACE>/<NAME>/<PROVIDER>"
  version = "<VERSION>"
  # ...
}

version 인자는 버전 제약 문자열을 받아요. Terraform은 제약을 충족하는 설치된 모듈 버전 중 가장 새로운 것을 사용해요. 허용 가능한 버전이 설치되어 있지 않으면 Terraform은 제약을 충족하는 가장 새로운 버전을 다운로드해요. 예기치 않거나 원치 않는 변경을 피하려면 허용 가능한 버전 번호를 명시적으로 제약할 것을 권장해요.

구성을 로컬에서 검증할 계획이라면 version 인자를 수정한 후 Terraform이 로컬 캐시를 업데이트할 수 있도록 terraform stacks init을 실행해요.

source 인자가 공개 Terraform 레지스트리나 HCP Terraform의 개인 모듈 레지스트리 같은 레지스트리에 나열된 모듈을 가리킬 때만 version 인자를 사용할 수 있어요. 로컬 파일 경로에서 가져온 모듈은 같은 소스 저장소에서 로드되고 항상 호출자와 같은 버전을 공유하므로 version을 지원하지 않아요.

요약 (Summary)

• 데이터 타입: 문자열
• 기본값: 없음

providers

providers 인자는 프로바이더 이름을 컴포넌트 구성에 선언된 프로바이더에 매핑하는 것을 정의해요. 컴포넌트 구성에서 모듈은 자체 프로바이더를 구성할 수 없으므로 Stack 수준에서 프로바이더를 선언하고 각 컴포넌트에 전달해야 해요.

component "storage" {
  source = "./modules/s3"
  providers = {
    PROVIDER_NAME_IN_MODULE    = "provider.<PROVIDER>.<ALIAS>"
  }
  # ...
}

providers 맵의 키는 소스 모듈이 기대하는 프로바이더 이름과 일치해야 하고, 값은 컴포넌트 구성에 선언된 프로바이더를 참조해야 해요. Stacks의 프로바이더 선언에 대해 더 알아보세요.

providers는 메타-인자예요. 메타-인자는 Terraform 언어에 내장되어 리소스를 어떻게 생성하고 관리할지 제어해요. 이 인자가 어떻게 동작하는지에 대한 자세한 내용은 providers 참조를 참고해요.

inputs

inputs 인자는 모듈 입력 변수 이름을 값에 매핑하는 것을 정의해요. 이 맵의 키는 소스 모듈이 정의한 변수 이름에 대응해야 해요.

component "database" {
  source = "./modules/database"
  providers = {
    random = provider.random.this
  }
  inputs = {
    VAR_NAME = "<VALUE>"
  }
}

inputs 맵에서 세 가지 유형의 값을 사용할 수 있어요:

• var.variable_name 같은 변수 참조.
• component.component_name.output_name 같은 컴포넌트 출력.
• 프리미티브와 함수 같은 리터럴 값.

요약 (Summary)

• 데이터 타입: 오브젝트
• 기본값: 없음
• 필수: 예

depends_on

depends_on 인자는 다른 컴포넌트에 대한 명시적 의존성을 지정해요. HCP Terraform은 depends_on 리스트의 컴포넌트를 현재 컴포넌트를 실행하기 전에 실행해요.

component "app_server" {
  depends_on = [
    component.<NAME>
  ]
  # ...
}

Terraform은 그 의존성을 자동으로 인식하므로 depends_on 리스트에 의존하는 컴포넌트의 출력을 포함할 필요가 없어요.

depends_on은 메타-인자예요. 메타-인자는 Terraform 언어에 내장되어 리소스를 어떻게 생성하고 관리할지 제어해요. 이 인자가 어떻게 동작하는지에 대한 자세한 내용은 depends_on 참조를 참고해요.

for_each

for_each 인자는 값의 맵이나 집합에 기반해 컴포넌트의 여러 인스턴스를 만들어요. 이 메타-인자를 사용해 여러 환경, 리전 또는 구성에 걸쳐 같은 인프라 패턴을 프로비저닝할 수 있어요.

component "<NAME>" {
  for_each = [ "<VALUE>" ]
  # . . .
}

component "<NAME>" {
  for_each = {
    "<KEY>" = "<VALUE>"
  }
}

for_each를 사용하면 Terraform은 컬렉션의 각 항목에 대해 컴포넌트 인스턴스를 하나씩 만들어요. component.<NAME>[<KEY>] 구문을 사용해 개별 인스턴스를 참조할 수 있어요.

for_each는 메타-인자예요. 메타-인자는 Terraform 언어에 내장되어 리소스를 어떻게 생성할지 제어해요. 이 인자가 어떻게 동작하는지에 대한 자세한 내용은 for_each 참조를 참고해요.

예시 (Examples)

다음 예시는 component 블록의 일반적인 사용 사례를 보여줘요.

로컬 모듈 소스로 사용 (Source a local module)

다음 예시에서 Terraform은 현재 컴포넌트 구성 내의 modules/web_server 디렉터리에서 web_server 모듈을 소스로 사용해 web 컴포넌트를 만들어요:

component "web" {
  source = "./modules/web_server"

  inputs = {
    instance_type = "t3.micro"
    subnet_id     = "subnet-12345678"
  }

  providers = {
    aws = provider.aws.main
  }
}

web 컴포넌트를 구성하는 일부로 web_server 모듈이 요구하는 프로바이더 구성을 정의하고 변수 값을 입력해야 해요.

Terraform 레지스트리에서 모듈 소스로 사용 (Source a module from the Terraform registry)

다음 예시에서 Terraform은 공개 Terraform 레지스트리의 terraform-aws-modules/vpc/aws 모듈에서 vpc 컴포넌트를 소스로 사용하고 버전 5.x로 제약해요:

component "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "~> 5.0"

  inputs = {
    name = "main-vpc"
    cidr = "10.0.0.0/16"
    azs  = ["us-west-2a", "us-west-2b"]
  }

  providers = {
    aws = provider.aws.main
  }
}

vpc 컴포넌트를 구성하는 일부로 terraform-aws-modules/vpc/aws 모듈이 요구하는 프로바이더 구성을 정의하고 변수 값을 입력해요.

의존성이 있는 컴포넌트 (Component with dependencies)

다음 예시에서 app_server 컴포넌트는 database 컴포넌트의 출력을 참조하고 그 컴포넌트에 대한 명시적 의존성을 선언해 Terraform이 컴포넌트를 올바른 순서로 만들게 해요:

component "app_server" {
  source = "./modules/app-server"

  inputs = {
    name = "main-vpc"
    cidr = "10.0.0.0/16"
    azs  = ["us-west-2a", "us-west-2b"]
  }

  providers = {
    aws = provider.aws.main
  }

  depends_on = [
    component.database
  ]
}

여러 컴포넌트 인스턴스 (Multiple component instances)

다음 예시에서 Terraform은 집합에 지정된 각 리전에 대해 하나씩 세 개의 스토리지 컴포넌트를 만들며, 각 컴포넌트는 리전별 구성을 받아요:

component "regional_storage" {
  for_each = toset(["us-east-1", "us-west-2", "eu-west-1"])

  source = "./modules/storage"

  inputs = {
    region      = each.value
    bucket_name = "app-data-${each.value}"
  }

  providers = {
    aws = provider.aws.configurations[each.value]
  }
}

인프라를 컴포넌트로 나누는 방법에 대해 더 알아보려면 컴포넌트 구성 정의를 참고해요.

더 알아보기 (Learn more)

• 컴포넌트 구성 개요
• variable 블록 참조
• required_providers 블록 참조
• Stacks 개요