기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

코드 기반 구조 및 구성 모범 사례

대규모 팀과 기업에서 Terraform 사용이 증가함에 따라 적절한 코드 기반 구조와 구성이 매우 중요합니다. 잘 설계된 코드베이스는 유지 관리성을 향상시키면서 대규모 협업을 가능하게 합니다.

이 섹션에서는 품질과 일관성을 지원하는 Terraform 모듈성, 명명 규칙, 문서 및 코딩 표준에 대한 권장 사항을 제공합니다.

지침에는 환경 및 구성 요소별로 구성을 재사용 가능한 모듈로 나누고, 접두사와 접미사를 사용하여 명명 규칙을 수립하고, 모듈을 문서화하고 입력과 출력을 명확하게 설명하며, 자동화된 스타일 검사를 사용하여 일관된 형식 지정 규칙을 적용하는 것이 포함됩니다.

추가 모범 사례에는 모듈과 리소스를 구조화된 계층 구조로 논리적으로 구성하고, 공개 및 비공개 모듈을 문서에 분류하고, 불필요한 구현 세부 정보를 모듈로 추상화하여 사용을 단순화하는 것이 포함됩니다.

모듈성, 문서화, 표준 및 논리적 구성에 대한 코드 기반 구조 지침을 구현하면 팀 간의 광범위한 협업을 지원하는 동시에 조직 전체에 사용량이 분산되어도 Terraform을 유지 관리할 수 있습니다. 규칙과 표준을 적용하면 조각난 코드베이스의 복잡성을 피할 수 있습니다.

표준 리포지토리 구조 구현

다음 리포지토리 레이아웃을 구현하는 것이 좋습니다. 모듈 전반에 걸쳐 이러한 일관성 관행을 표준화하면 검색 가능성, 투명성, 구성 및 안정성이 향상되는 동시에 여러 Terraform 구성에서 재사용할 수 있습니다.

루트 모듈 구조

Terraform은 항상 단일 루트 모듈의 컨텍스트에서 실행됩니다. 완전한 Terraform 구성은 루트 모듈과 하위 모듈 트리 (루트 모듈에서 호출하는 모듈, 해당 모듈에서 호출하는 모든 모듈 등 포함) 로 구성됩니다.

Terraform 루트 모듈 레이아웃 기본 예제:

.
├── data.tf
├── envs
│   ├── dev
│   │   └── terraform.tfvars
│   ├── prod
│   │   └── terraform.tfvars
│   └── test
│       └── terraform.tfvars
├── locals.tf
├── main.tf
├── outputs.tf
├── providers.tf
├── README.md
├── terraform.tfvars
├── variables.tf
└── versions.tf

재사용 가능한 모듈 구조

재사용 가능 모듈은 루트 모듈과 동일한 개념을 따릅니다. 모듈을 정의하려면 루트 모듈을 정의하는 것처럼 새 디렉토리를 만들고 그 안에 .tf 파일을 배치하십시오. Terraform은 로컬 상대 경로 또는 원격 리포지토리에서 모듈을 로드할 수 있습니다. 여러 구성에서 모듈을 재사용할 것으로 예상되는 경우 자체 버전 제어 리포지토리에 배치하세요. 모듈을 다양한 조합으로 쉽게 재사용할 수 있도록 모듈 트리를 비교적 평평하게 유지하는 것이 중요합니다.

Terraform 재사용 가능한 모듈 레이아웃 기본 예제:

.
├── data.tf
├── examples
│   ├── multi-az-new-vpc
│   │   ├── data.tf
│   │   ├── locals.tf
│   │   ├── main.tf
│   │   ├── outputs.tf
│   │   ├── providers.tf
│   │   ├── README.md
│   │   ├── terraform.tfvars
│   │   ├── variables.tf
│   │   ├── versions.tf
│   │   └── vpc.tf
│   └── single-az-existing-vpc
│   │   ├── data.tf
│   │   ├── locals.tf
│   │   ├── main.tf
│   │   ├── outputs.tf
│   │   ├── providers.tf
│   │   ├── README.md
│   │   ├── terraform.tfvars
│   │   ├── variables.tf
│   │   └── versions.tf
├── iam.tf
├── locals.tf
├── main.tf
├── outputs.tf
├── README.md
├── variables.tf
└── versions.tf

