`variable` 블록 참조

`variable` 블록 참조 (variable block reference)

variable 블록을 사용해 구성을 매개변수화해 모듈 소비자가 런타임에 구성에 사용자 지정 값을 전달할 수 있게 해요. 실습: 변수로 Terraform 구성 사용자 지정 튜토리얼을 따라 해 보세요. 이 페이지에서는 variable 블록의 구성 모델과 지원 인자를 다룰게요.

출처: 문서

본문

variable 블록을 사용해 구성을 매개변수화해 모듈 소비자가 런타임에 구성에 사용자 지정 값을 전달할 수 있게 해요.

실습: 변수로 Terraform 구성 사용자 지정 튜토리얼을 따라 해 보세요.

배경 (Background)

variable 블록은 다른 프로그래밍 언어의 함수 인자와 비슷해요. 입력 변수를 사용하면 소스 코드를 변경하지 않고 Terraform 모듈을 사용자 지정할 수 있어요. 변수는 모듈의 매개변수 역할을 해 모듈을 구성 가능하고 재사용 가능하게 만들어요.

루트 모듈이나 자식 모듈에서 변수를 정의할 수 있어요:

루트 모듈에서는 CLI 옵션, 환경 변수, 변수 정의 파일 또는 HCP Terraform 워크스페이스를 통해 변수 값을 설정할 수 있어요.
자식 모듈에서는 부모 모듈이 module 블록의 인자로 자식 모듈에 값을 전달해요.

변수를 사용하고 값을 설정하는 다양한 방법에 대해 더 알아보려면 변수를 사용해 모듈 인자 입력을 참고해요.

구성 모델 (Configuration model)

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

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

완전한 구성 (Complete configuration)

사용 가능한 모든 인자는 다음 variable 블록에 정의돼 있어요. variable 블록에는 상호 배타적인 인자가 없어요.

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

  validation {
    condition     = <CONDITION>
    error_message = "<MESSAGE>"
  }
}

사양 (Specification)

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

`variable "<NAME>"`

variable 키워드 뒤의 레이블은 변수의 이름이며, 같은 모듈의 모든 변수 사이에서 고유해야 해요. 변수의 이름은 source, version, providers, count, for_each, lifecycle, depends_on, locals라는 예약된 이름을 제외하고 유효한 식별자라면 무엇이든 될 수 있어요.

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

인자	설명	타입	필수?
`type`	이 변수의 값 인자에 대한 타입 제약을 지정해요.	타입 제약	선택
`default`	이 변수의 기본값을 설정해요. 기본값이 없는 변수는 값 인자를 정의해야 해요.	식	선택
`description`	변수의 목적과 기대하는 값에 대한 설명이에요.	문자열	선택
`validation`	타입 제약 외에 이 변수의 값이 충족해야 하는 규칙을 지정해요.	블록	선택
`sensitive`	Terraform이 이 값을 CLI 출력에서 숨기는지 지정해요.	불리언	선택
`nullable`	변수의 값이 `null`일 수 있는지 지정해요.	불리언	선택
`ephemeral`	이 값을 상태나 plan 파일에 저장하지 않도록 방지할지 지정해요.	불리언	선택
`const`	변수를 초기화 같은 초기 Terraform 작업 동안 사용할 수 있게 해요.	불리언	선택
`deprecated`	변수에 대한 폐기 메시지예요.	문자열	선택

`type`

variable 블록의 type 인자는 그 변수에 할당할 수 있는 값의 타입을 제약해요. 타입 제약을 설정하지 않으면 변수는 모든 타입의 값을 받아요.

variable "unique_name" {
  type = <TYPE>
}

타입 제약을 정의하면 모듈 소비자가 변수가 어떤 값을 필요로 하는지 이해하는 데 도움이 되고, 소비자가 유효하지 않은 타입을 사용하려 하면 유용한 오류 메시지도 제공해요.

변수 블록에서 유효한 기본 타입, 복합 타입, 구조적 타입을 제약으로 사용할 수 있어요. 타입, 생성자, 변환에 대한 자세한 내용은 타입 제약을 참고해요.

요약 (Summary)

데이터 타입: 타입 제약
기본값: any
예시: 기본 변수 선언

`default`

default 인자는 변수의 기본값을 정의해 값을 제공하는 것을 선택 사항으로 만들어요. 모듈을 사용할 때 변수 값을 제공하지 않으면 Terraform은 기본값을 사용해요.

variable "region" {
  type    = string
  default = <DEFAULT>
}

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

