View a markdown version of this page

Servidor de lenguaje de CloudFormation - AWS CloudFormation
Los IDE se integran con el servidor de lenguaje de CloudFormationIntroducciónInicialización de un proyecto de CloudFormation en el IDE (solo VS Code)Código abierto¿Necesita ayuda?

Servidor de lenguaje de CloudFormation

El servidor de lenguaje de AWS CloudFormation permite escribir plantillas de CloudFormation en un editor. A medida que escribe, sugiere tipos de recursos y propiedades, muestra la documentación, encuentra errores, le permite ir directamente a las definiciones y ofrece soluciones a algunos problemas. Utiliza el Language Server Protocol (LSP), que permite al servidor trabajar con distintos editores. Para iniciar y utilizar el servidor de lenguaje para estas funciones de creación local no se requieren credenciales de Cuenta de AWS o AWS.

Las integraciones del kit de herramientas de AWS también utilizan el servidor de lenguaje para los flujos de trabajo en línea que llaman a los servicios de AWS. Estos flujos de trabajo pueden buscar recursos y pilas. También pueden ejecutar la validación de plantillas desde el lado del servicio, implementar plantillas, mostrar las diferencias entre los conjuntos de cambios y monitorizar los eventos de la pila. Estos flujos de trabajo en línea son las únicas funciones que requieren una Cuenta de AWS activa y credenciales de AWS válidas.

Los IDE se integran con el servidor de lenguaje de CloudFormation

AWS ofrece una integración disponible con el servidor de lenguaje de CloudFormation mediante el Kit de herramientas de AWS para los siguientes IDE:

Los siguientes IDE también son compatibles con el servidor de lenguaje de CloudFormation:

  • Kiro

  • Cursor

  • La mayoría de los forks y las distribuciones de VS Code

Para los IDE de Visual Studio Code y JetBrains, instale el kit de herramientas de AWS. El kit de herramientas incluye e inicia el servidor de lenguaje, por lo que no es necesario descargar el servidor por separado.

Para otro editor que admita LSP, descargue el archivo para su equipo desde la última versión en GitHub, extráigalo y configure su editor para que ejecute el siguiente comando:

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

Para ver las versiones de Node.js compatibles, las descargas disponibles, la verificación de archivos y los ejemplos de configuración para distintos editores, consulte la guía de instalación independiente.

Introducción

Los siguientes pasos muestran cómo utilizar el servidor de lenguaje mediante el kit de herramientas de AWS para los IDE de Visual Studio Code y JetBrains. Para otro editor, siga el ejemplo de configuración de standalone installation guide.

Requisitos previos

Antes de comenzar, asegúrese de que:

  • Está utilizando un IDE compatible en macOS, Windows o Linux.

  • Para Visual Studio Code o un IDE de JetBrains, instale o actualice el kit de herramientas de AWS.

  • Para otro editor, instale una versión compatible de Node.js y descargue el archivo del servidor de lenguaje en su computadora. La guía de instalación independiente enumera las versiones y los archivos compatibles.

No necesita credenciales de Cuenta de AWS o AWS para iniciar el servidor de lenguaje ni utilizar sus funciones locales de creación y comprobación de plantillas. Configure credenciales de AWS válidas en el kit de herramientas solo cuando utilice flujos de trabajo en línea que examinen recursos o pilas, llamen al servicio CloudFormation o implementen una plantilla.

Paso 1: instalar o actualizar el Kit de herramientas de AWS

Instale o actualice a la última versión del Kit de herramientas de AWS desde el administrador de extensiones o complementos de su IDE y luego reinicie el IDE.

Tras la instalación, el Kit de herramientas de AWS habilita automáticamente la compatibilidad con el IDE de CloudFormation. La primera vez que instale o actualice el Kit de herramientas de AWS con el servidor de lenguaje de CloudFormation, se le solicitará que conceda permiso a AWS para recopilar datos de uso anónimos. Estos datos ayudan a que AWS mejore el servidor de lenguaje de CloudFormation y mejoran la experiencia de creación. No se recopila información confidencial y AWS no registra ni almacena el contenido de las plantillas, las configuraciones de los recursos ni ningún dato identificable del cliente. Puede cambiar las preferencias de telemetría en cualquier momento desde la configuración del IDE. Reinicie el IDE para que los cambios surtan efecto. Los datos de uso recopilados se centran únicamente en las interacciones de las características y las métricas de rendimiento. Esta información ayuda a AWS a identificar y priorizar mejoras, como una validación más rápida, un mejor autocompletado y un mejor diagnóstico de errores.

