Klausul Menggunakan kueri dalam klausa Menggunakan operator dalam klausa Menggunakan pesan khusus dalam klausa Menggabungkan klausa Menggunakan blok dengan aturan Guard

AWS CloudFormation Guard Aturan penulisan

Dalam AWS CloudFormation Guard, aturan adalah policy-as-code aturan. Anda menulis aturan dalam bahasa khusus domain Guard (DSL) yang dapat Anda validasi JSON - atau YAML data yang diformat -. Aturan terdiri dari klausa.

Anda dapat menyimpan aturan yang ditulis menggunakan Guard DSL ke dalam file plaintext yang menggunakan ekstensi file apa pun.

Anda dapat membuat beberapa file aturan dan mengkategorikannya sebagai kumpulan aturan. Set aturan memungkinkan Anda memvalidasi data yang YAML diformat JSON - atau -terhadap beberapa file aturan secara bersamaan.

Topik

Klausul

Klausa adalah ekspresi Boolean yang mengevaluasi ke true (PASS) atau false (). FAIL Klausul menggunakan operator biner untuk membandingkan dua nilai atau operator unary yang beroperasi pada satu nilai.

Contoh klausa unary

Klausul unary berikut mengevaluasi apakah koleksi TcpBlockedPorts kosong.


InputParameters.TcpBlockedPorts not empty

Klausa unary berikut mengevaluasi apakah ExecutionRoleArn properti adalah string.


Properties.ExecutionRoleArn is_string

Contoh klausa biner

Klausa biner berikut mengevaluasi apakah BucketName properti berisi stringencrypted, terlepas dari casing.


Properties.BucketName != /(?i)encrypted/

Klausul biner berikut mengevaluasi apakah ReadCapacityUnits properti kurang dari atau sama dengan 5.000.


Properties.ProvisionedThroughput.ReadCapacityUnits <= 5000

Sintaks untuk menulis klausa aturan Guard


<query> <operator> [query|value literal] [custom message]

Properti klausa aturan Penjaga

query

Ekspresi terpisah dot (.) ditulis untuk melintasi data hierarkis. Ekspresi kueri dapat mencakup ekspresi filter untuk menargetkan subset nilai. Kueri dapat ditetapkan ke variabel sehingga Anda dapat menulisnya sekali dan mereferensikannya di tempat lain dalam kumpulan aturan, yang akan memungkinkan Anda mengakses hasil kueri.

Untuk informasi selengkapnya tentang menulis kueri dan pemfilteran, lihat. Mendefinisikan kueri dan pemfilteran

Wajib: Ya

operator

Operator unary atau biner yang membantu memeriksa status kueri. Sisi kiri (LHS) dari operator biner harus berupa kueri, dan sisi kanan (RHS) harus berupa kueri atau nilai literal.

Operator unary yang didukung: exists | empty | is_string | is_list | is_struct not(!)

Wajib: Ya

query|value literal

Kueri atau nilai literal yang didukung seperti string atauinteger(64).

Literal nilai yang didukung:

Semua tipe primitif:string,,integer(64),float(64),bool, char regex
Semua jenis rentang khusus untuk mengekspresikaninteger(64),float(64), atau char rentang dinyatakan sebagai:
- r[<lower_limit>, <upper_limit>], yang diterjemahkan ke nilai apa pun k yang memenuhi ekspresi berikut: lower_limit <= k <= upper_limit
- r[<lower_limit>, <upper_limit>), yang diterjemahkan ke nilai apa pun k yang memenuhi ekspresi berikut: lower_limit <= k < upper_limit
- r(<lower_limit>, <upper_limit>], yang diterjemahkan ke nilai apa pun k yang memenuhi ekspresi berikut: lower_limit < k <= upper_limit
- r(<lower_limit>, <upper_limit>),yang diterjemahkan ke nilai apa pun k yang memenuhi ekspresi berikut: lower_limit < k < upper_limit
Array asosiatif (peta) untuk data struktur nilai kunci bersarang. Sebagai contoh:

