구성 검증하기

구성 검증하기 (Validate your configuration)

구성을 검증하면 모듈 사용자의 문제 해결을 개선하고, 실행(run)을 더 예측 가능하게 만들며, 유지보수 담당자가 구성의 의도를 이해하는 데 도움을 줄 수 있어요.

출처: 문서

본문

소개 (Introduction)

검증은 테라폼 구성이 의도한 대로 동작하는지 확인하는 데 도움을 줘요. 여러 종류의 검증을 사용해서 다음을 할 수 있어요.

• 입력 변수가 특정 요구사항을 충족하는지 확인.
• 잘못된 출력이 state에 쓰이는 것 방지.
• 테라폼이 적용한 뒤 리소스와 데이터 소스가 올바르게 구성됐는지 확인.
• 인프라의 더 넓은 동작 검증.
• 인프라에 대한 가정(assumptions) 문서화.
• HCP Terraform을 사용해 인프라를 정기적으로 검증.

검증이 실패하면 테라폼은 오류 메시지에서 사용할 수 있는 컨텍스트를 제공해서 사용자가 문제를 이해하고 고치도록 도와줘요. 테라폼은 실행 주기의 서로 다른 단계에서 서로 다른 방식의 검증을 평가하며, 검증은 추가 작업 실행을 막거나 경고와 함께 실행을 계속하게 할 수 있어요.

작성자(author) 입장에서 구성에 검증을 추가하면 모듈의 표준과 요구사항을 강제해서, 모듈 소비자가 구성을 이해하고 사용하는 데 도움을 줘요.

요구사항 (Requirements)

• 입력 변수 검증은 테라폼 v0.13.0 이상.
• 사전조건·사후조건은 테라폼 v1.2.0 이상.
• check 블록은 테라폼 v1.5.0 이상.

사용 사례에 맞는 검증 고르기 (Choose a validation for your use case)

직접 해보기: 사용자 지정 조건으로 모듈 검증 튜토리얼로 변수 검증, 사전조건, 사후조건을 배워보세요. Checks로 인프라 검증 튜토리얼로 check 블록 사용법을 배워보세요.

테라폼은 구성을 검증하는 여러 방법을 제공해요.

• 입력 변수 검증(Input variable validations) — 테라폼이 plan을 만들 때 구성의 매개변수를 검증해요.
• 사전조건(Preconditions) — 테라폼이 만들기 전에 개별 리소스, 데이터 소스, 출력이 요구사항을 충족하는지 보장해요.
• 사후조건(Postconditions) — 테라폼이 리소스와 데이터 소스를 기대하고 원하는 설정으로 만들었는지 검증해요.
• Checks — check의 결과에 기반해 테라폼 작업을 막지 않고 리소스가 예상대로 동작하는지 검증할 수 있게 해줘요.

구성 검증은 유연하며, 종종 같은 결과를 얻기 위해 서로 다른 종류의 검증을 사용할 수 있어요. 검증 방식을 고를 때는 검증이 작업을 막기를 원하는지, 테라폼 워크플로우의 어떤 단계에서 실행되어야 하는지 고려하세요.

입력 변수 검증 (Input variable validation)

입력 변수 검증을 사용해 다음 작업을 수행해요.

• 입력 변수가 특정 형식 요구사항을 충족하는지 확인.
• 입력 값이 허용 가능한 범위 안에 들어오는지 확인.
• 변수가 잘못 구성된 경우 테라폼 작업 방지.

예를 들어 변수 값이 유효한 AMI ID 문법을 갖는지 검증할 수 있어요.

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-\"."
  }
}

image_id 변수의 값을 AMI ID 문법이 없는 문자열로 설정하면 조건이 false로 평가돼요. 변수 검증이 실패하면 테라폼은 오류를 내고 구성된 error_message를 표시하며 작업 진행을 멈춰요. 프로바이더 API도 종종 같은 검증에서 오류를 내지만, 이 검증은 사용자가 그 오류를 피하고 도움이 되는 오류 메시지를 받게 해줘요. 또한 이런 검증을 사용해 명명 규칙 같은 조직의 설계 결정을 강제할 수 있어요.

변수 검증에 대해 더 알아보려면 입력 변수 블록을 참고하세요.

사전조건과 사후조건 (Preconditions and postconditions)