요약 (Summary)

데이터 타입: 식
기본값: 없음, 그러나 기본 인자를 정의하지 않으면 값 인자를 정의해야 해요.
예시: 기본 변수 선언

`description`

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

variable "image_id" {
  type        = string
  description = "<DESCRIPTION>"
}

모듈 소비자의 관점에서 설명을 작성해 사용자가 이 변수를 어떻게 사용하는지 이해하도록 도와요. 모듈 유지 관리자로서 변수 블록에 대한 주석을 남겨야 한다면 주석을 대신 사용해요.

요약 (Summary)

데이터 타입: 문자열
기본값: 없음
예시: 기본 변수 선언

`validation`

validation 블록을 사용하면 타입 제약 외에도 변수 값이 특정 요구 사항을 충족하는지 강제할 수 있어요. 변수 검증을 사용해 Terraform이 plan 생성을 마치기 전에 변수가 구성의 필요에 부합함을 보장해요.

variable "unique_name" {
  validation {
    condition     = <CONDITION>
    error_message = "<MESSAGE>"
  }
}

validation 블록에서 다음 인자를 지정할 수 있어요:

인자	설명	타입	필수
`condition`	Terraform이 작업을 진행하려면 `true`로 평가되어야 하는 식이에요.	유효한 조건식	필수
`error_message`	조건이 false로 평가될 때 표시할 메시지예요.	문자열	필수

Terraform은 plan을 만드는 동안 변수 검증을 평가하며, validation 블록의 condition 식이 false로 평가되면 Terraform은 오류를 던지고 error_message를 표시하며 현재 작업을 중지해요. 자세한 내용과 예시는 구성 검증을 참고해요.

요약 (Summary)

데이터 타입: 블록
기본값: 없음
예시: 검증이 있는 변수

`sensitive`

sensitive 인자는 구성에서 그 변수를 사용할 때 Terraform이 variable 블록의 값을 CLI 출력에 표시하지 못하게 해요.

variable "user_password" {
  type      = string
  sensitive = true
}

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

Terraform will perform the following actions:

  # some_resource.a will be created
  + resource "some_resource" "a" {
      + user_password = (sensitive value)
    }

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

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

요약 (Summary)

데이터 타입: 불리언
기본값: false
예시: 민감한 변수

`nullable`

nullable 인자를 활성화하면 모듈 소비자가 변수에 null 값을 할당할 수 있어요.

variable "example" {
  type     = string
  nullable = false
}

변수 블록에서 nullable이 false이면 그 변수는 null이 아닌 값을 가져야 해요. nullable이 true이고 변수에 default 인자가 있으면 기본 인자를 덮어써서 변수 값을 명시적으로 null로 설정할 수 있어요.

변수가 리스트나 오브젝트 같은 컬렉션 또는 구조적 타입을 사용하면, 컬렉션이나 구조 자체가 null이 아닌 한 모듈 소비자는 중첩된 요소에서 null을 사용할 수 있어요.

요약 (Summary)

데이터 타입: 불리언
기본값: true

`ephemeral`

참고: 임시 변수는 Terraform v1.10 이상에서 사용할 수 있어요.

ephemeral 인자는 변수를 런타임 동안 사용 가능하게 하지만 Terraform은 임시 값을 상태와 plan 파일에서 생략해요. ephemeral 인자는 단기 토큰이나 세션 식별자처럼 일시적으로만 존재하는 값에 유용해요.

variable "session_token" {
  type      = string
  ephemeral = true
}

특정 맥락에서 임시 변수 값을 참조하고 설정할 수 있어요:

ephemeral 인자가 있는 output 블록
ephemeral 인자가 있는 다른 variable 블록에서
리소스 블록의 쓰기 전용 인자
ephemeral 리소스 블록
프로바이더를 구성하는 provider 블록에서
프로비저너 및 프로비저너 연결 구성에서. 자세한 내용은 프로비저너 사용을 참고해요.

다른 식이 ephemeral 인자가 있는 변수를 참조하면 그 식도 암시적으로 임시가 돼요.

요약 (Summary)

데이터 타입: 불리언
기본값: false
예시: 임시 변수

`const`

const 인자를 활성화하면 Terraform이 구성을 로드할 때(예: Terraform init 작업 중) 그 변수를 사용할 수 있게 해요.

variable "example" {
  type     = string
  const    = true
}

