View a markdown version of this page

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

CloudFormation Language Server

O AWS CloudFormation Language Server ajuda a escrever modelos do CloudFormation em um editor. Conforme você digita, ele sugere tipos e propriedades de recursos, mostra documentação, encontra erros, permite que você vá para as definições e oferece correções para alguns problemas. Ele usa o Language Server Protocol (LSP), que permite que o servidor trabalhe com diferentes editores. Iniciar e usar o Language Server para esses recursos de criação local não requer credenciais de uma Conta da AWS ou da AWS.

As integrações do AWS Toolkit também usam o Language Server para fluxos de trabalho on-line que chamam os serviços da AWS. Esses fluxos de trabalho podem procurar recursos e pilhas. Eles também podem executar a validação de modelos do serviço, implantar modelos, mostrar diferenças no conjunto de alterações e monitorar eventos da pilha. Esses fluxos de trabalho on-line são os únicos recursos que exigem uma Conta da AWS ativa e credenciais válidas da AWS.

IDEs integrados ao 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

Para IDEs do Visual Studio Code e da JetBrains, instale o AWS Toolkit. O Toolkit inclui e inicia o Language Server e, portanto, você não precisa baixar o servidor separadamente.

No caso de outro editor compatível com LSP, baixe o arquivo para seu computador a partir da versão mais recente no GitHub, extraia-o e configure seu editor para executar o seguinte comando:

node /path/to/install-location/cfn-lsp-server-standalone.js --stdio

Para ver as versões compatíveis do Node.js, downloads disponíveis, verificação de arquivos e exemplos de configuração para diferentes editores, consulte o guia de instalação independente.

Introdução

As etapas a seguir mostram como usar o Language Server por meio do AWS Toolkit para IDEs do Visual Studio Code e da JetBrains. Para outro editor, siga o exemplo de configuração no guia de instalação independente.

Pré-requisitos

Antes de começar, verifique se:

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

  • Para IDEs do Visual Studio Code ou da JetBrains, instale ou atualize o AWS Toolkit.

  • Para outro editor, instale uma versão compatível do Node.js e baixe o arquivo do Language Server para o seu computador. O guia de instalação independente lista as versões e os arquivos compatíveis.

Você não precisa de uma Conta da AWS ou credenciais da AWS para iniciar o Language Server ou usar seus recursos locais de criação e verificação de modelos. Somente configure credenciais da AWS válidas no Toolkit ao usar fluxos de trabalho on-line que pesquisam recursos ou pilhas, chamam o serviço do CloudFormation ou implantam um modelo.

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 o AWS Toolkit com o CloudFormation Language Server pela primeira vez, será solicitada a concessão de permissão para que a AWS colete 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

Enquanto você escreve seu modelo do CloudFormation, o CloudFormation Language Server é executado em segundo plano e fornece assistência de criação local sem as credenciais da AWS:

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

  • 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.

O Toolkit também fornece um fluxo de trabalho on-line para adicionar os recursos atuais da AWS ao seu modelo. Esse fluxo de trabalho requer credenciais da AWS válidas e usa a AWS API Cloud Control (CCAPI) para recuperar a configuração e as propriedades ativas de um recurso, ajudando a clonar ou reutilizar a infraestrutura existente no seu modelo.

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, execute o comando AWS CloudFormation: Add Related Resources by Type na paleta de comandos. Selecione um tipo de recurso dentre os já definidos no seu modelo. O IDE lista os tipos de recursos que o tipo selecionado pode consultar por meio de suas propriedades. Por exemplo, se você selecionar AWS::EC2::Instance, o IDE pode sugerir AWS::EC2::SecurityGroup ou AWS::EC2::Subnet. Selecione um ou mais tipos de recursos relacionados e, em seguida, escolha criar novas definições de recursos ou importar recursos existentes. 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 em CloudFormation Linter e CloudFormation Guard. Essas verificações são executadas localmente em segundo plano e não exigem credenciais da AWS. Elas ajudam a identificar erros de sintaxe, lacunas de conformidade e problemas relacionados às 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

Validar e implantar é um fluxo de trabalho on-line que chama o serviço CloudFormation e exige credenciais válidas da AWS. Quando estiver pronto para implantar seu modelo, use esse recurso 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 e a configuração do ambiente corretas para validação e implantação do serviço. Esses fluxos de trabalho on-line exigem credenciais da AWS, mas elas não são necessárias para os recursos locais de criação e validação estática do Language Server. 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 é usado para detecção de ambiente, validação do serviço e implantação.

  • 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 CloudFormation Language Server é de código aberto sob a licença do Apache-2.0, oferecendo aos clientes total transparência sobre como são realizados o diagnóstico de modelos, a validação do esquema e a análise estática. 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.