{ "my-map": { "nested-maps": [ { "key": 10, "value": 20 } ] } }
Array tipe primitif atau tipe array asosiatif

Wajib: Bersyarat; diperlukan ketika operator biner digunakan.

custom message

String yang memberikan informasi tentang klausa. Pesan ditampilkan dalam output verbose dari test perintah validate dan dapat berguna untuk memahami atau men-debug evaluasi aturan pada data hierarkis.

Wajib: Tidak

Menggunakan kueri dalam klausa

Untuk informasi tentang menulis kueri, lihat Mendefinisikan kueri dan pemfilteran danMenetapkan dan mereferensikan variabel dalam aturan Guard.

Menggunakan operator dalam klausa

Berikut ini adalah contoh CloudFormation template, Template-1 danTemplate-2. Untuk mendemonstrasikan penggunaan operator yang didukung, contoh kueri dan klausa di bagian ini mengacu pada contoh templat ini.

Templat-1



Resources:
 S3Bucket:
   Type: "AWS::S3::Bucket"
   Properties:
     BucketName: "MyServiceS3Bucket"
     BucketEncryption:
       ServerSideEncryptionConfiguration:
         - ServerSideEncryptionByDefault:
             SSEAlgorithm: 'aws:kms'
             KMSMasterKeyID: 'arn:aws:kms:us-east-1:123456789:key/056ea50b-1013-3907-8617-c93e474e400'
     Tags:
       - Key: "stage"
         Value: "prod"
       - Key: "service"
         Value: "myService"

Templat-2


Resources:
 NewVolume:
   Type: AWS::EC2::Volume
   Properties: 
     Size: 100
     VolumeType: io1
     Iops: 100
     AvailabilityZone:
       Fn::Select:
         - 0
         - Fn::GetAZs: us-east-1
     Tags:
       - Key: environment
         Value: test
   DeletionPolicy: Snapshot

Contoh klausa yang menggunakan operator unary

empty— Memeriksa apakah koleksi kosong. Anda juga dapat menggunakannya untuk memeriksa apakah kueri memiliki nilai dalam data hierarkis karena kueri menghasilkan koleksi. Anda tidak dapat menggunakannya untuk memeriksa apakah kueri nilai string memiliki string kosong ("") yang ditentukan. Untuk informasi selengkapnya, lihat Mendefinisikan kueri dan pemfilteran.

Klausa berikut memeriksa apakah template memiliki satu atau lebih sumber daya yang ditentukan. Ini mengevaluasi PASS karena sumber daya dengan ID logis S3Bucket didefinisikan dalamTemplate-1.
```
Resources !empty
```
Klausa berikut memeriksa apakah satu atau beberapa tag didefinisikan untuk S3Bucket sumber daya. Ini mengevaluasi PASS karena S3Bucket memiliki dua tag yang didefinisikan untuk Tags properti diTemplate-1.
```
Resources.S3Bucket.Properties.Tags !empty
```
exists— Memeriksa apakah setiap kemunculan query memiliki nilai dan dapat digunakan sebagai pengganti!= null.

Klausul berikut memeriksa apakah BucketEncryption properti didefinisikan untuk. S3Bucket Ini mengevaluasi PASS karena BucketEncryption didefinisikan untuk S3Bucket dalamTemplate-1.
```
Resources.S3Bucket.Properties.BucketEncryption exists
```

catatan

The empty and not exists checks mengevaluasi true untuk kunci properti yang hilang saat melintasi data input. Misalnya, jika Properties bagian tidak ditentukan dalam templat untukS3Bucket, klausa akan Resources.S3Bucket.Properties.Tag empty dievaluasi. true emptyCek exists dan tidak menampilkan jalur JSON penunjuk di dalam dokumen dalam pesan kesalahan. Kedua klausa ini sering memiliki kesalahan pengambilan yang tidak mempertahankan informasi traversal ini.

