Este laboratório foi desenvolvido com nossa parceira, a Hashicorp (link em inglês). Suas informações pessoais podem ser compartilhadas com a Hashicorp, patrocinadora do laboratório, caso você tenha optado por receber atualizações de produtos, anúncios e ofertas em seu perfil de conta.

GSP752

Informações gerais

O Terraform precisa armazenar o estado de sua infraestrutura e configuração gerenciadas. Esse estado é usado pelo Terraform para mapear recursos práticos de sua configuração, acompanhar metadados e melhorar o desempenho de grandes infraestruturas.

Esse estado é armazenado por padrão em um arquivo local chamado terraform.tfstate, mas também pode ser armazenado remotamente, o que funciona melhor em um ambiente de equipe.

O Terraform usa esse estado local para criar planos e fazer alterações em sua infraestrutura. Antes de qualquer operação, o Terraform faz uma atualização do estado com a infraestrutura real (todos os links do Terraform neste laboratório estão em inglês).

O objetivo principal do estado do Terraform é armazenar vinculações entre objetos em um sistema remoto e instâncias de recursos declaradas em sua configuração. Quando o Terraform cria um objeto remoto em resposta a uma alteração de configuração, ele registra a identidade desse objeto remoto em relação a uma instância de recurso específica e, em seguida, atualiza ou exclui esse objeto em resposta a futuras alterações de configuração.

Objetivos

Neste laboratório, você aprenderá a realizar as tarefas abaixo:

• Criar um back-end local.
• Criar um back-end do Cloud Storage.
• Atualizar seu estado do Terraform.
• Importar uma configuração do Terraform.
• Gerenciar a configuração importada com o Terraform.

Configuração e requisitos

Antes de clicar no botão Start Lab

Leia estas instruções. Os laboratórios são cronometrados e não podem ser pausados. O timer é iniciado quando você clica em Começar o laboratório e mostra por quanto tempo os recursos do Google Cloud vão ficar disponíveis.

Este laboratório prático permite que você realize as atividades em um ambiente real de nuvem, não em uma simulação ou demonstração. Você vai receber novas credenciais temporárias para fazer login e acessar o Google Cloud durante o laboratório.

Confira os requisitos para concluir o laboratório:

• Acesso a um navegador de Internet padrão (recomendamos o Chrome).

Observação: para executar este laboratório, use o modo de navegação anônima ou uma janela anônima do navegador. Isso evita conflitos entre sua conta pessoal e a conta de estudante, o que poderia causar cobranças extras na sua conta pessoal.

• Tempo para concluir o laboratório---não se esqueça: depois de começar, não será possível pausar o laboratório.

Observação: não use seu projeto ou conta do Google Cloud neste laboratório para evitar cobranças extras na sua conta.

Como iniciar seu laboratório e fazer login no console do Google Cloud

1. Clique no botão Começar o laboratório. Se for preciso pagar, você verá um pop-up para selecionar a forma de pagamento. No painel Detalhes do laboratório à esquerda, você verá o seguinte:

   • O botão Abrir Console do Cloud
   • Tempo restante
   • As credenciais temporárias que você vai usar neste laboratório
   • Outras informações se forem necessárias

2. Clique em Abrir Console do Google. O laboratório ativa recursos e depois abre outra guia com a página Fazer login.

   Dica: coloque as guias em janelas separadas lado a lado.

   Observação: se aparecer a caixa de diálogo Escolher uma conta, clique em Usar outra conta.

3. Caso seja preciso, copie o Nome de usuário no painel Detalhes do laboratório e cole esse nome na caixa de diálogo Fazer login. Clique em Avançar.

4. Copie a Senha no painel Detalhes do laboratório e a cole na caixa de diálogo Olá. Clique em Avançar.

   Importante: você precisa usar as credenciais do painel à esquerda. Não use suas credenciais do Google Cloud Ensina. Observação: se você usar sua própria conta do Google Cloud neste laboratório, é possível que receba cobranças adicionais.

5. Acesse as próximas páginas:

   • Aceite os Termos e Condições.
   • Não adicione opções de recuperação nem autenticação de dois fatores (porque essa é uma conta temporária).
   • Não se inscreva em testes gratuitos.

Depois de alguns instantes, o console do GCP vai ser aberto nesta guia.

Observação: para ver uma lista dos produtos e serviços do Google Cloud, clique no Menu de navegação no canto superior esquerdo.

Ativar o Cloud Shell

O Cloud Shell é uma máquina virtual com várias ferramentas de desenvolvimento. Ele tem um diretório principal permanente de 5 GB e é executado no Google Cloud. O Cloud Shell oferece acesso de linha de comando aos recursos do Google Cloud.

1. Clique em Ativar o Cloud Shell na parte de cima do console do Google Cloud.

