콘텐츠로 이동
@aws/nx-plugin
Blog

Terraform 인프라

Terraform은 인프라를 안전하고 예측 가능하게 생성, 변경 및 개선할 수 있는 오픈 소스 코드형 인프라 소프트웨어 도구입니다.

Terraform 인프라 생성기는 Terraform 인프라 프로젝트를 생성합니다. 생성된 애플리케이션에는 Checkov 보안 검사를 통한 보안 모범 사례가 포함되어 있습니다.

사용법

섹션 제목: “사용법”

Terraform 프로젝트 생성

섹션 제목: “Terraform 프로젝트 생성”

두 가지 방법으로 새 Terraform 프로젝트를 생성할 수 있습니다:

이 제너레이터 실행@aws/nx-plugin:terraform#project

pnpm nx g @aws/nx-plugin:terraform#project
명령 구성하기5

필수

어떤 파일이 변경될지 확인하기 위해 드라이 런을 수행할 수도 있습니다

옵션

섹션 제목: “옵션”
제너레이터 옵션5 옵션
name필수string

프로젝트의 이름입니다.

typeenum기본값: application

terraform lib(재사용 가능한 모듈) 또는 app(배포 가능한 애플리케이션) 여부입니다.

applicationlibrary
directorystring기본값: packages

새 프로젝트의 디렉토리입니다.

subDirectorystring

프로젝트가 배치되는 하위 디렉토리입니다. 기본값은 프로젝트 이름입니다.

preferInstallDependenciesboolean기본값: true

생성기 실행 후 의존성 설치를 선호할지 여부입니다. 여러 생성기를 일괄 처리할 때 설치를 연기하려면 false로 설정하세요 (후속 생성기가 Nx 프로젝트 그래프를 계산할 수 있도록 필요한 경우 설치는 여전히 실행됩니다); 마지막에 한 번 설치합니다.

생성기 출력

섹션 제목: “생성기 출력”

생성기는 프로젝트 유형에 따라 다른 파일 구조를 생성합니다:

type = application

애플리케이션 타입

섹션 제목: “애플리케이션 타입”

애플리케이션 프로젝트(--type=application)의 경우, 생성기는 원격 상태 관리를 포함한 완전한 Terraform 애플리케이션을 생성합니다:

  • 디렉터리src
    • main.tf 메인 Terraform 구성 파일
    • providers.tf S3 백엔드를 사용한 프로바이더 구성
    • variables.tf 입력 변수 정의
    • outputs.tf 출력 값 정의
    • 디렉터리env 환경별 변수 파일
      • dev.tfvars 개발 환경 변수
  • 디렉터리bootstrap 원격 상태를 위한 부트스트랩 구성
    • main.tf 상태 저장을 위한 S3 버킷 및 정책
    • providers.tf AWS 프로바이더 구성
    • variables.tf 부트스트랩 변수 정의
  • 디렉터리scripts nx bootstrap, bootstrap-destroy 및 init 타겟에서 실행되는 Node 헬퍼
    • aws-config.ts AWS SDK 자격 증명 체인을 통해 계정 + 리전 확인
    • bootstrap.ts 부트스트랩 tfstate를 가져오기/푸시하고 terraform apply 실행
    • bootstrap-destroy.ts 상태 버킷을 비우고 terraform destroy 실행
    • init.ts S3 백엔드 구성으로 terraform init 실행
    • env.ts 공유 프로바이더 캐시에서 terraform init을 가리킴
  • checkov.yml 건너뛸 검사를 포함한 Checkov 구성
  • project.json 프로젝트 구성 및 빌드 타겟
type = library

라이브러리 타입

섹션 제목: “라이브러리 타입”

라이브러리 프로젝트(--type=library)의 경우, 생성기는 재사용 가능한 Terraform 모듈을 위한 더 간단한 구조를 생성합니다:

  • 디렉터리src
    • main.tf 메인 Terraform 모듈 파일
  • checkov.yml 건너뛸 검사를 포함한 Checkov 구성
  • project.json 프로젝트 구성 및 빌드 타겟

Terraform 인프라 구현

섹션 제목: “Terraform 인프라 구현”

src/main.tf 내부에서 Terraform 인프라 작성을 시작할 수 있습니다. 예를 들어:

src/main.tf
locals {
  account_id = data.aws_caller_identity.current.account_id
  aws_region = data.aws_region.current.id
}


resource "null_resource" "print_info" {
  # triggers = {
  #   always_run = timestamp()
  # }


  provisioner "local-exec" {
    command = "echo 'AWS Region: ${local.aws_region}, AWS Account: ${local.account_id}, Environment: ${var.environment}'"
  }
}


# Declare your infrastructure here
resource "aws_s3_bucket" "my_bucket" {
  bucket = "my-unique-bucket-name"
}

