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

코드 기반 구조 및 조직에 대한 모범 사례

대규모 팀과 엔터프라이즈에서 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 구성을 이해하고 유지 관리하기가 더 어려워질 수 있으므로 이러한 모듈을 조정에 사용하세요.

적절한 경우 구성을 재사용 가능한 모듈로 나누면 리소스 유형으로 구성된 아키텍처의 새로운 개념을 설명하여 추상화 수준을 높일 수 있습니다.

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

단일 리소스를 래핑하지 마십시오.

다른 단일 리소스 유형 주위에 얇은 래퍼인 모듈을 생성해서는 안 됩니다. 모듈 내부에 있는 기본 리소스 유형의 이름과 다른 모듈의 이름을 찾는 데 문제가 있는 경우 모듈이 새로운 추상화를 생성하지 않을 수 있습니다. 불필요한 복잡성이 추가됩니다. 대신 호출 모듈에서 직접 리소스 유형을 사용합니다.

논리적 관계 캡슐화

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

상속을 평평하게 유지

하위 디렉터리에 모듈을 중첩할 때는 하나 또는 두 개 이상의 레벨을 깊이 이동하지 마십시오. 깊이 중첩된 상속 구조는 구성과 문제 해결을 복잡하게 만듭니다. 모듈은 다른 모듈을 기반으로 빌드해야 합니다. 모듈을 통해 터널을 빌드해서는 안 됩니다.

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

출력의 참조 리소스

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

환경 일관성, 목적 기반 그룹화 및 내보낸 리소스 참조를 제공하는 잘 구성된 모듈을 사용하면 조직 전체의 Terraform 공동 작업을 대규모로 수행할 수 있습니다. 팀은 재사용 가능한 빌딩 블록에서 인프라를 조합할 수 있습니다.

공급자 구성 안 함

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

필수 공급자 선언

공급자 구성은 모듈 간에 공유되지만 공유 모듈은 자체 공급자 요구 사항도 선언해야 합니다. 이 방법을 통해 Terraform은 구성의 모든 모듈과 호환되는 공급자의 단일 버전이 있는지 확인하고 공급자의 글로벌(모듈에 구애받지 않음) 식별자 역할을 하는 소스 주소를 지정할 수 있습니다. 그러나 모듈별 공급자 요구 사항은와 같이 공급자가 액세스할 원격 엔드포인트를 결정하는 구성 설정을 지정하지 않습니다 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.57.1 및의 설치를 ~> 4.0 허용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
}

기본 태그 사용

태그를 수락할 수 있는 모든 리소스에 태그를 할당합니다. Terraform AWS Provider에는 루트 모듈 내에서 사용해야 하는 aws_default_tags 데이터 소스가 있습니다.

Terraform 모듈에서 생성한 모든 리소스에 필요한 태그를 추가하는 것이 좋습니다. 다음은 연결할 수 있는 태그 목록입니다.

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

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

모듈을 단기적으로 레지스트리에 게시할 계획이 없더라도 항상 이러한 요구 사항을 따라야 합니다. 이렇게 하면 리포지토리의 구성 및 구조를 변경할 필요 없이 나중에 모듈을 레지스트리에 게시할 수 있습니다.

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

권장 모듈 소스 사용

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

반복되는 코드 요소를 고려하고 기본 Terraform 모듈 레지스트리 또는 여러 구성에서 공유하도록 의도된 모듈에 대한 VCS 공급자를 사용하는 것을 기본 목적으로 하는 밀접하게 관련된 모듈에는 로컬 경로를 사용하는 것이 좋습니다.

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

레지스트리

Terraform 레지스트리:

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

  ...

}

커밋 해시를 고정하면 공급망 공격에 취약한 퍼블릭 레지스트리의 드리프트를 방지할 수 있습니다.

HCP Terraform:

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

  ...

  enable_karpenter = true
}

Terraform Enterprise:

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 린팅, 서식 지정 및 코드 스캔을 로컬 시스템의 후크로 추가합니다. 후크는 각 Git 커밋에서 실행되며 검사가 통과되지 않으면 커밋에 실패합니다.

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