Depois de se conectar, vai notar que sua conta já está autenticada, e que o projeto está configurado com seu PROJECT_ID. A saída contém uma linha que declara o projeto PROJECT_ID para esta sessão:

Your Cloud Platform project in this session is set to YOUR_PROJECT_ID

gcloud é a ferramenta de linha de comando do Google Cloud. Ela vem pré-instalada no Cloud Shell e aceita preenchimento com tabulação.

2. (Opcional) É possível listar o nome da conta ativa usando este comando:

gcloud auth list

3. Clique em Autorizar.

4. A saída será parecida com esta:

Saída:

ACTIVE: * ACCOUNT: student-01-xxxxxxxxxxxx@qwiklabs.net To set the active account, run: $ gcloud config set account `ACCOUNT`

5. (Opcional) É possível listar o ID do projeto usando este comando:

gcloud config list project

Saída:

[core] project = <project_ID>

Exemplo de saída:

[core] project = qwiklabs-gcp-44776a13dea667a6 Observação: para conferir a documentação completa da gcloud, acesse o guia com informações gerais sobre a gcloud CLI no Google Cloud.

Objetivo do estado do Terraform

O estado é um requisito necessário para o funcionamento do Terraform. As pessoas às vezes perguntam se o Terraform pode funcionar sem estado ou não usar estado e apenas inspecionar os recursos da nuvem em cada execução. Nos cenários em que o Terraform pode ficar sem estado, a complexidade muda muito de um lugar (estado) para outro (o conceito da substituição). Nesta seção, vamos ajudar a explicar por que o estado do Terraform é necessário.

Como mapear em cenários práticos

O Terraform exige algum tipo de banco de dados para mapear a configuração em um cenário prático. Quando sua configuração contém um resource "google_compute_instance" "foo", o Terraform usa esse mapa para saber que a instância i-abcd1234 é representada por esse recurso.

O Terraform espera que cada objeto remoto esteja vinculado a apenas uma instância de recurso, o que normalmente é garantido porque o Terraform é responsável por criar os objetos e registrar as identidades deles no estado. Se você importar objetos que foram criados fora do Terraform, será necessário verificar se cada objeto distinto é importado para apenas uma instância de recurso.

Se um objeto remoto estiver vinculado a duas ou mais instâncias de recursos, o Terraform poderá executar ações inesperadas nele porque o mapeamento da configuração para o estado do objeto remoto se tornou ambíguo.

Metadados

Além de rastrear os mapeamentos entre recursos e objetos remotos, o Terraform também precisa rastrear metadados, como dependências de recursos.

O Terraform normalmente usa a configuração para determinar a ordem de dependência. No entanto, quando você remove um recurso de uma configuração do Terraform, o Terraform precisa saber como excluí-lo. O Terraform pode ver que há um mapeamento para um recurso que não está em seu arquivo de configuração e planejar destruí-lo. No entanto, como o recurso não existe mais, a ordem não pode ser determinada apenas pela configuração.

Para garantir a operação correta, o Terraform retém uma cópia do conjunto de dependências mais recente no estado. Agora o Terraform ainda pode determinar a ordem correta de destruição do estado quando você exclui um ou mais itens da configuração.

Isso poderia ser evitado se o Terraform soubesse uma ordem obrigatória entre os tipos de recursos. Por exemplo, o Terraform poderia saber que os servidores precisam ser excluídos antes das sub-redes de que fazem parte. No entanto, a complexidade dessa abordagem rapidamente se torna incontrolável: além de interpretar a semântica de ordenação de cada recurso para cada nuvem, o Terraform também precisa entender a ordem entre os provedores.

O Terraform também armazena outros metadados por motivos semelhantes, como um ponteiro para a configuração do provedor que foi usada mais recentemente com o recurso em situações em que vários provedores com alias estão presentes.

Desempenho

Além do mapeamento básico, o Terraform armazena um cache dos valores dos atributos de todos os recursos do estado. Esse é um recurso opcional do estado do Terraform e é usado apenas como melhoria de desempenho.

Ao executar um terraform plan, o Terraform precisa saber o estado atual dos recursos para determinar efetivamente as alterações necessárias para alcançar a configuração pretendida.

Em pequenas infraestruturas, o Terraform pode consultar seus provedores e sincronizar os atributos mais recentes de todos os seus recursos. Este é o comportamento padrão do Terraform: para cada plan e apply, ele sincronizará todos os recursos em seu estado.

Em infraestruturas maiores, consultar todos os recursos é uma tarefa muito lenta. Muitos provedores de nuvem não fornecem APIs para consultar vários recursos ao mesmo tempo, e o tempo de retorno de cada recurso é de centenas de milissegundos. Além disso, os provedores de nuvem quase sempre têm limitação de taxa de API. Por isso, o Terraform pode solicitar apenas um número limitado de recursos em um período. Grandes usuários do Terraform usam com frequência as sinalizações -refresh=false e -target para contornar isso. Nesses cenários, o estado em cache é tratado como o registro da verdade.

