재사용 가능한 모듈 권장사항

이 문서에는 재사용 가능한 Terraform 모듈 사용 시 고려해야 할 가이드라인과 권장사항을 제공합니다.

이 가이드는 Terraform 소개 내용이 아닙니다. Google Cloud에서 Terraform 사용에 대한 소개는 정보는 Terraform 시작하기를 참조하세요.

모듈에서 필요한 API 활성화

Terraform 모듈은 google_project_service 리소스 또는 project_services 모듈을 사용하여 필요한 서비스를 활성화할 수 있습니다. API 활성화를 포함하면 데모가 더 쉬워집니다.

  • API 활성화가 모듈에 포함된 경우 기본적으로 true로 설정되는 enable_apis 변수를 노출하여 API 활성화를 사용 중지할 수 있어야 합니다.

  • API 활성화가 모듈에 포함된 경우에는 모듈의 여러 인스턴스를 사용할 때 이 속성으로 인해 문제가 발생할 수 있기 때문에 API 활성화가 disable_services_on_destroy를 false로 설정해야 합니다.

    예를 들면 다음과 같습니다.

    module "project-services" {
  source  = "terraform-google-modules/project-factory/google//modules/project_services"
  version = "~> 12.0"

  project_id  = var.project_id
  enable_apis = var.enable_apis

  activate_apis = [
    "compute.googleapis.com",
    "pubsub.googleapis.com",
  ]
  disable_services_on_destroy = false
}

소유자 파일 포함

모든 공유 모듈의 경우 OWNERS 파일(또는 GitHub의 CODEOWNERS)을 포함하고 모듈 책임자를 기술합니다. pull 요청을 병합하려면 먼저 소유자가 이를 승인해야 합니다.

태그 지정된 버전 출시

일부 경우에는 모듈에 브레이킹 체인지가 필요하고 구성을 특정 버전으로 고정할 수 있도록 해당 효과를 사용자에게 알려야 합니다.

새 버전이 태그 지정되었거나 출시되었을 때 공유 모듈이 SemVer v2.0.0을 따르는지 확인합니다.

모듈을 참조할 때는 버전 제약조건을 사용해서 해당 주 버전으로 고정합니다. 예를 들면 다음과 같습니다.

module "gke" {
  source  = "terraform-google-modules/kubernetes-engine/google"
  version = "~> 20.0"
}

제공자 또는 백엔드 선언 안 함

공유 모듈은 제공자 또는 백엔드를 구성하지 않아야 합니다. 대신 루트 모듈에서 제공자 및 백엔드를 구성합니다.

공유 모듈의 경우 required_providers 블록에서 다음과 같이 필요한 최소 제공자 버전을 정의합니다.

terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = ">= 4.0.0"
    }
  }
}

달리 입증되지 않은 한 새 제공자 버전이 작동한다고 가정합니다.

라벨을 변수로 노출

모듈 인터페이스를 통한 리소스 라벨 지정을 유연하게 수행합니다. 다음과 같이 빈 맵의 기본값을 labels 변수에 제공합니다.

variable "labels" {
  description = "A map of labels to apply to contained resources."
  default     = {}
  type        = "map"
}

모든 리소스에 대해 출력 노출

변수 및 출력을 사용해서 모듈과 리소스 사이의 종속 항목을 유추할 수 있습니다. 출력이 없으면 해당 Terraform 구성과 관련해서 사용자가 모듈을 올바르게 주문할 수 없습니다.

공유 모듈에 정의된 모든 리소스에 대해 리소스를 참조하는 출력을 하나 이상 포함합니다.

복잡한 논리에 인라인 하위 모듈 사용

  • 인라인 모듈을 사용하여 복잡한 Terraform 모듈을 더 작고 중복성이 제거된 공통 리소스로 관리할 수 있습니다.
  • modules/$modulename에 인라인 모듈을 둡니다.
  • 공유 모델 문서에 특별히 기술되어 있지 않은 한 인라인 모듈을 외부 모듈에 사용되지 않는 비공개 모듈로 취급합니다.
  • Terraform은 리팩터링된 리소스를 추적하지 않습니다. 최상위 모듈에서 일부 리소스로 시작하고 이를 하위 모듈에 푸시하면 Terraform이 모든 리팩터링된 리소스를 다시 만들려고 시도합니다. 이러한 동작을 해결하기 위해서는 리팩터링할 때 moved 블록을 사용합니다.
  • 내부 모듈에 정의된 출력은 자동으로 노출되지 않습니다. 내부 모듈의 출력을 공유하려면 이를 다시 내보냅니다.

다음 단계