모듈화를 위한 구조

원칙적으로 모든 리소스와 기타 구조를 모듈로 결합할 수 있지만 중첩되고 재사용 가능한 모듈을 과도하게 사용하면 전체 Terraform 구성을 이해하고 유지 관리하기가 더 어려워질 수 있으므로 이러한 모듈을 적당히 사용하십시오.

합당하다면 구성을 재사용 가능한 모듈로 나눠 리소스 유형으로 구성된 아키텍처의 새로운 개념을 설명함으로써 추상화 수준을 높이세요.

인프라를 재사용 가능한 정의로 모듈화할 때는 개별 구성 요소나 지나치게 복잡한 컬렉션 대신 논리적인 리소스 세트를 사용하는 것이 좋습니다.

단일 리소스를 래핑하지 마세요.

다른 단일 리소스 유형을 중심으로 얇은 래퍼 형태의 모듈을 만들면 안 됩니다. 모듈에 포함된 기본 리소스 유형의 이름과 다른 이름을 찾는 데 문제가 있다면 모듈이 새로운 추상화를 생성하지 않는 것일 수 있습니다. 불필요한 복잡성이 가중되기 때문입니다. 대신 호출 모듈에서 직접 리소스 유형을 사용하세요.

논리적 관계를 캡슐화하세요.

네트워킹 기반, 데이터 계층, 보안 제어, 애플리케이션 등의 관련 리소스 세트를 그룹화합니다. 재사용 가능한 모듈은 기능을 활성화하기 위해 함께 작동하는 인프라 요소를 캡슐화해야 합니다.

상속은 단순하게 유지하세요.

모듈을 하위 디렉터리에 중첩할 때는 1~2단계 이상 깊이로 이동하지 마세요. 깊이 중첩된 상속 구조는 구성과 문제 해결을 복잡하게 만듭니다. 모듈은 다른 모듈을 기반으로 빌드해야 하며, 다른 모듈을 통해 터널을 구축해서는 안 됩니다.

아키텍처 패턴을 나타내는 논리적 리소스 그룹화에 모듈을 집중함으로써 팀은 신뢰할 수 있는 인프라 기반을 신속하게 구성할 수 있습니다. 과도한 엔지니어링이나 지나친 단순화 없이 추상화의 균형을 맞출 수 있습니다.

산출물의 참조 리소스

재사용 가능한 모듈에 정의된 모든 리소스에 대해 해당 리소스를 참조하는 출력을 하나 이상 포함하세요. 변수와 출력을 통해 모듈과 리소스 간의 종속성을 유추할 수 있습니다. 출력이 없으면 사용자는 Terraform 구성과 관련하여 모듈을 올바르게 주문할 수 없습니다.

환경 일관성, 목적 기반 그룹화 및 내보낸 리소스 참조를 제공하는 잘 구성된 모듈을 통해 조직 전반의 Terraform 대규모 협업이 가능합니다. 팀은 재사용 가능한 구성 요소로 인프라를 조립할 수 있습니다.

제공자를 구성하지 마세요.

공유 모듈은 호출 모듈의 공급자를 상속하지만 모듈 자체가 제공자 설정을 구성해서는 안 됩니다. 모듈에 제공자 구성 블록을 지정하지 마십시오. 이 구성은 전역적으로 한 번만 선언해야 합니다.

필수 제공자 신고

공급자 구성은 모듈 간에 공유되지만 공유 모듈은 자체 공급자 요구 사항도 선언해야 합니다. 이 방법을 통해 Terraform은 구성의 모든 모듈과 호환되는 단일 버전의 공급자가 있는지 확인하고 공급자의 글로벌 (모듈에 구애받지 않는) 식별자 역할을 하는 소스 주소를 지정할 수 있습니다. 그러나 모듈별 공급자 요구 사항에는 공급자가 액세스할 원격 엔드포인트를 결정하는 구성 설정 (예: a) 이 지정되어 있지 않습니다. AWS 리전

