Módulos modernos de pilha Gitops

O Modern Gitops Stack é separado em vários módulos Terraform, cada um deles contendo um conjunto de recursos relacionados.

A fim de melhorar a legibilidade e manutenção do código, esta página contém algumas orientações e explicações por trás da criação e desenvolvimento dos módulos Modern Gitops Stack. Há também um modelo de repositório no GitHub que pode ser usado como ponto de partida para novos módulos e você pode consultá-lo enquanto lê esta página.

Módulos básicos

Esses tipos de módulos são normalmente aqueles que provisionam clusters e recursos relacionados. Bons exemplos disso são módulo Amazon EKS e módulo KinD.

Um módulo básico Modern Gitops Stack conterá os seguintes arquivos e pastas:

modern-gitops-stack-module-template
├── .github
│   └── workflows
│       ├── linters.yaml
│       ├── release-please.yaml
│       └── terraform-docs.yaml
├── CHANGELOG.md
├── CODEOWNERS
├── docs
│   └── ...
├── LICENSE
├── locals.tf
├── main.tf
├── outputs.tf
├── README.adoc
├── terraform.tf
├── variables.tf
└── version.txt

Visão geral rápida de cada arquivo/pasta:

  1. .github - Contém os fluxos de trabalho do GitHub Actions que são usados para limpar o código, gerar a documentação e liberar o módulo. Eles são armazenados no repositório principal e cada módulo chama os mesmos fluxos de trabalho.

  2. CHANGELOG.md - Contém o changelog do módulo. Ele é atualizado automaticamente pela ação Release Please GitHub e você não precisa criar este arquivo manualmente.

  3. CODEOWNERS - Contém a lista de usuários do GitHub que serão atribuídos automaticamente como revisores para pull requests no módulo. No nosso caso é a equipe @GersonRS/is-modern-gitops-stack.

  4. docs - Esta é uma pasta que contém uma subestrutura precisa necessária para a renderização destas páginas de documentação pelo Antora. A documentação real está contida nos arquivos README.adoc. Você encontrará essas e algumas outras explicações sobre os documentos na página Documentação.

  5. LICENSE - A licença do módulo. No nosso caso é a licença Apache 2.0.

  6. README.adoc - A documentação do módulo. Está escrito em AsciiDoc e contém o exemplo de uso junto com algumas explicações, bem como a documentação automática gerada pelo Terraform Docs.

  7. locals.tf - Contém a definição das variáveis locais utilizadas no módulo.

  8. main.tf - Contém a definição dos recursos que são criados pelo módulo. Pode ser qualquer tipo de recurso Terraform, dependendo do caso de uso.

  9. outputs.tf - Contém a definição das variáveis de saída do módulo.

  10. terraform.tf - Contém as versões dos provedores necessários.

O arquivo terraform.tf deve conter apenas a versão mínima necessária dos provedores necessários. Isso evita incompatibilidades entre módulos e é melhores práticas recomendadas pela Terraform.

  1. variables.tf - Contém a definição das variáveis de entrada do módulo.

  2. version.txt - Contém a versão do módulo. Você só deve criá-lo se estiver criando um novo módulo, após isso ele é atualizado automaticamente pelo Release Please GitHub Action.

Tome cuidado para descrever corretamente cada entrada nos arquivos variables.tf e outputs.tf. Estas descrições são levadas em consideração pelo Terraform Docs para a documentação automática do módulo.

Módulos com gráficos Helm incorporados

Estes são os módulos mais típicos do Modern Gitops Stack e são usados para implantar os componentes restantes da pilha. Bons exemplos disso são módulo Argo CD e módulo cert-manager.

O módulo Argo CD é um caso especial, pois é utilizado para implantar os demais módulos. Um CD bootstrap Argo é implantado usando recursos do tipo helm_release. Este CD Argo é então responsável por implantar os módulos restantes, que utilizam recursos do tipo argocd_project e argocd_application.

Uma estrutura típica de arquivo/pasta para um módulo com gráficos Helm incorporados é a seguinte:

modern-gitops-stack-module-template
├── .github
│   └── ...
├── CHANGELOG.md
├── charts
│   └── CHART_NAME
│       ├── Chart.lock
│       ├── charts
│       │   └── CHART_NAME.tar.gz
│       ├── Chart.yaml
│       ├── templates
│       │   └── RESOURCE.yaml
│       └── values.yaml
├── CODEOWNERS
├── docs
│   └── ...
├── LICENSE
├── locals.tf
├── main.tf
├── outputs.tf
├── README.adoc
├── terraform.tf
├── variables.tf
└── version.txt

Comparativamente a um módulo mais básico, observe as seguintes alterações (todos os outros arquivos são iguais e estão descritos acima):

  1. charts - Contém os gráficos do Helm implantados pelo módulo, se houver. O gráfico em si refere-se ao gráfico que realmente queremos implantar como uma dependência, que deve estar localizado na pasta charts/CHART_NAME/charts. O pacote de gráficos é simplesmente baixado manualmente usando uma atualização de dependência do leme e carregado no repositório junto com o restante do código.

  2. locals.tf - Contém a definição das variáveis locais utilizadas no módulo. É aqui que definimos o local helm_values que contém os valores padrão para o gráfico Helm, conforme necessário pelo módulo. Eles devem ser escritos em HCL e não em YAML.

  3. main.tf - Contém a definição dos recursos que são criados pelo módulo. É aqui que definimos os recursos argocd_project e argocd_application que implantam o gráfico Helm.