Sincronização

Na configuração padrão, o Terraform armazena o estado em um arquivo no diretório de trabalho atual em que foi executado. Isso funciona quando você está começando, mas quando o Terraform é usado em uma equipe, é importante que todos trabalhem com o mesmo estado para que as operações sejam aplicadas aos mesmos objetos remotos.

O estado remoto é a solução recomendada para esse problema. Com um back-end de estado completo, o Terraform pode usar o bloqueio remoto como uma medida para evitar que vários usuários diferentes executem acidentalmente o Terraform ao mesmo tempo, o que garante que cada execução comece com o estado atualizado mais recente.

Bloqueio de estado

Se for compatível com seu back-end, o Terraform bloqueará seu estado para todas as operações que possam gravar o estado. Isso impede que outras pessoas consigam o bloqueio e possam corromper seu estado.

O bloqueio acontece automaticamente em todas as operações que podem gravar o estado. Você não verá nenhuma mensagem quando isso acontecer. Se o bloqueio de estado falhar, o Terraform não continuará. É possível desativar o bloqueio de estado na maioria dos comandos com a flag -lock, mas isso não é recomendado.

Se o recebimento do bloqueio estiver demorando mais do que o esperado, o Terraform emitirá uma mensagem de status. Se o Terraform não enviar uma mensagem, o bloqueio de estado vai continuar.

Nem todos os back-ends são compatíveis com o bloqueio. Veja a lista de tipos de back-end para saber detalhes sobre a compatibilidade de um back-end com o bloqueio.

Espaços de trabalho

Cada configuração do Terraform tem um back-end associado que define como as operações são executadas e onde os dados persistentes, como o estado do Terraform, são armazenados.

Os dados persistentes armazenados no back-end pertencem a um espaço de trabalho. Inicialmente, o back-end tem apenas um espaço de trabalho, chamado padrão. Portanto, apenas um estado do Terraform está associado a essa configuração.

Certos back-ends oferecem suporte a vários espaços de trabalho nomeados, o que permite que vários estados sejam associados a uma única configuração. A configuração ainda tem apenas um back-end, mas várias instâncias distintas dessa configuração podem ser implantadas sem configurar um novo back-end ou alterar as credenciais de autenticação.

Tarefa 1: trabalhar com back-ends

Um back-end no Terraform determina como o estado é carregado e como uma operação como apply é executada. Essa abstração permite armazenamento de estado de arquivo não local, execução remota etc.

Por padrão, o Terraform usa o back-end "local", ou seja, o comportamento normal do Terraform que você já conhece. Esse é o back-end que estava sendo invocado nos laboratórios anteriores.

Aqui estão alguns dos benefícios dos back-ends:

• Trabalho em equipe: os back-ends podem armazenar o estado remotamente e protegê-lo com bloqueios para evitar corrupção. Alguns back-ends, como o Terraform Cloud, até armazenam automaticamente um histórico de todas as revisões de estado.
• Manutenção das informações sensíveis fora do disco: o estado é recuperado de back-ends sob demanda e armazenado apenas na memória.
• Operações remotas: para infraestruturas maiores ou certas mudanças, o terraform apply pode levar muito tempo. Alguns back-ends são compatíveis com operações remotas, que permitem a execução remota da operação. Nesse caso é possível desligar o computador, e sua operação ainda será concluída. Combinado com armazenamento e bloqueio de estado remoto (descritos acima), isso também ajuda em ambientes de equipe.

Os back-ends são opcionais: é possível usar o Terraform sem precisar usar back-ends ou aprender sobre eles. No entanto, eles resolvem os pontos problemáticos que afligem as equipes em uma determinada escala. Se você estiver trabalhando por conta própria, provavelmente poderá ir bem sem nunca usar back-ends.

Mesmo que você pretenda usar apenas o back-end "local", pode ser útil aprender sobre o assunto, já que também é possível alterar o comportamento desse back-end.

Adicionar um back-end local

Nesta seção, você vai configurar um back-end local.

Ao configurar um back-end pela primeira vez (passando de nenhum back-end definido para uma configuração explícita), o Terraform oferecerá a opção de migrar seu estado para o back-end novo. Isso permite que você adote back-ends sem perder nenhum estado atual.

Para ter mais cuidado ainda, sempre recomendamos que você também faça backup manual do seu estado. É possível fazer isso simplesmente copiando seu arquivo terraform.tfstate para outro local. O processo de inicialização também criará um backup, mas segurança nunca é demais.