버전 요구 사항을 선언하고 하드코딩된 공급자 구성을 피함으로써 모듈은 공유 공급자를 사용하여 Terraform 구성 전반에 걸쳐 이식성과 재사용성을 제공합니다.

공유 모듈의 경우 required_providers 블록인에서 필요한 최소 공급자 버전을 정의하십시오. versions.tf

모듈에 특정 버전의 AWS 제공자가 필요하다고 선언하려면 required_providers 블록 안에 블록을 사용하십시오. terraform

terraform {
  required_version = ">= 1.0.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 4.0.0"
    }
  }
}

공유 모듈이 특정 버전의 AWS 제공자만 지원하는 경우 가장 오른쪽에 있는 버전 구성 요소만 증가하도록 허용하는 비관적 제약 조건 연산자 (~>) 를 사용하십시오.

terraform {
  required_version = ">= 1.0.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 4.0"
    }
  }
}

이 예제에서는 설치는 ~> 4.0 허용하지만 설치는 허용하지 않습니다. 4.57.1 4.67.0 5.0.0 자세한 내용은 HashiCorp 설명서의 버전 제약 구문을 참조하십시오.

명명 규칙을 따르십시오.

명확하고 설명적인 이름을 사용하면 모듈의 리소스와 구성 값의 목적 간의 관계를 쉽게 이해할 수 있습니다. 스타일 가이드라인을 일관되게 준수하면 모듈 사용자와 유지 관리자 모두 가독성을 높일 수 있습니다.

리소스 이름 지정 가이드라인을 따르세요.

변수 이름 지정 가이드라인을 따르세요.

첨부 리소스 사용

일부 리소스에는 가상 리소스가 속성으로 내장되어 있습니다. 가능하면 이러한 내장된 리소스 속성을 사용하지 말고 대신 고유한 리소스를 사용하여 해당 유사 리소스를 연결해야 합니다. 이러한 리소스 관계로 인해 각 리소스마다 고유한 cause-and-effect 문제가 발생할 수 있습니다.

내장된 속성 사용 (이 패턴은 피해야 함):

resource "aws_security_group" "allow_tls" {
  ...
  ingress {
    description      = "TLS from VPC"
    from_port        = 443
    to_port          = 443
    protocol         = "tcp"
    cidr_blocks      = [aws_vpc.main.cidr_block]
    ipv6_cidr_blocks = [aws_vpc.main.ipv6_cidr_block]
  }

  egress {
    from_port        = 0
    to_port          = 0
    protocol         = "-1"
    cidr_blocks      = ["0.0.0.0/0"]
    ipv6_cidr_blocks = ["::/0"]
  }
}

첨부 리소스 사용 (권장):

resource "aws_security_group" "allow_tls" {
  ...
}

resource "aws_security_group_rule" "example" {
  type              = "ingress"
  description      = "TLS from VPC"
  from_port        = 443
  to_port          = 443
  protocol         = "tcp"
  cidr_blocks      = [aws_vpc.main.cidr_block]
  ipv6_cidr_blocks = [aws_vpc.main.ipv6_cidr_block]
  security_group_id = aws_security_group.allow_tls.id
}

기본 태그 사용

태그를 받아들일 수 있는 모든 리소스에 태그를 할당하세요. 테라폼 AWS 공급자에는 루트 모듈 내에서 사용해야 하는 aws_default_tags 데이터 소스가 있습니다.

Terraform 모듈에서 생성하는 모든 리소스에 필요한 태그를 추가하는 것을 고려해 보세요. 첨부할 수 있는 태그 목록은 다음과 같습니다.

Terraform 레지스트리 요구 사항 충족

모듈 리포지토리는 다음 요구 사항을 모두 충족해야 Terraform 레지스트리에 게시할 수 있습니다.

