Validación de plantillas con cloudformation-validate
AWS CloudFormation Validate (cloudformation-validate) le ayuda a encontrar problemas con las plantillas antes de la implementación. Comprueba las plantillas JSON y YAML localmente para detectar estructuras de plantilla no válidas, referencias rotas, problemas de seguridad y problemas relacionados con las prácticas recomendadas. Cada resultado incluye un identificador de regla estable, una gravedad, la línea y la columna de la plantilla, el recurso afectado y, si está disponible, una sugerencia de cómo solucionarlo.
La herramienta incluye las reglas y los esquemas de recursos de CloudFormation que necesita. Como resultado, se ejecuta sin acceso a la red ni credenciales de AWS después de la instalación. La validación de una plantilla típica se completa en menos de un segundo. Puede ejecutarlo desde la línea de comandos o incrustarlo en una aplicación Rust, Node.js, Python, Go o JVM. También puede dejar que AWS CDK lo ejecute después de la síntesis. Todos estos métodos producen los mismos resultados.
Para ver las notas de la versión y la lista completa de reglas integradas, consulte cloudformation-validate
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
Cómo funciona la validación
Cuando valida una plantilla, cloudformation-validate resuelve funciones intrínsecas como Ref, Fn::GetAtt, Fn::Sub y Fn::If, y luego ejecuta las siguientes comprobaciones:
-
Comprobaciones de esquemas: compara cada recurso con los esquemas del proveedor de recursos de CloudFormation e informa de las discrepancias de tipos, la falta de propiedades obligatorias, los valores de enumeración no válidos y los errores de patrones o restricciones.
-
Reglas: ejecuta las reglas integradas y cualquier regla personalizada que usted proporcione. Estas reglas detectan errores semánticos, referencias incorrectas entre recursos, riesgos de seguridad y problemas relacionados con las prácticas recomendadas.
-
Comprobaciones de máquinas de estado: valida las definiciones de recursos
AWS::StepFunctions::StateMachine, incluidos los tipos de estado, las referenciasStartAtyNext, y los campos obligatorios.
Seleccione un método de validación.
-
Línea de comandos: ejecute
cfn-validatepara comprobar una plantilla o todas las plantillas de un directorio desde una terminal o una compilación automática. Consulte Instalación de la herramienta de línea de comandos. -
Biblioteca: agregue el validador a una aplicación de Rust, Node.js, Python, Go o JVM y procese los resultados en su código. Consulte Inserción de la biblioteca de validación.
-
AWS CDK: valide las plantillas automáticamente después de que AWS CDK las sintetice. Consulte Use con AWS CDK.
Con cualquier método, puede agregar reglas personalizadas escritas en Common Expression Language (CEL), Rego o el lenguaje de reglas Guard. Consulte Adición de reglas personalizadas.
Instalación de la herramienta de línea de comandos
El comando cfn-validate es un archivo único sin dependencias. Abra la última versión
En Linux o macOS, haga que el archivo sea ejecutable, cámbiele el nombre a cfn-validate y muévalo a un directorio de su PATH. En el siguiente ejemplo se utiliza el archivo Linux x86-64. Reemplace VERSION por la versión que haya descargado.
chmod +x cfn-validate-VERSION-linux-x64 sudo mv cfn-validate-VERSION-linux-x64 /usr/local/bin/cfn-validate
En Windows, cambie el nombre del archivo a cfn-validate.exe y muévalo a un directorio de su PATH.
Cada versión también incluye un archivo de firma para cada descarga y la clave pública utilizada para firmarla. Para verificar una descarga antes de usarla, consulte Verificar un activo de versión descargado
Ejecución de la validación
El comando utiliza la siguiente sintaxis:
cfn-validateTEMPLATE_OR_DIRECTORY[OPTIONS]
Compruebe una plantilla:
cfn-validate template.yaml
Pase un directorio para comprobar de forma recursiva todos los archivos .yaml, .yml y .json:
cfn-validate ./templates/
Algunas comprobaciones dependen de la Región de AWS o de los valores de los parámetros. Se utiliza --region para configurar el pseudoparámetro AWS::Region, --parameter para establecer un parámetro de plantilla y --pseudo-parameter para establecer otros pseudoparámetros, como AWS::AccountId o AWS::Partition. Puede repetir --parameter y --pseudo-parameter:
cfn-validate template.yaml --region us-west-2 --parameter Environment=prod --parameter InstanceType=t3.micro
Para tratar las advertencias como errores, por ejemplo, en una compilación automatizada, agregue --strict. Para enumerar todas las reglas integradas, ejecute cfn-validate
--list-rules.
Comprender los resultados
El comando escribe un informe JSON en la salida estándar. Cada resultado del informe incluye el identificador de la regla, la gravedad, el mensaje, la ubicación de origen (línea y columna), el recurso u otra entidad de la plantilla, y una sugerencia de corrección cuando esté disponible. El informe predeterminado --format detailed también incluye la descripción de la regla y el contexto relacionado. Utilice --format standard para obtener un informe compacto que omita esos campos.
Para limitar el informe a resultados más graves, utilice --level con la gravedad mínima para incluir:
cfn-validate template.yaml --level error
El comando devuelve el código de salida 0 cuando no encuentra ningún error, 1 cuando encuentra errores y 2 para un error de uso o de inicialización, como una opción no válida o un archivo que no existe. Con --strict, las advertencias también provocan un código de salida 1.
Filtrar los resultados
Puede incluir o excluir los resultados por ID de regla, rango de ID de regla, categoría, tipo de recurso, prefijo de servicio o ID lógico de una entidad de plantilla. Cada filtro tiene un formulario --include- y un formulario --exclude-. En los siguientes ejemplos se muestran filtros comunes:
# Suppress specific rules everywhere cfn-validate template.yaml --exclude-idsRULE_ID,RULE_ID# Report only security findings cfn-validate template.yaml --include-categories Security # Suppress one rule for one resource only cfn-validate template.yaml --exclude-logical-id MyBucket=RULE_ID# Suppress every rule for a resource type cfn-validate template.yaml --exclude-resource-type AWS::EC2::Instance # Suppress every rule for a service cfn-validate template.yaml --exclude-service AWS::AutoScaling
Los filtros que se dirigen a un tipo de recurso, servicio o ID lógico aceptan un sufijo = opcional para limitar el filtro a una sola regla. Sin el sufijo, el filtro se aplica a todas las reglas de ese objetivo. Para ver todas las opciones de filtro, consulte la referencia de la CLI de RULE_IDcfn-validate
Adición de reglas personalizadas
Puede agregar sus propias comprobaciones en cualquiera de los siguientes formatos. Cada formato asume una familiaridad básica con el lenguaje de sus reglas. De forma predeterminada, las reglas personalizadas se ejecutan además de las reglas integradas. Para ejecutar solo sus reglas personalizadas, agregue --disable-builtin-rules.
-
CEL (
.json): comprobaciones basadas en propiedades y datos escritas como expresiones CELen un archivo JSON. Cargue con --rule-source. -
Rego (
.rego): lógica compleja de recursos cruzados escrita en el lenguaje de políticas de Rego. Cargue con --rule-source. -
Guard (
.guard): reglas de cumplimiento declarativas en el lenguaje de reglas de Guard. Cargue un archivo o directorio con--guard-rule-source. El validador admite un subconjunto del lenguaje Guard. Si una regla usa un constructo no compatible, el validador rechaza la regla cuando se carga en lugar de ignorar el constructo. Para obtener información sobre la sintaxis de la regla, consulte Validación de plantillas con Guard.
Puede repetir cualquiera de las dos opciones para cargar varios orígenes de reglas:
cfn-validate template.yaml --rule-source ./rules/checks.json --rule-source ./rules/network.rego cfn-validate template.yaml --guard-rule-source ./guard-rules/
El siguiente ejemplo de CEL en checks.json informa de un resultado para cada bucket de Amazon S3 sin cifrado. El campo resource_type hace que la regla se ejecute una vez para cada recurso de ese tipo y {name} en el mensaje se sustituye por el ID lógico del recurso.
{ "rules": [ { "rule_id": "CUSTOM001", "severity": "ERROR", "resource_type": "AWS::S3::Bucket", "expression": "!has(properties.BucketEncryption)", "message": "S3 bucket {name} must have encryption configured", "prop_path": "Properties.BucketEncryption", "suggested_fix": "Add BucketEncryption with SSEAlgorithm: aws:kms" } ] }
Para más información sobre los datos disponibles para las reglas, las funciones de CEL compatibles y la escritura de reglas de Rego, consulte la Referencia de reglas personalizadas
Valide nuevos tipos y propiedades de recursos
Los esquemas agrupados coinciden con el registro de CloudFormation en el momento de la publicación. Si una plantilla usa un tipo de recurso, una propiedad o un valor permitido que CloudFormation publicó después de esa versión, o un tipo de recurso privado de su propio registro, pase el esquema del proveedor de recursos con --additional-schema. El validador lo usa para ampliar el esquema agrupado para un tipo existente o para validar un tipo nuevo. Puede pasar un archivo .json o un directorio de archivos de esquema y repetir la opción:
cfn-validate template.yaml --additional-schema ./schemas/
Un esquema adicional nunca elimina una restricción del esquema agrupado. Si un esquema no se puede leer ni aplicar, el comando se cierra con el código 2 en lugar de ignorarlo.
Inserción de la biblioteca de validación
Instale el paquete para su lenguaje de programación, a fin de ejecutar las mismas comprobaciones sin conexión desde su aplicación. Cree un motor de validación una vez, reutilícelo para varias plantillas y procese los diagnósticos estructurados devueltos para cada plantilla. También puede configurar reglas CEL, Rego o Guard personalizadas y esquemas adicionales a través de la API de la biblioteca.
| Idioma | Paquete | Instalación | Documentación |
|---|---|---|---|
| Rust | cloudformation-validate |
cargo add cloudformation-validate |
API y ejemplos |
| Node.js | @aws/cloudformation-validate |
npm install @aws/cloudformation-validate |
API y ejemplos |
| Python | cloudformation-validate |
python3 -m pip install cloudformation-validate |
API y ejemplos |
| Go | cloudformation-validate/src/bindings-go/go |
go get github.com/aws-cloudformation/cloudformation-validate/src/bindings-go/go@latest |
API y ejemplos |
| JVM (Java o Kotlin) | software.amazon.cloudformation:cloudformation-validate |
implementation("software.amazon.cloudformation:cloudformation-validate: (Gradle) o la dependencia equivalente de Maven |
API y ejemplos |
Cada biblioteca expone un método que valida una plantilla y devuelve un informe con los mismos diagnósticos que la herramienta de línea de comandos. En los ejemplos siguientes se utiliza CompositeEngine, el motor predeterminado, que ejecuta las reglas integradas y cualquier regla personalizada de CEL, Rego o Guard que se configure. Cada ejemplo valida una plantilla e imprime cada resultado.
Python:
from cloudformation_validate import CompositeEngine engine = CompositeEngine() report = engine.validate_template("template.yaml") for d in report.diagnostics: print(f"[{d.severity.name}] {d.rule_id}: {d.message}")
Kotlin:
import software.amazon.cloudformation.validate.CompositeEngine import java.io.File fun main() { val engine = CompositeEngine() val report = engine.validateTemplate(File("template.yaml")) for (d in report.diagnostics) { println("[${d.severity}] ${d.ruleId}: ${d.message}") } }
Para conocer los tiempos de ejecución de lenguajes compatibles, la fijación de versiones, los canales de versiones preliminares y la sintaxis de Maven y Gradle, consulte la guía de instalación de enlaces de lenguajes
Use con AWS CDK
Si utiliza AWS CDK, no necesita instalar el validador por separado. La biblioteca de construcciones de AWS CDK incluye un valor predeterminado CloudFormationValidatePlugin que ejecuta automáticamente las mismas comprobaciones después de sintetizar las plantillas de CloudFormation.
cdk synth
AWS CDK informa de los posibles errores de implementación y de los resultados de prácticas recomendadas junto con sus resultados de validación. Puede configurar de forma explícita CloudFormationValidatePlugin cuando quiera agregar reglas Rego o Guard personalizadas.
Para obtener información sobre la configuración de los complementos, las confirmaciones y los informes de validación, consulte Template and Policy Validation en la Referencia de la API de AWS CDK.