CloudFormation para Pulumi: migre stacks com inventário e importação sem surpresa

ANÁLISE EDITORIAL

Migrar uma stack do AWS CloudFormation para Pulumi não é trocar YAML por TypeScript e aplicar o resultado. Os recursos já existem, têm identificadores físicos, dependências e uma ferramenta responsável por seu estado. A Skill oficial cloudformation-to-pulumi ajuda a organizar a conversão e a importação sem tratar uma prévia de código como prova de que a infraestrutura está segura. Ela pede inventário completo, nomes compatíveis com a importação, validação de diferenças e um relatório final. A etapa mais importante continua humana: decidir, com acesso autorizado e plano de recuperação, quando cada recurso deixará de ser gerenciado pelo CloudFormation.

O que esta Skill faz de verdade

O SKILL.md da release fixada orienta um agente a levantar template, parâmetros, mapeamentos, condições, saídas e recursos de uma stack. Depois, propõe a tradução para um programa Pulumi em TypeScript. Para cada recurso, o nome no programa deve preservar o Logical ID do CloudFormation. Essa correspondência é uma exigência do fluxo de importação sugerido pela Skill, não uma regra universal para qualquer projeto Pulumi.

A Skill também aponta os documentos cfn-importer.md e cloudformation-id-lookup.md para importar recursos existentes e investigar IDs que não possam ser resolvidos automaticamente. Ambos acompanham o ZIP desta página. O pacote é texto, não inclui os plugins citados e não faz chamadas à AWS. Na consulta de 14 de outubro de 2026, a API do GitHub registrava 78 estrelas para o repositório inteiro. Este item entra por ser mantido oficialmente pela Pulumi, ter release identificada, documentação e licença verificadas. Não apresentamos esse número como prova de adoção ampla ou de segurança.

Para quem serve

Ela faz sentido para uma equipe que já administra uma stack CloudFormation e quer estudar a adoção gradual de seus recursos no Pulumi. Também pode orientar a análise de um template fornecido sem acesso à conta AWS. O arquivo original cobre duas situações diferentes: converter a definição para código e, quando há recursos implantados, importar os recursos existentes para o estado Pulumi. Confundir esses caminhos é perigoso. Gerar um programa que criaria uma nova VPC não equivale a assumir com segurança uma VPC já existente.

O guia da Pulumi distingue coexistir com a stack, implantá-la como um recurso opaco e migrar cada recurso para código. A Skill trata principalmente da última opção e de sua preparação. Se a equipe só precisa consultar saídas de uma stack existente, a migração integral pode ser desnecessária. O agente deve ajudar a identificar essa diferença antes de sugerir comandos de importação.

Compatibilidade e pré-requisitos

O fluxo descrito usa AWS CloudFormation, Pulumi, AWS CLI e TypeScript. Para importar recursos, a equipe precisa das ferramentas e dos plugins apropriados, incluindo o provedor aws-native citado pela Skill. O documento prioriza esse provedor porque mapeia tipos CloudFormation de modo mais direto para o importador indicado, mas exige justificar exceções que usem o provedor aws clássico. Confira suporte do tipo de recurso, versão instalada, região AWS e permissões antes de executar qualquer comando. Não presuma que todos os tipos ou propriedades estejam cobertos.

O arquivo original exige um ambiente Pulumi ESC para carregar credenciais e pede confirmação explícita da região. Se não houver ambiente definido, a instrução é perguntar qual usar antes de consultar a AWS. Isso não autoriza o agente a escolher uma conta ou escopo por conta própria. Para estudar o documento sem tocar na nuvem, basta o template exportado, preferencialmente sanitizado, e um projeto de teste. Não testamos a migração em uma conta real nesta curadoria.

Instalação recomendada

Baixe o ZIP documental do Bastidores e compare seu SHA-256 com o valor no fim desta página. Extraia os cinco arquivos em uma pasta cloudformation-to-pulumi dentro do diretório de Skills aceito pelo seu agente. Mantenha cfn-importer.md e cloudformation-id-lookup.md ao lado de SKILL.md, pois as referências são relativas. Leia ORIGEM.md e LICENSE antes de habilitar a Skill. Reinicie a sessão se o agente só detectar Skills no início.

O README oficial mostra também a instalação de grupos pelo marketplace de plugins ou pelo Skills CLI. Esses métodos podem instalar várias Skills e trazer uma revisão posterior à que auditamos. Para reproduzir este material, use o pacote com commit fixado; para acompanhar o mantenedor, use o repositório oficial e revise novamente arquivos, licença e permissões. Nenhum dos dois métodos instala automaticamente a AWS CLI, o Pulumi CLI ou os plugins de importação usados numa migração real.

Configuração antes do primeiro uso

Comece com escopo de leitura. Registre nome da stack, conta e região autorizadas, dono da mudança, janela de manutenção e política de rollback. Peça ao agente um inventário de Logical IDs, Physical IDs e tipos, além de parâmetros, condições, saídas e recursos personalizados. A referência do comando AWS explica a listagem de recursos; a Skill usa essa relação para comparar o que existe com o que o programa Pulumi representa. Não compartilhe credenciais ou templates com segredos em um prompt público.