단기간에 모듈을 레지스트리에 게시할 계획이 없더라도 항상 이러한 요구 사항을 준수해야 합니다. 이렇게 하면 나중에 저장소의 구성과 구조를 변경할 필요 없이 모듈을 레지스트리에 게시할 수 있습니다.

자세한 내용은 Terraform 설명서의 모듈 리포지토리 준비를 참조하십시오.

권장 모듈 소스 사용

Terraform은 모듈 블록의 source 인수를 사용하여 하위 모듈의 소스 코드를 찾아 다운로드합니다.

반복되는 코드 요소를 제거하는 것이 주 목적인 밀접하게 관련된 모듈에는 로컬 경로를 사용하고, 여러 구성에서 공유하려는 모듈에는 네이티브 Terraform 모듈 레지스트리 또는 VCS 공급자를 사용하는 것이 좋습니다.

다음 예는 모듈 공유를 위한 가장 일반적이고 권장되는 소스 유형을 보여줍니다. 레지스트리 모듈은 버전 관리를 지원합니다. 다음 예와 같이 항상 특정 버전을 제공해야 합니다.

레지스트리

테라폼 레지스트리:

module "lambda" {
  source = "github.com/terraform-aws-modules/terraform-aws-lambda.git?ref=e78cdf1f82944897ca6e30d6489f43cf24539374" #--> v4.18.0

  ...

}

커밋 해시를 고정하면 공급망 공격에 취약한 공개 레지스트리로부터의 드리프트를 피할 수 있습니다.

HCP 테라폼:

module "eks_karpenter" {
  source = "app.terraform.io/my-org/eks/aws"
  version = "1.1.0"

  ...

  enable_karpenter = true
}

테라폼 엔터프라이즈:

module "eks_karpenter" {
  source = "terraform.mydomain.com/my-org/eks/aws"
  version = "1.1.0"

  ...

  enable_karpenter = true
}

VCS 제공업체

VCS 공급자는 다음 예와 같이 특정 개정을 선택하는 ref 주장을 지지합니다.

GitHub (HTTPS):

module "eks_karpenter" {
  source = "github.com/my-org/terraform-aws-eks.git?ref=v1.1.0"

  ...

  enable_karpenter = true
}

일반 Git 리포지토리 (HTTPS):

module "eks_karpenter" {
  source = "git::https://example.com/terraform-aws-eks.git?ref=v1.1.0"

  ...

  enable_karpenter = true
}

일반 Git 리포지토리 (SSH):

module "eks_karpenter" {
  source = "git::ssh://username@example.com/terraform-aws-eks.git?ref=v1.1.0"

  ...

  enable_karpenter = true
}

코딩 표준을 따르세요.

모든 구성 파일에 일관된 Terraform 형식 지정 규칙 및 스타일을 적용합니다. CI/CD 파이프라인에서 자동화된 스타일 검사를 사용하여 표준을 적용하세요. 코딩 모범 사례를 팀 워크플로에 포함하면 조직 전체에 널리 사용되더라도 구성을 읽고 유지 관리할 수 있으며 협업이 가능한 상태로 유지됩니다.

스타일 가이드라인을 따르세요.

사전 커밋 후크를 구성합니다.

커밋을 허용하기 전에terraform fmt, tflintcheckov, 및 기타 코드 스캔과 스타일 검사를 실행하는 클라이언트측 사전 커밋 후크를 구성하십시오. 이 방법을 사용하면 개발자 워크플로의 초기에 표준 적합성을 검증할 수 있습니다.

사전 커밋과 같은 사전 커밋 프레임워크를 사용하여 Terraform 린팅, 형식 지정 및 코드 스캔을 로컬 시스템의 후크로 추가할 수 있습니다. Hook은 각 Git 커밋에서 실행되며 검사가 통과하지 못하면 커밋에 실패합니다.

스타일 및 품질 검사를 로컬 사전 커밋 후크로 옮기면 변경 사항이 도입되기 전에 개발자에게 빠른 피드백을 제공할 수 있습니다. 표준은 코딩 워크플로의 일부가 됩니다.