is_string— Memeriksa apakah setiap kemunculan kueri adalah string tipe.

Klausa berikut memeriksa apakah nilai string ditentukan untuk BucketName properti S3Bucket sumber daya. Ini mengevaluasi PASS karena nilai string "MyServiceS3Bucket" ditentukan untuk BucketName inTemplate-1.
```
Resources.S3Bucket.Properties.BucketName is_string
```
is_list— Memeriksa apakah setiap kemunculan kueri adalah list tipe.

Klausa berikut memeriksa apakah daftar ditentukan untuk Tags properti S3Bucket sumber daya. Ini mengevaluasi PASS karena dua pasangan kunci-nilai ditentukan untuk in. Tags Template-1
```
Resources.S3Bucket.Properties.Tags is_list
```
is_struct— Memeriksa apakah setiap kemunculan kueri adalah data terstruktur.

Klausa berikut memeriksa apakah data terstruktur ditentukan untuk BucketEncryption properti S3Bucket sumber daya. Ini mengevaluasi PASS karena BucketEncryption ditentukan menggunakan tipe ServerSideEncryptionConfiguration properti (object) diTemplate-1.

catatan

Untuk memeriksa keadaan terbalik, Anda dapat menggunakan operator ( not !) denganis_string,is_list, dan is_struct operator.

Contoh klausa yang menggunakan operator biner

Klausa berikut memeriksa apakah nilai yang ditentukan untuk BucketName properti S3Bucket sumber daya di Template-1 berisi stringencrypt, terlepas dari casing. Ini dievaluasi PASS karena nama bucket yang ditentukan "MyServiceS3Bucket" tidak berisi stringencrypt.


Resources.S3Bucket.Properties.BucketName != /(?i)encrypt/

Klausa berikut memeriksa apakah nilai yang ditentukan untuk Size properti NewVolume sumber daya Template-2 berada dalam rentang tertentu: 50 <= Size <= 200. Ini mengevaluasi PASS karena 100 ditentukan untukSize.


Resources.NewVolume.Properties.Size IN r[50,200]

Klausa berikut memeriksa apakah nilai yang ditentukan untuk VolumeType properti NewVolume sumber daya di Template-2 adalahio1,io2, ataugp3. Ini mengevaluasi PASS karena io1 ditentukan untukNewVolume.


Resources.NewVolume.Properties.NewVolume.VolumeType IN [ 'io1','io2','gp3' ]

catatan

Contoh kueri di bagian ini menunjukkan penggunaan operator menggunakan sumber daya dengan logis IDs S3Bucket danNewVolume. Nama sumber daya sering kali ditentukan pengguna dan dapat secara sewenang-wenang dinamai dalam templat infrastruktur sebagai kode (IAc). Untuk menulis aturan yang generik dan berlaku untuk semua AWS::S3::Bucket sumber daya yang didefinisikan dalam template, bentuk kueri yang paling umum digunakan adalahResources.*[ Type == ‘AWS::S3::Bucket’ ]. Untuk informasi selengkapnya, lihat Mendefinisikan kueri dan pemfilteran detail tentang penggunaan dan jelajahi direktori examples di cloudformation-guard GitHub repositori.

Menggunakan pesan khusus dalam klausa

Dalam contoh berikut, klausa untuk Template-2 menyertakan pesan kustom.


Resources.NewVolume.Properties.Size IN r[50,200] 
<<
    EC2Volume size must be between 50 and 200, 
    not including 50 and 200
>>
Resources.NewVolume.Properties.VolumeType IN [ 'io1','io2','gp3' ] <<Allowed Volume Types are io1, io2, and gp3>>

Menggabungkan klausa

Di Guard, setiap klausa yang ditulis pada baris baru digabungkan secara implisit dengan klausa berikutnya dengan menggunakan konjungsi (logika Boolean). and Lihat contoh berikut ini.


# clause_A ^ clause_B ^ clause_C
clause_A
clause_B
clause_C

