View a markdown version of this page

Convalida i modelli con cloudformation-validate - AWS CloudFormation

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Convalida i modelli con cloudformation-validate

AWS CloudFormation Validate (cloudformation-validate) consente di individuare i problemi relativi ai modelli prima della distribuzione. Controlla localmente i modelli JSON e YAML per individuare la struttura dei modelli non valida, i riferimenti non funzionanti, i problemi di sicurezza e i problemi relativi alle best practice. Ogni risultato include un ID di regola stabile, una gravità, la riga e la colonna del modello, la risorsa interessata e, se disponibile, una correzione suggerita.

Lo strumento include le regole e gli schemi di CloudFormation risorse di cui ha bisogno. Di conseguenza, viene eseguito senza accesso alla rete o AWS credenziali dopo l'installazione. La convalida di un modello tipico viene completata in meno di un secondo. Puoi eseguirlo dalla riga di comando o incorporarlo in un'applicazione Rust, Python Node.js, Go o JVM. Puoi anche lasciarlo AWS CDK eseguire dopo la sintesi. Tutti questi metodi producono gli stessi risultati.

Per le note di rilascio e l'elenco completo delle regole integrate, vedi cloudformation-validatesu GitHub.

Per i limiti della convalida locale e le procedure da eseguire prima della distribuzione, consultaComprendi l'ambito della convalida.

Come funziona la convalida

Quando si convalida un modello, cloudformation-validate risolve funzioni intrinseche comeRef, Fn::GetAtt Fn::SubFn::If, e quindi esegue i seguenti controlli:

  • Controlli dello schema: confronta ogni risorsa con gli schemi del provider di risorse e segnala le CloudFormation mancate corrispondenze dei tipi, le proprietà obbligatorie mancanti, i valori di enumerazione non validi e gli errori di pattern o vincoli.

  • Regole: esegue le regole integrate e tutte le regole personalizzate fornite dall'utente. Queste regole rilevano errori semantici, riferimenti interrotti tra risorse, rischi per la sicurezza e problemi relativi alle best practice.

  • Controlli automatici a stato: convalida le definizioni delle AWS::StepFunctions::StateMachine risorse, inclusi i tipi di stato, i Next riferimenti StartAt e i campi obbligatori.

Scegliete un metodo di convalida

Con qualsiasi metodo, puoi aggiungere regole personalizzate scritte in Common Expression Language (CEL), Rego o il linguaggio di regole Guard. Consulta Aggiungi regole personalizzate.

Installa lo strumento da riga di comando

Il cfn-validate comando è un singolo file senza dipendenze. Apri la versione più recente GitHub e scarica il file per il tuo sistema operativo e processore. I file sono disponibili per Linux (x86-64 e ARM64), macOS (Apple silicon e Intel) e Windows (x86-64 e ARM64).

Su Linux omacOS, rendi eseguibile il file, rinominalo in e spostalo in una directory del tuo. cfn-validate PATH L'esempio seguente utilizza il file Linux x86-64. VERSIONSostituiscilo con la versione che hai scaricato.

chmod +x cfn-validate-VERSION-linux-x64 sudo mv cfn-validate-VERSION-linux-x64 /usr/local/bin/cfn-validate

In Windows, rinomina il file in cfn-validate.exe e spostalo in una directory sul tuoPATH.

Ogni versione include anche un file di firma per ogni download e la chiave pubblica utilizzata per firmarlo. Per verificare un download prima di utilizzarlo, consulta Verificare una risorsa di rilascio scaricata su GitHub.

Esegui la convalida

Il comando utilizza la seguente sintassi:

cfn-validate TEMPLATE_OR_DIRECTORY [OPTIONS]

Seleziona un modello:

cfn-validate template.yaml

Passa una directory per controllare ricorsivamente ogni file .yaml.yml, e.json:

cfn-validate ./templates/

Alcuni controlli dipendono dal Regione AWS o dai valori dei parametri. Si usa --region per impostare lo AWS::Region pseudo parametro, --parameter per impostare un parametro modello e --pseudo-parameter per impostare altri pseudo parametri come o. AWS::AccountId AWS::Partition Puoi ripetere e: --parameter --pseudo-parameter

cfn-validate template.yaml --region us-west-2 --parameter Environment=prod --parameter InstanceType=t3.micro

Per trattare gli avvisi come errori, ad esempio in una build automatizzata, aggiungi--strict. Per elencare tutte le regole integrate, cfn-validate --list-rules esegui.

Comprendi i risultati

Il comando scrive un report JSON sullo standard output. Ogni risultato del rapporto include l'ID della regola, la gravità, il messaggio, la posizione di origine (riga e colonna), la risorsa o altra entità modello e una correzione suggerita, se disponibile. Il --format detailed rapporto predefinito include anche la descrizione della regola e il relativo contesto. --format standardUtilizzalo per un report compatto che omette tali campi.

Per limitare il rapporto a risultati più gravi, utilizzalo --level con la gravità minima per includere:

cfn-validate template.yaml --level error

Il comando restituisce il codice di uscita 0 quando non trova errori, 1 quando trova errori e 2 per un errore di utilizzo o di inizializzazione, ad esempio un'opzione non valida o un file che non esiste. Con--strict, gli avvisi causano anche il codice di uscita. 1

Filtra i risultati

È possibile includere o escludere i risultati in base all'ID della regola, all'intervallo di ID della regola, alla categoria, al tipo di risorsa, al prefisso del servizio o all'ID logico di un'entità modello. Ogni filtro ha una --exclude- forma --include- e una. Gli esempi seguenti mostrano i filtri più comuni:

