Práticas recomendadas para módulos reutilizáveis

Este documento fornece diretrizes e recomendações a ter em conta quando usar módulos do Terraform reutilizáveis.

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

Ative as APIs necessárias nos módulos

Os módulos do Terraform podem ativar todos os serviços necessários através do recurso google_project_service ou do módulo project_services. A inclusão da ativação da API facilita as demonstrações.

  • Se a ativação da API estiver incluída num módulo, tem de ser possível desativá-la através da exposição de uma variável enable_apis que tenha true como predefinição.

  • Se a ativação da API estiver incluída num módulo, a ativação da API tem de definir disable_services_on_destroy como false, porque este atributo pode causar problemas quando trabalha com várias instâncias do módulo.

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

Inclua um ficheiro de proprietários

Para todos os módulos partilhados, inclua um ficheiro OWNERS (ou CODEOWNERS no GitHub) que documente quem é responsável pelo módulo. Antes de qualquer pedido de obtenção ser unido, um proprietário deve aprová-lo.

Lance versões etiquetadas

Por vezes, os módulos requerem alterações significativas e tem de comunicar os efeitos aos utilizadores para que possam fixar as respetivas configurações a uma versão específica.

Certifique-se de que os módulos partilhados seguem a SemVer v2.0.0 quando são etiquetadas ou lançadas novas versões.

Quando fizer referência a um módulo, use uma restrição de versão para fixar a versão principal. Por exemplo:

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

Não configure fornecedores nem backends

Os módulos partilhados não podem configurar fornecedores nem back-ends. Em alternativa, configure fornecedores e backends em módulos de raiz.

Para módulos partilhados, defina as versões mínimas necessárias do fornecedor num bloco required_providers da seguinte forma:

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

Salvo prova em contrário, assuma que as novas versões do fornecedor vão funcionar.

Exponha as etiquetas como uma variável

Permitir flexibilidade na etiquetagem de recursos através da interface do módulo. Considere fornecer uma variável labels com um valor predefinido de um mapa vazio, da seguinte forma:

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

Exponha as saídas de todos os recursos

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

Para cada recurso definido num módulo partilhado, inclua, pelo menos, um resultado que faça referência ao recurso.

Use submódulos inline para lógica complexa

  • Os módulos inline permitem-lhe organizar módulos complexos do Terraform em unidades mais pequenas e remover recursos comuns duplicados.
  • Coloque módulos inline em modules/$modulename.
  • Trate os módulos inline como privados, não para serem usados por módulos externos, a menos que a documentação do módulo partilhado indique especificamente o contrário.
  • O Terraform não acompanha os recursos refatorados. Se começar com vários recursos no módulo de nível superior e, em seguida, os transferir para submódulos, o Terraform tenta recriar todos os recursos refatorados. Para mitigar este comportamento, use blocos moved quando refatorar.
  • As saídas definidas por módulos internos não são expostas automaticamente. Para partilhar resultados de módulos internos, reexporte-os.

O que se segue?