View a markdown version of this page

Validación de plantillas con cfn-lint - AWS CloudFormation

Validación de plantillas con cfn-lint

AWS CloudFormation Linter (cfn-lint) compara las plantillas JSON y YAML con los esquemas de proveedores de recursos de CloudFormation y reglas adicionales. Puede encontrar propiedades de recursos no válidas, valores de propiedad no admitidos, referencias rotas y problemas comunes de prácticas recomendadas. Úselo para detectar estos problemas antes de enviar una plantilla a CloudFormation. Si una plantilla usa la transformación de AWS Serverless Application Model (AWS SAM), cfn-lint aplica la transformación antes de comprobar la plantilla.

Para ver las notas de la versión, la lista completa de reglas y todas las opciones de comando, consulte cfn-lint en GitHub.

Para conocer las limitaciones de la validación local y los pasos a seguir antes de la implementación, consulte Descripción del alcance de validación.

Instalar cfn-lint

Instale cfn-lint desde el Índice de paquetes de Python (PyPI):

python3 -m pip install cfn-lint

En macOS, puede instalarlo con Homebrew:

brew install cfn-lint

Para confirmar la instalación, imprima la versión instalada:

cfn-lint --version

Para ver una imagen de Docker y otros métodos de instalación, consulte las instrucciones de instalación en GitHub.

Ejecuta cfn-lint

Pase una o más rutas de plantilla al comando:

cfn-lint template.yaml cfn-lint template-one.yaml template-two.json

También puede utilizar comodines para comprobar todas las plantillas de un directorio. Utilice ** para incluir subdirectorios:

cfn-lint templates/*.yaml cfn-lint templates/**/*.yaml
nota

En bash, ejecute shopt -s globstar antes de usar ** para que coincida con los subdirectorios. En zsh, ** coincide con los subdirectorios de forma predeterminada.

Para leer una plantilla a partir de una entrada estándar, pase - como ruta de la plantilla:

cat template.yaml | cfn-lint -

De forma predeterminada, cfn-lint compara las plantillas con los esquemas de us-east-1. Para comprobar las plantillas para otras Regiones de AWS, utilice la opción --regions. Como esta opción acepta varios valores, agregue -- antes de la ruta de la plantilla o utilice -t para identificar la plantilla:

cfn-lint --regions us-east-1 us-west-2 -- template.yaml cfn-lint --regions us-east-1 us-west-2 -t template.yaml

Algunas comprobaciones dependen de los valores de los parámetros. Para comprobar una plantilla con valores específicos, páselos con --parameters o proporcione un archivo de parámetros con --parameter-files:

cfn-lint --parameters InstanceType=t3.micro Environment=prod -- template.yaml cfn-lint --parameter-files params.json -- template.yaml

Para enumerar todas las reglas que cfn-lint puede aplicar, ejecute el siguiente comando:

cfn-lint --list-rules

Comprender los resultados

Para cada resultado, cfn-lint imprime el ID de la regla, un mensaje y el archivo, la línea y la columna del problema. Para ver la lista completa de reglas y lo que comprueba cada una, consulte las reglas de cfn-lint en GitHub.

Para cambiar el formato de salida, utilice --format con quiet, parseable, json, junit, pretty o sarif:

cfn-lint --format json template.yaml

cfn-lint devuelve el código de salida 0 cuando no encuentra ningún problema y, en caso contrario, devuelve un código de salida distinto de cero. Para controlar qué resultados provocan un código de salida distinto de cero, utilice --non-zero-exit-code. Puede usar el código de salida para detener una compilación automática cuando una plantilla no pase las comprobaciones seleccionadas.

Configuración de comprobaciones

Puede configurar cfn-lint con opciones de línea de comandos, un archivo de configuración o metadatos en la plantilla. Cuando la misma configuración aparece en más de un lugar, las opciones de la línea de comandos anulan los metadatos de la plantilla y los metadatos de la plantilla anulan el archivo de configuración.

Seleccionar y configurar reglas

Para omitir reglas, utilice --ignore-checks con uno o más ID de regla o prefijos de ID de regla. Para ejecutar reglas que están desactivadas de forma predeterminada, utilice --include-checks. Para ejecutar una regla incluso cuando coincida con una configuración que implique ignorar, utilice --mandatory-checks.