위의 S3 버킷은 버킷에 적절한 보안 설정이 활성화되어 있는지 확인하는 Checkov 보안 스캔에 실패할 것입니다.

프로젝트 간 종속성

섹션 제목: “프로젝트 간 종속성”

별도의 프로젝트(lib)에서 모듈을 실행하려면 다음과 같이 할 수 있습니다:

module "lib_module" {
  source = "../../path/to/my-lib/src"
}

이렇게 하면 Nx 그래프가 자동으로 업데이트되어 사용하는 애플리케이션과 라이브러리 간에 종속성이 추가됩니다.

환경 구성

섹션 제목: “환경 구성”

src/env/*.tfvars 파일에서 환경별 변수를 구성합니다.

새 환경을 추가하려면 환경별 변수가 포함된 새 src/env/<environment>.tfvars 파일을 생성하고 새 환경 구성을 위해 project.json의 apply, destroy, init, plan에 새 항목을 추가합니다. 예를 들어, prod 환경을 추가한다고 가정해 봅시다:

# Production environment variables
environment = "prod"
aws_region  = "us-west-2"
type = application

원격 상태 부트스트랩 (애플리케이션 프로젝트만 해당)

섹션 제목: “원격 상태 부트스트랩 (애플리케이션 프로젝트만 해당)”

인프라를 배포하기 전에 원격 상태 백엔드를 부트스트랩해야 합니다. 이렇게 하면 Terraform 상태 파일을 저장할 S3 버킷이 생성됩니다:

Terminal window
pnpm nx bootstrap tf-infra

사용 가능한 타겟

섹션 제목: “사용 가능한 타겟”

사용 가능한 타겟은 프로젝트 유형에 따라 다릅니다:

공통 타겟 (애플리케이션 및 라이브러리 모두)

섹션 제목: “공통 타겟 (애플리케이션 및 라이브러리 모두)”

인프라 검증

섹션 제목: “인프라 검증”

validate 타겟을 사용하여 Terraform 구성을 검증할 수 있습니다:

Terminal window
pnpm nx validate tf-infra

린팅

섹션 제목: “린팅”

Terraform 프로젝트는 terraform fmt를 사용하여 포맷팅을 확인합니다.

린터 실행
섹션 제목: “린터 실행”

프로젝트를 확인하기 위해 린터를 호출하려면 lint 타겟을 실행할 수 있습니다.

Terminal window
pnpm nx lint tf-infra
린트 문제 수정
섹션 제목: “린트 문제 수정”

대부분의 린팅 또는 포맷팅 문제는 --configuration=fix 인수를 사용하여 자동으로 수정할 수 있습니다.

Terminal window
pnpm nx lint tf-infra --configuration=fix

마찬가지로 워크스페이스의 모든 패키지에서 모든 린트 문제를 수정하려면 다음을 실행할 수 있습니다:

Terminal window
pnpm nx run-many --target lint --all --configuration=fix
린트 문제 건너뛰기
섹션 제목: “린트 문제 건너뛰기”

개발 중에 린팅 문제로 인해 속도가 느려지는 것을 방지하려면(특히 프로젝트에 자동으로 수정할 수 없는 문제가 있는 경우) skip-lint 구성으로 빌드를 실행할 수 있습니다:

Terminal window
pnpm nx run-many --target build --configuration=skip-lint

이렇게 하면 빌드 중에 포맷 검사를 완전히 건너뜁니다.

보안 테스트

섹션 제목: “보안 테스트”

checkov 타겟을 사용하여 Checkov로 인프라에 대한 보안 검사를 실행합니다:

Terminal window
pnpm nx checkov tf-infra

보안 테스트 결과는 루트 dist 폴더의 dist/packages/<my-terraform-project>/checkov 아래에서 찾을 수 있습니다.

Checkov는 build의 일부로 실행됩니다.

검사는 프로젝트의 checkov.yml에서 구성됩니다. 전체 프로젝트에서 검사를 억제하려면 skip-check에 검사 ID를 추가하세요:

checkov.yml
skip-check:
  - CKV_AWS_115 # Concurrent execution limit
  - CKV_AWS_116 # Dead Letter Queue

단일 리소스에 대한 검사만 억제하려면 리소스 블록 내부에 #checkov:skip=<id>:<reason> 주석을 추가하세요:

resource "aws_s3_bucket" "example" {
  #checkov:skip=CKV_AWS_18:Access logging not required for this bucket
  bucket = "example"
}

Terraform 테스트 실행

섹션 제목: “Terraform 테스트 실행”

test 타겟은 프로젝트의 모든 .tftest.hcl 파일에 대해 Terraform의 네이티브 테스트 프레임워크를 실행합니다:

Terminal window
pnpm nx test tf-infra

테스트 파일이 없는 프로젝트는 성공으로 처리되므로 필요할 때 테스트를 추가할 수 있습니다. build는 이 타겟을 실행하므로 테스트는 일반 빌드의 일부로 실행됩니다.

각 run 블록은 구성을 평가합니다. command = plan을 사용하여 Terraform이 수행할 작업을 확인하거나(전체 모듈 그래프를 확장하므로 validate가 감지할 수 없는 계획 시간 오류를 포착합니다), command = apply를 사용하여 실제 리소스를 생성하고 출력을 검증할 수 있습니다. mock_provider를 선언하면 API 호출이 이루어지지 않고 AWS 자격 증명이 필요하지 않으므로 plan 테스트를 빠르고 안전하게 CI에서 실행할 수 있습니다:

src/main.tftest.hcl
mock_provider "aws" {
  mock_data "aws_caller_identity" {
    defaults = { account_id = "123456789012" }
  }
  mock_data "aws_region" {
    defaults = { region = "us-east-1" }
  }
}


variables {
  aws_region  = "us-east-1"
  environment = "dev"
}


run "plan_is_valid" {
  command = plan


  assert {
    condition     = data.aws_caller_identity.current.account_id == "123456789012"
    error_message = "Unexpected account id"
  }
}

variables 블록에 구성에 필요한 모든 변수를 설정하세요. 그렇지 않으면 “has a required variable … with no set value” 오류와 함께 실행이 실패합니다.

terraform init을 실행하는 모든 타겟은 워크스페이스 루트의 .terraform/plugin-cache 아래에 있는 프로바이더 캐시를 재사용하므로 프로바이더는 매번 실행할 때마다가 아니라 한 번만 다운로드됩니다. 각 프로젝트는 거기에 자체 디렉터리를 가지고 있습니다: 동시에 하나의 캐시를 채우는 두 개의 terraform init 실행은 각각 동일한 프로바이더에 대해 다른 해시를 계산할 수 있으며, terraform은 이를 .terraform.lock.hcl에 대해 거부합니다. 자세한 내용은 Terraform 문서를 참조하세요.

환경에서 TF_PLUGIN_CACHE_DIR을 설정하여 제공된 init 스크립트가 직접 관리하는 캐시(예: 워크스페이스 간에 공유되는 볼륨)를 가리키도록 할 수 있습니다. test 타겟은 project.json에서 경로를 읽으므로 거기에서도 변경해야 합니다.

type = application

애플리케이션 전용 타겟

섹션 제목: “애플리케이션 전용 타겟”

다음 타겟은 애플리케이션 타입 프로젝트에만 사용할 수 있습니다:

인프라 계획

섹션 제목: “인프라 계획”

변경 사항을 적용하기 전에 plan 타겟을 실행하여 Terraform이 수행할 작업을 확인할 수 있습니다:

Terminal window
pnpm nx plan tf-infra

이렇게 하면 dist/packages/<my-terraform-project>/terraform/dev.tfplan에 계획 파일이 생성됩니다.

plan은 assemble에 의존하므로 Lambda 번들 및 생성된 작업 메타데이터와 같이 모듈이 참조하는 아티팩트를 생성하지만, lint, test 및 type-check 게이트는 실행하지 않습니다.

Terraform 초기화

섹션 제목: “Terraform 초기화”

init 타겟을 사용하여 Terraform 작업 디렉터리를 초기화합니다:

Terminal window
pnpm nx run tf-infra:init

AWS에 배포

섹션 제목: “AWS에 배포”

계획 후 apply 타겟을 사용하여 인프라를 AWS에 배포할 수 있습니다:

Terminal window
pnpm nx apply tf-infra

출력 가져오기

섹션 제목: “출력 가져오기”

Terraform 구성에서 출력 값을 검색합니다:

Terminal window
pnpm nx output tf-infra

인프라 삭제

섹션 제목: “인프라 삭제”

인프라를 해체해야 할 때 destroy 타겟을 사용합니다:

Terminal window
pnpm nx destroy tf-infra

부트스트랩 리소스 삭제

섹션 제목: “부트스트랩 리소스 삭제”

부트스트랩 리소스(상태 저장을 위한 S3 버킷)를 정리하려면:

Terminal window
pnpm nx bootstrap-destroy tf-infra

이렇게 하면 상태 버킷을 파괴하기 전에 비우고, AWS SDK 자격 증명 체인에서 리전을 확인하므로 CI에서 무인으로 실행됩니다.

추가 정보

섹션 제목: “추가 정보”

Terraform에 대한 자세한 내용은 Terraform 문서 및 AWS 프로바이더 문서를 참조하세요.