Módulos com variantes

Alguns módulos possuem múltiplas variantes. Embora o módulo principal seja o mesmo, as variantes implantam recursos diferentes ou personalizam os valores do Helm para atender a um caso de uso específico ou a uma plataforma diferente. Um bom exemplo é o módulo Thanos, que possui variantes para EKS, AKS e KinD.

Esses tipos de módulos devem ser chamados de dentro de sua variante. A variante então recursivamente chama o módulo raiz para aplicar seus recursos principais.

Uma estrutura típica de arquivo/pasta para um módulo com variantes é a seguinte:

modern-gitops-stack-module-template
├── aks
│   ├── extra-variables.tf
│   ├── extra-terraform.tf
│   ├── locals.tf
│   ├── main.tf
│   ├── outputs.tf
│   ├── README.adoc
│   ├── variables.tf -> ../variables.tf
│   └── terraform.tf -> ../terraform.tf
├── CHANGELOG.md
├── charts
│   └── ...
├── CODEOWNERS
├── docs
│   └── ...
├── eks
│   ├── extra-variables.tf
│   ├── extra-terraform.tf
│   ├── locals.tf
│   ├── main.tf
│   ├── outputs.tf
│   ├── README.adoc
│   ├── variables.tf -> ../variables.tf
│   └── terraform.tf -> ../terraform.tf
├── .github
│   └── ...
├── kind
│   ├── extra-variables.tf
│   ├── extra-terraform.tf
│   ├── locals.tf
│   ├── main.tf
│   ├── outputs.tf
│   ├── README.adoc
│   ├── variables.tf -> ../variables.tf
│   └── terraform.tf -> ../terraform.tf
├── LICENSE
├── locals.tf
├── main.tf
├── outputs.tf
├── README.adoc
├── variables.tf
├── terraform.tf
└── version.txt
Observe como os arquivos variables.tf e terraform.tf são links simbólicos para o módulo raiz. Isso evita a necessidade de manter as mesmas variáveis e provedores em vários locais. Caso existam variáveis e/ou provedores específicos que você precisa definir, você pode simplesmente criar novos arquivos como extra-variables.tf e extra-terraform.tf e adicioná-los à variante.

Comparativamente a um módulo mais básico, observe os seguintes arquivos dentro das variantes (todos os outros arquivos são iguais e estão descritos acima):

  1. extra-variables.tf - Contém a definição das variáveis de entrada extras da variante. Estas são as variáveis específicas da variante e não estão presentes no módulo raiz.

  2. extra-terraform.tf - Contém as versões dos provedores necessários da variante. Esses são os provedores específicos da variante e não estão presentes no módulo raiz.

  3. locals.tf - Contém a definição das variáveis locais utilizadas na variante. É aqui que definimos o local helm_values que contém apenas os valores específicos da variante. Eles devem ser escritos em HCL e não em YAML. Eles serão mesclados com os provenientes da variável helm_values e então passados ​​para o módulo raiz. Depois, eles serão mesclados novamente, traduzidos para YAML e então passados para o recurso argocd_application.

  4. main.tf - Normalmente, este arquivo contém apenas a chamada ao módulo raiz e repassa todas as variáveis recebidas bem como as entradas modificadas. Em casos específicos também poderá conter outros recursos específicos da variante. Dê uma olhada neste exemplo do módulo Loki:

module "loki-stack" {
  source = "../"

  cluster_name     = var.cluster_name
  base_domain      = var.base_domain
  argocd_namespace = var.argocd_namespace
  target_revision  = var.target_revision
  namespace        = var.namespace
  app_autosync     = var.app_autosync
  dependency_ids   = var.dependency_ids

  distributed_mode = var.distributed_mode
  ingress          = var.ingress
  enable_filebeat  = var.enable_filebeat

  sensitive_values = merge({}, var.sensitive_values)

  helm_values = concat(local.helm_values, var.helm_values)
}

  1. outputs.tf - Contém a definição das variáveis de saída da variante. No mínimo, deve conter as mesmas saídas presentes no módulo raiz, para propagá-las. Além disso, pode conter outras saídas específicas da variante. Veja este exemplo do módulo Loki (observe a saída id, que apenas propaga a saída id do módulo raiz):

output "id" {
  description = "..."
  value       = module.loki-stack.id
}

output "loki_credentials" {
  description = "..."
  value       = module.loki-stack.loki_credentials
  sensitive   = true
}

  1. README.adoc - Contém a documentação da variante. Mais explicações na página Documentação.

  2. variables.tf e terraform.tf - Esses arquivos são links simbólicos para o módulo raiz.

Documentação

A documentação específica para cada módulo está localizada em seu arquivo README.adoc. Se um módulo contém uma variante (por exemplo, eks ou aks), a documentação deve ser dividida em vários arquivos, um por variante. Consulte a página Documentação para obter mais informações.

Liberação

Cada módulo é lançado e versionado separadamente. Usamos Semantic Versioning para versionar os módulos. O processo de lançamento é descrito com mais detalhes na página Lançamento.