Se houver acesso à AWS, confirme qual ambiente ESC e qual região serão usados, em vez de deixar o agente adivinhar. Separe um projeto Pulumi e um estado de teste, registre as versões de CLI e provedor e faça backup dos arquivos de definição. Não autorize pulumi up, exclusão da stack original ou importação durante a primeira análise. Um template exportado pode revelar nomes e parâmetros sensíveis; revise o material antes de anexá-lo à conversa.

Primeiro uso seguro e resultado esperado

Um pedido inicial útil é: “Leia o template e produza apenas a tabela de recursos, parâmetros, condições, dependências e lacunas; não execute comandos de escrita”. Depois, solicite a proposta de mapeamento para aws-native, preservando o Logical ID como nome do recurso Pulumi e justificando qualquer exceção. Confira manualmente a tabela, em especial recursos personalizados, propriedades condicionais e referências entre stacks. A Skill exige que cada recurso seja representado ou tenha sua ausência explicada no relatório.

Com código revisado, uma pulumi preview pode mostrar o que o programa tentaria fazer, mas não prova por si só que a importação de uma stack existente será segura. O procedimento do importador descrito pela Pulumi usa cdk-importer, instalado separadamente como plugin. Ele pode falhar em parte dos recursos e gerar IDs pendentes. Antes de qualquer execução, a equipe deve validar as opções do plugin instalado e ensaiar em ambiente descartável quando possível. Após a importação, a meta da Skill é uma prévia sem operações de criação, alteração, substituição ou exclusão. Se houver diferença, pare e investigue, não aplique para “ver o que acontece”.

O resultado esperado desta orientação é um plano de migração revisável, um programa candidato e uma tabela que liga cada Logical ID ao tipo CloudFormation e ao recurso Pulumi proposto. Para uma stack já implantada, acrescente o estado de cada importação, diferenças encontradas e decisões humanas pendentes. O guia oficial alerta que assumir recursos pode envolver política de retenção no CloudFormation. Essa transição de responsabilidade merece procedimento próprio, backup e aprovação, nunca um comando implícito num pedido ao agente.

Permissões e riscos

O ZIP hospeda apenas Markdown e licença. O risco operacional aparece quando o agente recebe permissão de executar AWS CLI, instalar plugins, ler ESC, alterar código ou atualizar estado Pulumi. Uma região errada pode produzir inventário incorreto; uma conta errada pode expor ou modificar recursos fora do escopo. Use credenciais de menor privilégio, confirme identidade e região com a equipe e comece pela inspeção. O documento original pede confirmação do ambiente ESC e da região justamente porque não há escolha segura por inferência.

Importar um recurso no Pulumi não remove automaticamente o gerenciamento anterior em todas as situações. Duas ferramentas disputando o mesmo recurso podem causar deriva ou substituição. A documentação Pulumi discute adoção com retenção para evitar apagar o recurso quando a definição CloudFormation for retirada. Trate alterações de DeletionPolicy e remoção da stack como mudanças de produção separadas, com ordem aprovada e forma de recuperação. Recursos personalizados e IDs compostos exigem atenção adicional; o importador não promete cobertura total.

Erros comuns e como investigar

Se o importador não encontrar um recurso, compare primeiro o nome Pulumi com o Logical ID original. Se um recurso aparecer como criação na prévia, confirme se foi importado, se o tipo e o provedor estão corretos e se o ID físico corresponde à conta e região esperadas. O arquivo cloudformation-id-lookup.md mostra como consultar o formato de ID com o plugin cdk2pulumi; alguns recursos exigem identificadores compostos. Não substitua um ID desconhecido por um palpite.

Se a prévia mostrar substituição, investigue propriedades, valores padrão, dependências e versões de provedor antes de avançar. Uma tradução literal de Ref, GetAtt, condições ou parâmetros pode mudar o comportamento. Se um recurso personalizado não tiver equivalente claro, documente a lacuna e deixe a implementação para uma revisão específica; o próprio material do importador aponta limitações. Se o comando falhar por credenciais ou região, pare, valide a identidade usada e peça correção ao responsável. Repetir a importação às cegas pode dificultar a reconciliação do estado.

Versão, licença e download local

O pacote fixa a release v2.0.7, publicada em outubro de 2026, no commit 99abfdac0ef8180e7723b3b5f30bb11171e3e4e3 do repositório pulumi/agent-skills. A licença Apache 2.0 permite redistribuição mediante seus termos e avisos. Preservamos sem alterações o SKILL.md, os dois Markdown de apoio e o LICENSE; ORIGEM.md registra URL, versão e SHA-256 de cada arquivo. Não há plugins, executáveis, dependências, template CloudFormation, código de projeto ou credenciais no ZIP.

O download local é uma ação separada do botão para abrir o repositório oficial. SHA-256 do ZIP: da16cc7a626d43080f18b66226181da5eeeaef8bd82da908814ab7cd93b20baa. Calcule o hash do arquivo baixado e compare-o com esse valor antes de instalar. Esta curadoria não executou uma migração nem validou compatibilidade de uma stack específica; versões futuras do mantenedor podem mudar instruções e suporte.

Fontes primárias

Pasta original da Skill na Pulumi; release fixada; guia de migração da Pulumi; referência AWS para o inventário da stack. Consulte as revisões atuais antes de operar infraestrutura real.