GitBook: [#1] No subject

README.md

@@ -0,0 +1,57 @@
+---
+description: >-
+  Este documento é uma tentativa de descrever sistematicamente as melhores
+  práticas usando o Terraform, e, fornecer recomendações para os problemas mais
+  frequentes de seus usuários.
+---
+
+# Seja Bem-Vindo(a)
+
+O [Terraform](https://www.terraform.io) é um projeto relativamente novo (como a maioria das ferramentas de DevOps, na verdade) que foi iniciado em 2014.
+
+O Terraform é poderoso (se não o mais poderoso que existe atualmente) e uma das ferramentas mais utilizadas que permitem o gerenciamento de infraestrutura como código (IaC). Ele permite que os desenvolvedores realizem uma grande variedade de coisas e não os restringe de fazê-las de forma com que sejam difíceis de integrar ou suportar à longo prazo.
+
+Algumas informações descritas neste livro podem não parecer as melhores práticas. Sei disso, e, para ajudar os leitores a separar as melhores práticas estabelecidas e do que apenas mais uma maneira opinativa, às vezes, dou dicas para fornecer algum contexto e ícones para especificar o nível de maturidade em cada subseção relacionada às melhores práticas.
+
+Este livro começou na ensolarada Madri em 2018 e está disponível gratuitamente aqui - [https://www.terraform-best-practices.com/](https://www.terraform-best-practices.com) .
+
+Alguns anos depois, ele foi atualizado com mais práticas atuais recomendadas disponíveis com o Terraform 1.0. Eventualmente, este livro deve conter a maioria das melhores práticas e recomendações incontestáveis para usuários do Terraform.
+
+## Traduções
+
+{% content-ref url="https://app.gitbook.com/o/-LMqIrDlzEiI-N4uHrWg/s/fTxekzr50pIuGmrPkXUD/" %}
+[Español (Spanish)](https://app.gitbook.com/o/-LMqIrDlzEiI-N4uHrWg/s/fTxekzr50pIuGmrPkXUD/)
+{% endcontent-ref %}
+
+{% content-ref url="https://app.gitbook.com/o/-LMqIrDlzEiI-N4uHrWg/s/ZLCz7lNWbSJxDGuNOI44/" %}
+[Bahasa Indonesia (Indonesian)](https://app.gitbook.com/o/-LMqIrDlzEiI-N4uHrWg/s/ZLCz7lNWbSJxDGuNOI44/)
+{% endcontent-ref %}
+
+{% content-ref url="https://app.gitbook.com/o/-LMqIrDlzEiI-N4uHrWg/s/6shyPtr2KrqW4ANbFXYg/" %}
+[Français (French)](https://app.gitbook.com/o/-LMqIrDlzEiI-N4uHrWg/s/6shyPtr2KrqW4ANbFXYg/)
+{% endcontent-ref %}
+
+Entre em contato se você quer ajudar a traduzir este livro para outros idiomas.
+
+## Contribuições
+
+Continuarei atualizando este livro conforme a comunidade amadurece e novas ideias são implementadas e verificadas. Por favor, deixe seu comentário ou crítica construtiva para que o livro esteja sempre em boa qualidade.
+
+Se você tem interesse em determinados tópicos, [abra um problema no Github](https://github.com/antonbabenko/terraform-best-practices/issues), ou curta um já aberto que você julga ser importante e deva ter prioridade.
+
+## Autores
+
+Este livro é mantido por [Anton Babenko](https://github.com/antonbabenko) com a ajuda de diversos colaboradores e tradutores.
+
+## Patrocinadores
+
+| [![](.gitbook/assets/cluster-dev-logo-site.png)](https://cluster.dev) | [Cluster.dev](http://cluster.dev) — o único gerenciador de infraestruturas nativas da núvem. |
+| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+
+## Licença
+
+Este trabalho está licenciado sob a Licença Apache 2. Veja LICENSE para maiores detalhes.
+
+Os autores e colaboradores deste conteúdo não podem garantir a validade das informações aqui encontradas. Certifique-se de que entende que as informações aqui contidas estão sendo fornecidas livremente, e que, nenhum acordo ou contrato é criado entre você e quaisquer pessoas associadas a este conteúdo ou projeto. Os autores e colaboradores não assumem e, por meio deste, se isentam de qualquer responsabilidade perante qualquer parte, por qualquer perda, dano ou interrupção causada por erros, ou omissões nas informações contidas, associadas ou vinculadas a este conteúdo, sejam tais erros ou omissões resultantes de negligência, acidente ou qualquer outra causa.
+
+Direito autoral © 2018-2022 Anton Babenko.

SUMMARY.md

@@ -0,0 +1,17 @@
+# Table of contents
+
+* [Seja Bem-Vindo(a)](README.md)
+* [Conceitos chave](key-concepts.md)
+* [Estrutura do código](code-structure.md)
+* [Exemplos de estrutura de códigos](examples/README.md)
+  * [Terragrunt](examples/terragrunt.md)
+  * [Terraform](examples/terraform/README.md)
+    * [Infraestrutura pequena com o Terraform](examples/terraform/small-size-infrastructure.md)
+    * [Infraestrutura média com o Terraform](examples/terraform/medium-size-infrastructure.md)
+    * [Infraestrutura grande com o Terraform](examples/terraform/large-size-infrastructure-with-terraform.md)
+* [Convenções de nomenclatura](naming.md)
+* [Estilo de código](code-styling.md)
+* [FAQ](faq.md)
+* [Referências](references.md)
+* [Escrevendo configurações do Terraform](writing-terraform-configurations.md)
+* [Workshop](workshop.md)

code-structure.md

@@ -0,0 +1,80 @@
+# Estrutura do código
+
+As perguntas relacionadas à estrutura de código do Terraform sào de longe as mais frequentes na comunidade. Todos pensaram na melhor estrutura de código para o projeto em algum momento também.
+
+## Como devo estruturar minhas configurações do Terraform?
+
+Esta é uma das questões em que existem muitas soluções e é muito difícil dar conselhos dinâmicos, então vamos começar entendendo com o que estamos lidando.
+
+* Qual é a complexidade do seu projeto?
+  * Número de recursos relacionados.
+  * Número de provedores Terraform (veja a nota abaixo sobre “provedores lógicos”).
+* Com que frequência sua infraestrutura muda?
+  * **A partir** de uma vez por mês/semana/dia.
+  * **Continuamente** (toda vez que houver um novo commit).
+* Iniciadores de mudança de código? _Você permite que o servidor CI atualize o repositório quando um novo artefato é criado?_
+  * Somente desenvolvedores podem realizar o push para o repositório de infraestrutura.
+  * Todos podem propor uma mudança em qualquer coisa abrindo um PR (incluindo tarefas automatizadas em execução no servidor CI).
+* Qual plataforma de implementação ou serviço de implementação você utiliza?
+  * AWS CodeDeploy, Kubernetes, ou OpenShift exigem uma abordagem um pouco diferente.
+* Como os ambientes são agrupados?
+  * Por ambiente, região, projeto...
+
+{% hint style="info" %}
+_Os provedores lógicos trabalham inteiramente dentro da lógica do Terraform e, muitas vezes, não interagem com nenhum outro serviço, entao podemos pensar em sua complexidade como_ O(1). Os provedores lógicos mais comuns incluem [random](https://registry.terraform.io/providers/hashicorp/random/latest/docs), [local](https://registry.terraform.io/providers/hashicorp/local/latest/docs), [terraform](https://www.terraform.io/docs/providers/terraform/index.html), [null](https://registry.terraform.io/providers/hashicorp/null/latest/docs), [time](https://registry.terraform.io/providers/hashicorp/time/latest).
+{% endhint %}
+
+## Introdução à estruturação de configurações do Terraform
+
+Colocar todo o código em um único `main.tf` é uma boa ideia quando você está começando ou escrevendo um código de exemplo. Em todos os outros casos, será melhor ter vários arquivos divididos logicamente assim:
+
+* `main.tf` - chame módulos, locais e fontes de dados para criar todos os recursos.
+* `variables.tf` - contém declarações de variáveis utilizadas em `main.tf.`
+* `outputs.tf` - contém saídas dos recursos criados em `main.tf.`
+* `versions.tf` - contém requisitos de versão para Terraform e provedores.
+
+`terraform.tfvars` não deve ser utilizado em nenhum lugar exceto na [composição](key-concepts.md#composicao).
+
+## Como pensar sobre a estrutura de configurações do Terraform?
+
+{% hint style="info" %}
+Por favor, certifique-se de entender os principais conceitos - [módulo de recursos](key-concepts.md#modulo-de-recursos), 
+
+[módulo de infraestrutura](key-concepts.md#modulo-de-infraestrutura) e [composição](key-concepts.md#composicao), conforme são utilizados nos exemplos a seguir.
+{% endhint %}
+
+### Recomendações comuns para estruturar código
+
+* É mais fácil e rápido trabalhar com um número menor de recursos
+  * `terraform plan` e `terraform apply` fazem chamada API na nuvem para verificar o status dos recursos.
+  * Se você tiver toda a sua infraestrutura em uma única composição, isso pode levar algum tempo.
+* O raio afetado é menor com menos recursos
+  * Isolar recursos não relacionados uns aos outros, colocando-os em composições separadas, reduz o risco se algo der errado.
+* Inicie seu projeto utilizando o estado remoto porque:
+  * Seu notebook não é lugar para sua fonte de verdade de infraestrutura.
+  * Gerenciar um arquivo `tfstate` no git é um pesadelo.
+  * Mais tarde, quando as camadas de infraestrutura começarem a crescer em várias direções (número de dependências ou recursos), será mais fácil manter as coisas sob controle.
+* Pratique uma estrutura consistente e uma convenção de [nomenclatura](naming.md#convencoes-gerais):
+  * Assim como o código procedural, o código do Terraform deve ser escrito para que as pessoas leiam primeiro, a consistência ajudará quando as mudanças ocorrerem daqui a seis meses.
+  * É possível mover recursos no arquivo de estado do Terraform, mas pode ser mais difícil de efetuar se você tiver estrutura e nomenclatura inconsistentes.
+* Mantenha os módulos de recursos o mais simples possível.
+* Não codifique valores que possam ser passados como variáveis ou descobertos usando fontes de dados.
+* Use fontes de dados e o `terraform_remote_state` especificamente como uma cola entre os módulos de infraestrutura na composição.
+
+Neste livro, os projetos de exemplo são agrupados por _complexidade_ - de infraestruturas pequenas a muito grandes. Essa separação não é rígida, portanto, verifique também outras estruturas.
+
+### Orquestração de módulos e composições de infraestrutura
+
+Ter uma infraestrutura pequena significa haver um pequeno número de dependências e poucos recursos. À medida que o projeto cresce, torna-se óbvia a necessidade de encadear a execução das configurações do Terraform, conectar diferentes módulos de infraestrutura e passar valores em uma composição.
+
+Existem pelo menos 5 grupos distintos de soluções de orquestração que os desenvolvedores usam:
+
+1. Somente o Terraform. Muito simples, os desenvolvedores precisam conhecer apenas o Terraform para realizar o trabalho.
+2. Terragrunt. Ferramenta de orquestração pura que pode ser usada para orquestrar toda a infraestrutura, bem como lidar com dependências. O Terragrunt opera com módulos e composições de infraestrutura nativamente, reduzindo assim a duplicação de código.
+3. Roteiros internos (in-house scripts). Muitas vezes isso acontece como um ponto de partida para a orquestração e antes de descobrir o Terragrunt.
+4. Ansible ou ferramenta de automação de uso geral similar. Geralmente utilizado quando o Terraform é adotado após o Ansible, ou quando a “interface” do usuário do Ansible é usada ativamente.
+5. [Crossplane](https://crossplane.io) e outras soluções inspiradas no Kubernetes. Às vezes, faz sentido utilizar o ecossistema Kubernetes e empregar um recurso de “loop” de reconciliação para atingir o estado desejado de suas configurações do Terraform. Observe o vídeo [Crossplane vs Terraform](https://www.youtube.com/watch?v=ELhVbSdcqSY) para mais informações.
+
+Com isso em mente, este livro analisa às duas primeiras dessas estruturas de projeto, apenas Terraform e Terragrunt.
+
+Veja exemplos de estruturas de código para o [Terraform](examples/#estruturas-de-codigo-do-terraform) e/ou [Terragrunt](examples/#estruturas-de-codigo-do-terragrunt) no próximo capítulo.

code-styling.md

@@ -0,0 +1,30 @@
+# Estilo de código
+
+{% hint style="info" %}
+* Os módulos de exemplos e do Terraform devem conter documentação explicando os recursos e como usá-los.
+* Todos os links nos arquivos README.md devem ser absolutos para que o site do Terraform Registry os mostre corretamente.
+* A documentação pode incluir diagramas criados com [mermaid](https://github.com/mermaid-js/mermaid) e plantas criadas com o [cloudcraft.co](https://cloudcraft.co).
+* Utilize o [Terraform pre-commit hooks](https://github.com/antonbabenko/pre-commit-terraform) para garantir que o código seja válido, formatado corretamente e documentado automaticamente antes de ser enviado para o git e revisado por humanos.
+{% endhint %}
+
+## Documentação
+
+### Documentação gerada automaticamente
+
+O [pre-commit](https://pre-commit.com) é um framework para gerenciar e manter hooks pré-commit multi-idioma. Ele é escrito em Python e é uma ferramente poderosa para fazer algo automaticamente na máquina de um desenvolvedor antes que o código seja enviado para o repositório git. Normalmente, ele é usado para executar linters e formatar código (veja [supported hooks](https://pre-commit.com/hooks.html)).
+
+Com as configurações do Terraform, o `pre-commit` pode ser usado para formatar e validar o código, bem como para atualizar a documentação.
+
+Confirma o repositório [pre-commit-terraform](https://github.com/antonbabenko/pre-commit-terraform/blob/master/README.md) para se familiarizar com ele e os repositórios existentes (por exemplo, [terraform-aws-vpc](https://github.com/terraform-aws-modules/terraform-aws-vpc)) onde ele já é utilizado.
+
+### terraform-docs
+
+O [terraform-docs](https://github.com/segmentio/terraform-docs) é uma ferramente que faz a geração de documentação a partir de módulos Terraform em vários formatos de saída (output). Você pode executá-lo manualmente (sem ganchos — pre-commit hooks — de pré-commit) ou usar o  [pre-commit-terraform hooks](https://github.com/antonbabenko/pre-commit-terraform) para atualizar a documentação automaticamente.
+
+@todo: Document module versions, release, GH actions
+
+## Recursos
+
+1. [pre-commit framework homepage](https://pre-commit.com)
+2. [Collection of git hooks for Terraform to be used with pre-commit framework](https://github.com/antonbabenko/pre-commit-terraform)
+3. Blog post by [Dean Wilson](https://github.com/deanwilson): [pre-commit hooks and terraform - a safety net for your repositories](https://www.unixdaemon.net/tools/terraform-precommit-hooks/)

examples/README.md

@@ -0,0 +1,22 @@
+# Exemplos de estrutura de códigos
+
+## Estruturas de código do Terraform
+
+{% hint style="info" %}
+Esses exemplos estão mostrando o provedor da AWS, mas a maioria dos princípios mostrados nos exemplos pode ser aplicada a outros provedores de núvem pública, bem como a outros tipos de provedores (DNS, DB, Monitoring, etc).
+{% endhint %}
+
+| Tipo                                                            | Descrição                                                                                                                                                                          | Disponibilidade       |
+| --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
+| [pequeno](terraform/small-size-infrastructure.md)               | Poucos recursos, sem dependências externas. Conta única da AWS. Região única. Ambiente único.                                                                                      | Sim                   |
+| [médio](terraform/medium-size-infrastructure.md)                | Diversas contas e ambientes na AWS, módulos de infraestrutura prontos para o uso utilizando o Terraform.                                                                           | Sim                   |
+| [grande](terraform/large-size-infrastructure-with-terraform.md) | Muitas contas na AWS, muitas regiões, necessidade urgente de reduzir copiar e colar, módulos de infraestrutura personalizados, uso intenso de composições. Utilizando o Terraform. | Trabalho em progresso |
+| muito grande (nível Enterprise)                                 | Diversos provedores (AWS, GCP, Azure). Implementações em diversas nuvens. Utilizando o Terraform.                                                                                  | Não                   |
+
+## Estruturas de código do Terragrunt
+
+| Tipo                            | Descrição                                                                                                                                                                           | Disponibilidade |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
+| médio                           | Diversas contas e ambientes na AWS, módulos de infraestrutura prontos para o uso utilizando o Terragrunt.                                                                           | Não             |
+| grande                          | Muitas contas na AWS, muitas regiões, necessidade urgente de reduzir copiar e colar, módulos de infraestrutura personalizados, uso intenso de composições. Utilizando o Terragrunt. | Não             |
+| muito grande (nível Enterprise) | Diversos provedores (AWS, GCP, Azure). Implementações em diversas nuvens. Utilizando o Terragrunt.                                                                                  | Não             |

examples/terraform/README.md

@@ -0,0 +1,2 @@
+# Terraform
+

examples/terraform/large-size-infrastructure-with-terraform.md

@@ -0,0 +1,28 @@
+# Infraestrutura grande com o Terraform
+
+Fonte: [https://github.com/antonbabenko/terraform-best-practices/tree/master/examples/large-terraform](https://github.com/antonbabenko/terraform-best-practices/tree/master/examples/large-terraform)
+
+Este exemplo contém código como um exemplo de estruturação de configurações do Terraform para uma infraestrutura de médio porte, que utiliza:
+
+* 2 contas na AWS
+* 2 regiões (`ap-southeast-2` e `us-west-1`, por exemplo)
+* 2 ambientes separados (`prod` e `stage` que não compartilham nada entre eles). Cada ambiente está em uma conta separada na AWS.
+* Cada ambiente utiliza uma versão diferente do módulo de infraestrutura pronto para uso (`alb`) originado do [Terraform Registry](https://registry.terraform.io)
+* Cada ambiente utiliza a mesma versão de `módulos/rede` de um módulo interno, pois é originado de um diretório local.
+
+{% hint style="info" %}
+Em um grande projeto como o descrito aqui, os benefócios do uso do Terragrunt se tornam muito visíveis. Veja [Estruturas de código de exemplos com o Terragrunt.](../terragrunt.md)
+{% endhint %}
+
+{% hint style="success" %}
+* Perfeito para projetos em que a infraestrutura é separada logicamente (contas AWS separadas)
+* Bom para quando não há necessidade de modificar recursos compartilhados entre contas da AWS (um ambiente = uma conta da AWS = um arquivo de estado)
+* Bom para quando não há necessidade na orquestração de mudanças entre os ambientes
+* Bom para quando os recursos de infraestrutura são diferentes por ambiente de propósito e não podem ser generalizados (por exemplo, alguns recursos estão ausentes em um ambiente ou em algumas regiões)
+{% endhint %}
+
+{% hint style="warning" %}
+À medida que o projeto cresce, será mais difícil manter esses ambientes atualizados entre sí. Considere o uso de módulos de infraestrutura (já prontos ou internos) para tarefas repetíveis.
+{% endhint %}
+
+##