Configurar um back-end pela primeira vez não é diferente de alterar uma configuração no futuro: crie a configuração nova e execute terraform init. O Terraform vai guiar você pelo restante do caminho.

1. Em uma nova janela do Cloud Shell, crie seu arquivo de configuração main.tf:

touch main.tf

2. Para recuperar o ID do projeto, execute o comando a seguir:

gcloud config list --format 'value(core.project)'

3. Na barra de ferramentas do Cloud Shell, clique em Abrir editor. Para alternar entre o Cloud Shell e o editor de código, clique em Abrir editor ou Abrir terminal, conforme necessário, ou clique em Abrir em uma nova janela para deixar o editor aberto em uma guia separada.

4. Copie o código do recurso do bucket do Cloud Storage no arquivo de configuração main.tf, substituindo as definições de variável name e project pelo ID do projeto:

provider "google" { project = "# SUBSTITUA PELO ID DO SEU PROJETO" region = "{{{project_0.default_region | REGION}}}" } resource "google_storage_bucket" "test-bucket-for-state" { name = "# SUBSTITUA PELO ID DO SEU PROJETO" location = "US" uniform_bucket_level_access = true }

Saiba mais sobre os recursos do Cloud Storage na Documentação do Terraform (em inglês).

5. Adicione um back-end local ao arquivo main.tf:

terraform { backend "local" { path = "terraform/state/terraform.tfstate" } }

Isso fará referência a um arquivo terraform.tfstate no diretório terraform/state. Para especificar um caminho de arquivo diferente, altere a variável path.

O back-end local armazena o estado no sistema de arquivos local, bloqueia esse estado usando APIs do sistema e executa operações de modo local.

O Terraform precisa inicializar qualquer back-end configurado antes do uso. Para fazer isso, você executará o terraform init. O comando terraform init precisa ser executado por um membro de sua equipe em qualquer configuração do Terraform como uma primeira etapa. É seguro executar várias vezes e realizar todas as ações de configuração necessárias para um ambiente do Terraform, incluindo a inicialização do back-end.

O comando init precisa ser chamado:

• em qualquer novo ambiente que configure um back-end;
• em qualquer alteração da configuração de back-end (incluindo o tipo de back-end);
• ao remover completamente a configuração de back-end.

Você não precisa se lembrar desses casos exatos. O Terraform vai detectar quando a inicialização for necessária e vai apresentar uma mensagem de erro nessa situação. O Terraform não inicializa automaticamente porque pode exigir informações adicionais do usuário ou realizar migrações de estado etc.

6. Na barra de ferramentas do Cloud Shell, clique em Abrir terminal e inicialize o Terraform:

terraform init

7. Aplique as alterações. Digite yes no prompt para confirmar:

terraform apply

O editor do Cloud Shell agora exibirá o arquivo de estado chamado terraform.tfstate no diretório terraform/state.

8. Examine seu arquivo de estado:

terraform show

Seu recurso google_storage_bucket.test-bucket-for-state será mostrado.

Adicionar um back-end do Cloud Storage

Um back-end do Cloud Storage armazena o estado como um objeto em um prefixo configurável em um determinado bucket no Cloud Storage. Esse back-end também é compatível com bloqueio de estado. Isso bloqueará seu estado para todas as operações que podem gravar estado. Isso impede que outras pessoas consigam o bloqueio e possam corromper seu estado.

O bloqueio acontece automaticamente em todas as operações que podem gravar o estado. Você não verá nenhuma mensagem quando isso acontecer. Se o bloqueio de estado falhar, o Terraform não continuará. É possível desativar o bloqueio de estado na maioria dos comandos com a sinalização -lock, mas não é recomendado.

1. Navegue de volta ao seu arquivo main.tf no editor. Agora você substituirá o back-end local por um back-end gcs.

2. Para alterar a configuração de back-end local, copie a seguinte configuração em seu arquivo, substituindo o back-end local:

terraform { backend "gcs" { bucket = "# SUBSTITUA PELO NOME DO BUCKET" prefix = "terraform/state" } } Observação: atualize a definição de variável do bucket. Se você não alterou a configuração, será o name do recurso google_storage_bucket. Esse bucket será usado para hospedar o arquivo de estado.

3. Inicialize seu back-end novamente, desta vez para migrar o estado de forma automática:

terraform init -migrate-state

Digite yes no prompt para confirmar.

4. No console do Cloud, acesse o Menu de navegação e clique em Cloud Storage > Buckets.

5. Clique no seu bucket e navegue até o arquivo terraform/state/default.tfstate. Seu arquivo de estado agora existe em um bucket do Cloud Storage.

Observação: se você não quiser mais usar nenhum back-end, basta remover a configuração do arquivo. O Terraform vai detectar isso como qualquer outra alteração e solicitará a reinicialização.