리소스, 데이터 소스, 출력에 대한 구성의 가정을 테라폼이 만들기 전에 검증하고 싶을 때는 precondition 블록을 사용해요. 구성이 실행되기 위해 리소스와 데이터 소스가 충족해야 하는 보장을 검증할 때는 postcondition 블록을 사용해요.

사전조건 (Preconditions)

테라폼은 plan을 만들 때 리소스, 데이터 소스, 출력에 대한 사전조건을 평가해요. 사전조건은 잘못 구성된 리소스·데이터 소스·출력에 대해 프로바이더가 제기하는 인자 오류보다 우선해요.

다음 예제는 aws_instance용으로 구성된 AMI가 x86_64 CPU 아키텍처를 사용하는지 확인하는 사전조건을 사용해요.

resource "aws_instance" "example" {
  instance_type = "t3.micro"
  ami           = data.aws_ami.example.id

  lifecycle {
    # The AMI ID must refer to an AMI that contains an operating system
    # for the `x86_64` architecture.
    precondition {
      condition     = data.aws_ami.example.architecture == "x86_64"
      error_message = "The selected AMI must be for the x86_64 architecture."
    }
  }
}

이 사전조건은 호출자가 다른 아키텍처용 AMI를 실수로 선택했을 때 감지해요. 이 인스턴스가 호스팅하는 소프트웨어를 실행하지 못할 수 있기 때문이에요. 테라폼은 plan을 만드는 동안 사전조건을 평가하고, 실패하면 error_message 인자와 함께 오류를 던지고 현재 작업을 멈춰요. 사전조건 블록 사용의 더 많은 예시는 리소스 구성 레퍼런스를 참고하세요.

output 블록도 모듈의 출력을 검증하는 사전조건을 포함할 수 있어요. 테라폼이 출력을 노출하거나 그 값을 state에 저장하기 전에 출력 값이 요구사항을 충족하는지 검증하려면 출력에 사전조건을 사용해요.

예를 들어 사전조건을 사용해 서버의 보안 그룹이 포트 80 또는 443의 트래픽을 허용하는 인그레스 규칙을 최소 하나 이상 갖는지 확인할 수 있어요.

output "instance_public_ip" {
  value = aws_instance.web.public_ip

  precondition {
    condition     = length([for rule in aws_security_group.web.ingress : rule if rule.to_port == 80 || rule.to_port == 443]) > 0
    error_message = "Security group must allow HTTP (port 80) or HTTPS (port 443) traffic."
  }
}

precondition이 실패하면 테라폼은 error_message와 함께 오류를 던지고 현재 작업을 멈춰요. 자세한 내용은 output 블록 레퍼런스를 참고하세요.

사후조건 (Postconditions)

테라폼은 리소스에 변경을 계획하고 적용한 뒤, 또는 데이터 소스에서 읽은 뒤에 postcondition 블록을 평가해요.

예를 들어 postcondition을 사용해 사용자가 잘못된 시스템 컴포넌트용 AMI를 실수로 제공했는지 감지할 수 있어요.

data "aws_ami" "example" {
  executable_users = ["self"]
  most_recent      = true
  owners           = ["self"]
  filter {
    name   = "name"
    values = ["myami-*"]
  }

  lifecycle {
    # The AMI ID must refer to an existing AMI that has the tag "nomad-server".
    postcondition {
      condition     = self.tags["Component"] == "nomad-server"
      error_message = "tags[\"Component\"] must be \"nomad-server\"."
    }
  }
}

컴포넌트에 "nomad-server" 태그가 없으면 사후조건이 실패해서, 잘못된 AMI로 서버를 프로비저닝하는 것을 방지해요. 사후조건이 실패하면 테라폼은 error_message 인자와 함께 오류를 던지고 현재 작업을 멈춰요.

사후조건을 추가하면 다른 의존 리소스로의 연쇄 변경(cascading changes)을 방지할 수 있어요. postcondition 블록 사용의 더 많은 예시는 리소스 구성 레퍼런스를 참고하세요.

사후조건은 data와 resource 블록에 필수 구성 측면을 강제하는 정적 가드레일(guardrail) 역할을 할 수 있어요. 외부 또는 변화하는 조건에 대해 인프라를 동적으로 검증하려면, 사후조건 이후 테라폼 작업의 마지막 단계로 실행되는 check 블록을 사용하는 것을 권장해요. check 블록에 대해 더 알아보세요.

