As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Melhores práticas para organização e estrutura de base de código

A estrutura e a organização adequadas da base de código são essenciais à medida que o uso do Terraform cresce em grandes equipes e empresas. Uma base de código bem arquitetada permite a colaboração em grande escala e, ao mesmo tempo, aprimora a capacidade de manutenção.

Esta seção fornece recomendações sobre modularidade, convenções de nomenclatura, documentação e padrões de codificação do Terraform que oferecem suporte à qualidade e consistência.

A orientação inclui dividir a configuração em módulos reutilizáveis por ambiente e componentes, estabelecer convenções de nomenclatura usando prefixos e sufixos, documentar módulos e explicar claramente as entradas e saídas e aplicar regras de formatação consistentes usando verificações de estilo automatizadas.

As melhores práticas adicionais abrangem a organização lógica de módulos e recursos em uma hierarquia estruturada, a catalogação de módulos públicos e privados na documentação e a abstração de detalhes de implementação desnecessários em módulos para simplificar o uso.

Ao implementar diretrizes de estrutura de base de código sobre modularidade, documentação, padrões e organização lógica, você pode oferecer suporte à ampla colaboração entre equipes e, ao mesmo tempo, manter o Terraform sustentável à medida que o uso se espalha pela organização. Ao aplicar convenções e padrões, você pode evitar a complexidade de uma base de código fragmentada.

Implemente uma estrutura de repositório padrão

Recomendamos que você implemente o seguinte layout de repositório. A padronização dessas práticas de consistência em todos os módulos melhora a capacidade de descoberta, a transparência, a organização e a confiabilidade, ao mesmo tempo que permite a reutilização em muitas configurações do Terraform.

Estrutura do módulo raiz

O Terraform sempre é executado no contexto de um único módulo raiz. Uma configuração completa do Terraform consiste em um módulo raiz e na árvore de módulos secundários (que inclui os módulos que são chamados pelo módulo raiz, quaisquer módulos chamados por esses módulos e assim por diante).

Exemplo básico do layout do módulo raiz do 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

Estrutura de módulo reutilizável

Os módulos reutilizáveis seguem os mesmos conceitos dos módulos raiz. Para definir um módulo, crie um novo diretório para ele e coloque os .tf arquivos nele, assim como você definiria um módulo raiz. O Terraform pode carregar módulos a partir de caminhos relativos locais ou de repositórios remotos. Se você espera que um módulo seja reutilizado por várias configurações, coloque-o em seu próprio repositório de controle de versão. É importante manter a árvore de módulos relativamente plana para facilitar a reutilização dos módulos em diferentes combinações.

Exemplo básico de layout de módulo reutilizável do 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

Estrutura para modularidade

Em princípio, você pode combinar quaisquer recursos e outras construções em um módulo, mas o uso excessivo de módulos aninhados e reutilizáveis pode tornar sua configuração geral do Terraform mais difícil de entender e manter, portanto, use esses módulos com moderação.

Quando fizer sentido, divida sua configuração em módulos reutilizáveis que elevam o nível de abstração descrevendo um novo conceito em sua arquitetura que é construído a partir de tipos de recursos.

Ao modularizar sua infraestrutura em definições reutilizáveis, busque conjuntos lógicos de recursos em vez de componentes individuais ou coleções excessivamente complexas.

Não envolva recursos únicos

Você não deve criar módulos que envolvam outros tipos de recursos únicos. Se você tiver problemas para encontrar um nome para seu módulo que seja diferente do nome do tipo de recurso principal dentro dele, seu módulo provavelmente não está criando uma nova abstração ― está adicionando complexidade desnecessária. Em vez disso, use o tipo de recurso diretamente no módulo de chamada.

Encapsular relacionamentos lógicos

Agrupe conjuntos de recursos relacionados, como bases de rede, camadas de dados, controles de segurança e aplicativos. Um módulo reutilizável deve encapsular partes da infraestrutura que funcionem juntas para habilitar um recurso.

Mantenha a herança estável

Ao agrupar módulos em subdiretórios, evite aprofundar mais de um ou dois níveis. Estruturas de herança profundamente aninhadas complicam as configurações e a solução de problemas. Os módulos devem se basear em outros módulos, não construir túneis por meio deles.

Ao focar os módulos em agrupamentos lógicos de recursos que representam padrões de arquitetura, as equipes podem configurar rapidamente bases de infraestrutura confiáveis. Equilibre a abstração sem excesso de engenharia ou simplificação.

Recursos de referência em resultados

Para cada recurso definido em um módulo reutilizável, inclua pelo menos uma saída que faça referência ao recurso. Variáveis e saídas permitem inferir dependências entre módulos e recursos. Sem nenhuma saída, os usuários não podem solicitar adequadamente seu módulo em relação às configurações do Terraform.

Módulos bem estruturados que fornecem consistência de ambiente, agrupamentos orientados por propósitos e referências de recursos exportados permitem a colaboração em grande escala com o Terraform em toda a organização. As equipes podem montar a infraestrutura a partir de blocos de construção reutilizáveis.

Não configure provedores

Embora os módulos compartilhados herdem os provedores dos módulos de chamada, os módulos não devem definir as configurações do provedor sozinhos. Evite especificar blocos de configuração do provedor nos módulos. Essa configuração só deve ser declarada uma vez globalmente.

Declare os fornecedores necessários