Anda juga dapat menggunakan disjungsi untuk menggabungkan klausa dengan klausa berikutnya dengan menentukan or|OR di akhir klausa pertama.


<query> <operator> [query|value literal] [custom message] [or|OR]

Dalam klausa Penjaga, disjungsi dievaluasi terlebih dahulu, diikuti oleh konjungsi. Aturan penjaga dapat didefinisikan sebagai gabungan dari disjungsi klausa (an and|AND of or|OR s) yang mengevaluasi ke () atau true (PASS). false FAIL Ini mirip dengan bentuk normal konjungtif.

Contoh-contoh berikut menunjukkan urutan evaluasi klausa.


# (clause_E v clause_F) ^ clause_G
clause_E OR clause_F
clause_G

# (clause_H v clause_I) ^ (clause_J v clause_K)
clause_H OR
clause_I
clause_J OR
clause_K

# (clause_L v clause_M v clause_N) ^ clause_O
clause_L OR
clause_M OR
clause_N 
clause_O

Semua klausa yang didasarkan pada contoh Template-1 dapat digabungkan dengan menggunakan konjungsi. Lihat contoh berikut ini.


Resources.S3Bucket.Properties.BucketName is_string
Resources.S3Bucket.Properties.BucketName != /(?i)encrypt/
Resources.S3Bucket.Properties.BucketEncryption exists
Resources.S3Bucket.Properties.BucketEncryption is_struct
Resources.S3Bucket.Properties.Tags is_list
Resources.S3Bucket.Properties.Tags !empty

Menggunakan blok dengan aturan Guard

Blok adalah komposisi yang menghilangkan verbositas dan pengulangan dari serangkaian klausa, kondisi, atau aturan terkait. Ada tiga jenis blok:

Blok kueri
whenblok
Blok aturan bernama

Blok kueri

Berikut ini adalah klausa yang didasarkan pada contoh. Template-1 Konjungsi digunakan untuk menggabungkan klausa.


Resources.S3Bucket.Properties.BucketName is_string
Resources.S3Bucket.Properties.BucketName != /(?i)encrypt/
Resources.S3Bucket.Properties.BucketEncryption exists
Resources.S3Bucket.Properties.BucketEncryption is_struct
Resources.S3Bucket.Properties.Tags is_list
Resources.S3Bucket.Properties.Tags !empty

Bagian dari ekspresi kueri di setiap klausa diulang. Anda dapat meningkatkan kemampuan komposisi dan menghapus verbositas dan pengulangan dari sekumpulan klausa terkait dengan jalur kueri awal yang sama dengan menggunakan blok kueri. Kumpulan klausa yang sama dapat ditulis seperti yang ditunjukkan pada contoh berikut.


Resources.S3Bucket.Properties {
    BucketName is_string
    BucketName != /(?i)encrypt/
    BucketEncryption exists
    BucketEncryption is_struct
    Tags is_list
    Tags !empty
}

Dalam blok kueri, kueri sebelum blok menetapkan konteks untuk klausa di dalam blok.

Untuk informasi selengkapnya tentang menggunakan blok, lihatMenyusun blok aturan bernama.

`when`blok

Anda dapat mengevaluasi blok secara kondisional dengan menggunakan when blok, yang mengambil formulir berikut.


  when <condition> {
       Guard_rule_1
       Guard_rule_2
       ...
   }

Kata when kunci menunjuk awal when blok. conditionadalah aturan penjaga. Blok hanya dievaluasi jika evaluasi kondisi menghasilkan true (PASS).

Berikut ini adalah contoh when blok yang didasarkan padaTemplate-1.


when Resources.S3Bucket.Properties.BucketName is_string {
     Resources.S3Bucket.Properties.BucketName != /(?i)encrypt/
 }