사전조건 또는 사후조건 고르기 (Choose between a precondition or postcondition)

종종 서로 다른 종류의 검증으로 유사한 검증을 구현해 같은 결과를 얻을 수 있어요. 예를 들어 데이터를 생성하는 리소스에 사후조건을 추가하거나, 같은 데이터를 참조하는 리소스나 출력에 사전조건을 추가할 수 있어요. 사전조건과 사후조건 중 선택하려면, 설정하려는 규칙이 구성에 대해 해야 하는 가정을 나타내는지, 결과 리소스에 대한 보장을 나타내는지, 그리고 언제 실행되어야 하는지 고려해요.

테라폼이 대상 블록을 만들기 전에 검증하고 싶은 가정에는 사전조건을 사용해요. 예를 들어 aws_instance용으로 선택한 AMI가 인스턴스를 만들기 전에 x86_64 CPU 아키텍처를 갖는지 확인하고 싶을 수 있어요. 가정에 사전조건을 사용하면 미래의 유지보수 담당자가 리소스·출력·데이터 소스가 허용해야 하는 값을 이해하는 데 도움을 줘요.

테라폼이 리소스를 만들거나 데이터 소스에서 읽은 뒤에 검증해야 하는 보장에는 사후조건을 사용해요. 예를 들어 aws_instance가 개인 DNS 레코드를 할당해주는 네트워크에서 시작되었는지 확인하고 싶을 수 있어요. 보장에 사후조건을 사용하면 미래의 유지보수 담당자가 구성을 변경할 때 보존해야 하는 동작을 이해하는 데 도움을 줘요.

사전조건과 사후조건을 결정하는 데 다음 고려사항을 사용해요.

• 어느 블록이 오류 메시지를 가장 명확하게 보고할지 결정해요. 예를 들어 리소스에 의존성이 많다면, 각 의존성에 사전조건을 두는 것보다 그 리소스에 사후조건을 하나 선언하는 것이 실용적일 수 있어요.
• 사전조건과 사후조건에 같은 조건을 선언해야 하는지 결정해요. 사후조건이 사전조건과 다른 모듈에 있다면 둘 다 두는 것이 유익할 수 있어요. 각 모듈이 독립적으로 진화하면서 서로를 검증해주기 때문이에요.

Checks (Checks)

직접 해보기: check 블록 사용법은 Checks로 인프라 검증 튜토리얼을 참고하세요.

일반적인 리소스 생명주기 밖에서 인프라를 검증하려면 check 블록을 사용해요.

check 블록은 테라폼이 인프라를 계획하거나 프로비저닝한 뒤, plan 또는 apply 작업의 마지막 단계로 실행돼요. check 블록의 단언(assert)이 실패하면 테라폼은 경고를 보고하고 현재 작업을 계속 실행해요.

check 블록을 사용해 다음 작업을 완료할 수 있어요.

• 구성의 리소스, 데이터 소스, 변수, 출력 검증.
• 인프라 전체의 동작 검증.
• 작업을 막지 않고 인프라 구성을 검증.
• HCP Terraform에서 지속적 검증 수행.

다음 예제는 check 블록으로 테라폼 웹사이트가 정상인지 검증해요.

check "health_check" {
  data "http" "terraform_io" {
    url = "https://www.terraform.io"
  }

  assert {
    condition = data.http.terraform_io.status_code == 200
    error_message = "${data.http.terraform_io.url} returned an unhealthy status code"
  }
}

웹사이트 엔드포인트가 200 상태 코드를 반환하면 웹사이트는 정상이고 check는 통과해요. 다른 검증 방식과 달리 check 블록은 작업을 막지 않아요. 단언이 false로 평가되면 테라폼은 error_message 표현식의 결과를 포함한 경고를 던지고 작업을 계속해요.

자세한 내용은 check 구성 레퍼런스를 참고하세요.

HCP Terraform에서 지속적 검증 (Continuous validation in HCP Terraform)

워크스페이스에서 health checks를 활성화하면 HCP Terraform이 워크스페이스 구성의 모든 check 블록, 사전조건, 사후조건을 지속적으로 검증해서 인프라를 정기적으로 확인해요. 예를 들어 check 블록으로 API 게이트웨이 인증서의 유효성을 지속적으로 모니터링할 수 있어요. 지속적 검증은 조건이 실패할 때 경고하므로, 인증서를 갱신하고 다음에 인프라를 갱신할 때 오류를 피할 수 있어요.

