Melhores práticas para módulos reutilizáveis

Este documento fornece diretrizes e recomendações a serem consideradas ao usar módulos reutilizáveis do Terraform.

Este guia não é uma introdução ao Terraform. Para uma introdução ao uso do Terraform com o Google Cloud, consulte Primeiros passos com o Terraform.

Ativar as APIs necessárias em módulos

Os módulos do Terraform podem ativar todos os serviços necessários usando o recurso google_project_service ou o módulo project_services. A inclusão de ativação de APIs facilita as demonstrações.

  • Se a ativação da API estiver incluída em um módulo, ela precisa ser desativada ao expor uma variável enable_apis que tem true como padrão.

  • Se a ativação da API estiver incluída em um módulo, ela precisa definir disable_services_on_destroy como false, porque esse atributo pode causar problemas ao trabalhar com várias instâncias de do módulo.

    Exemplo:

    module "project-services" {
  source  = "terraform-google-modules/project-factory/google//modules/project_services"
  version = "~> 12.0"

  project_id  = var.project_id
  enable_apis = var.enable_apis

  activate_apis = [
    "compute.googleapis.com",
    "pubsub.googleapis.com",
  ]
  disable_services_on_destroy = false
}

Incluir um arquivo de proprietários

Para todos os módulos compartilhados, inclua um arquivo OWNERS (ou CODEOWNERS no GitHub), que documenta quem é responsável pelo módulo. Antes que qualquer solicitação de envio seja mesclada, um proprietário deve aprová-la.

Lançar versões marcadas

Às vezes, os módulos exigem alterações interruptivas e você precisa comunicar os efeitos aos usuários para que eles possam fixar as configurações em uma versão específica.

Confira se os módulos compartilhados seguem o SemVer v2.0.0 quando novas versões são marcadas ou lançadas.

Ao referenciar um módulo, use uma restrição de versão para fixar na versão principal. Exemplo:

module "gke" {
  source  = "terraform-google-modules/kubernetes-engine/google"
  version = "~> 20.0"
}

Não configurar provedores ou back-ends

Os módulos compartilhados não podem configurar provedores ou back-ends. Em vez disso, configure provedores e back-ends em módulos raiz.

Para módulos compartilhados, defina as versões mínimas de provedor necessárias em um bloco required_providers, da seguinte maneira:

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

A menos que seja comprovado de outra forma, suponha que as novas versões do provedor funcionarão.

Expor rótulos como uma variável

Permitir flexibilidade na rotulagem de recursos por meio da interface do módulo. Forneça uma variável labels com um valor padrão de um mapa vazio, da seguinte maneira:

variable "labels" {
  description = "A map of labels to apply to contained resources."
  default     = {}
  type        = "map"
}

Expor saídas para todos os recursos

As variáveis e saídas permitem inferir dependências entre módulos e recursos. Sem nenhuma saída, os usuários não podem ordenar corretamente seu módulo em relação às configurações do Terraform.

Para cada recurso definido em um módulo compartilhado, inclua pelo menos uma saída que faça referência ao recurso.

Usar submódulos in-line para lógica complexa

  • Os módulos in-line permitem organizar módulos complexos do Terraform em unidades menores e eliminar a duplicação de recursos comuns.
  • Coloque módulos in-line em modules/$modulename.
  • Tratar módulos in-line como particulares, não a serem usados por módulos externos, a menos que a documentação do módulo compartilhado declare especificamente o contrário.
  • O Terraform não rastreia recursos refatorados. Se você começar com vários recursos no módulo de nível superior e depois enviá-los a submódulos, o Terraform tentará recriar todos os recursos refatorados. Para atenuar esse comportamento, use blocos moved (link em inglês) ao refatorar.
  • As saídas definidas por módulos internos não são expostas automaticamente. Para compartilhar as saídas de módulos internos, exporte-as novamente.

A seguir