Terraform Provider
Provider terraform merender Recipes Aggrega menjadi konfigurasi Terraform. Provider ini menghasilkan konfigurasi dan tidak pernah menjalankan Terraform: build Aggrega adalah kompilasi ahead-of-time, sehingga tidak dapat me-resolve ID sumber daya, alamat IP, dan output yang baru ada setelah terraform apply. Interpolasi ${ ... } milik Terraform diteruskan tanpa diubah sebagai string penunjuk deterministik yang akan di-resolve kemudian oleh runtime Terraform. Provider ini bersifat offline dan hermetis — tidak pernah mengakses jaringan dan tidak pernah memanggil terraform atau tofu.
Cara sebuah boundary disusun
Provider terraform menyusun sebuah boundary alih-alih menghasilkan komponen-komponennya secara berdampingan. Setiap boundary yang dirender mendapatkan satu konfigurasi root, aggrega.modules.tf, yang mendeklarasikan setiap komponen yang dirender di sana sebagai blok module yang source-nya adalah subdirektori milik komponen tersebut di bawah modules/:
module "cache" { source = "./modules/cache"}
module "db" { source = "./modules/db"
allocated_storage = 100 db_name = "appdb" engine_version = "11.4"}Berkas-berkas milik setiap komponen — modul yang di-vendor atau isi yang ditulis sendiri, serta cap provenans — berada di subdirektori yang ditunjuk oleh bloknya. Ini adalah struktur standar Terraform di mana root menyusun anak-anaknya, dengan konvensi bahwa modul bersarang berada di bawah subdirektori modules/, dan ini adalah tata letak yang didapatkan setiap boundary terraform, baik berisi satu komponen maupun beberapa. Sebuah Feature yang dilampirkan ke sebuah komponen atau ke boundary dideklarasikan sebagai blok module tersendiri di konfigurasi root yang sama — lihat Tempat keluaran Feature yang dilampirkan berada.
Bentuk ini bersifat struktural, bukan kosmetik, karena dua alasan.
Graf dependensi Terraform bersifat per konfigurasi. Components yang diemisikan ke direktori terpisah merupakan graf terpisah yang tidak saling berhubungan: baik referensi maupun depends_on tidak dapat menjangkau dari satu ke yang lain, dan tidak ada satu terraform plan pun yang melihat keduanya. Satu root yang menyusun setiap komponen sebagai modul anak menempatkan seluruh boundary dalam satu graf dan satu plan.
Berkas sebuah komponen dialamatkan melalui direktorinya sendiri. Dua komponen dalam satu boundary dapat me-vendor modul yang menulis berkas dengan nama identik — main.tf, variables.tf — dan setiap set berada di bawah direktori komponennya sendiri alih-alih berebut satu jalur.
Tempat provider dikonfigurasi
Konfigurasi sebuah provider — blok provider — ditulis di root, tidak pernah di dalam modul sebuah komponen. Dokumentasi Terraform menyatakan bahwa modul yang dimaksudkan untuk dipanggil oleh modul lain tidak boleh berisi blok provider, dan modul yang dipanggilnya mewarisi konfigurasi default root untuk setiap provider yang digunakan modul tersebut. Modul yang membawa blok provider sendiri tidak dapat dipanggil dengan depends_on, count atau for_each, dan provider ini menulis depends_on pada blok module sebuah komponen setiap kali komponen lain di root yang sama membawa syncWave yang lebih awal, seperti dijelaskan di bagian Urutan deployment di bawah; Terraform kemudian menolak seluruh konfigurasi saat dimuat, sebelum merencanakan apa pun.
Jadi, sebuah Recipe yang provider-nya perlu dikonfigurasi menulis konfigurasi tersebut sebagai berkas di bawah spec.boundary.artifacts. Setiap berkas tersebut ditulis sekali di samping aggrega.modules.tf, tempat Terraform membacanya bersama konfigurasi root, dan modul komponen hanya menyimpan deklarasi required_providers berisi sumber dan versi provider:
infra/terraform/ aggrega.modules.tf provider-azurerm.tf modules/ gateway/main.tfComponents dari satu root yang mendeklarasikan file yang sama dengan byte yang sama berbagi satu salinan tersebut; nama yang sama dengan byte yang berbeda menghentikan build. Sumber daya modul-modul tersebut dicatat terhadap satu konfigurasi itu, sehingga konfigurasi itu pula yang digunakan Terraform untuk menghancurkannya. Release yang menghapus komponen terakhir yang mendeklarasikan file tersebut juga menghapus file itu, dan Terraform kemudian menolak merencanakan penghancuran apa yang dibuat oleh modul-modul tersebut, dengan meminta blok provider yang mengonfigurasi provider tersebut. Hancurkan sumber daya tersebut sebelum menghapus komponen terakhir semacam itu.
Tempat input sebuah komponen diberikan
Input sebuah komponen adalah argumen blok module-nya di konfigurasi root, dan hanya di sanalah input tersebut ditulis. Sebuah blok membawa argumen jika compiler memberikan input modul — yaitu Recipe yang me-vendor modul dengan source:. Blok tersebut kosong jika Recipe menulis sendiri isi konfigurasi dan me-resolve nilainya ke dalam isi itu, sehingga tidak ada yang tersisa untuk diteruskan oleh compiler.
Argumen modul adalah posisi yang dievaluasi Terraform, itulah sebabnya nilai-nilai ditempatkan di sana. Pointer ${ ... } yang diberikan Recipe di-resolve di sana alih-alih tiba di modul sebagai string literal. Yang menjadi acuan resolusinya adalah konfigurasi root: sebuah referensi menamai sesuatu yang dideklarasikan konfigurasi tersebut — salah satu blok module-nya, sebagai module.<name>.<output> — dan referensi ke apa pun yang tidak dideklarasikannya menghasilkan error yang jelas saat plan, dengan menyebutkan referen yang hilang.
Karena itu, direktori milik sebuah komponen bukanlah konfigurasi yang dapat Anda plan sebagaimana di-deploy. Inputnya dinyatakan satu tingkat di atas, di root, sehingga berada di modules/<component> dan menjalankan engine di sana akan merencanakan hal lain, dan mana dari dua hal yang terjadi bergantung pada blok variable milik modul itu sendiri:
- Jika setidaknya satu input tidak mendeklarasikan
default, plan gagal secara jelas —No value for required variable, dengan menyebutkan setiap variabel yang tidak diatur beserta barisnya, dan menawarkan solusi-var/-var-filemilik Terraform sendiri. - Jika setiap input membawa
default, plan berhasil dan membangun dari nilai default modul alih-alih dari nilai yang diberikan konfigurasi root. Tidak ada peringatan, sehingga inilah kasus yang perlu diketahui: plan yang tampak benar sebenarnya menggambarkan konfigurasi yang tidak diminta siapa pun.
Sebagai gantinya, lakukan plan pada direktori keluaran milik boundary itu sendiri — direktori yang berisi aggrega.modules.tf, tepat di atas modules/. Di sanalah nilai-nilai deployment berada, dan itulah satu-satunya tempat sebuah plan dapat melihat seluruh boundary.
Mengonsumsi nilai yang dipublikasikan komponen lain
Komponen yang terhubung ke komponen lain dengan edge uses membaca nilai yang dipublikasikan komponen tersebut melalui pipe .context.inject miliknya (atau melalui .context.uses.<alias>.provides.<name>). Yang dibacanya adalah string yang dialirkan compiler tanpa diinterpretasikan, dan tempat string itu mendarat adalah teks yang dievaluasi Terraform dalam scope tempat Recipe menuliskannya. Boundary terraform memiliki dua scope semacam itu, dan hanya satu yang mendeklarasikan pemanggilan modul yang dibutuhkan referensi lintas komponen:
- konfigurasi root mendeklarasikan setiap kontributor sebagai blok
module, sehinggamodule.<name>.<output>dapat di-resolve di sana; - direktori milik sebuah komponen sama sekali tidak mendeklarasikan pemanggilan modul, sehingga
module.<name>.<output>tidak menamai apa pun di sana — apa pun<name>-nya. Mengganti dengan nama yang benar tidak mengubah apa pun, karena yang hilang adalah deklarasinya, bukan ejaannya.
Jadi, jenis input Recipe yang mengonsumsi menentukan apakah referensi yang dikonsumsi dapat di-resolve, bukan nilai yang dikonsumsi.
Tulis Recipe yang mengonsumsi sebagai Recipe source:. valuesMapping:-nya menjadi argumen blok module miliknya di konfigurasi root — satu-satunya posisi yang sekaligus dievaluasi dan berada dalam scope tempat tetangganya dideklarasikan.
Contoh pasangan
Produsen memublikasikan alamat yang menamai pemanggilan modulnya sendiri, yaitu bentuk yang dideklarasikan scope konsumennya. .context.instance_id tersedia pada permukaan evaluasi provides, dan untuk komponen yang dideklarasikan Aggregate milik deployment, nilai ini adalah nama yang dibawa blok module komponen tersebut:
# Recipe — the producer. Its vendored module declares `output "endpoint"`.spec: capability: terraform implements: example/storage/object-store:1.0.0 source: ./module valuesMapping: | bucket: "{{ .values.bucket }}" provides: endpoint: "${module.{{ .context.instance_id }}.endpoint}"Konsumen me-vendor modul yang mendeklarasikan sebuah input, lalu memetakan nilai yang diinjeksikan ke input tersebut:
# Recipe — the consumer. Its vendored module declares `variable "store_endpoint"`.spec: capability: terraform implements: example/compute/reporting-api:1.0.0 source: ./module valuesMapping: | store_endpoint: "{{ .context.inject.env.STORE_ENDPOINT }}"Aggregate menghubungkan keduanya, dengan menyebutkan kunci yang dipublikasikan yang dibawa edge:
spec: components: store: type: example/storage/object-store values: bucket: app-artifacts
api: type: example/compute/reporting-api uses: store: store: target: store inject: env: - in: STORE_ENDPOINT from: endpointBuild menghasilkan satu konfigurasi root tempat referensi dan referennya dideklarasikan bersama:
module "api" { source = "./modules/api"
store_endpoint = "${module.store.endpoint}"}
module "store" { source = "./modules/store"
bucket = "app-artifacts"}Terraform me-resolve module.store.endpoint karena konfigurasi yang sama mendeklarasikan module "store", dan nilainya sampai ke modul konsumen sebagai input biasa.
Contoh aws-rds-and-ecs-service membangun pasangan ini dari Recipes pustaka standar: database PostgreSQL yang disediakan oleh modul RDS yang dipublikasikan dan server yang dijalankan di Amazon ECS, yang argumen environment-nya membawa ${module.db.db_instance_address} di konfigurasi root yang mendeklarasikan module "db".
Tiga cara hal ini bisa salah, dan seperti apa masing-masing terlihat
Recipe yang menulis isinya sendiri tidak dapat mengonsumsi referensi lintas komponen. Recipe artifacts: me-resolve nilainya ke dalam isi yang ditulisnya, dan isi tersebut diemisikan ke direktori milik komponen itu sendiri. Referensi tersebut kemudian berada dalam cakupan yang tidak mendeklarasikan pemanggilan modul apa pun:
Error: Reference to undeclared module on modules/api/main.tf line 11, in output "seen": 11: value = "${module.store.endpoint}"No module call named "store" is declared in module.api.Tidak ada ejaan yang dapat memperbaikinya, karena ekspresi modul bersarang sama sekali tidak dapat menamai modul saudaranya — modul bersarang menerima nilai dari tetangganya hanya sebagai input, yaitu argumen blok module yang sudah disediakan oleh jalur bersumber. Komponen yang mengonsumsi nilai yang dipublikasikan komponen lain ditulis sebagai Recipe source:.
Alamat yang menamai sesuatu di dalam modul milik produsen di-resolve terhadap root, bukan terhadap modul tersebut. Entri provides yang mengeja aws_db_instance.this.endpoint menamai resource yang dideklarasikan modul produsen; jika ditulis sebagai interpolasi, entri itu dievaluasi di tempat argumen konsumen berada, yaitu root:
Error: Reference to undeclared resource on aggrega.modules.tf line 19, in module "api": 19: store_endpoint = "${aws_db_instance.this.endpoint}"There is no managed resource "aws_db_instance" "this" definition in the root module.Publikasikan ${module.<...>.<output>} dan berikan modul tersebut blok output untuk nilainya, alih-alih menjangkau ke dalam resource-nya.
Entri provides yang tidak memuat interpolasi dikirimkan sebagai teks. Inilah satu-satunya yang tidak gagal: kompiler menyalurkan string dan tidak dapat membedakan pointer dari literal, sehingga aws_db_instance.this.endpoint yang ditulis tanpa ${ ... } dirender sebagai string berkutip, build berhasil, engine memvalidasi, dan konsumen menerima karakter aws_db_instance.this.endpoint. Tulis pembungkus ${ ... } setiap kali nilai tersebut dimaksudkan sebagai referensi — itulah yang menandai string tersebut sebagai sesuatu yang harus dievaluasi Terraform.
Satu batasan yang perlu diketahui sebelum Anda mengandalkannya
.context.instance_id mengeja identitas komponen, dan nama blok module diturunkan dari direktori tempat file komponen berada. Untuk komponen yang dideklarasikan oleh Aggregate milik deployment itu sendiri, keduanya adalah nama yang sama. Untuk komponen yang disusun dari Aggregate lain, keduanya tidak sama: identitas hasil komposisi dan nama modul ditulis ke dalam dua alfabetnya secara berbeda, dan referensi tersebut kemudian gagal secara jelas di root, bukan secara diam-diam:
Error: Reference to undeclared module on aggrega.modules.tf line 25, in module "api": 25: store_endpoint = "${module.nested-zdinner.endpoint}"No module call named "nested-zdinner" is declared in the root module.Deklarasikan produsen yang alamatnya di-resolve oleh komponen lain di dalam Aggregate milik deployment itu sendiri, berdampingan dengan komponen yang mengonsumsinya.
Tempat output Feature yang dilampirkan berada
Lampiran Feature yang merender konfigurasinya sendiri mendapatkan modulnya sendiri, yang dideklarasikan dalam konfigurasi root yang sama dengan komponen di sampingnya. Inilah yang membuat konfigurasinya menjadi bagian dari deployment sama sekali: Terraform hanya memuat file yang berada langsung di dalam sebuah direktori dan memperlakukan direktori bersarang sebagai modul yang sepenuhnya terpisah yang harus dipanggil secara eksplisit, sehingga file lampiran dibaca karena root mendeklarasikan blok yang menamai direktori tempat file tersebut berada.
Direktori modul lampiran berada di samping direktori komponen, satu tingkat di bawah modules/, dan dinamai berdasarkan dua hal yang mengidentifikasinya — komponen yang menampungnya dan nama yang digunakan saat dilampirkan, digabungkan dengan --. Jadi, untuk komponen api yang membawa lampiran bernama aux, konfigurasi root mendeklarasikan dua modul:
module "api--aux" { source = "./modules/api--aux"}
module "api" { source = "./modules/api"}Feature yang dilampirkan pada boundary alih-alih pada komponen tidak memiliki komponen penampung untuk dinamai, sehingga direktorinya hanya menggunakan namanya sendiri: lampiran bernama aux pada boundary yang menampung komponen api menghasilkan ./modules/aux di samping ./modules/api.
Mengapa di samping, bukan di dalam. Terraform menggabungkan setiap file tingkat atas dalam direktori modul ke dalam satu namespace — baik output, variable, resource maupun locals — sehingga dua kontributor yang berbagi direktori akan bertabrakan pada nama apa pun yang sama-sama mereka deklarasikan, apa pun nama file mereka. Satu direktori untuk masing-masing itulah yang memisahkan mereka. Di samping alih-alih di dalam juga merupakan hal yang diminta oleh panduan Terraform sendiri untuk modul bersarang: bahwa modul-modul tersebut dapat disusun oleh pemanggil alih-alih saling memanggil secara langsung dan membentuk pohon modul yang bersarang dalam.
Penggabungan di-escape per koordinat. Masing-masing dari kedua koordinat ditulis ke dalam alfabet direktori sebelum digabungkan, sehingga koordinat yang sendiri memuat -- tidak dapat tertukar dengan penggabungnya: host bernama a--b dengan lampiran c dapat dibedakan dari host a dengan lampiran b--c. Huruf ASCII dalam kedua bentuk huruf, digit, titik, dan garis bawah dilewatkan apa adanya; tanda hubung yang Anda tulis dipertahankan di mana pun karakter setelahnya termasuk salah satu dari itu; selain itu di-escape. Aturan yang sama dan alfabet yang sama menghasilkan direktori anak pada target chart, sehingga direktori satu lampiran dieja dengan cara yang sama, target mana pun dari keduanya yang merendernya.
Nama blok diturunkan dari direktori yang ditunjuk oleh source-nya, dengan setiap karakter di luar tata bahasa Terraform untuk nama modul diganti dengan garis bawah. Pemetaan tersebut tidak satu-satu, sehingga ketika dua kontributor akan menghasilkan satu nama modul yang sama, build berhenti dan menyebutkan keduanya, alih-alih mengemisikan konfigurasi yang akan ditolak Terraform.
Tiga hal mengikuti dari lampiran yang merupakan modul tersendiri.
Inputnya berasal dari pemetaannya sendiri. Lampiran yang FeatureRecipe-nya mengambil sumber dari sebuah modul dan mendeklarasikan valuesMapping akan memiliki nilai yang dihasilkan pemetaan tersebut, yang ditulis sebagai argumen blok module miliknya sendiri, sama seperti modul bersumber milik komponen menerima nilainya. FeatureRecipe yang tidak mendeklarasikan valuesMapping tidak meneruskan argumen apa pun ke modulnya: variabel yang dideklarasikan modul dengan default akan memakainya, dan variabel yang dideklarasikan tanpa default dibiarkan tidak diatur, sehingga Terraform menolak plan tersebut.
Resource-nya berada dalam satu grafik dependensi milik boundary. Referensi atau depends_on dapat menjangkau antara lampiran dan komponen tempat lampiran itu dipasang, dan satu terraform plan melihat keduanya — properti yang sama yang diberikan bentuk root-composes-children kepada komponen, dengan alasan yang sama.
Nama tingkat atasnya adalah miliknya sendiri. Karena penggabungan namespace yang dijelaskan di atas berlaku per direktori, kontributor yang berada di direktorinya sendiri mendeklarasikan nama output, variable, resource dan locals miliknya tanpa bersaing dengan milik tetangganya — sehingga lampiran dapat memakai ulang nama yang sudah dideklarasikan host-nya, dan tidak ada yang perlu mengetahui nama yang digunakan pihak lain.
Perhatikan apa yang tidak diwajibkan target ini, karena batasan target chart berbeda dan tata letak bersama dapat dibaca seolah menyiratkan lebih dari yang sebenarnya: modul yang bersarang di dalam direktori kontributor lain tetap dapat dijangkau di sini, karena konfigurasi root membaca source setiap kontributor dari posisi yang disusun oleh build alih-alih membangunnya ulang dari sebuah pengenal. Yang ditolak target ini adalah dua kontributor yang berbagi direktori. Target chart menolak posisi bersarang sepenuhnya, karena target tersebut menemukan chart anak hanya satu tingkat ke bawah dan tidak lebih jauh.
Jenis input yang didukung
Provider terraform menerima dua dari tiga jenis input Recipe:
- Mode artifacts. Sebuah Recipe menulis konfigurasi Terraform sebagai body bertemplat; provider mengevaluasi template Aggrega dan mengeluarkan hasilnya tanpa menulis ulangnya. HCL (
main.tf) adalah default yang ergonomis, dan Terraform JSON (.tf.json) diterima secara setara. Provenans build dicap sebagai blok komentar Terraform di bagian atas body HCL; untuk body JSON — yang tidak memiliki sintaks komentar — provenans ditulis sebagai file pendamping,aggrega.provenance.tf, bukan secara inline. - Mode sourced. Sebuah Recipe mereferensikan modul Terraform dengan
source:. File modul di-vendor apa adanya ke direktori komponen tersebut, danvaluesMapping:milik Recipe menjadi argumen blokmodulekomponen tersebut dalam konfigurasi root boundary. Body modul dipertahankan persis seperti yang ditulis dan tidak ada yang ditulis ke dalamnya; nilai-nilai dinyatakan satu kali, di root, tempat Terraform mengevaluasinya. Ketika daunvaluesyang dideklarasikan node menjadi input modul secara langsung — Recipesource:tanpavaluesMapping:— input yang membawa materi yang dideklarasikan sensitif oleh penulis juga mendapatkan file override yang dihasilkan, yang membawa atribut sensitivitas milik Terraform sendiri; templatevaluesMapping:menciptakan nama output-nya sendiri, sehingga kasus tersebut tidak membawa penandaan dan build melaporkannya dengan sebuah peringatan. Keduanya dijelaskan di bagian Input modul yang dideklarasikan sensitif.
null dalam valuesMapping: adalah argumen null. Kunci yang disetel mapping ke null ditulis sebagai <name> = null dalam blok modul, dan engine memberikan nilai null kepada variabel modul, menimpa default-nya, kecuali variabel tersebut mendeklarasikan nullable = false, yang dalam hal ini default-nya berlaku; untuk memberikan default modul kepada sebuah input, hilangkan kunci tersebut dari mapping.
Jenis input synthesized tidak ditawarkan. Tidak ada pemetaan yang setia dan agnostik terhadap kapabilitas dari jenis Workload platform ke sumber daya Terraform sembarang, sehingga Recipe yang mendeklarasikan workload: terhadap provider terraform menghasilkan error yang jelas, bukan terjemahan yang dikarang.
Recipe yang mendeklarasikan omits: ditolak. Kunci omits: mengecualikan dari build dokumen yang dirender sebuah source, sedangkan provider ini tidak merender apa pun dari modul sourced pada saat build: provider ini mem-vendor file modul apa adanya, dan Terraform mengevaluasinya saat konfigurasi di-plan dan di-apply. Karena tidak ada yang dirender, tidak ada yang perlu dikecualikan, sehingga provider ini tidak mendeklarasikan bahwa ia mematuhi kunci tersebut, dan Recipe atau FeatureRecipe yang mendeklarasikannya ditolak sebelum apa pun di-vendor — lihat The provider does not support omits (Provider tidak mendukung omits). Untuk modul yang Anda simpan di samping Recipe, sebuah baris dalam .aggregaignore di sana mengecualikan file modul sebagai gantinya, mulai dari saat Recipe berikutnya di-pin.
Mengambil modul yang diterbitkan registry
Registry modul menerbitkan setiap versi modul sebagai tag dari repositori git milik modul itu sendiri, dan yang dijawabnya ketika diminta mengunduh sebuah versi adalah source git yang di-pin ke commit yang ditunjuk tag tersebut. Jadi, sebuah Recipe mengambil modul yang diterbitkan dari repositori tersebut pada tag tersebut, dengan jenis source git-repository:
spec: capability: terraform implements: example/storage/database:1.0.0 source: kind: git-repository url: https://github.com/terraform-aws-modules/terraform-aws-rds.git ref: v7.2.2 valuesMapping: | identifier: "{{ .values.identifier }}" provides: host: "${module.{{ .context.instance_id }}.db_instance_address}" port: "${module.{{ .context.instance_id }}.db_instance_port}"ref: adalah tag rilis persis seperti yang dinamai repositori. valuesMapping: menyediakan input modul, dengan nama yang dideklarasikan blok variable-nya — Terraform mewajibkan nilai untuk setiap input yang tidak mendeklarasikan default — dan input tersebut menjadi argumen blok module komponen ini dalam konfigurasi root, seperti untuk modul sourced mana pun.
Apa yang di-pin. aggrega pin dan pull meresolusi tag ke commit yang ditunjuknya dan mengarsipkan repositori pada commit tersebut. Lockfile Release kemudian mencatat commit tersebut sebagai versi source yang di-pin, tag sebagai referensi yang Anda tulis, dan digest arsip. Setiap build berikutnya membaca arsip dari cache dan memverifikasinya terhadap digest tersebut sebelum mem-vendor apa pun, sehingga tidak memerlukan jaringan, dan arsip cache yang byte-nya tidak lagi cocok akan menghentikan build. Tag adalah nama yang dapat dipindahkan repositori ke commit lain; pull berikutnya yang mendapati tag Anda teresolusi ke tempat lain akan berhenti alih-alih mengadopsi commit baru, dan aggrega pull --upgrade mengadopsinya secara sengaja. Itu adalah pin yang lebih ketat daripada dependency lock file milik Terraform sendiri, yang mencatat provider yang dipilih sebuah konfigurasi dan tidak mencatat modul sama sekali, sehingga modul yang ditulis ke dalam konfigurasi sebagai source git pada sebuah tag hanya setetap tag tersebut. Di sini, commit modul dan digest byte-nya ditetapkan dalam lock, byte-nya di-vendor ke dalam output, dan konfigurasi root memanggilnya melalui path lokal, sehingga engine tidak mengambil apa pun untuk memuat modul itu sendiri — modul yang dipanggil modul ter-vendor melalui source registry atau remote tetap diambil, dan build melaporkan setiap panggilan tersebut, seperti yang dijelaskan di Panggilan modul yang diambil engine saat inisialisasi.
Apa yang di-vendor. Seluruh repositori pada commit yang di-pin, kecuali direktori .git/-nya, ditempatkan di direktori milik komponen di bawah modules/, byte demi byte — file konfigurasi dan modul anak milik modul itu sendiri, serta apa pun lainnya yang dibawa repositori: direktori examples/ dan wrappers/-nya, dokumentasinya, konfigurasi CI-nya, dan fixture pengujian apa pun, termasuk yang biner. Engine hanya membaca apa yang dipanggil modul: ketika konfigurasi root memanggil direktori komponen, engine memuat file konfigurasi yang berada langsung di dalamnya dan di setiap direktori yang dijangkau source lokal dari sana. Direktori contoh yang memanggil modul registry lain karenanya di-vendor tetapi tidak pernah dimuat, dan tidak ada yang dipanggilnya yang diambil.
Mempersempit apa yang di-vendor. Source yang diambil adalah arsip seperti saat diambil, sehingga satu-satunya cara mempersempitnya adalah module_subdir:, yang menjadikan satu direktori repositori sebagai artefak. Itu hanya membantu ketika modul yang Anda inginkan berada di subdirektori: modul di root repositori yang memanggil ./modules/* miliknya sendiri memerlukan seluruh pohon. Baik .terraformignore yang dibawa repositori maupun .aggregaignore di samping Recipe tidak mengubah apa yang di-vendor source yang diambil — keduanya membentuk modul yang disimpan di samping Recipe, dan keduanya tidak dibaca untuk modul yang diambil dari repositori.
Membaca apa yang diterbitkan modul. Nilai yang diterbitkan modul adalah salah satu blok output-nya, dan konsumen membacanya sebagai ${module.<name>.<output>}, dengan <name> adalah blok modul produsen — itulah sebabnya produsen di atas menerbitkan ${module.{{ .context.instance_id }}.<output>}. Engine meresolusi referensi terhadap blok output milik modul saat memvalidasi konfigurasi root, sehingga nama output yang tidak dideklarasikan modul ditolak di sana, dengan menyebutkan namanya:
Error: Unsupported attribute on aggrega.modules.tf line 9, in module "api": 9: db_host = "${module.db.db_instance_addresz}"This object does not have an attribute named "db_instance_addresz".Build tidak membaca blok variable atau output modul, tidak menulis apa pun ke dalam modul, dan tidak menambahkan konfigurasi provider ke dalamnya, sehingga nama output yang salah ketik ditangkap oleh engine, bukan oleh build. Lihat Mengonsumsi nilai yang diterbitkan komponen lain untuk sisi konsumen.
Emisi verbatim dan vendoring
Provider terraform tidak mentranspilasi, memformat ulang, atau menulis ulang isi Terraform. Isi HCL atau .tf.json yang ditulis diemisikan persis seperti hasil evaluasi template-nya, dengan isi HCL yang diawali komentar provenans, dan modul bersumber di-vendor file demi file. Inilah yang menjaga keluaran terraform tetap deterministik dan dapat direproduksi: dengan masukan yang sama, konfigurasi yang dirender identik byte demi byte di setiap eksekusi, dan modul yang di-vendor bolak-balik tanpa perubahan. Karena provider tidak pernah menyelesaikan state runtime, segala sesuatu yang bergantung pada runtime tetap berupa string interpolasi yang diikat oleh Terraform pada saat apply.
Anotasi platform
Provider terraform tidak membaca satu pun anotasi aggrega.ai/. Modul yang di-vendor, file artefak sebuah Recipe, dan konfigurasi root yang ditulis provider tidak memiliki tempat untuk namespace, prefiks registry, pull secret, atau service account, sehingga nilai yang ditetapkan untuk salah satunya tidak mengubah apa pun dalam konfigurasi yang dirender; modul yang memerlukan nilai seperti itu menerimanya sebagai salah satu inputnya sendiri, melalui values milik komponen.
Provider menyatakan hal ini dalam entitas Plugin miliknya, dengan readsNoWellKnownAnnotations: true (lihat entitas Plugin), sehingga build memberikan peringatan untuk setiap anotasi aggrega.ai/ yang mencapai sebuah render melaluinya — sekali per kunci dan per render, dengan menyebutkan input kind yang dideklarasikan render tersebut:
warning: node "db" (provider "terraform"): target "terraform" does not support annotation aggrega.ai/namespace on sourced input and ignored itNilai tersebut tetap melewati build tanpa diubah, dan build tidak dihentikan: anotasi boundary berkaskade ke setiap komponen di bawahnya, dan boundary yang komponennya dirender melalui target yang berbeda adalah hal biasa, bukan kesalahan. Peringatan ini termasuk dalam kelas unsupported-field dan dibungkam dengan flag kelas tersebut.
Input modul yang dideklarasikan sensitif
Terraform adalah satu-satunya target pustaka standar yang memiliki primitif sensitivitas per nilai secara native, sehingga datum yang dideklarasikan sensitif oleh penulis dapat dirender dalam istilah Terraform sendiri, alih-alih hanya dicatat dalam istilah Aggrega.
Ketika input modul yang di-vendor membawa materi yang dideklarasikan sensitif oleh penulis, provider menambahkan satu file lagi di samping modul, aggrega_override.tf.json, yang mendeklarasikan sensitive = true untuk input tersebut:
{ "variable": { "db_password": { "sensitive": true } }}Terraform menggabungkan file konfigurasi yang namanya persis override atau berakhiran _override ke dalam konfigurasi di direktori yang sama, sehingga blok variable milik modul itu sendiri memperoleh atribut tersebut sementara setiap byte yang di-vendor tetap persis seperti yang ditulis. Tipe, nilai bawaan, dan deskripsi input yang dideklarasikan tidak diubah — override hanya membawa atribut sensitivitas, tidak lebih. Node yang tidak ditandai tidak mendapatkan file semacam itu.
Batasan itu disengaja, bukan sesuatu yang dipaksakan oleh format file: tidak ada apa pun dalam override yang menolak atribut kedua, dan default pada blok variable adalah slot terdekat yang dapat digunakan jika Anda ingin membawa sebuah nilai ke dalam modul yang di-vendor tanpa mengubah byte-nya — tetapi nilai itu tidak akan sampai. default dalam sintaks konfigurasi JSON yang digunakan file ini bukanlah posisi yang dievaluasi oleh Terraform, sehingga nilai yang membawa pointer ${ ... } yang ditulis di sana sampai ke modul sebagai karakter literal pointer tersebut, pada plan yang berhasil tanpa memberi keterangan apa pun. Pointer yang sama yang ditulis ke dalam default pada HCL native langsung ditolak, yang menempatkan kebisuan itu pada sintaks ini, bukan pada file override itu sendiri. Karena itu override hanya membawa sensitive: maknanya tidak bergantung pada evaluasi.
Input mana yang ditandai berasal dari deklarasi, tidak pernah dari nama. Provider membaca penandaan yang dihitung oleh kompilasi dan tidak memeriksa apa pun sendiri: provider tidak mengenali password, secret, atau token, dan tidak membaca teks modul untuk menebak. Input modul bernama db_password yang nilainya tidak membawa deklarasi dikeluarkan tanpa tanda, dan input bernama region yang dideklarasikan akan ditandai.
Penandaan hanya dibawa ke tempat identitas input dapat dipulihkan dari deklarasi. Recipe yang me-vendor modul dengan source: dan membiarkan daun values yang dideklarasikan node langsung menjadi input modul memberi setiap input nama yang sama dengan yang dideklarasikan penulis, sehingga keterkaitannya tepat — demikian pula FeatureRecipe dari Feature yang dilampirkan ke komponen yang me-vendor modul dengan cara yang sama, atas daun-daun yang dideklarasikan Feature-nya. Recipe atau FeatureRecipe semacam itu yang membentuk ulang nilai-nilai tersebut melalui templat valuesMapping: menciptakan nama output-nya sendiri, dan tidak ada deklarasi yang menamainya — sehingga penandaan tidak ada alih-alih diperkirakan, dan build menyatakannya dengan satu saran per daun yang dideklarasikan, dengan menyebut daun tersebut dan entitas pemilik pemetaannya (Feature yang dilampirkan ke boundary dirender tanpa values sama sekali, sehingga tidak ada yang perlu ditandai dan tidak memunculkan saran apa pun); lihat A declared-sensitive value reaches the target through a values mapping (Nilai yang dideklarasikan sensitif mencapai target melalui pemetaan nilai). Ketiadaan ini disengaja: menebak input hasil pembentukan ulang mana yang membawa datum yang dideklarasikan akan menandai input publik sebagai rahasia, dan Terraform kemudian akan menyembunyikan dari output plan sebuah nilai yang sebenarnya tidak pernah sensitif.
Contoh terraform-declared-sensitivity membangun hal ini dari awal hingga akhir dan cukup kecil untuk dibaca seluruhnya: satu komponen yang mendeklarasikan tiga daun values, dua di antaranya membawa pengenal publik dan satu membawa kredensial. Output yang dirender menunjukkan argumen blok module yang membawa ketiga input modul dan override yang hanya menyebut input yang dideklarasikan, sehingga kedua sisi aturan terlihat dalam build yang sama — termasuk bahwa pengenal kredensial yang berada di samping rahasia dibiarkan tanpa tanda. Menghapus satu deklarasi itu lalu membangun ulang tidak menghasilkan file override sama sekali.
Apa yang dijamin dan tidak dijamin oleh sensitive milik Terraform
Aggrega menjanjikan persis apa yang diberikan oleh atribut Terraform itu sendiri, tidak lebih.
Atribut ini membatasi tampilan. Nilai sensitif terbaca sebagai (sensitive value) pada output plan dan <sensitive> pada output apply. Penandaan menjalar melalui ekspresi, sehingga nilai yang diturunkan dari input sensitif juga sensitif, dan Terraform menolak mengekspornya dari output root yang tidak ditandai sensitif — galat yang jelas terlihat, bukan pengungkapan diam-diam.
Atribut ini tidak mengubah penyimpanan, dan bukan enkripsi. Terraform mencatat nilai sensitif di state dalam bentuk teks biasa. Membaca sensitive = true sebagai janji bahwa state aman untuk di-commit atau dibagikan adalah satu-satunya salah tafsir yang harus dihindari: perlindungan state tetap bergantung pada cara backend state dikonfigurasi, persis seperti untuk modul yang sama sekali tidak membawa penandaan. Atribut ini juga tidak membatasi siapa yang dapat membaca nilai tersebut, tidak memengaruhi apa yang dikirimkan provider, dan tidak mengubah konfigurasi yang dirender dengan cara lain apa pun.
Jadi penandaan membuat input yang dideklarasikan sensitif lebih sulit terungkap secara tidak sengaja ketika seseorang membaca plan. Penandaan tidak membuat hasil deployment aman untuk dipublikasikan. Lihat Mendeklarasikan daun sebagai sensitif untuk kata kuncinya dan untuk apa yang dicapai sebuah deklarasi di setiap target.
Validasi struktural input
Provider terraform memvalidasi struktur modul bersumber sebelum melakukan render. Provider ini mem-parse file HCL dan .tf.json milik modul serta melaporkan kesalahan parse, menghentikan build dengan pesan yang jelas yang menyebutkan node yang bermasalah dan provider-nya. Parse ini memeriksa bentuk, bukan semantik — parse tidak me-resolve provider, tidak mengevaluasi ekspresi, dan tidak menghubungi registry. Validasi bersifat hermetis: validasi menggunakan parser HCL mandiri yang dikompilasi ke dalam provider, tanpa biner terraform dan tanpa akses jaringan. Modul yang rusak tertangkap di batas penulisan, alih-alih muncul sebagai kesalahan yang membingungkan pada eksekusi terraform berikutnya.
Pemanggilan modul yang diambil mesin saat inisialisasi
Pembacaan yang sama melaporkan, sebagai peringatan yang tidak menolak apa pun, setiap blok module yang sumbernya diunduh Terraform saat konfigurasi diinisialisasi. Commit dan digest arsip dari modul yang di-vendor ditetapkan dalam lock, tetapi blok module di dalamnya yang source-nya berupa alamat registry, URL git, Mercurial, atau arsip HTTP, bucket S3 atau GCS, atau path absolut menunjuk modul yang diambil mesin saat inisialisasi, pada versi apa pun yang dipilihnya saat itu — dan file dependency lock milik Terraform sendiri hanya mencatat provider, sehingga tidak ada yang mengunci modul tersebut. source lokal yang keluar dari modul yang di-vendor juga dilaporkan, karena menunjuk file yang tidak di-vendor oleh build. Setiap temuan menyebutkan node dan provider, lalu blok, file dan baris tempatnya berada, serta sumber sebagaimana ditulis:
warning: node "app" (provider "terraform"): module "vpc" (main.tf, line 2) has the source "terraform-aws-modules/vpc/aws", which Terraform downloads when the configuration is initialised, at whatever version it then selects, so no commit or digest this build records covers that moduleApa yang dibaca. File yang dimuat mesin saat modul dipanggil: file konfigurasi yang langsung berada di direktori modul itu sendiri, lalu file di setiap direktori yang dicapai dari sana oleh source lokal — yang diawali ./ atau ../, atau ejaan backslash-nya — diikuti dari direktori ke direktori dan masing-masing dibaca sekali. Direktori yang tidak dipanggil apa pun tidak dibaca, sehingga pemanggilan yang dilakukan direktori examples/ atau tests/ milik modul tidak dilaporkan: mesin tidak pernah memuatnya saat modul dipanggil, dan tidak ada yang dipanggilnya yang diambil. Pemeriksaan parse di atas tetap mem-parse setiap file konfigurasi yang di-vendor. Badan yang ditulis dalam sebuah Recipe dibaca dengan cara yang sama saat di-render, dimulai dari direktori tempat badan itu ditulis, sehingga blok module yang ditulis badan tersebut dengan sumber registry juga dilaporkan. File di bawah spec.boundary.artifacts dievaluasi dan ditulis oleh compiler sendiri dan tidak diserahkan ke provider mana pun, sehingga blok module yang ditulis di dalamnya tidak dibaca dan tidak memicu peringatan.
Apa yang tidak dibaca. Hanya apa yang dinyatakan oleh source yang dibaca. Build tidak membaca modul yang ditunjuk pemanggilan, tidak menilai apa yang dilakukan modul itu, dan tidak memutuskan apakah pemanggilan tersebut dapat diterima. source yang dievaluasi mesin alih-alih dibaca sebagaimana ditulis — yang memuat interpolasi, atau referensi — dinilai dari teks awalnya: yang diawali alamat dilaporkan sebagaimana ditulis, sedangkan yang diawali prefiks lokal, atau dengan interpolasi itu sendiri, tidak dilaporkan maupun diikuti, karena ke mana arahnya tidak ada dalam teks. source di dalam required_providers menunjuk provider, bukan modul, dan bukan pemanggilan modul.
Mengapa dilaporkan alih-alih ditolak. Modul yang memanggil modul lain adalah input yang sah: Terraform mengambil modul yang dipanggil dan konfigurasinya berfungsi. Yang dilepaskan penulis adalah penguncian build atas modul yang dipanggil, yang merupakan fakta yang patut diketahui, bukan kesalahan yang harus diperbaiki, dan apakah pengambilan itu dapat diterima merupakan pertimbangan penulis. Konfigurasi yang harus tetap terkunci sepenuhnya hanya me-vendor modul yang tidak melakukan pemanggilan semacam itu. Peringatan ini, kode kelasnya, dan ke mana lagi jangkauannya dijelaskan dalam Peringatan dan output linter.
Batas patch FeatureRecipe
Langkah pipeline FeatureRecipe pasca-render hanya mem-patch keluaran yang dirender provider ke dalam pohon terstruktur. Untuk terraform, hal ini berarti:
- Terraform yang ditulis dalam JSON dapat di-patch. Modul
.tf.jsonadalah dokumen terstruktur, sehingga JSONPatch dari sebuah langkah pipeline menyunting nilai yang dituju di tempatnya dan membiarkan setiap byte lainnya — urutan, format, kunci di sekitarnya — tidak tersentuh. - HCL native bersifat opak. Body HCL native (
main.tf) bukan target patch terstruktur. Patch terhadap body yang opak menghentikan build dengan sebuah diagnostik alih-alih mengubah teks yang tidak dapat dituju secara struktural; menulis langkah pipeline terhadap body HCL adalah kesalahan desain yang dimunculkan sebagai penghentian yang jelas, bukan no-op yang diam-diam. - Input modul bersumber sama sekali bukan target patch. Input tersebut adalah argumen blok
modulemilik komponen, yang berada di konfigurasi root: HCL native, sehingga opak, dan merupakan artefak dari seluruh boundary, bukan dari satu node mana pun. Langkahpipelinemem-patch keluaran yang dirender milik node itu sendiri, sehingga tidak ada posisi untuk menuju input tersebut.
Oleh karena itu, penulis yang membutuhkan body Terraform agar dapat di-patch oleh pipeline menulisnya sebagai .tf.json. Lihat FeatureRecipe untuk batas target patch umum di seluruh provider.
Urutan deployment
Nilai syncWave: dari sebuah batas Release mengurutkan blok module dalam konfigurasi root tempat batas tersebut dirakit. Setiap komponen dalam batas mewarisi wave batas tersebut, dan apabila beberapa batas mengarah ke direktori keluaran yang sama — sehingga komponen-komponennya disusun ke dalam satu konfigurasi root — root tersebut memuat lebih dari satu wave dan provider menyatakan urutan di antara wave-wave tersebut sebagai depends_on pada blok module.
Setiap modul menyebut setiap modul dari wave yang tepat sebelumnya yang memiliki komponen, dan tidak menyebut wave yang lebih awal dari itu. Terraform merangkai sisanya: modul di wave 2 bergantung pada wave 1, yang bergantung pada wave 0, sehingga seluruh urutan teratur sementara daftar milik setiap modul hanya sebesar satu wave, bukan sebesar seluruh batas. Wave tidak harus berurutan tanpa celah, dan nilai negatif adalah hal biasa — -1 merupakan pilihan umum untuk bucket atau role yang dibaca oleh bagian lain konfigurasi. Wave terendah tidak menyebut apa pun, karena tidak ada yang mendahuluinya.
Apa arti urutan ini: urutan Terraform menjalankan tindakannya. Terraform membangun graf dependensi dan memprosesnya secara paralel sejauh yang dimungkinkan graf tersebut. depends_on menambahkan sebuah sisi pada graf itu, sehingga Terraform menyelesaikan tindakannya pada modul yang disebut sebelum memulai tindakan pada modul yang mendeklarasikan dependensi tersebut. Dengan demikian, wave membagi eksekusi menjadi tahapan: komponen wave yang lebih awal ditindak sebelum komponen wave berikutnya dimulai.
Ini bukan pengurutan kesiapan. Konfigurasi Terraform tidak mengenal konsep sumber daya yang siap melayani, sehingga tidak ada yang menunggu sumber daya menjadi siap — hanya menunggu Terraform selesai menindaknya. Ini merupakan perbedaan nyata dari wave yang sama pada compose, di mana layanan yang mendeklarasikan healthcheck ditunggu hingga melaporkan status sehat: compose memiliki primitif kesiapan sebagai acuan, sedangkan konfigurasi Terraform tidak memilikinya. Urutan tindakan adalah yang ditawarkan target ini, dan menyatakannya secara lugas lebih berguna daripada catatan peringatan yang menyertai janji yang tidak dapat dipenuhinya.
Tidak ada urutan pembongkaran yang dijanjikan. Yang dinyatakan depends_on adalah bahwa Terraform menyelesaikan tindakan dependensi sebelum memulai tindakan pihak yang bergantung; urutan destroy menghapusnya bukan bagian dari pernyataan itu, sehingga tidak ada klaim di sini tentang urutan pembongkaran. Janji ini lebih sempit daripada yang dibawa wave yang sama pada cloudformation, yang atributnya mengatur kedua arah — perlu diketahui jika Anda mengandalkan wave untuk mengurutkan pembongkaran, karena pada target ini hal itu tidak terjadi.
Batas yang seluruh komponennya membawa satu wave tidak mendapatkan apa pun dari ini. Demikian pula Release yang sama sekali tidak mendeklarasikan syncWave: setiap kontributor membawa nilai bawaan field tersebut, yaitu 0, konfigurasi root memuat satu wave saja, dan byte yang dihasilkan persis sama seperti jika provider tidak menyatakan pengurutan wave.
Pengurutan antara dua konfigurasi root tidak dapat dinyatakan, dan tidak didekati. Graf dependensi Terraform berlaku per konfigurasi dan depends_on menyebut modul di dalam konfigurasi yang mendeklarasikannya, sehingga wave mengurutkan setiap komponen yang disusun ke dalam root tersebut dan tidak ada yang di luarnya. Mengurutkan dua konfigurasi merupakan urusan operator, sama seperti referensi remote-state merupakan resolusi saat deploy, bukan saat build.
Wave dicatat sekaligus ditindaklanjuti: wave ikut bersama provenans build node lainnya, sebagai aggrega.ai/sync-wave dalam blok komentar yang dibubuhkan, atau dalam berkas provenans pendamping jika body berupa JSON atau modul yang di-vendor. Dengan demikian, konfigurasi yang dirender mencatat wave mana yang dideklarasikan batasnya sekaligus diurutkan olehnya.
Pengurutan yang tidak dinyatakan oleh wave tetap menjadi urusan Terraform sendiri, dan referensi antarsumber daya sudah mencakup sebagian besarnya: referensi ke atribut sumber daya lain memberi tahu Terraform untuk menindak sumber daya tersebut terlebih dahulu. Modul yang memerlukan batasan yang tidak tersirat dari referensi maupun wave menulis depends_on miliknya sendiri di dalam modul, yang dihasilkan provider apa adanya seperti setiap bagian lain dari body.
Referensi terkait
- Arsitektur Provider — bagaimana provider ditempatkan dalam pipeline kompilasi dan dispatch per provider.
- Indeks referensi Provider — apa yang dihasilkan oleh setiap provider pustaka standar, dan halaman mana yang menjawab pertanyaan mana.
- Entitas Recipe — permukaan penulisan Recipe dan tiga jenis input.
- FeatureRecipe — model patch
pipelinepascarender beserta batas terstruktur/opaknya. - Komposisi input Recipe — Matriks Kapabilitas Provider yang kanonis.