AWS CloudFormation Language Server - AWS CloudFormation
IDEs integrados ao AWS CloudFormation Language ServerIntroduçãoInicialização de um projeto do CloudFormation no IDE (apenas VS Code)Código abertoPrecisa de ajuda?

AWS CloudFormation Language Server

O AWS CloudFormation Language Server fornece recursos para acelerar a criação de infraestrutura como código (IaC) e a implantação de recursos da AWS com segurança e confiança. Ele segue o protocolo de servidor de linguagens (LSP) para fornecer documentação contextual e sobre preenchimento automático, diagnóstico por meio de validação estática, acesso à definição e ações de código. Além desses recursos tradicionais de servidor de idiomas, o servidor adiciona recursos on-line para explorar e implantar recursos da AWS por meio do CloudFormation. Isso inclui a capacidade de validar e implantar modelos usando conjuntos de alterações, de visualizar diferenças de pilhas, eventos, recursos e saídas, de listar pilhas e procurar recursos por tipo e de inserir o estado ativo dos recursos diretamente nos modelos do CloudFormation.

IDEs integrados ao AWS CloudFormation Language Server

O AWS oferece integração pronta para uso com o CloudFormation Language Server por meio do AWS Toolkit para os seguintes IDEs:

Os seguintes IDEs também oferecem suporte ao CloudFormation Language Server:

  • Kiro

  • Cursor

  • A maioria dos forks e distribuições do VS Code

O CloudFormation Language Server segue o Language Server Protocol (LSP) e, portanto, outras integrações podem ser configuradas. Para obter instruções sobre como integrar o servidor de idiomas com outros editores, consulte o guia de instalação.

Introdução

Pré-requisitos

Antes de começar, verifique se:

  • Você está usando um IDE compatível em um sistema operacional compatível (macOS, Windows ou Linux).

  • Você instalou ou atualizou para a versão mais recente do kit de ferramentas da AWS para seu IDE.

Alguns recursos no AWS CloudFormation Language Server exigem as credenciais configuradas e ativas da Conta da AWS. Você deve fazer login em sua Conta da AWS por meio do kit de ferramentas da AWS usando credenciais válidas.

Etapa 1: instalar ou atualizar o kit de ferramentas da AWS

Instale ou atualize para a versão mais recente do AWS Toolkit a partir do gerenciador de extensões ou plug-ins do seu IDE e, em seguida, reinicie o IDE.

Após a instalação, o kit de ferramentas da AWS habilita automaticamente o suporte ao IDE do CloudFormation. Ao instalar ou atualizar AWS o Toolkit com o AWS CloudFormation Language Server pela primeira vez, será solicitado que conceda permissão para o AWS para a coleta de dados de uso anônimos. Esses dados ajudam a AWS a melhorar o CloudFormation Language Server e aprimoram a experiência de criação de conteúdo. Nenhuma informação sensível é coletada, e AWS não registra nem armazena conteúdo de modelos, configurações de recursos ou quaisquer dados identificáveis do cliente. Você pode alterar suas preferências de telemetria a qualquer momento nas configurações do IDE. Reinicie o IDE para que as alterações tenham efeito. Os dados de uso coletados focam apenas as interações de recursos e as métricas de performance. Esses insights ajudam a identificar e priorizar melhorias da AWS, como validação mais rápida, preenchimento automático aprimorado e melhores diagnósticos de erros.

Etapa 2: acessar o CloudFormation no painel do AWS Toolkit

Depois de instalar o AWS Toolkit, abra o painel CloudFormation no seu IDE. No VS Code, abra o painel do AWS Toolkit na barra de atividades e escolha CLOUDFORMATION. Nos IDEs da JetBrains, abra a janela de ferramentas AWS Toolkit na barra lateral e selecione a guia CloudFormation.

O painel do CloudFormation contém as seguintes seções:

  • Região: exibe a Região da AWS atual. No VS Code, você pode alterá-la selecionando o nome da região ou usando o comando AWS CloudFormation: Select Region na paleta de comandos. Nos IDEs da JetBrains, a Região é configurada por meio das configurações de conexão do AWS Toolkit.

  • Pilhas: exibe uma lista paginada das pilhas do CloudFormation em sua conta. Expanda uma pilha para visualizar o nó Change Sets, que lista os conjuntos de alterações associados a essa pilha. Utilize a ação Visualizar detalhes da pilha para abrir a visualização detalhada da pilha, que exibe a visão geral da pilha, os eventos, as saídas e os recursos.

  • Recursos: depois de adicionar um tipo de recurso, o painel exibe os recursos da AWS desse tipo em sua conta. Você pode visualizá-los, atualizá-los, copiá-los ou importá-los para o seu modelo.