변수 블록에서 const가 true이면 그 변수는 알려진 상수 값만 포함할 수 있어요. plan 작업의 동적 결과에 의존할 수 없어요. 그런 다음 이 변수들을 모듈 source와 version 속성에 사용할 수 있어요.

요약 (Summary)

데이터 타입: 불리언
기본값: false

`deprecated`

참고: 폐기된 변수는 Terraform v1.15 이상에서 사용할 수 있어요.

deprecated 인자는 변수가 폐기된 이유를 지정해요. Terraform은 루트 모듈에서 변수를 설정하거나 자식 모듈 호출자가 변수에 값을 전달할 때 이 이유를 표시해요.

variable "old_input" {
  type       = string
  deprecated = "This variable is deprecated, please use 'new_input' instead."
}

variable "new_input" {
  type    = list(string)
  default = []
}

요약 (Summary)

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

예시 (Examples)

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

기본 변수 선언 (Basic variable declaration)

다음 예시에서 image_id 변수는 문자열 값을 요구하고 기본값이 없어 필수예요. availability_zone_names 변수는 문자열 리스트를 받고 기본값을 제공해 사용자가 이 변수에 값을 제공하는 것을 선택 사항으로 만들어요:

variable "image_id" {
  type        = string
  description = "The ID of the machine image (AMI) to use for the server."
}

variable "availability_zone_names" {
  type        = list(string)
  description = "List of availability zones where resources will be deployed."
  default     = ["us-west-1a"]
}

복합 타입에 값 설정 (Set a value to a complex type)

다음 예시에서 docker_ports 변수는 각 객체가 internal과 external 숫자 속성과 protocol 문자열 속성을 가져야 하는 객체의 리스트를 받아요:

variable "docker_ports" {
  type = list(object({
    internal = number
    external = number
    protocol = string
  }))
  description = "List of port configurations for Docker containers."
  default = [
    {
      internal = 8300
      external = 8300
      protocol = "tcp"
    }
  ]
}

검증이 있는 변수 (Variable with validation)

다음 예시에서 validation 블록은 image_id 값이 4자보다 길고 "ami-"로 시작하는지 확인해요. 변수 값이 조건을 충족하지 않으면 Terraform은 지정된 오류 메시지를 표시해요:

variable "image_id" {
  type        = string
  description = "The ID of the machine image (AMI) to use for the server."

  validation {
    condition     = length(var.image_id) > 4 && substr(var.image_id, 0, 4) == "ami-"
    error_message = "The image_id value must be a valid AMI ID, starting with \"ami-\"."
  }
}

민감한 변수 (Sensitive variable)

다음 예시에서 database_password 변수는 민감으로 표시되며, 이로 인해 Terraform이 변수 값과 그 변수를 사용하는 리소스 속성을 모두 로그에서 검열해요:

variable "database_password" {
  type        = string
  description = "Password for the database instance."
  sensitive   = true
}

resource "aws_db_instance" "example" {
  identifier = "my-database"
  engine     = "mysql"
  username   = "admin"
  password   = var.database_password
  # …
}

plan 또는 apply 작업을 실행하면 Terraform은 민감한 값을 (sensitive value)로 표시해요. Terraform은 database_password 변수와 그 변수를 사용하는 리소스 인자를 모두 숨겨요. 예를 들어 구성을 적용할 때 Terraform은 다음을 기록해요:

Terraform will perform the following actions:

  # aws_db_instance.example will be created
  + resource "aws_db_instance" "example" {
      + identifier = "my-database"
      + engine     = "mysql"
      + username   = "admin"
      + password   = (sensitive value)
    }

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

민감한 변수를 참조하는 어떤 식이든 자동으로 민감해져요.

임시 변수 (Ephemeral variable)

다음 예시는 민감한 데이터를 포함하는 세 개의 별도 변수의 자격 증명을 참조해 AWS 프로바이더를 구성해요. access_key, secret_key, session_token 변수는 ephemeral이므로 Terraform 작업 동안 사용할 수 있지만 그 후에는 상태나 plan 파일에 저장되지 않아요.

variable "access_key" {
  description = "AWS access key"
  type     = string
  ephemeral = true
}

variable "secret_key" {
  description = "AWS sensitive secret key."
  type     = string
  sensitive = true
  ephemeral = true
}

variable "session_token" {
  description = "AWS session token."
  type     = string
  sensitive = true
  ephemeral = true
}

provider "aws" {
  access_key = var.access_key
  secret_key = var.secret_key
  token      = var.session_token
}

`variable` 블록 참조