컴포넌트 구성용 `variable` 블록 참조

컴포넌트 구성용 `variable` 블록 참조 (variable block reference for component configurations)

variable 블록을 사용해 컴포넌트 구성의 입력 변수를 선언해 컴포넌트를 동적이고 재사용 가능하게 만들어요. 이 페이지에서는 컴포넌트 구성의 .tfcomponent.hcl 파일에서 variable 블록을 구성하는 방법과 지원 인자를 다룰게요.

출처: 문서

본문

variable 블록을 사용해 컴포넌트 구성의 입력 변수를 선언해 컴포넌트를 동적이고 재사용 가능하게 만들어요.

.tf로 끝나는 전통적인 Terraform 구성 파일에서 variable 블록을 선언한다면 Terraform 구성 variable 블록 참조를 대신 참고해요.

배경 (Background)

컴포넌트 구성(.tfcomponent.hcl 파일)에서 variable 블록을 사용해 배포 사이에 변경될 수 있는 값을 선언해요.

배포 구성 파일의 배포는 배포 구성의 inputs 인자를 통해 Stack 변수에 값을 전달해요. 컴포넌트 구성과 배포 구성을 분리하면 단일 Stack 정의를 유지하면서 서로 다른 입력으로 여러 배포를 만들 수 있어요.

구성 모델 (Configuration model)

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

variable "<NAME>" 블록
- type 타입 제약
- default 식
- description 문자열
- sensitive 불리언
- nullable 불리언
- ephemeral 불리언

완전한 구성 (Complete configuration)

사용 가능한 모든 인자는 다음 variable 블록에 정의돼 있어요:

variable "<NAME>" {
  type        = <TYPE>
  default     = <DEFAULT>
  description = "<DESCRIPTION>"
  sensitive   = <BOOL>
  nullable    = <BOOL>
  ephemeral   = <BOOL>
}

사양 (Specification)

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

`variable "<NAME>"`

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

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

인자	설명	타입	필수?
`type`	이 변수 값에 대한 타입 제약이에요.	타입 제약	필수
`default`	이 변수의 기본값이에요. 기본값이 없는 변수는 배포가 값을 제공해야 해요.	식	선택
`description`	변수의 목적과 기대하는 값에 대한 설명이에요.	문자열	선택
`sensitive`	Terraform이 이 값을 UI와 로그에서 숨기는지 여부를 지정해요.	불리언	선택
`nullable`	변수의 값이 `null`일 수 있는지 여부를 지정해요.	불리언	선택
`ephemeral`	Terraform이 이 값을 plan과 상태에서 제외하는지 여부를 지정해요.	불리언	선택

`type`

type 인자는 배포가 이 변수에 할당할 수 있는 값의 타입을 제약해요. 컴포넌트 구성은 각 변수에 대해 타입을 명시적으로 정의할 것을 요구해요.

variable "<NAME>" {
  type = <TYPE>
}

타입 제약을 정의하면 배포 작성자가 유효하지 않은 타입을 사용하려 할 때 오류 메시지를 제공함으로써 변수가 어떤 값을 받는지 이해하는 데 도움이 돼요.

타입, 생성자, 변환에 대한 자세한 내용은 타입 제약을 참고해요.

요약 (Summary)

데이터 타입: 타입 제약
기본값: 없음
필수: 예

`default`

default 인자는 변수의 기본값을 정의해 배포가 값을 제공하는 것을 선택 사항으로 만들어요.

variable "<NAME>" {
  type    = <TYPE>
  default = <DEFAULT>
}

type과 default 인자를 모두 지정하면 기본값은 지정된 타입과 일치해야 해요. default 인자는 리터럴 값을 요구하며 구성의 다른 객체를 참조할 수 없어요.

요약 (Summary)

데이터 타입: 식
기본값: 없음 (기본값이 없으면 배포가 값을 제공해야 함)
필수: 아니요

`description`

description 인자는 변수의 목적과 기대하는 값을 문서화해요.

variable "<NAME>" {
  type        = <TYPE>
  description = "<DESCRIPTION>"
}

배포를 구성하는 사람의 관점에서 설명을 작성해 그들이 이 변수를 어떻게 사용하는지 이해하도록 도와요.