Paso 2: acceder a CloudFormation en el Kit de herramientas de AWS

Luego de instalar el Kit de herramientas de AWS, abra el panel de CloudFormation en su IDE. En VS Code, abra el panel del Kit de herramientas de AWS desde la barra de actividades y seleccione CLOUDFORMATION. En los IDE de JetBrains, abra la ventana de herramientas del Kit de herramientas de AWS desde la barra lateral y seleccione la pestaña CloudFormation.

El panel de CloudFormation contiene las siguientes secciones:

  • Región: muestra la Región de AWS actual. En VS Code, puede cambiarla seleccionando el nombre de la región o utilizando el comando AWS CloudFormation: seleccionar región de la paleta de comandos. En los IDE de JetBrains, la región se configura mediante los ajustes de conexión del Kit de herramientas de AWS.

  • Pilas: muestra una lista paginada de las pilas de CloudFormation de su cuenta. Expanda una pila para ver su nodo de Conjuntos de cambios, que muestra los conjuntos de cambios asociados. Utilice la acción Ver detalles de la pila para abrir la vista de detalles de la pila, que muestra su descripción general, eventos, resultados y recursos.

  • Recursos: Después de agregar un tipo de recurso, el panel muestra los recursos de AWS de ese tipo en su cuenta. Puede verlos, actualizarlos, copiarlos o importarlos a su plantilla.

En los IDE de JetBrains, la barra de herramientas situada sobre el árbol otorga un acceso rápido a las acciones habituales, como Validar e implementar, Volver a ejecutar, validar e implementar, Agregar tipo de recurso y Actualizar. Las acciones también están disponibles en los menús contextuales que se abren al hacer clic derecho en los nodos del árbol.

Paso 3: validar, probar y refinar la plantilla

A medida que escribe su plantilla de CloudFormation, el servidor de lenguaje de CloudFormation se ejecuta en segundo plano y proporciona asistencia de creación local sin credenciales de AWS:

  • Finalización de código: sugiere tipos de recursos, parámetros y propiedades en función de los esquemas de CloudFormation.

  • Extraer a parámetro: cuando el cursor está sobre un valor literal de una plantilla (por ejemplo, una cadena similar a t2.micro), el IDE ofrece una acción de refactorización para extraer el valor en la sección Parameters y reemplazar el literal por !Ref para el nuevo parámetro. Si el mismo valor literal aparece en diversos lugares, puede optar por extraer todas las apariciones a la vez.

El kit de herramientas también proporciona un flujo de trabajo en línea para agregar los recursos de AWS existentes a la plantilla. Este flujo de trabajo requiere credenciales de AWS válidas y utiliza API de control de nube de AWS (CCAPI) para recuperar la configuración y las propiedades activas de un recurso, lo que permite clonar o reutilizar la infraestructura existente en su plantilla.

Adición de recursos a una plantilla

  • Agregue un tipo de recurso: En el panel de CloudFormation de Kit de herramientas de AWS, en Recursos, agregue un tipo de recurso para consultarlo. En VS Code, haga clic en el icono Agregar + o utilice el comando AWS CloudFormation: Agregar tipos de recursos de la paleta de comandos. En JetBrains, haga clic en el botón Agregar tipo de recurso de la barra de herramientas o haga clic derecho en el nodo de Recursos.

  • Busque un tipo de recurso: En el cuadro de diálogo de búsqueda, escriba el tipo de recurso de AWS que desee agregar. Ejemplo:

    • AWS::S3::Bucket

    • AWS::Lambda::Function

  • Explore los recursos: En la sección Recursos, se muestra una lista paginada de los recursos de AWS detectados en su cuenta. Si tiene muchos recursos, solo se muestra la primera página. Use los controles de navegación para desplazarse por páginas adicionales y ver todos los recursos disponibles.

  • Elija el recurso que desea incluir en la plantilla.

  • Puede insertar un recurso en la plantilla en dos formas, en función de su objetivo:

    • Clonar un recurso existente: para crear un recurso nuevo en su plantilla, utilice la configuración activa y las propiedades de un recurso de AWS existente.

    • Importar un recurso existente: para insertar el recurso real en su pila, añádalo a su plantilla utilizando su estado activo.