Nos IDEs da JetBrains, a barra de ferramentas acima da árvore oferece acesso rápido a ações comuns, incluindo Validate and Deploy, Rerun Validate and Deploy, Add Resource Type e Refresh. As ações também estão disponíveis nos menus de contexto acessados ao clicar com o botão direito do mouse nos nós da árvore.

Etapa 3: validar, testar e refinar seu modelo

À medida que você escreve seu modelo do CloudFormation, o IDE fornece assistência de criação inteligente para ajudar a criar uma infraestrutura precisa e compatível com mais rapidez. O CloudFormation Language Server é executado em segundo plano e oferece os seguintes recursos de criação:

  • Preenchimento de código: sugere tipos de recursos, parâmetros e propriedades com base nos esquemas do CloudFormation.

  • Adicionar recursos existentes da AWS: permite que você importe recursos existentes da sua Conta da AWS para o seu modelo. O IDE usa o AWS API Cloud Control (CCAPI) para recuperar a configuração ativa e as propriedades do recurso, ajudando você a clonar ou a reutilizar a infraestrutura existente em seu modelo.

  • Extrair para parâmetro: quando o cursor estiver sobre um valor literal em um modelo (por exemplo, uma string como t2.micro), o IDE oferece uma ação de refatoração para extrair o valor para a seção !Ref e substituir o literal por uma Parameters ao novo parâmetro. Se o mesmo valor literal aparecer em vários lugares, você pode optar por extrair todas as ocorrências de uma só vez.

Para adicionar recursos a seu modelo

  • Adicionar um tipo de recurso: no painel AWS Toolkit CloudFormation, em Recursos, adicione um tipo de recurso para navegar. No VS Code, clique no ícone Adicionar + ou use o comando AWS CloudFormation: Add Resource Types na paleta de comandos. Na JetBrains, clique no botão Add Resource Type na barra de ferramentas ou clique com o botão direito do mouse no nó Recursos.

  • Pesquisar um tipo de recurso: na caixa de diálogo de pesquisa, digite o tipo de recurso AWS que você deseja adicionar. Exemplo:

    • AWS::S3::Bucket

    • AWS::Lambda::Function

  • Explorar recursos: na seção Resources, é exibida uma lista paginada dos recursos da AWS detectados na sua conta. Se você tiver muitos recursos, somente a primeira página será exibida. Utilize os controles de navegação para percorrer as páginas adicionais e visualizar todos os recursos disponíveis.

  • Escolha o recurso que você deseja incluir em seu modelo.

  • Você pode inserir um recurso em seu modelo de duas formas, dependendo do seu objetivo:

    • Clonar um recurso existente: crie um novo recurso em seu modelo usando a configuração ativa e as propriedades de um recurso existente daAWS.

    • Importar um recurso existente: insira o recurso real em sua pilha adicionando-o ao seu modelo usando seu estado ativo.

Dicas

  • Você pode atualizar a seção Recursos a qualquer momento para ver a lista mais recente de recursos disponíveis em sua conta ou região.

  • Se você estiver importando recursos, não adicione um recurso que já pertença a uma pilha existente do CloudFormation na mesma conta.

  • Para confirmar se um recurso já é gerenciado pelo CloudFormation, utilize a ação “Informações” ao lado do recurso. No VS Code, clique no ícone i. Nos IDEs da JetBrains, clique com o botão direito do mouse no recurso e selecione Get Stack Management Info.

No VS Code, você pode adicionar recursos relacionados ao recurso selecionado usando o comando AWS CloudFormation: Add Related Resources by Type. Depois de selecionar um tipo de recurso dos já definidos em seu modelo, o IDE exibirá uma lista de recursos que normalmente estão associados ou dependem desse tipo. Por exemplo, se você selecionar o AWS::EC2::Instance, o IDE poderá sugerir a adição de recursos relacionados, como AWS::EC2::SecurityGroup ou AWS::EC2::Subnet. Esse recurso ajuda você a criar rapidamente componentes de infraestrutura conectados sem procurar manualmente por tipos de recursos compatíveis. Atualmente, esse recurso não é compatível com os IDEs da JetBrains.₢

Validação estática

O CloudFormation Language Server fornece validação estática integrada baseada no AWS CloudFormation Linter (cfn-lint) e AWS CloudFormation Guard. Essas validações são executadas em segundo plano à medida que você cria modelos, ajudando a identificar erros de sintaxe, lacunas de conformidade e problemas de práticas recomendadas antes da implantação.

Visão geral da validação estática

Você verá dois tipos de validações estáticas em tempo real no IDE:

  • CloudFormation Linter (cfn-lint): valida seu modelo em relação às especificações de recursos e regras de esquema do CloudFormation.

  • Guard (cfn-guard): valida seu modelo em relação às regras de conformidade e aos pacotes de políticas organizacionais.