Como parte da reinicialização, o Terraform perguntará se você quer migrar seu estado de volta para o estado local normal. Quando essa ação for concluída, o Terraform voltará ao comportamento padrão.

Atualizar o estado

O comando terraform refresh é usado para reconciliar o estado que o Terraform conhece (usando o arquivo de estado) com a infraestrutura do cenário prático. Isso pode ser usado para detectar qualquer desvio do último estado conhecido e atualizar o arquivo de estado.

Isso não modifica a infraestrutura, mas o arquivo de estado. Se o estado for alterado, isso pode causar mudanças durante o próximo plano ou aplicação.

1. Retorne ao seu bucket de armazenamento no console do Cloud. Selecione a caixa de seleção ao lado do nome.

2. Clique na guia Rótulos.

3. Clique em Adicionar rótulo. Defina Key 1 = key e Value 1 = value.

4. Clique em Save.

5. Retorne ao Cloud Shell e use o comando a seguir para atualizar o arquivo de estado:

terraform refresh

6. Examine as atualizações:

terraform show

O par de chave-valor "key" = "value" será exibido no atributo "rótulos" da configuração.

Clique em Verificar meu progresso para conferir o objetivo. Trabalhar com back-ends

Limpar seu espaço de trabalho

Antes de continuar para a próxima tarefa, destrua sua infraestrutura provisionada.

1. Primeiro, reverta seu back-end para local para poder excluir o bucket de armazenamento. Copie e substitua a configuração do gcs pelo seguinte código:

terraform { backend "local" { path = "terraform/state/terraform.tfstate" } }

2. Inicialize o back-end local novamente:

terraform init -migrate-state

Digite yes no prompt para confirmar.

3. No arquivo main.tf, adicione o argumento force_destroy = true ao seu recurso google_storage_bucket. Ao excluir um bucket, essa opção booleana excluirá todos os objetos contidos. Se você tentar excluir um bucket que contém objetos, o Terraform falhará nessa execução. Sua configuração de recurso vai ser semelhante à seguinte:

resource "google_storage_bucket" "test-bucket-for-state" { name = "qwiklabs-gcp-03-c26136e27648" location = "US" uniform_bucket_level_access = true force_destroy = true }

4. Aplique as alterações:

terraform apply

Digite yes no prompt para confirmar.

5. Agora é possível destruir a infraestrutura:

terraform destroy

Digite yes no prompt para confirmar.

Tarefa 2: importar a configuração do Terraform

Nesta seção, você importará um contêiner e uma imagem do Docker para um espaço de trabalho vazio do Terraform. Ao fazer isso, você aprenderá estratégias e considerações para importar infraestruturas de cenários práticos para o Terraform.

O fluxo de trabalho padrão do Terraform envolve a criação e o gerenciamento de infraestrutura inteiramente com o Terraform.

• Grave uma configuração do Terraform que defina a infraestrutura que você pretende criar.

• Analise o plano do Terraform para que a configuração gere o estado e a infraestrutura esperados.

• Aplique a configuração para criar o estado e a infraestrutura do Terraform.

Depois de criar a infraestrutura com o Terraform, é possível atualizar a configuração e planejar e aplicar essas alterações. Em algum momento, você usará o Terraform para destruir a infraestrutura quando ela não for mais necessária. Esse fluxo de trabalho pressupõe que o Terraform criará uma infraestrutura totalmente nova.

No entanto, pode ser necessário gerenciar uma infraestrutura que não foi criada pelo Terraform. A importação do Terraform resolve esse problema carregando recursos compatíveis com o estado do seu espaço de trabalho do Terraform.

No entanto, o comando de importação não gera automaticamente a configuração para gerenciar a infraestrutura. Por isso, importar a infraestrutura atual para o Terraform é um processo de várias etapas.

Colocar a infraestrutura atual sob o controle do Terraform envolve cinco etapas principais:

• Identificar a infraestrutura atual a ser importada.
• Importar a infraestrutura para o estado do Terraform.
• Gravar uma configuração do Terraform que corresponda a essa infraestrutura.
• Analisar o plano do Terraform para que a configuração corresponda ao estado e à infraestrutura esperados.
• Aplicar a configuração para atualizar seu estado do Terraform.

Nesta seção, primeiro você vai criar um contêiner do Docker com a CLI do Docker. Em seguida, você o importará para um novo espaço de trabalho do Terraform. Em seguida, você vai atualizar a configuração do contêiner usando o Terraform antes de destruí-lo quando terminar.

Aviso: a importação de infraestrutura manipula o estado do Terraform de maneiras que podem deixar os projetos atuais do Terraform em um estado inválido. Faça um backup do arquivo terraform.tfstate e do diretório .terraform antes de usar a importação do Terraform em um projeto real e armazene-os com segurança.

Criar um contêiner do Docker