Consejos

  • Puede actualizar la sección Recursos en cualquier momento para ver la lista más reciente de recursos disponibles en su cuenta o región.

  • Si va a importar recursos, no añada un recurso que ya pertenezca a una pila de CloudFormation existente en la misma cuenta.

  • Para confirmar si CloudFormation ya administra un recurso, utilice la acción de información disponible junto al recurso. En VS Code, haga clic en el icono i. En los IDE de JetBrains, haga clic derecho en el recurso y seleccione Obtener información de administración de la pila.

En VS Code, ejecute el comando AWS CloudFormation: Agregar recursos relacionados por tipo desde la paleta de comandos. Seleccione un tipo de recurso de entre los ya definidos en su plantilla. El IDE muestra los tipos de recursos a los que el tipo seleccionado puede hacer referencia a través de sus propiedades. Por ejemplo, si selecciona un AWS::EC2::Instance, el IDE puede sugerirle AWS::EC2::SecurityGroup o AWS::EC2::Subnet. Seleccione uno o más tipos de recursos relacionados y, a continuación, elija si desea crear nuevas definiciones de recursos o importar los recursos existentes. Esta característica no se admite actualmente en los IDE de JetBrains.

Validación estática

El servidor de lenguaje de CloudFormation proporciona una validación estática integrada basada en CloudFormation Linter y CloudFormation Guard. Estas comprobaciones se realizan localmente en segundo plano y no requieren credenciales de AWS. Le ayudan a identificar errores de sintaxis, incumplimientos y problemas con las prácticas recomendadas antes de la implementación.

Descripción general de la validación estática

Verá dos tipos de validaciones estáticas en tiempo real en el IDE:

  • CloudFormation Linter (cfn-lint): valida la plantilla según las especificaciones de recursos y las reglas del esquema de CloudFormation.

  • Guard (cfn-guard): valida la plantilla según las normas de cumplimiento y los paquetes de políticas organizacionales.

CloudFormation Linter (cfn-lint)

CloudFormation Linter está integrado en el IDE para comprobar automáticamente la sintaxis y la estructura de la plantilla a medida que escribe.

  • Validación de esquemas: detecta errores de sintaxis y esquema para garantizar que las plantillas se ajusten al esquema de recursos de CloudFormation.

  • Resaltado de error: muestra marcadores en línea debajo de los problemas, que representan advertencias o bloqueos de implementación.

  • Pase el cursor sobre la ayuda: al pasar el cursor por encima de un error, el IDE muestra el mensaje de diagnóstico asociado a ese problema. También estará disponible una solución rápida, de haber alguna.

Integración de CI/CD

Guard valida sus plantillas comparándolas con los conjuntos de reglas que definen las políticas de cumplimiento y seguridad. El IDE ejecuta las validaciones de Guard en tiempo real a través del servidor de lenguaje de CloudFormation, lo que le proporciona comentarios inmediatos mientras crea plantillas.

  • Paquetes de reglas predeterminados: el IDE incluye un conjunto de reglas de Guard previamente registradas que se centran en las prácticas recomendadas fundamentales para la seguridad de los recursos y la higiene de la configuración. Para obtener más información, consulte el registro de reglas de Guard.

  • Cómo agregar paquetes de reglas: para agregar o modificar conjuntos de reglas, abra los ajustes de su IDE y diríjase a la sección de configuración de Guard para seleccionar o cargar paquetes de reglas de Guard adicionales.

Consejos: Comprensión de los indicadores de diagnóstico

  • Indicadores azules: sugerencias de prácticas recomendadas o recomendaciones de optimización.

  • Indicadores amarillos: advertencias sobre problemas no relacionados con el bloqueo (por ejemplo, falta de etiquetas o parámetros).

  • Indicadores rojos: bloquean la implementación, como nombres de propiedades no válidos, campos obligatorios que faltan o discordancias en los esquemas.