cfn-lint --ignore-checks RULE_ID -- template.yaml

Algunas reglas aceptan ajustes. Use --configure-rule con el formato RULE_ID:key=value:

cfn-lint --configure-rule RULE_ID:key=value -- template.yaml

Usar un archivo de configuración

Para mantener la configuración con las plantillas, cree un archivo .cfnlintrc, .cfnlintrc.yaml o .cfnlintrc.yml en el directorio en el que se ejecuta cfn-lint. También puede crear un archivo ~/.cfnlintrc en su directorio principal para que los ajustes se apliquen en todas partes. En el siguiente ejemplo, se seleccionan las plantillas que se van a comprobar, se omite una plantilla, se establecen las regiones y se omite una regla:

templates: - templates/**/*.yaml ignore_templates: - templates/legacy.yaml regions: - us-east-1 - us-west-2 ignore_checks: - RULE_ID

Cuando el archivo de configuración selecciona plantillas, puede ejecutar cfn-lint sin argumentos para comprobarlas todas. Para todas las configuraciones, consulte el archivo de configuración en GitHub.

Configurar comprobaciones en la plantilla

Para configurar cfn-lint para una plantilla, agregue una clave cfn-lint a la sección Metadata de nivel superior:

Metadata: cfn-lint: config: regions: - us-east-1 - us-east-2 ignore_checks: - RULE_ID

Para omitir una regla para un solo recurso, agregue la misma clave al atributo Metadata de ese recurso. En el siguiente ejemplo, se omite una regla solo para una instancia:

Resources: MyInstance: Type: AWS::EC2::Instance Metadata: cfn-lint: config: ignore_checks: - RULE_ID Properties: InstanceType: t3.micro ImageId: ami-abc1234

Adición de reglas personalizadas

Puede agregar sus propias comprobaciones sin necesidad de escribir Python. Un archivo de reglas personalizado contiene una regla por línea con el siguiente formato:

ResourceType Property Operator Value [ErrorLevel] [Message]

Por ejemplo, la siguiente regla en custom_rules.txt muestra una advertencia cuando una plantilla utiliza un tipo de instancia caro:

AWS::EC2::Instance InstanceType NOT_EQUALS "m4.16xlarge" WARN "This is an expensive instance type, don't use it"

Pase el archivo con --custom-rules (o -z) o agregue un ajuste custom_rules a su archivo de configuración:

cfn-lint --custom-rules custom_rules.txt -- template.yaml

Para conocer los operadores compatibles, consulte Reglas personalizadas en GitHub. Para comprobaciones más complejas, puede escribir reglas en Python y cargarlas con --append-rules. Para cambiar lo que cfn-lint considera válido, como requerir etiquetas específicas, puede proporcionar un archivo de anulación de especificaciones con --override-spec. Para más información, consulte Introducción a las reglas y Personalizar las especificaciones en GitHub.

Agregue cfn-lint a su flujo de trabajo.

Puede ejecutar cfn-lint en los siguientes lugares:

  • En su editor: el servidor de lenguaje de CloudFormation usa cfn-lint para mostrar los problemas mientras usted escribe. Para obtener información sobre la configuración, consulte Servidor de lenguaje de CloudFormation. Los complementos también están disponibles para otros editores, como Vim, Emacs y Sublime Text.

  • Antes de una confirmación de Git: agregue cfn-lint a su archivo .pre-commit-config.yaml para que se ejecute en las plantillas modificadas antes de cada confirmación. Reemplace el valor de rev por la versión que desee utilizar.

    repos: - repo: https://github.com/aws-cloudformation/cfn-lint rev: v1.56.0 hooks: - id: cfn-lint files: templates/.*\.(json|yml|yaml)$
  • En una compilación automática: ejecute cfn-lint como un paso de compilación y use el código de salida para que la compilación falle. También está disponible una GitHub Action para cfn-lint.

  • En su propio código Python: importe cfnlint.api y llame a lint o lint_all para comprobar una cadena de plantilla y procesar los resultados en su aplicación.

    from cfnlint.api import lint, ManualArgs with open("template.yaml") as f: template = f.read() matches = lint(template, config=ManualArgs(regions=["us-east-1"])) for match in matches: print(match)

Para ver los complementos del editor, la GitHub Action y más ejemplos de integración, consulte cfn-lint en GitHub.