자세한 내용은 지속적 검증(Continuous validation)을 참고하세요.

검증 순서 (Order of validation)

테라폼은 구성의 여러 측면을 가능한 한 빨리 검증해요. 일반적으로 테라폼은 다음 순서로 평가를 실행해요.

1. 테라폼은 입력 변수 검증을 plan을 생성하기 전에 즉시 실행해요.
2. 테라폼은 plan을 생성한 뒤, 리소스·데이터 소스·출력을 만들기 전에 사전조건을 실행해요.
3. 테라폼은 변경을 계획하고 적용한 뒤 사후조건을 실행해요.
4. 테라폼은 plan과 apply 작업이 끝날 때, 그리고 HCP Terraform에서 워크스페이스에 health assessments가 실행될 때마다 checks를 실행해요.

테라폼이 check 블록, 사전조건, 사후조건을 실행하는 정확한 순서는 테라폼이 조건 값에 대한 정보를 구성을 적용하기 전에 갖는지 아니면 후에 갖는지에 따라 달라질 수 있어요. 관련 값을 apply 작업 전에 사용할 수 있다면 테라폼은 planning 단계에서 검증을 수행해요. 예를 들어 테라폼이 planning 동안 리소스의 이미지 ID에 접근할 수 있다면, 그 ID에 의존하는 어떤 검증이든 실행할 수 있어요.

테라폼이 값을 apply 후에만 알게 된다면 그 검증은 apply 단계로 미뤄져요. 예를 들어 AWS는 EC2 인스턴스를 시작할 때 루트 볼륨 ID를 할당하므로, 테라폼은 apply가 완료될 때까지 루트 볼륨 ID를 참조할 수 없어요.

apply 단계에서 실패한 사전조건은 연관된 리소스·데이터 소스·출력에 대한 계획된 작업을 테라폼이 수행하지 못하게 해요. 실패한 사후조건은 처리를 중단하고 그 리소스나 데이터 소스에 의존하는 추가 다운스트림 작업을 막지만, 테라폼이 이미 수행한 작업은 되돌리지 않아요.

오류 메시지 (Error Messages)

입력 변수 검증, 사전조건, 사후조건, checks는 모두 error_message 인자를 포함해야 해요. 이 인자는 테라폼이 충족되지 않은 조건을 감지할 때 오류 메시지의 일부로 포함하는 텍스트를 담아요.

Error: Resource postcondition failed

  with data.aws_ami.example,
  on ec2.tf line 19, in data "aws_ami" "example":
  72:       condition     = self.tags["Component"] == "nomad-server"
    |----------------
    | self.tags["Component"] is "consul-server"

The selected AMI must be tagged with the Component value "nomad-server".

error_message 인자는 문자열로 평가되는 어떤 표현식이든 지원해요. 여기에는 리터럴 문자열, heredoc, 템플릿 표현식이 포함돼요. format 함수를 사용해 null, list, map 타입 항목을 서식화된 문자열로 변환할 수 있어요. 여러 줄 오류 메시지도 지원되며, 테라폼은 선행 공백이 있는 줄을 감싸지(wrap) 않아요.

오류 메시지는 테라폼 자체의 오류 메시지와 비슷한 스타일로 하나 이상의 완전한 문장으로 작성하는 것을 권장해요. 테라폼은 문제를 감지한 리소스의 이름과 조건 표현식에 포함된 외부 값들과 함께 메시지를 표시해요.

조건 (Conditions)

검증에 사용할 수 있는 조건에 대해 더 알아보려면 조건식(Conditional Expressions)을 참고하세요.

다음 단계

구성 검증은 인프라의 위험을 완화하는 첫 단계예요. 인프라 생명주기의 위험 완화에 대한 추가 정보는 다음 주제를 참고하세요.

• 테스트(Tests) — 작성자가 모듈 구성 갱신이 파괴적 변경(breaking changes)을 도입하지 않는지 검증하게 해줘요.
• HCP Terraform의 정책 기능(Policy features) — 테라폼 plan을 실행할 때 조직의 보안 규칙과 모범 사례 준수를 강제해요.

더 알아보기 (Learn more)

• 사용자 지정 조건(custom conditions) — 사전조건·사후조건 세부.
• check 블록 레퍼런스 — check 블록.
• 입력 변수 검증 — 변수 검증.