Paso 4: navegar por la plantilla

El IDE ofrece una vista jerárquica y estructurada de la plantilla de CloudFormation, organizada en secciones como Parameters, Resources, Outputs y Mappings que muestran cada tipo de recurso e ID lógico. Esto facilita la búsqueda rápida de recursos o parámetros específicos dentro de plantillas grandes y la navegación a ellos. En VS Code, el panel Esquema de la barra lateral del Explorador muestra esta estructura. En los IDE de JetBrains, abra la ventana de herramientas Estructura para ver la estructura de la plantilla del archivo que está abierto.

Puede utilizar Ir a la definición para funciones intrínsecas, como GetAtt y Ref, que le permite ir directamente al recurso o parámetro al que se hace referencia en la plantilla. Esto le ayuda a rastrear las dependencias, comprender las relaciones entre los recursos y realizar modificaciones de manera más eficiente.

Paso 5: validar e implementar

Validar e implementar es un flujo de trabajo en línea que llama al servicio CloudFormation y requiere credenciales válidas de AWS. Cuando tenga todo listo para implementar la plantilla, utilice esta característica para crear un conjunto de cambios. El IDE valida la plantilla y, si no se encuentra ningún error de bloqueo, crea un conjunto de cambios con reconocimiento de desviación. Luego, el IDE muestra una vista de diferencias para que pueda revisar todos los cambios propuestos antes de ejecutar el conjunto de cambios.

En VS Code, abra la paleta de comandos y ejecute AWS CloudFormation: Validar e implementar. La paleta de comandos permite seleccionar una plantilla, el nombre de la pila, los parámetros, las capacidades y otras opciones de implementación. En los IDE de JetBrains, utilice el botón de la barra de herramientas Validar e implementar, haga clic derecho en un archivo de plantilla del editor o en una pila del árbol. JetBrains presenta un cuadro de diálogo con un asistente en el que se pueden configurar todas las opciones de implementación, entre ellas la selección de plantillas, el nombre de la pila, los parámetros, las capacidades, las etiquetas y las opciones avanzadas.

Cómo funciona la validación

El IDE realiza automáticamente una comprobación de validación antes de la implementación y valida la plantilla en función de las causas de error más comunes, entre las que se incluyen las siguientes:

  • Discordancias entre esquemas o sintaxis de propiedades no válidas: estos problemas suele detectarlos cfn-lint durante la creación, pero si continúa con la implementación sin solucionarlos, la validación de CloudFormation en el momento de la implementación mostrará los mismos errores antes de que se cree o actualice la pila.

  • El nombre del recurso entra en conflicto con los recursos existentes en su cuenta.

  • Restricciones específicas del servicio, como conflictos en el nombre del bucket de S3 o falta de cifrado.

Si la validación detecta errores, el IDE resalta los problemas directamente en la plantilla y enumera los errores en el panel de diagnóstico. Cada problema incluye la propiedad o el recurso específico que causó el error, junto con una sugerencia de solución. Si no hay errores de bloqueo, puede pasar a la fase de implementación.

Si se encuentran advertencias (problemas no relacionados con el bloqueo), aparece un cuadro de diálogo que le permite continuar con la implementación o cancelar y realizar las correcciones necesarias.

El IDE abre un conjunto de cambios con reconocimiento de desviación en el que se muestran las diferencias entre la plantilla actual y la configuración de la pila implementada. Esto le permite revisar, confirmar o cancelar el conjunto de cambios antes de su ejecución. Si se cancela la implementación, se elimina el conjunto de cambios.

Los conjuntos de cambios con reconocimiento de desviación mejoran el proceso de implementación de CloudFormation al permitirle gestionar la desviación de la pila de forma segura. La desviación de la pila se produce cuando el estado real de los recursos difiere del definido en la plantilla de CloudFormation, a menudo debido a cambios manuales realizados mediante la Consola de administración de AWS, la CLI o el SDK. Los conjuntos de cambios con reconocimiento de desviación de CloudFormation compara la configuración de la pila procesada con el estado actual de los recursos, y el IDE muestra estas diferencias para que pueda hacer que los recursos vuelvan a cumplir con las normas antes de la implementación.

