Práticas recomendadas para módulos raiz

Este documento fornece diretrizes e recomendações a ter em conta quando usar módulos raiz.

As configurações de raiz ou os módulos de raiz são os diretórios de trabalho a partir dos quais executa a CLI do Terraform. Certifique-se de que as configurações de raiz cumprem as seguintes normas (e as diretrizes anteriores do Terraform, quando aplicável). As recomendações explícitas para módulos raiz substituem as diretrizes gerais.

Este guia não é uma introdução ao Terraform. Para uma introdução à utilização do Terraform com o Trusted Cloud by S3NS, consulte o artigo Comece a usar o Terraform.

Minimize o número de recursos em cada módulo raiz

É importante evitar que uma única configuração raiz cresça demasiado, com demasiados recursos armazenados no mesmo diretório e estado. Todos os recursos numa configuração raiz específica são atualizados sempre que o Terraform é executado. Isto pode causar uma execução lenta se forem incluídos demasiados recursos num único estado. Uma regra geral: não inclua mais de 100 recursos (e, idealmente, apenas algumas dezenas) num único estado.

Use diretórios separados para cada aplicação

Para gerir aplicações e projetos de forma independente, coloque os recursos de cada aplicação e projeto nos respetivos diretórios do Terraform. Um serviço pode representar uma aplicação específica ou um serviço comum, como a rede partilhada. Organize todo o código Terraform de um serviço específico num diretório (incluindo subdiretórios).

Divida as aplicações em subdiretórios específicos do ambiente

Quando implementar serviços no Trusted Cloud, divida a configuração do Terraform para o serviço em dois diretórios de nível superior: um diretório modules que contém a configuração real do serviço e um diretório environments que contém as configurações de raiz para cada ambiente.

-- 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

Use diretórios de ambiente

Para partilhar código entre ambientes, faça referência a módulos. Normalmente, este pode ser um módulo de serviço que inclui a configuração do Terraform partilhada base para o serviço. Nos módulos de serviço, codifique de forma rígida as entradas comuns e exija apenas entradas específicas do ambiente como variáveis.

Cada diretório de ambiente tem de conter os seguintes ficheiros:

  • Um ficheiro backend.tf que declara a localização do estado do backend do Terraform (normalmente, o Cloud Storage)
  • Um ficheiro main.tf que instancia o módulo de serviço

Cada diretório de ambiente (dev, qa, prod) corresponde a um espaço de trabalho do Terraform predefinido e implementa uma versão do serviço nesse ambiente. Estes espaços de trabalho isolam os recursos específicos do ambiente nos seus próprios contextos. Use apenas o espaço de trabalho predefinido.

Ter vários espaços de trabalho da CLI num ambiente não é recomendado pelos seguintes motivos:

  • Pode ser difícil inspecionar a configuração em cada espaço de trabalho.
  • Não é recomendável ter um único back-end partilhado para vários espaços de trabalho, porque o back-end partilhado torna-se um único ponto de falha se for usado para a separação de ambientes.
  • Embora a reutilização de código seja possível, o código torna-se mais difícil de ler, pois tem de mudar com base na variável do espaço de trabalho atual (por exemplo, terraform.workspace == "foo" ? this : that).

Para mais informações, consulte o seguinte:

Exponha resultados através do estado remoto

Certifique-se de que está a expor resultados úteis de instâncias de módulos a partir de um módulo raiz.

Por exemplo, o seguinte fragmento do código passa pela saída do ID do projeto da instância do módulo da fábrica de projetos como uma saída do módulo raiz.

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

Outras aplicações e ambientes do Terraform só podem referenciar resultados ao nível do módulo principal.

Ao usar o estado remoto, pode fazer referência às saídas do módulo raiz. Para permitir a utilização por outras apps dependentes para configuração, certifique-se de que está a exportar informações relacionadas com os pontos finais de um serviço para o estado remoto.

# 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"
  ...
}

Por vezes, como quando invoca um módulo de serviço partilhado a partir de diretórios de ambiente, é adequado reexportar o módulo secundário completo, da seguinte forma:

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

Afixe a versões secundárias de fornecedores

Nos módulos raiz, declare cada fornecedor e fixe-o a uma versão secundária. Isto permite a atualização automática para novos lançamentos de patches, mantendo um alvo sólido. Para manter a consistência, atribua o nome versions.tf ao ficheiro de versões.

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

Armazene variáveis num ficheiro tfvars

Para módulos raiz, forneça variáveis através de um .tfvars ficheiro de variáveis. Para manter a consistência, atribua o nome terraform.tfvars aos ficheiros de variáveis.

Não especifique variáveis através de opções alternativas de linha de comandos var-files ou var='key=val'. As opções da linha de comandos são efémeras e fáceis de esquecer. A utilização de um ficheiro de variáveis predefinido é mais previsível.

Ficheiro de check-in .terraform.lock.hcl

Para módulos raiz, o ficheiro .terraform.lock.hcl dependency lock deve ser adicionado ao controlo de origem. Isto permite o acompanhamento e a revisão das alterações nas seleções de fornecedores para uma determinada configuração.

O que se segue?