Embora as configurações do provedor sejam compartilhadas entre os módulos, os módulos compartilhados também devem declarar seus próprios requisitos de provedor. Essa prática permite que o Terraform garanta que haja uma única versão do provedor compatível com todos os módulos na configuração e especifique o endereço de origem que serve como identificador global (independente do módulo) para o provedor. No entanto, os requisitos específicos do provedor do módulo não especificam nenhuma das configurações que determinam quais endpoints remotos o provedor acessará, como um. Região da AWS

Ao declarar os requisitos de versão e evitar a configuração codificada do provedor, os módulos oferecem portabilidade e reutilização em todas as configurações do Terraform usando provedores compartilhados.

Para módulos compartilhados, defina as versões mínimas necessárias do provedor em um bloco required_providers. versions.tf

Para declarar que um módulo requer uma versão específica do AWS provedor, use um required_providers bloco dentro de um terraform bloco:

terraform {
  required_version = ">= 1.0.0"

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

Se um módulo compartilhado suportar somente uma versão específica do AWS provedor, use o operador de restrição pessimista (~>), que permite que somente o componente da versão mais à direita seja incrementado:

terraform {
  required_version = ">= 1.0.0"

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

Neste exemplo, ~> 4.0 permite a instalação de 4.57.1 e4.67.0, mas não5.0.0. Para obter mais informações, consulte Sintaxe de restrição de versão na HashiCorp documentação.

Siga as convenções de nomenclatura

Nomes claros e descritivos simplificam sua compreensão das relações entre os recursos no módulo e a finalidade dos valores de configuração. A consistência com as diretrizes de estilo melhora a legibilidade tanto para os usuários quanto para os mantenedores do módulo.

Siga as diretrizes para nomeação de recursos

Siga as diretrizes para nomenclatura de variáveis

Use recursos de anexo

Alguns recursos têm pseudo-recursos incorporados como atributos. Sempre que possível, você deve evitar usar esses atributos de recursos incorporados e, em vez disso, usar o recurso exclusivo para anexar esse pseudo-recurso. Esses relacionamentos de recursos podem causar cause-and-effect problemas exclusivos para cada recurso.

Usando um atributo incorporado (evite esse padrão):

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"]
  }
}

Usando recursos de anexo (preferencial):

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
}

Use tags padrão

Atribua tags a todos os recursos que podem aceitar tags. O Terraform AWS Provider tem uma fonte de dados aws_default_tags que você deve usar dentro do módulo raiz.

Considere adicionar as tags necessárias a todos os recursos criados por um módulo do Terraform. Aqui está uma lista de possíveis tags para anexar:

Atenda aos requisitos de registro do Terraform

Um repositório de módulos deve atender a todos os requisitos a seguir para que possa ser publicado em um registro do Terraform.

Você deve sempre seguir esses requisitos, mesmo que não esteja planejando publicar o módulo em um registro a curto prazo. Ao fazer isso, você pode publicar o módulo em um registro posteriormente sem precisar alterar a configuração e a estrutura do repositório.

Para obter mais informações, consulte Preparando um repositório de módulos na documentação do Terraform.

Use fontes de módulos recomendadas

O Terraform usa o source argumento em um bloco de módulo para encontrar e baixar o código-fonte de um módulo filho.

Recomendamos que você use caminhos locais para módulos estreitamente relacionados que tenham o objetivo principal de eliminar elementos de código repetidos e usar um registro de módulo nativo do Terraform ou um provedor de VCS para módulos que devem ser compartilhados por várias configurações.

Os exemplos a seguir ilustram os tipos de fonte mais comuns e recomendados para compartilhar módulos. Os módulos de registro oferecem suporte ao controle de versão. Você deve sempre fornecer uma versão específica, conforme mostrado nos exemplos a seguir.

Registro

Registro do Terraform:

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

  ...

}

Ao fixar hashes de confirmação, você pode evitar o desvio de registros públicos que são vulneráveis a ataques na cadeia de suprimentos.

Terraform do HCP:

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
}

Provedores de VCS

Os provedores de VCS apoiam o ref argumento de selecionar uma revisão específica, conforme mostrado nos exemplos a seguir.

GitHub (HTTPS):

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

  ...

  enable_karpenter = true
}

Repositório Git genérico (HTTPS):

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

  ...

  enable_karpenter = true
}

Repositório Git genérico (SSH):

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

  ...

  enable_karpenter = true
}

Siga os padrões de codificação

Aplique regras e estilos consistentes de formatação do Terraform em todos os arquivos de configuração. Aplique padrões usando verificações de estilo automatizadas em pipelines de CI/CD. Quando você incorpora as melhores práticas de codificação nos fluxos de trabalho da equipe, as configurações permanecem legíveis, sustentáveis e colaborativas à medida que o uso se espalha amplamente pela organização.

Siga as diretrizes de estilo

Configurar ganchos de pré-confirmação

Configure ganchos de pré-confirmação do lado do cliente que executamterraform fmt, tflintcheckov, e outras digitalizações de código e verificações de estilo antes de permitir confirmações. Essa prática ajuda você a validar a conformidade com os padrões mais cedo nos fluxos de trabalho do desenvolvedor.

Use estruturas de pré-confirmação, como pré-confirmação, para adicionar linting, formatação e digitalização de código do Terraform como ganchos em sua máquina local. Os ganchos são executados em cada confirmação do Git e falham na confirmação se as verificações não forem aprovadas.

Mover as verificações de estilo e qualidade para ganchos locais de pré-confirmação fornece feedback rápido aos desenvolvedores antes que as mudanças sejam introduzidas. Os padrões se tornam parte do fluxo de trabalho de codificação.