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
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.
Temas
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
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
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
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-checksRULE_ID-- template.yaml
Algunas reglas aceptan ajustes. Use --configure-rule con el formato :RULE_ID:key=value
cfn-lint --configure-ruleRULE_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
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_IDProperties: 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:
ResourceTypePropertyOperatorValue[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--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
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-lintpara 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-linta su archivo.pre-commit-config.yamlpara que se ejecute en las plantillas modificadas antes de cada confirmación. Reemplace el valor derevpor 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-lintcomo 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 paracfn-lint. -
En su propio código Python: importe
cfnlint.apiy llame alintolint_allpara 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