Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris. # 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 memvalidasi data berformat JSON- atau YAML. Aturan terdiri dari *klausa*. Anda dapat menyimpan aturan yang ditulis menggunakan Guard DSL ke dalam file teks biasa yang menggunakan ekstensi file apa pun. Anda dapat membuat beberapa file aturan dan mengkategorikannya sebagai kumpulan *aturan*. Set aturan memungkinkan Anda memvalidasi data berformat JSON atau YAML terhadap beberapa file aturan secara bersamaan. **Topics** + [Klausul](#clauses) + [Menggunakan kueri dalam klausa](#clauses-queries) + [Menggunakan operator dalam klausa](#clauses-operators) + [Menggunakan pesan kustom dalam klausa](#clauses-custom-messages) + [Menggabungkan klausa](#combining-clauses) + [Menggunakan blok dengan aturan Guard](#blocks) + [Menggunakan fungsi bawaan](#built-in-functions) + [Mendefinisikan kueri Guard dan pemfilteran](query-and-filtering.md) + [Menetapkan dan mereferensikan variabel dalam aturan Guard](variables.md) + [Menyusun blok aturan bernama di AWS CloudFormation Guard](named-rule-block-composition.md) + [Menulis klausa untuk melakukan evaluasi sadar konteks](context-aware-evaluations.md) ## 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 string`encrypted`, 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|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](query-and-filtering.md) *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 biner yang didukung*: `==` `!=` (Sama) \| (Tidak sama) \| `>` (Lebih besar dari) \| `>=` (Lebih besar dari atau sama dengan) \| `<` (Kurang dari) \| `<=` (Kurang dari atau sama dengan) \| `IN` (Dalam daftar formulir [x, y, z] *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` atau`integer(64)`. *Literal nilai yang didukung*: + Semua tipe primitif:`string`,,`integer(64)`,`float(64)`,`bool`, `char` `regex` + Semua jenis rentang khusus untuk mengekspresikan`integer(64)`,`float(64)`, atau `char` rentang dinyatakan sebagai: + `r[, ]`, yang diterjemahkan ke nilai apa pun `k` yang memenuhi ekspresi berikut: `lower_limit <= k <= upper_limit` + `r[, `), yang diterjemahkan ke nilai apa pun `k` yang memenuhi ekspresi berikut: `lower_limit <= k < upper_limit` + `r(, ]`, yang diterjemahkan ke nilai apa pun `k` yang memenuhi ekspresi berikut: `lower_limit < k <= upper_limit` + `r(, ),`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. 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](query-and-filtering.md) dan[Menetapkan dan mereferensikan variabel dalam aturan Guard](variables.md). ## Menggunakan operator dalam klausa Berikut ini adalah contoh CloudFormation template, `Template-1` dan`Template-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](query-and-filtering.md). Klausa berikut memeriksa apakah template memiliki satu atau lebih sumber daya yang ditentukan. Ini mengevaluasi `PASS` karena sumber daya dengan ID logis `S3Bucket` didefinisikan dalam`Template-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 di`Template-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` dalam`Template-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 untuk`S3Bucket`, klausa akan `Resources.S3Bucket.Properties.Tag empty` dievaluasi. `true` `empty`Pemeriksaan `exists` dan tidak menampilkan jalur penunjuk JSON 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` in`Template-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)}} di`Template-1`. ``` Resources.S3Bucket.Properties.BucketEncryption is_struct ``` **catatan** Untuk memeriksa keadaan terbalik, Anda dapat menggunakan operator (` not !`) dengan`is_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 string`encrypt`, terlepas dari casing. Ini dievaluasi `PASS` karena nama bucket yang ditentukan `"MyServiceS3Bucket"` tidak berisi string`encrypt`. ``` 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 untuk`Size`. ``` Resources.NewVolume.Properties.Size IN r[50,200] ``` Klausa berikut memeriksa apakah nilai yang ditentukan untuk `VolumeType` properti `NewVolume` sumber daya di `Template-2` adalah`io1`,`io2`, atau`gp3`. Ini mengevaluasi `PASS` karena `io1` ditentukan untuk`NewVolume`. ``` 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` dan`NewVolume`. 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 adalah`Resources.*[ Type == ‘AWS::S3::Bucket’ ]`. Untuk informasi selengkapnya, lihat [Mendefinisikan kueri dan pemfilteran](query-and-filtering.md) detail tentang penggunaan dan jelajahi direktori [examples](https://github.com/aws-cloudformation/cloudformation-guard/tree/main/guard-examples) di `cloudformation-guard` GitHub repositori. ## Menggunakan pesan kustom 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' ] <> ``` ## 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|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](https://en.wikipedia.org/wiki/Conjunctive_normal_form). 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 + `when`blok + 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, lihat[Menyusun blok aturan bernama](named-rule-block-composition.md). ### `when`blok Anda dapat mengevaluasi blok secara kondisional dengan menggunakan `when` blok, yang mengambil formulir berikut. ``` when { Guard_rule_1 Guard_rule_2 ... } ``` Kata `when` kunci menunjuk awal `when` blok. `condition`adalah aturan penjaga. Blok hanya dievaluasi jika evaluasi kondisi menghasilkan `true` (`PASS`). Berikut ini adalah contoh `when` blok yang didasarkan pada`Template-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 [when ] { Guard_rule_1 Guard_rule_2 ... } ``` `rule`Kata kunci menunjuk awal dari blok aturan bernama. `rule name`adalah string yang dapat dibaca manusia yang secara unik mengidentifikasi blok aturan bernama. Ini adalah label untuk aturan Guard set yang dienkapsulasi. 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`, atau`SKIP`) dalam output evaluasi file aturan. Lihat contoh berikut ini. ``` # Sample output of an evaluation where check1, check2, and check3 are rule names. template.json Status = **FAIL** **SKIP rules** check1 **SKIP** **PASS rules** 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 ini 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 ... } ``` ## Menggunakan fungsi bawaan AWS CloudFormation Guard menyediakan fungsi bawaan yang dapat Anda gunakan dalam aturan Anda untuk melakukan operasi seperti manipulasi string, penguraian JSON, dan konversi tipe data. Fungsi didukung hanya melalui penugasan ke variabel. ### Fungsi kunci `json_parse(json_string)` Mem-parsing string JSON sebaris dari template. Setelah parsing, Anda dapat mengevaluasi properti dari objek yang dihasilkan. `count(collection)` Mengembalikan jumlah item yang query menyelesaikan ke. `regex_replace(base_string, regex_to_extract, regex_replacement)` Mengganti bagian dari string menggunakan ekspresi reguler. Untuk daftar lengkap fungsi yang tersedia termasuk manipulasi string, operasi pengumpulan, dan fungsi konversi tipe data, lihat [dokumentasi Fungsi](https://github.com/aws-cloudformation/cloudformation-guard/blob/main/docs/FUNCTIONS.md) di GitHub repositori Guard.