CloudFormation Linter (cfn-lint)

O CloudFormation Linter é integrado ao IDE para verificar automaticamente a sintaxe e a estrutura do modelo à medida que você digita.

  • Validação do esquema: detecta erros de sintaxe e esquema para garantir que seus modelos estejam em conformidade com o esquema de recursos do CloudFormation.

  • Realce de erros: exibe marcadores embutidos nas questões, indicando bloqueadores de implantação ou avisos.

  • Ajuda ao passar o mouse: quando você passa o mouse sobre um erro, o IDE mostra a mensagem de diagnóstico associada a esse problema. Se uma solução rápida estiver disponível, ela também será oferecida.

Integração do Guard

O Guard valida seus modelos em relação aos conjuntos de regras que definem as políticas de conformidade e segurança. O IDE executa validações do Guard em tempo real por meio do CloudFormation Language Server, fornecendo feedback imediato enquanto você cria modelos.

  • Pacotes de regras padrão: o IDE inclui um conjunto pré-registrado de regras do Guard focado nas práticas recomendadas básicas de segurança de recursos e limpeza da configuração. Para saber mais, consulte o registro de regras de proteção.

  • Adicionando pacotes de regras: para adicionar ou modificar conjuntos de regras, abra as configurações do seu IDE e acesse a seção de configuração do Guard para selecionar ou carregar pacotes de regras adicionais do Guard.

Dicas: entendendo os indicadores de diagnóstico

  • Indicadores azuis: sugestões de melhores práticas ou recomendações de otimização.

  • Indicadores amarelos: avisos sobre problemas de não bloqueio (por exemplo, tags ou parâmetros ausentes).

  • Indicadores vermelhos: bloqueadores de implantação, como nomes de propriedades inválidos, campos obrigatórios ausentes ou incompatibilidades de esquema.

Etapa 4: navegar pelo modelo

O IDE oferece uma visualização estruturada e hierárquica do seu modelo do CloudFormation, organizado em seções como Parameters, Resources, Outputs, e Mappings, mostrando cada tipo de recurso e ID lógico. Isso facilita a localização e a navegação rápida para recursos ou parâmetros específicos em grandes modelos. No VS Code, o painel Outline na barra lateral do Explorer exibe essa estrutura. Nos IDEs da JetBrains, abra a janela de ferramentas Structure para visualizar a estrutura do modelo para o arquivo aberto no momento.

Você pode usar Ir para a definição para funções intrínsecas, como GetAtt eRef, permitindo que você vá diretamente para o recurso ou parâmetro referenciado em seu modelo. Isso ajuda você a rastrear dependências, a entender as relações de recursos e a fazer edições com mais eficiência.

Etapa 5: validar e implantar

Quando estiver pronto para implementar seu modelo do CloudFormation, utilize o recurso “Validate and Deploy” para criar um conjunto de alterações. O IDE valida o seu modelo e, caso não sejam encontrados erros que impeçam a continuação, prossegue com a criação de um conjunto de alterações sensível a desvios progressivos. O IDE exibe então uma visualização de diferenças para que você possa revisar todas as alterações propostas antes de executar o conjunto de alterações.

No VS Code, abra a paleta de comandos e execute AWS CloudFormation: validar e realizar a implantação. A paleta de comandos orienta-o passo a passo na seleção de um modelo, nome da pilha, parâmetros, recursos e outras opções de implantação. Nos IDEs da JetBrains, utilize o botão na barra de ferramentas Validate and Deploy, clique com o botão direito do mouse em um arquivo de modelo no editor ou clique com o botão direito do mouse em uma pilha na árvore. A JetBrains apresenta uma caixa de diálogo do assistente onde é possível configurar todas as opções de implantação, incluindo a seleção do modelo, o nome da pilha, os parâmetros, os recursos, as etiquetas e as opções avançadas.

Como a validação funciona

O IDE executa automaticamente uma verificação de validação antes da implantação e valida seu modelo quanto a causas comuns de falha, incluindo:

  • Sintaxe inválida de propriedades ou incompatibilidades de esquema: esses problemas geralmente são detectados por cfn-lint durante a criação, mas se você prosseguir com a implantação sem corrigi-los, a validação do CloudFormation no momento da implantação exibirá os mesmos erros antes que a pilha seja criada ou atualizada.

  • O nome do recurso está em conflito com os recursos existentes na sua conta.

  • Restrições específicas do serviço, como conflitos de nomes de buckets do S3 ou falta de criptografia.

Se a validação detectar erros, o IDE destaca os problemas diretamente no seu modelo e lista os erros no painel de diagnóstico. Cada problema inclui a propriedade ou o recurso específico que causou a falha, junto com uma sugestão de correção. Se não houver erros de bloqueio, você poderá prosseguir para a fase de implantação.

