루트 모듈 권장사항

이 문서에서는 루트 모듈을 사용할 때 고려해야 할 가이드라인과 권장사항을 제공합니다.

루트 구성 또는 루트 모듈은 Terraform CLI를 실행하는 작업 디렉터리입니다. 루트 구성이 다음 표준(및 해당하는 경우 이전 Terraform 가이드라인)을 준수하는지 확인합니다. 루트 모듈에 대해 명시적인 권장사항이 있으면 일반 가이드라인보다 우선 적용됩니다.

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

각 루트 모듈의 리소스 수 최소화

동일한 디렉터리 및 상태로 너무 많은 리소스가 저장되어 단일 루트 구성이 너무 커지지 않도록 하는 것이 좋습니다. 특정 루트 구성의 모든 리소스는 Terraform이 실행될 때마다 새로고침됩니다. 이렇게 하면 단일 상태에 포함된 리소스가 너무 많은 경우 실행 속도가 느려질 수 있습니다. 일반 규칙: 단일 상태에 포함되는 리소스 수를 100개 미만(이상적으로는 몇십 개까지만)으로 제한하는 것이 좋습니다.

각 애플리케이션에 개별 디렉터리 사용

애플리케이션 및 프로젝트를 서로 독립적으로 관리하기 위해 각 애플리케이션 및 프로젝트의 리소스를 자체 Terraform 디렉터리에 둡니다. 서비스는 특정 애플리케이션 또는 공유 네트워킹과 같은 공통 서비스를 제공할 수 있습니다. 특정 서비스의 모든 Terraform 코드를 하나의 디렉터리(하위 디렉터리 포함)에 끼워 넣습니다.

애플리케이션을 환경별 하위 디렉터리로 분할

Google Cloud에서 서비스를 배포할 때 해당 서비스의 Terraform 구성을 2개의 최상위 디렉터리로 분할합니다. 하나는 서비스의 실제 구성이 포함된 modules 디렉터리이고 다른 하나는 각 환경의 루트 구성이 포함된 environments 디렉터리입니다.

-- SERVICE-DIRECTORY/
   -- OWNERS
   -- modules/
      -- <service-name>/
         -- main.tf
         -- variables.tf
         -- outputs.tf
         -- provider.tf
         -- README
      -- ...other…
   -- environments/
      -- dev/
         -- backend.tf
         -- main.tf

      -- qa/
         -- backend.tf
         -- main.tf

      -- prod/
         -- backend.tf
         -- main.tf

환경 디렉터리 사용

환경 간 코드 공유를 위해 모듈을 참조합니다. 일반적으로 서비스의 기본 공유 Terraform 구성이 포함된 서비스 모듈일 수 있습니다. 서비스 모듈에서 공통 입력을 하드 코딩하고 환경 특정 입력만 변수로 요구합니다.

각 환경 디렉터리에는 다음 파일이 포함되어야 합니다.

  • Terraform backend 상태 위치(일반적으로 Cloud Storage)를 선언하는 backend.tf 파일
  • 서비스 모듈을 인스턴스화하는 main.tf 파일

각 환경 디렉터리(dev, qa, prod)는 기본 Terraform 작업공간에 해당하며 서비스 버전을 이 환경에 배포합니다. 이러한 작업공간은 환경별 리소스를 자체 컨텍스트로 격리합니다. 기본 작업공간만 사용합니다.

한 환경 내 여러 개의 CLI 작업공간은 다음과 같은 이유로 권장되지 않습니다.

  • 각 작업공간에서 구성을 검사하기 어려울 수 있습니다.
  • 공유 백엔드가 환경 분리에 사용될 경우 단일 장애점이 되기 때문에 여러 작업공간에 단일 공유 백엔드를 사용하는 것은 권장되지 않습니다.
  • 코드 재사용이 가능하지만 현재 작업공간 변수(예: terraform.workspace == "foo" ? this : that)에 따라 코드를 전환해야 하는 코드는 읽기가 어려워집니다.

자세한 내용은 다음을 참조하세요.

원격 상태를 통한 출력 노출

루트 모듈에서 모듈 인스턴스의 유용한 출력을 노출하는지 확인합니다.

예를 들어 다음 코드 스니펫은 프로젝트 팩토리 모듈 인스턴스의 프로젝트 ID 출력을 루트 모듈의 출력으로 전달합니다.

# Project root module
terraform {
  backend "gcs" {
    bucket  = "BUCKET"
  }
}

module "project" {
  source  = "terraform-google-modules/project-factory/google"
  ...
}

output "project_id" {
  value       = module.project.project_id
  description = "The ID of the created project"
}

다른 Terraform 환경 및 애플리케이션은 루트 모듈 수준 출력만 참조할 수 있습니다.

원격 상태를 사용하여 루트 모듈 출력을 참조할 수 있습니다. 구성을 위해 다른 종속된 앱에서 사용하도록 허용하려면 서비스의 엔드포인트와 관련된 정보를 원격 상태로 내보내야 합니다.

# Networks root module
data "terraform_remote_state" "network_project" {
  backend = "gcs"

  config = {
    bucket = "BUCKET"
  }
}

module "vpc" {
  source  = "terraform-google-modules/network/google"
  version = "~> 9.0"

  project_id   = data.terraform_remote_state.network_project.outputs.project_id
  network_name = "vpc-1"
  ...
}

환경 디렉터리에서 공유된 서비스 모듈을 호출할 때와 같은 일부 경우에는 다음과 같이 전체 하위 모듈을 다시 내보내는 것이 적합합니다.

output "service" {
  value       = module.service
  description = "The service module outputs"
}

부 제공자 버전으로 고정

루트 모듈에서 각 제공자를 선언하고 부 버전으로 고정합니다. 이렇게 하면 확실한 대상을 유지하면서도 새 패치 출시 버전으로 자동 업그레이드할 수 있습니다. 일관성을 위해 버전 파일의 이름을 versions.tf로 지정합니다.

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

tfvars 파일에 변수 저장

루트 모듈의 경우 .tfvars 변수 파일을 사용하여 변수를 제공합니다. 일관성을 위해 변수 파일 이름을 terraform.tfvars로 지정합니다.

대체 var-files 또는 var='key=val' 명령줄 옵션을 사용하여 변수를 지정하지 마세요. 명령줄 옵션은 임시적이고 잊기 쉽습니다. 기본 변수 파일을 사용하는 것이 보다 예측 가능합니다.

.terraform.lock.hcl 파일 체크인

루트 모듈의 경우 .terraform.lock.hcl 종속 항목 잠금 파일을 소스 제어에 체크인해야 합니다. 이렇게 하면 지정된 구성의 제공업체 선택 항목의 변경사항을 추적하고 검토할 수 있습니다.

다음 단계