Passe a gerenciar um recurso existente

Introdução

Você está assumindo a manutenção de um bucket de relatórios em uso que foi criado fora do Terraform. Passe a gerenciá-lo sem recriá-lo nem reescrever seu relatório. Em seguida, revise e aplique um pequeno alinhamento de configuração, mantendo inalterado o armazenamento vizinho da equipe financeira.

Você já deve compreender a configuração do Terraform, endereços de recursos, init, plan, apply e estado local, além de operações básicas com objetos S3. O Terraform, seu provedor AWS, a configuração de acesso e dois buckets de relatórios independentes estão preparados neste novo ambiente. Não é necessário ter uma conta pessoal da AWS nem recursos de um laboratório anterior.

Relação com certificações

Visão geral do laboratório

Inspecione o armazenamento existente e a configuração desejada

Nesta etapa, compare o recurso que já existe na AWS com a configuração que você passará a gerenciar. O AWS View, acima do Terminal, exibe os mesmos recursos S3 que sua CLI lê. Expanda report.txt no cartão handover-daily-reports para inspecionar os dados do relatório; finance-reference-reports pertence a outra equipe e deve permanecer inalterado.

Um endereço de recurso do Terraform, como aws_s3_bucket.reports, identifica um bloco de configuração. O nome do bucket identifica o recurso remoto da AWS. O estado registra o mapeamento entre essas duas identidades. Um arquivo de configuração, por si só, não estabelece esse mapeamento.

Entre no diretório raiz preparado e leia a configuração desejada do bucket:

cd /home/labex/project/report-storage
cat main.tf

O argumento bucket seleciona handover-daily-reports. Owner deve permanecer como reporting; a nova tag ManagedBy registrará a transferência de responsabilidade. force_destroy = false impede que o Terraform esvazie automaticamente um bucket não vazio durante uma destruição posterior. Essa é uma configuração de comportamento do Terraform, separada do relatório armazenado no bucket.

Inspecione as tags existentes:

aws s3api \
  get-bucket-tagging \
  --bucket handover-daily-reports

Inicialmente, existe apenas Owner=reporting. Recupere o relatório original para a saída padrão, usando - como destino:

aws s3 \
  cp s3://handover-daily-reports/report.txt -

Relatório esperado:

Daily sales: 120 orders

Inicialize o diretório de trabalho. init instala o provedor na versão fixada para este diretório raiz; ele não importa nem cria o bucket:

terraform init

Inspecione as ações propostas sem aplicá-las:

terraform plan

O plano propõe 1 to add porque este diretório raiz ainda não tem um mapeamento de recurso gerenciado. O bucket já existe; isso evidencia a ausência de um vínculo de gerenciamento no estado, e não uma autorização para substituir o armazenamento. Não aplique este plano de criação. A próxima etapa estabelece o mapeamento explicitamente.

Antes de continuar, confirme manualmente que você consegue identificar o bucket de relatórios, ler seu relatório e diferenciá-lo do armazenamento financeiro. A verificação em segundo plano desta etapa de inspeção confere a preservação dos recursos fornecidos, e não se você compreendeu o plano exibido.

Importe o bucket existente e revise a diferença

Nesta etapa, mapeie o bucket existente para seu endereço pretendido no Terraform. O comando import da CLI lê um recurso remoto e registra sua identidade no estado. Ele não gera a configuração desejada nem importa todos os objetos dentro do bucket.

Execute a importação com o endereço da configuração primeiro e o nome do bucket existente em segundo lugar:

terraform import aws_s3_bucket.reports handover-daily-reports

Procure por Import successful!. Verifique qual endereço passou a ser gerenciado:

terraform state list

Endereço esperado:

aws_s3_bucket.reports

Leia seus atributos:

terraform state show aws_s3_bucket.reports

Tanto id quanto bucket devem identificar handover-daily-reports. report.txt continua armazenado no S3; importar um bucket não incorpora o objeto a um endereço aws_s3_object separado. O bucket financeiro não deve aparecer no estado deste diretório raiz.

A importação não garante um plano imediatamente vazio. Algumas configurações vêm do serviço remoto; outras, incluindo force_destroy, descrevem o comportamento do próprio Terraform e podem precisar de alinhamento com a configuração após a importação. Essa diferença não significa que seu relatório foi danificado.

Salve um plano para revisão. -out=handover.tfplan salva as ações planejadas para que a próxima etapa possa aplicar o mesmo plano revisado:

terraform plan -out=handover.tfplan

Leia o plano salvo:

terraform show handover.tfplan

Espere uma atualização no próprio recurso (~), a adição da tag ManagedBy=Terraform e, possivelmente, o alinhamento de force_destroy para false. O resumo deve ser:

Plan: 0 to add, 1 to change, 0 to destroy.

Se o plano propuser exclusão, substituição, criação, um nome de bucket diferente ou alterações no armazenamento financeiro, pare e revise o diretório raiz, o endereço do recurso e o ID de importação. Não resolva um plano inesperado excluindo o relatório existente.

Aplique o alinhamento e confirme a preservação

Nesta etapa, aplique apenas o plano que você revisou e comprove que o relatório original foi preservado. Fornecer um plano salvo a apply executa esse plano diretamente, sem uma segunda solicitação de aprovação. Execute-o somente após confirmar o resumo da etapa anterior, sem criações nem destruições:

terraform apply handover.tfplan

Espere Resources: 0 added, 1 changed, 0 destroyed. O bucket agora é gerenciado, e a tag de transferência de responsabilidade está alinhada à configuração.

Leia as tags atuais para verificar o resultado na AWS:

aws s3api \
  get-bucket-tagging \
  --bucket handover-daily-reports

Tanto Owner=reporting quanto ManagedBy=Terraform devem estar presentes; a ordem das tags não importa.

Leia o relatório novamente:

aws s3 \
  cp s3://handover-daily-reports/report.txt -

Ele ainda deve conter Daily sales: 120 orders. No AWS View, expanda os dois relatórios e confirme que o conteúdo do relatório e a referência financeira continuam disponíveis. Um alinhamento de tags não exige um novo bucket nem a reescrita de um objeto.

Verifique a convergência entre a configuração atual, o estado e o recurso AWS atualizado pela consulta:

terraform plan

Resultado esperado:

No changes. Your infrastructure matches the configuration.

Um plano sem alterações, por si só, não é evidência suficiente de uma transferência segura de responsabilidade: você também verificou o endereço de recurso pretendido e os dados originais, enquanto a verificação em segundo plano compara a versão original do objeto e o armazenamento vizinho e gera um plano da configuração atual em uma cópia descartável para confirmar a convergência. Mantenha os dois buckets para esta transferência. Não execute terraform destroy: o relatório ainda está em uso. Em uma transferência real, proteja o estado como dado operacional sensível e organize o acesso para o próximo responsável pela manutenção; não faça commit do estado nem de planos salvos que contenham valores sensíveis em um repositório público.

Para mais contexto, consulte o fluxo de importação pela CLI da HashiCorp.

Resumo

Você comparou um bucket existente com a configuração do Terraform, importou sua identidade para o endereço pretendido no estado e revisou um alinhamento não destrutivo antes de aplicá-lo. Você confirmou um plano sem alterações, preservando o relatório original e o armazenamento financeiro. A importação estabelece o gerenciamento; a revisão da configuração determina o que o Terraform deve alterar em seguida.