Se forem encontrados avisos (problemas de não bloqueio), uma caixa de diálogo será exibida permitindo que você continue com a implantação ou cancele e faça correções.

O IDE abre um conjunto de alterações sensível a desvios que exibe todas as diferenças entre seu modelo atual e a configuração da pilha implantada. Isso permite que você revise, confirme ou cancele o conjunto de alterações antes da execução. O cancelamento da implantação exclui o conjunto de alterações.

Conjuntos de alterações sensíveis a desvios aprimoram o processo de implantação do CloudFormation, permitindo que você gerencie o desvio de pilha com segurança. O desvio de pilha ocorre quando o estado real dos seus recursos é diferente do que está definido no seu modelo do CloudFormation, geralmente devido a alterações manuais feitas por meio do Console de gerenciamento da AWS, da CLI ou do SDK. Os conjuntos de alterações sensível a desvios do CloudFormation comparam sua configuração de pilha processada com o estado ativo do recurso, e o IDE mostra essas diferenças para que você possa trazer os recursos de volta à conformidade antes da implantação.

Visualizar eventos de pilha

Quando a implantação começar, poderá acompanhar o andamento em tempo real no painel do CloudFormation. Em Eventos de pilha, você verá uma lista das operações realizadas durante a implantação. Cada evento inclui detalhes como:

  • Carimbo de data e hora: a hora em que o evento ocorreu

  • Recurso: o recurso específico da AWS que está sendo criado, atualizado ou excluído

  • Status: o estado atual da operação (por exemplo, CREATE_IN_PROGRESS, UPDATE_COMPLETE ou ROLLBACK_IN_PROGRESS)

  • Motivo: contexto adicional ou mensagens de erro, se aplicável

Você também pode ver os recursos e as saídas da pilha nesse painel. A visualização Eventos de pilha ajuda você a acompanhar o progresso da implantação, a identificar possíveis problemas e a confirmar quando sua pilha foi concluída com êxito.

Inicialização de um projeto do CloudFormation no IDE (apenas VS Code)

Inicializar um projeto do CloudFormation no IDE ajuda você a configurar um espaço de trabalho estruturado com as pastas, a configuração do ambiente e as credenciais da AWS corretas para que você possa validar e implantar seus modelos de forma confiável. Você pode inicializar um novo projeto do CloudFormation diretamente do IDE para criar essa configuração recomendada. Atualmente, esse recurso está disponível apenas no VS Code e não é compatível com os IDEs da JetBrains.

Para inicializar um projeto CloudFormation:

  • Abrir a paleta de comandos

    • No VS Code, abra a paleta de comandos (Ctrl+Shift+P ou Cmd+Shift+P em macOS).

    • Escolha AWS CloudFormation: CFN Init: Initialize Project.

  • Escolher um diretório de projeto

    • Por padrão, o IDE usará seu diretório de trabalho atual.

    • Você pode alterar esse caminho para qualquer pasta em que deseja armazenar seus modelos do CloudFormation.

  • Selecione seu perfil de credencial da AWS

    • Você receberá um prompt para escolher um perfil de credencial da AWS. O perfil selecionado será usado para detecção, validações e implantações do ambiente.

  • Configure o ambiente

    • Você receberá um prompt para criar ou selecionar um ambiente.

    • Os ambientes definem onde e como seus modelos serão implantados ou validados (por exemplo, desenvolvimento, versão beta ou produção). Você pode usar AWS CloudFormation: CFN Init: Add Environment para selecionar ou alterar seu ambiente.

    • Você pode usar AWS CloudFormation: CFN Init: Remove Environment para remover o ambiente selecionado.

  • (Opcional) Importar arquivos de parâmetros

    • Se você já tiver arquivos de parâmetros existentes, o IDE permitirá importá-los durante a inicialização.

    • O IDE detecta automaticamente arquivos compatíveis e os vincula ao seu projeto para uso na validação e implantação de modelos.

  • Nomear e finalizar o projeto

    • Forneça um nome de projeto, como ambiente beta, e conclua a configuração.

    • O IDE cria a estrutura inicial do projeto e o arquivo de configuração para você.

Você pode executar validações, visualizar implantações ou alternar entre ambientes diretamente do IDE.

Código aberto

O AWS CloudFormation Language Server é de código aberto de acordo com a Licença do Apache-2.0, oferecendo aos clientes total transparência sobre como o diagnóstico de modelos, a validação do esquema e a análise estática são realizados. Isso reduz o atrito de segurança e conformidade para clientes que precisam de visibilidade no nível da origem antes de adotar ferramentas.

A base de código está disponível publicamente no GitHub: https://github.com/aws-cloudformation/cloudformation-languageserver/.

Precisa de ajuda?

Experimente a comunidade do CloudFormation no AWS re:Post.