# Suppress specific rules everywhere cfn-validate template.yaml --exclude-ids RULE_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

I filtri che hanno come target un tipo di risorsa, un servizio o un ID logico accettano un =RULE_ID suffisso opzionale per limitare il filtro a una sola regola. Senza il suffisso, il filtro si applica a tutte le regole per quella destinazione. Per tutte le opzioni di filtro, consulta il riferimento cfn-validate CLI su. GitHub

Aggiungi regole personalizzate

Puoi aggiungere i tuoi assegni in uno dei seguenti formati. Ogni formato presuppone una conoscenza di base del relativo linguaggio delle regole. Per impostazione predefinita, le regole personalizzate vengono eseguite in aggiunta alle regole integrate. Per eseguire solo le regole personalizzate, aggiungi--disable-builtin-rules.

  • CEL (.json) — Controlli basati su proprietà e dati scritti come espressioni CEL in un file JSON. Carica con. --rule-source

  • Rego (.rego) — Logica complessa tra risorse scritta nel linguaggio di policy Rego. Carica con. --rule-source

  • Guard (.guard): regole di conformità dichiarative nel linguaggio delle regole Guard. Carica un file o una directory con--guard-rule-source. Il validatore supporta un sottoinsieme del linguaggio Guard. Se una regola utilizza un costrutto non supportato, il validatore rifiuta la regola quando viene caricata invece di ignorare il costrutto. Per la sintassi della regola, vedere. Convalida i modelli con Guard

Puoi ripetere entrambe le opzioni per caricare più fonti di regole:

cfn-validate template.yaml --rule-source ./rules/checks.json --rule-source ./rules/network.rego cfn-validate template.yaml --guard-rule-source ./guard-rules/

Il seguente esempio di CEL checks.json riporta un risultato per ogni bucket Amazon S3 senza crittografia. Il resource_type campo fa sì che la regola venga eseguita una volta per ogni risorsa di quel tipo e {name} nel messaggio viene sostituito dall'ID logico della risorsa.

{ "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" } ] }

Per ulteriori informazioni sui dati disponibili per le regole, sulle funzioni CEL supportate e sulla scrittura delle regole Rego, consulta il riferimento alle regole personalizzate su GitHub.

Convalida nuovi tipi e proprietà di risorse

Gli schemi raggruppati corrispondono al CloudFormation registro al momento del rilascio. Se un modello utilizza un tipo di risorsa, una proprietà o un valore consentito CloudFormation pubblicato dopo tale versione o un tipo di risorsa privato dal tuo registro, passa lo schema del provider di risorse con. --additional-schema Il validatore lo utilizza per estendere lo schema in bundle per un tipo esistente o per convalidare un nuovo tipo. Puoi passare un .json file o una directory di file di schema e ripetere l'opzione:

cfn-validate template.yaml --additional-schema ./schemas/

Uno schema aggiuntivo non rimuove mai un vincolo dallo schema in bundle. Se uno schema non può essere letto o applicato, il comando termina con il codice 2 anziché ignorarlo.

Incorpora la libreria di convalida

Installa il pacchetto per il tuo linguaggio di programmazione per eseguire gli stessi controlli offline dall'applicazione. Crea un motore di convalida una sola volta, riutilizzalo per più modelli ed elabora la diagnostica strutturata restituita per ogni modello. Puoi anche configurare regole CEL, Rego o Guard personalizzate e schemi aggiuntivi tramite l'API della libreria.

Lingua Pacchetto Installa Documentazione
Rust cloudformation-validatesu crates.io cargo add cloudformation-validate API ed esempi
Node.js @aws/cloudformation-validatesu npm npm install @aws/cloudformation-validate API ed esempi
Python cloudformation-validatesu PyPI python3 -m pip install cloudformation-validate API ed esempi
Go cloudformation-validate/src/bindings-go/gosu pkg.go.dev go get github.com/aws-cloudformation/cloudformation-validate/src/bindings-go/go@latest API ed esempi
JVM (Java o Kotlin) software.amazon.cloudformation:cloudformation-validatesu Maven Central implementation("software.amazon.cloudformation:cloudformation-validate:VERSION")(Gradle) o l'equivalente dipendenza da Maven API ed esempi

Ogni libreria espone un metodo che convalida un modello e restituisce un report con la stessa diagnostica dello strumento da riga di comando. Negli esempi seguenti viene utilizzato il motore predefinitoCompositeEngine, che esegue le regole integrate e tutte le regole CEL, Rego o Guard personalizzate configurate dall'utente. Ogni esempio convalida un modello e stampa ogni risultato.

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}") } }

Per i runtime delle lingue supportati, il blocco delle versioni, i canali di versione non definitiva e la sintassi di Maven e Gradle, consulta la guida all'installazione di Language Binding su. GitHub Per il riferimento all'API e gli esempi completi in ogni lingua, vedi Embedding as a library on. GitHub

Utilizzo con AWS CDK

Se lo utilizzi AWS CDK, non è necessario installare il validatore separatamente. La libreria di AWS CDK costruzione include un'impostazione predefinita CloudFormationValidatePlugin che esegue automaticamente gli stessi controlli dopo la sintesi dei modelli. CloudFormation

cdk synth

AWS CDK riporta i possibili errori di implementazione e i risultati delle migliori pratiche con i risultati della convalida. È possibile configurare in modo esplicito CloudFormationValidatePlugin quando si desidera aggiungere regole Rego o Guard personalizzate.

Per la configurazione dei plug-in, i riconoscimenti e i report di convalida, consulta la sezione Validazione dei modelli e delle politiche nel riferimento API.AWS CDK