요약 (Summary)

데이터 타입: 문자열
기본값: 없음
필수: 아니요

`sensitive`

sensitive 인자는 Terraform이 변수 값을 HCP Terraform UI와 로그에 표시하지 못하게 해요.

variable "<NAME>" {
  type      = <TYPE>
  sensitive = <BOOL>
}

변수를 민감으로 표시하면 Terraform은 plan과 apply 로그에서 그 값을 검열하고 대신 (sensitive value)를 표시해요. Terraform은 민감한 변수를 사용하는 식도 민감한 것으로 취급해요.

Terraform은 여전히 민감한 값을 상태에 기록하므로, 상태 데이터에 접근할 수 있는 사람은 민감한 값에 접근할 수 있어요. 민감한 데이터를 안전하게 저장하는 방법에 대한 자세한 내용은 민감한 데이터 관리를 참고해요.

요약 (Summary)

데이터 타입: 불리언
기본값: false
필수: 아니요

`nullable`

nullable 인자는 배포가 변수에 null 값을 할당할 수 있는지 제어해요.

variable "<NAME>" {
  type     = <TYPE>
  nullable = <BOOL>
}

nullable이 false이면 변수는 null이 아닌 값을 가져야 해요. nullable이 true이고 변수에 default 인자가 있으면 배포는 기본값을 재정의하여 변수 값을 명시적으로 null로 설정할 수 있어요.

요약 (Summary)

데이터 타입: 불리언
기본값: true
필수: 아니요

`ephemeral`

ephemeral 인자는 변수를 런타임 동안 사용 가능하게 하지만 Terraform이 그 값을 상태와 plan 파일에 저장하지 못하게 해요.

variable "<NAME>" {
  type      = <TYPE>
  ephemeral = <BOOL>
}

임시 변수는 상태에 지속시키고 싶지 않은 세션 토큰이나 단기 자격 증명 같은 임시 값에 유용해요.

임시 변수는 특정 맥락에서만 참조할 수 있으며 그렇지 않으면 Terraform이 오류를 발생시켜요:

관리 리소스의 쓰기 전용 인자에서
ephemeral 블록에서
locals 블록에서
ephemeral 인자가 true로 설정된 다른 variable 블록에서
ephemeral 인자가 true로 설정된 자식 모듈 output 블록에서
provider 블록에서 프로바이더 구성하기
프로비저너와 connection 블록에서

요약 (Summary)

데이터 타입: 불리언
기본값: false
필수: 아니요

예시 (Examples)

다음 예시는 컴포넌트 구성에서 variable 블록의 일반적인 사용 사례를 보여줘요.

컴포넌트 구성에서 변수 사용 (Using variables in component configurations)

다음 예시는 aws_region과 instance_count 변수를 선언해요. 그런 다음 network 컴포넌트는 inputs 인자를 사용해 그 변수들을 받아들여요:

main.tfcomponent.hcl

variable "aws_region" {
  type        = string
  description = "The AWS region where resources will be deployed"
}

variable "instance_count" {
  type        = number
  description = "Number of instances to create"
  default     = 2
}

component "network" {
  source = "./modules/network"

  inputs = {
    region      = var.aws_region
    cidr_block  = var.instance_count
  }
}

./modules/network 모듈은 이제 구성에서 var.aws_region과 var.instance_count를 참조할 수 있어요.

배포는 inputs 인자를 통해 변수에 값을 제공해요. 다음 예시에서 production과 staging 배포는 aws_region과 instance_count 변수에 값을 제공해요:

main.tfdeploy.hcl

deployment "production" {
  inputs = {
    aws_region     = "us-west-2"
    instance_count = 5
  }
}

deployment "staging" {
  inputs = {
    aws_region     = "us-east-1"
    instance_count = 2
  }
}

production과 staging 배포는 같은 컴포넌트 구성을 빌드하면서 aws_region과 instance_count에 서로 다른 값을 각각 입력할 수 있어요. 배포의 inputs 블록에 있는 변수의 이름은 컴포넌트 구성 variable 블록에 선언된 이름과 일치해야 해요.

컴포넌트 구성용 `variable` 블록 참조