1. Crie um contêiner chamado hashicorp-learn usando a imagem NGINX mais recente do Hub do Docker e visualize o contêiner na máquina virtual do Cloud Shell pela porta 80 (HTTP):

docker run --name hashicorp-learn --detach --publish 8080:80 nginx:latest

2. Verifique se o contêiner está em execução:

docker ps

3. No painel do Cloud Shell, clique em Visualização da Web e, em seguida, clique em Visualizar na porta 8080.

O Cloud Shell abre o URL de visualização no serviço de proxy em uma nova janela do navegador e exibe a página de índice padrão do NGINX. Agora você tem uma imagem e um contêiner do Docker para importar para seu espaço de trabalho e gerenciar com o Terraform.

Importar o contêiner para o Terraform

1. Clone o repositório de exemplo (em inglês):

git clone https://github.com/hashicorp/learn-terraform-import.git

2. Altere para este diretório:

cd learn-terraform-import

Esse diretório contém dois arquivos de configuração do Terraform que compõem a configuração que você usará neste guia:

• O arquivo main.tf configura o provedor do Docker.
• O arquivo docker.tf conterá a configuração necessária para gerenciar o contêiner do Docker que você criou em uma etapa anterior.

3. Inicialize seu espaço de trabalho do Terraform:

terraform init Observação: se você receber um erro como Erro: Falha ao consultar pacotes de provedores disponíveis, execute o comando terraform init -upgrade

4. No Editor do Cloud Shell, navegue até learn-terraform-import/main.tf.

5. Encontre o recurso provider: docker e comente ou exclua o argumento host:

provider "docker" { # host = "npipe:////.//pipe//docker_engine" } Observação: essa é uma solução para um problema conhecido com um erro de inicialização do Docker.

6. Em seguida, navegue até learn-terraform-import/docker.tf.

7. No código comentado, defina um recurso docker_container vazio em seu arquivo docker.tf, que representa um contêiner do Docker com o ID de recurso do Terraform docker_container.web:

resource "docker_container" "web" {}

8. Encontre o nome do contêiner que você quer importar. Neste caso, o contêiner que você criou na etapa anterior:

docker ps

9. Execute o comando terraform import a seguir para anexar o contêiner do Docker ao recurso docker_container.web que você acabou de criar. A importação do Terraform requer esse ID de recurso do Terraform e o ID completo do contêiner do Docker. O comando docker inspect -f {{.ID}} hashicorp-learn retorna o ID do contêiner SHA256 completo:

terraform import docker_container.web $(docker inspect -f {{.ID}} hashicorp-learn) Observação: o ID aceito pelo terraform import varia de acordo com o tipo de recurso e está registrado na documentação do provedor para qualquer recurso que possa ser importado para o Terraform. Para este exemplo, consulte a documentação do provedor do Docker.

10. Verifique se o contêiner foi importado para o estado do Terraform:

terraform show

Esse estado contém tudo o que o Terraform sabe sobre o contêiner do Docker que você acabou de importar. No entanto, a importação do Terraform não cria a configuração do recurso.

Criar configuração

Você precisará criar a configuração do Terraform antes de usá-lo para gerenciar esse contêiner.

1. Execute o seguinte código:

terraform plan Note: O Terraform vai mostrar erros para os argumentos necessários ausentes image e name. O Terraform não pode gerar um plano para um recurso sem argumentos obrigatórios.

Há duas abordagens para atualizar a configuração em docker.tf para corresponder ao estado importado. É possível aceitar todo o estado atual do recurso em sua configuração como está ou selecionar os atributos necessários em sua configuração individualmente. Cada uma dessas abordagens pode ser útil em diferentes circunstâncias.

• Usar o estado atual geralmente é mais rápido, mas pode resultar em uma configuração detalhada demais porque cada atributo é incluído no estado, por mais que não seja necessário incluir em sua configuração.

• A seleção individual dos atributos necessários pode levar a uma configuração mais gerenciável, mas exige que você entenda quais atributos precisam ser definidos na configuração.

Para os propósitos deste laboratório, você usará o estado atual como recurso.

2. Copie o estado do Terraform para o arquivo docker.tf:

terraform show -no-color > docker.tf Observação: o símbolo > vai substituir todo o conteúdo de docker.tf pela saída do comando terraform show. Importar um recurso para uma configuração que já gerencia recursos funciona para este exemplo, mas exigirá que você edite a saída do terraform show para remover recursos atuais que têm configuração que você não pretende substituir completamente e mesclar os novos recursos em sua configuração atual.

3. Inspecione o arquivo docker.tf para ver se o conteúdo foi substituído pela saída do comando "terraform show" que você acabou de executar.

4. Execute o seguinte código:

terraform plan

O Terraform mostrará avisos e erros sobre um argumento descontinuado ("links") e vários argumentos somente leitura (ip_address, network_data, gateway, ip_prefix_length, id).

Esses argumentos somente leitura são valores que o Terraform armazena no estado para contêineres do Docker, mas que não podem ser definidos com a configuração porque são gerenciados internamente pelo Docker. O Terraform pode definir o argumento de links com a configuração, mas ainda exibe um aviso porque foi descontinuado e pode não ser compatível com versões futuras do provedor do Docker.

Como a abordagem mostrada aqui carrega todos os atributos representados no estado do Terraform, sua configuração inclui atributos opcionais com valores que são os mesmos que os padrões deles. Os atributos que são opcionais e os valores padrão deles variam de um provedor para outro e estão listados na documentação do provedor.

5. Agora é possível remover seletivamente esses atributos opcionais. Remova todos esses atributos, mantendo apenas os necessários: image, name e ports. Depois de remover esses atributos opcionais, sua configuração precisa corresponder ao seguinte:

resource "docker_container" "web" { image = "sha256:87a94228f133e2da99cb16d653cd1373c5b4e8689956386c1c12b60a20421a02" name = "hashicorp-learn" ports { external = 8080 internal = 80 ip = "0.0.0.0" protocol = "tcp" } }

Ao importar uma infraestrutura real, consulte a documentação do provedor para saber o que cada argumento faz. Isso ajudará você a determinar como lidar com os erros ou avisos da etapa do plano. Por exemplo, a documentação do argumento links está na documentação do provedor do Docker.

6. Verifique se os erros foram resolvidos:

terraform plan

O plano vai ser executado. O plano indica que o Terraform atualizará o contêiner para adicionar os atributos attach, logs, must_run e start.

O Terraform usa esses atributos para criar contêineres do Docker, mas o Docker não os armazena. Como resultado, o terraform import não carregou os valores no estado. Quando você planejar e aplicar sua configuração, o provedor Docker atribuirá os valores padrão para esses atributos e os salvará no estado, mas eles não afetarão o contêiner em execução.

7. Aplique as alterações e conclua o processo de sincronização da configuração e do estado atualizados do Terraform com o contêiner do Docker que eles representam. Digite yes no prompt para confirmar.

terraform apply

Agora, seu arquivo de configuração, o estado do Terraform e o contêiner estão sincronizados, e é possível usar o Terraform para gerenciar o contêiner dele como você faria normalmente.

Criar recurso de imagem

Em alguns casos, é possível colocar recursos sob o controle do Terraform sem usar o comando terraform import. Geralmente, esse é o caso de recursos definidos por uma tag ou um ID exclusivos, como imagens do Docker.

Em seu arquivo docker.tf, o recurso docker_container.web especifica o ID da hash SHA256 da imagem usada para criar o contêiner. É assim que o docker armazena o ID da imagem internamente. Portanto, o terraform import carregou o ID da imagem diretamente em seu estado. No entanto, o ID da imagem não é tão legível quanto o nome ou a imagem da tag e pode não corresponder à sua intenção. Por exemplo, talvez você queira usar a versão mais recente da imagem "nginx".

1. Para recuperar o nome da tag da imagem, execute o seguinte comando, substituindo <IMAGE-ID> pelo ID da imagem de docker.tf:

docker image inspect -f {{.RepoTags}}

2. Adicione a seguinte configuração ao seu arquivo docker.tf para representar essa imagem como um recurso:

resource "docker_image" "nginx" { name = "nginx:latest" } Observação: não substitua o valor da imagem no recurso docker_container.web ainda, ou o Terraform vai destruir e recriar seu contêiner. Como o Terraform ainda não carregou o recurso docker_image.nginx no estado, ele não tem um ID de imagem para comparar com o codificado, o que fará com que o Terraform presuma que o contêiner precisa ser substituído. Para contornar essa situação, primeiro crie a imagem e, em seguida, atualize o contêiner para usá-la, conforme mostrado neste laboratório.

3. Crie um recurso de imagem no estado:

terraform apply

Agora que o Terraform criou um recurso para a imagem, é possível fazer referência a ele na configuração do seu contêiner.

4. Altere o valor da imagem para docker_container.web para fazer referência ao novo recurso de imagem:

resource "docker_container" "web" { image = docker_image.nginx.image_id name = "hashicorp-learn" ports { external = 8080 internal = 80 ip = "0.0.0.0" protocol = "tcp" } }

5. Procure as mudanças:

terraform apply

Como o docker_image.nginx.latest vai corresponder ao ID da imagem codificada que você substituiu, a execução do terraform apply neste ponto não vai mostrar alterações.

Observação: se o ID da imagem para a tag "nginx:latest" for alterado entre o momento em que você criou o contêiner do Docker e a execução dele, o contêiner será destruído e recriado com a nova imagem.

Gerenciar o contêiner com o Terraform

Agora que o Terraform gerencia o contêiner do Docker, use-o para alterar a configuração.

1. Em seu arquivo docker.tf, altere a porta externa do contêiner de 8080 para 8081:

resource "docker_container" "web" { name = "hashicorp-learn" image = docker_image.nginx.image_id ports { external = 8081 internal = 80 ip = "0.0.0.0" protocol = "tcp" } }

2. Aplique a alteração:

terraform apply

Digite yes no prompt para confirmar.

Isso fará com que o Terraform destrua e recrie o contêiner com a nova configuração de porta.

3. Verifique se o contêiner foi substituído por um novo com a nova configuração:

docker ps

Observe que o ID do contêiner foi alterado. Como alterar a configuração da porta exigia destruí-la e recriá-la, este é um contêiner completamente novo.

Destruir a infraestrutura

Agora você importou seu contêiner do Docker e a imagem usada para criá-lo no Terraform.

1. Destrua o contêiner e a imagem:

terraform destroy

Digite yes no prompt para confirmar.

2. Verifique se o contêiner foi destruído:

docker ps --filter "name=hashicorp-learn" Observação: como você adicionou a imagem à configuração do Terraform e ao contêiner, ela será removida do Docker e do contêiner. Se outro contêiner estivesse usando a mesma imagem, a etapa de destruição apresentaria falha. Importar um recurso para o Terraform significa que ele gerenciará todo o ciclo de vida do recurso, incluindo a destruição.

Limitações e outras considerações

Há vários fatores importantes a serem considerados ao importar recursos para o Terraform.

A importação do Terraform só consegue saber o estado atual da infraestrutura conforme relatado pelo provedor do Terraform. Ela não sabe:

• se a infraestrutura está funcionando corretamente;
• o propósito da infraestrutura;
• as alterações feitas na infraestrutura que não são controladas pelo Terraform (por exemplo, o estado do sistema de arquivos de um contêiner do Docker).

A importação envolve etapas manuais que podem estar sujeitas a erros, principalmente se a pessoa que importa recursos não tiver o contexto de como e por que eles foram criados originalmente.

A importação manipula o arquivo de estado do Terraform. Convém criar um backup antes de importar a nova infraestrutura.

A importação do Terraform não detecta nem gera relacionamentos entre a infraestrutura.

O Terraform não detecta atributos padrão que não precisam ser definidos em sua configuração.

Nem todos os provedores e recursos são compatíveis com a importação do Terraform.

Importar infraestrutura para o Terraform não significa que ela possa ser destruída e recriada pelo Terraform. Por exemplo, a infraestrutura importada pode depender de outra infraestrutura ou configuração não gerenciada.

Seguir as práticas recomendadas de infraestrutura como código (IaC, na sigla em inglês), como infraestrutura imutável, pode ajudar a evitar muitos desses problemas, mas é improvável que a infraestrutura criada manualmente siga as práticas recomendadas de IaC.

Ferramentas como o Terraformer (em inglês) podem automatizar algumas etapas manuais associadas à importação de infraestrutura. No entanto, essas ferramentas não fazem parte do próprio Terraform e não têm endosso ou suporte da HashiCorp.

Parabéns!

Neste laboratório, você aprendeu a gerenciar back-ends e estados com o Terraform. Você criou back-ends locais e do Cloud Storage para gerenciar seu arquivo de estado, atualizou seu estado e importou a configuração para o Terraform. Depois, atualizou a configuração e editou manualmente para gerenciar totalmente o contêiner do Docker com o Terraform.

Próximas etapas/Saiba mais

Verifique os links abaixo para ter acesso a mais material prático do Terraform:

• Hashicorp no Google Cloud Marketplace.
• Hashicorp Learn
• Comunidade do Terraform
• Exemplos do Terraform no Google

Treinamento e certificação do Google Cloud

Esses treinamentos ajudam você a aproveitar as tecnologias do Google Cloud ao máximo. Nossas aulas incluem habilidades técnicas e práticas recomendadas para ajudar você a alcançar rapidamente o nível esperado e continuar sua jornada de aprendizado. Oferecemos treinamentos que vão do nível básico ao avançado, com opções de aulas virtuais, sob demanda e por meio de transmissões ao vivo para que você possa encaixá-las na correria do seu dia a dia. As certificações validam sua experiência e comprovam suas habilidades com as tecnologias do Google Cloud.

Manual atualizado em 26 de janeiro de 2024

Laboratório testado em 11 de dezembro de 2023

Copyright 2024 Google LLC. Todos os direitos reservados. Google e o logotipo do Google são marcas registradas da Google LLC. Todos os outros nomes de produtos e empresas podem ser marcas registradas das respectivas empresas a que estão associados.