Visualización de eventos de pilas

Cuando comience la implementación, puede supervisar el progreso en tiempo real desde el panel de CloudFormation. En Eventos de la pila, verá una lista de las operaciones realizadas durante la implementación. Cada evento incluye detalles como:

  • Marca temporal: la hora en que ocurrió el evento.

  • Recurso: el recurso de AWS específico que se crea, actualiza o elimina

  • Estado: el estado actual de la operación (por ejemplo, CREATE_IN_PROGRESS, UPDATE_COMPLETE o ROLLBACK_IN_PROGRESS)

  • Motivo: mensajes de contexto o de error adicionales, si corresponde

También puede ver los recursos y las salidas de la pila desde este panel. La vista Eventos de la pila le ayuda a realizar un seguimiento del progreso de la implementación, identificar posibles problemas y confirmar si la pila se ha completado correctamente.

Inicialización de un proyecto de CloudFormation en el IDE (solo VS Code)

La inicialización de un proyecto de CloudFormation en el IDE le ayuda a configurar un espacio de trabajo estructurado con las carpetas y la configuración del entorno correctas para la validación del lado del servicio y la implementación. Estos flujos de trabajo en línea requieren credenciales de AWS, pero las funciones de creación local y validación estática del servidor de lenguaje no. Puede inicializar un nuevo proyecto de CloudFormation directamente desde el IDE para crear la configuración recomendada. Esta característica solo está disponible en VS Code y no es compatible con los IDE de JetBrains.

Para inicializar un proyecto de CloudFormation:

  • Abra la paleta de comandos

    • Desde VS Code, abra la paleta de comandos (Ctrl+Shift+P o Cmd+Shift+P en macOS).

    • Elija AWS CloudFormation: CFN Init: inicializar proyecto.

  • Elija un directorio de proyectos

    • El IDE utiliza su directorio de trabajo actual de forma predeterminada.

    • Puede cambiar esta ruta a cualquier carpeta en la que desea almacenar las plantillas de CloudFormation.

  • Seleccione su perfil de credenciales de AWS

    • Se le pedirá que elija un perfil de credencial de AWS. El perfil seleccionado se utiliza para la detección del entorno, la validación del lado del servicio y la implementación.

  • Configure el entorno

    • Se le pedirá que cree o seleccione un entorno.

    • Los entornos definen dónde y cómo se implementan o validan las plantillas (por ejemplo, desarrollo, versión beta o producción). Puede usar AWS CloudFormation: CFN Init: añadir entorno para seleccionar o cambiar su entorno.

    • Puede usar AWS CloudFormation: CFN Init: eliminar entorno para eliminar el entorno que ha seleccionado.

  • (Opcional) Importe archivos de parámetros

    • Si ya tiene archivos de parámetros existentes, el IDE le permite importarlos durante la inicialización.

    • El IDE detecta automáticamente los archivos compatibles y los vincula a su proyecto para utilizarlos en la validación y la implementación de la plantilla.

  • Asigne un nombre al proyecto y finalícelo

    • Proporcione un nombre de proyecto, como un entorno beta, y complete la configuración.

    • El IDE crea automáticamente la estructura inicial del proyecto y el archivo de configuración.

Puede ejecutar validaciones, previsualizar las implementaciones o cambiar de un entorno a otro directamente desde el IDE.

Código abierto

El servidor de lenguaje de CloudFormation es de código abierto bajo la licencia Apache-2.0, lo que brinda a los clientes total transparencia sobre cómo se realizan el diagnóstico de las plantillas, la validación de esquemas y el análisis estático. Esto reduce los problemas de seguridad y cumplimiento para los clientes que requieren visibilidad a nivel de origen antes de adoptar las herramientas.

La base de código está disponible públicamente en GitHub: https://github.com/aws-cloudformation/cloudformation-languageserver/.

¿Necesita ayuda?

Pruebe la comunidad de CloudFormation en AWS re:Post.