Klausa dalam when blok hanya dievaluasi jika nilai yang ditentukan untuk BucketName adalah string. Jika nilai yang BucketName ditentukan untuk direferensikan di Parameters bagian template seperti yang ditunjukkan pada contoh berikut, klausa dalam when blok tidak dievaluasi.


Parameters:
   S3BucketName:
     Type: String
 
 Resources:
   S3Bucket:
     Type: "AWS::S3::Bucket"
     Properties:
       BucketName: 
         Ref: S3BucketName
     ...

Blok aturan bernama

Anda dapat menetapkan nama ke seperangkat aturan (kumpulan aturan), dan kemudian mereferensikan blok validasi modular ini, yang disebut blok aturan bernama, dalam aturan lain. Blok aturan bernama mengambil bentuk berikut.


  rule <rule name> [when <condition>] {
    Guard_rule_1
    Guard_rule_2
    ...
    }

ruleKata kunci menunjuk awal dari blok aturan bernama.

rule nameadalah string yang dapat dibaca manusia yang secara unik mengidentifikasi blok aturan bernama. Ini adalah label untuk aturan Guard yang dirangkum. Dalam penggunaan ini, istilah aturan Penjaga mencakup klausa, blok kueri, blok, dan when blok aturan bernama. Nama aturan dapat digunakan untuk merujuk pada hasil evaluasi dari kumpulan aturan yang dirangkum, yang membuat blok aturan bernama dapat digunakan kembali. Nama aturan juga menyediakan konteks tentang kegagalan aturan dalam output validate dan test perintah. Nama aturan ditampilkan bersama dengan status evaluasi blok (PASS,FAIL, atauSKIP) dalam output evaluasi file aturan. Lihat contoh berikut ini.


# Sample output of an evaluation where check1, check2, and check3 are rule names.
_Summary__ __Report_ Overall File Status = **FAIL**
**PASS/****SKIP** **rules**
check1 **SKIP**
check2 **PASS**
**FAILED rules**
check3 **FAIL**

Anda juga dapat mengevaluasi blok aturan bernama secara kondisional dengan menentukan when kata kunci diikuti dengan kondisi setelah nama aturan.

Berikut ini adalah contoh when blok yang telah dibahas sebelumnya dalam topik ini.


rule checkBucketNameStringValue when Resources.S3Bucket.Properties.BucketName is_string {
    Resources.S3Bucket.Properties.BucketName != /(?i)encrypt/
}

Menggunakan blok aturan bernama, yang sebelumnya juga dapat ditulis sebagai berikut.


rule checkBucketNameIsString {
    Resources.S3Bucket.Properties.BucketName is_string
}
rule checkBucketNameStringValue when checkBucketNameIsString {
    Resources.S3Bucket.Properties.BucketName != /(?i)encrypt/
}

Anda dapat menggunakan kembali dan mengelompokkan blok aturan bernama dengan aturan Penjaga lainnya. Berikut adalah beberapa contoh.


rule rule_name_A {
    Guard_rule_1 OR
    Guard_rule_2
    ...
}

rule rule_name_B {
    Guard_rule_3
    Guard_rule_4
    ...
}

rule rule_name_C {
    rule_name_A OR rule_name_B
}

rule rule_name_D {
    rule_name_A
    rule_name_B
}

rule rule_name_E when rule_name_D {
    Guard_rule_5
    Guard_rule_6
    ...
}

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Prasyarat dan ikhtisar untuk menggunakan aturan Guard

Mendefinisikan kueri dan pemfilteran

AWS CloudFormation Guard Aturan penulisan

Topik

Klausul

Sintaks untuk menulis klausa aturan Guard

Properti klausa aturan Penjaga

Menggunakan kueri dalam klausa

Menggunakan operator dalam klausa

Contoh klausa yang menggunakan operator unary

catatan

catatan

Contoh klausa yang menggunakan operator biner

catatan

Menggunakan pesan khusus dalam klausa

Menggabungkan klausa

Menggunakan blok dengan aturan Guard

Blok kueri

whenblok

Blok aturan bernama

`when`blok