Terraform Provider
Provider terraform kết xuất các Aggrega Recipes thành cấu hình Terraform. Nó phát sinh cấu hình và không bao giờ chạy Terraform: một bản build Aggrega là một quá trình biên dịch trước (ahead-of-time), vì vậy nó không thể phân giải các ID tài nguyên, địa chỉ IP và các output chỉ tồn tại sau terraform apply. Các phép nội suy ${ ... } của Terraform được truyền qua nguyên vẹn dưới dạng các chuỗi con trỏ tất định mà runtime của Terraform sẽ phân giải sau. Provider này hoạt động ngoại tuyến và khép kín — nó không bao giờ truy cập mạng và không bao giờ gọi terraform hay tofu.
Cách bố trí một boundary
Provider terraform kết hợp một boundary thay vì xuất các component của nó cạnh nhau. Mỗi boundary mà nó render có một cấu hình gốc, aggrega.modules.tf, khai báo mỗi component được render ở đó dưới dạng một khối module có source là thư mục con riêng của component đó dưới modules/:
module "cache" { source = "./modules/cache"}
module "db" { source = "./modules/db"
allocated_storage = 100 db_name = "appdb" engine_version = "11.4"}Các tệp riêng của mỗi component — module được vendor hoặc phần thân do tác giả viết, cùng dấu nguồn gốc — nằm trong thư mục con mà khối của nó trỏ tới. Đây là cấu trúc chuẩn của Terraform, trong đó gốc kết hợp các module con, với quy ước là các module lồng nhau nằm dưới một thư mục con modules/, và đó là bố cục mà mọi boundary terraform đều có, dù nó chứa một hay nhiều component. Một Feature gắn vào một component hoặc vào boundary được khai báo thành một khối module riêng trong cùng cấu hình gốc — xem Nơi đầu ra của một Feature được gắn được đặt.
Hình dạng này mang tính chịu lực chứ không phải để trang trí, vì hai lý do.
Đồ thị phụ thuộc của Terraform là riêng cho từng cấu hình. Các Components được xuất ra các thư mục riêng biệt là những đồ thị riêng biệt, không có quan hệ gì với nhau: cả một tham chiếu lẫn một depends_on đều không thể vươn từ đồ thị này sang đồ thị kia, và không có một terraform plan đơn lẻ nào nhìn thấy cả hai. Một root kết hợp từng component thành một module con sẽ đặt toàn bộ một boundary vào một đồ thị và một plan.
Các tệp của một component được định vị bằng thư mục riêng của nó. Hai component trong một boundary có thể vendor các module ghi ra các tệp trùng tên — main.tf, variables.tf — và mỗi bộ tệp nằm dưới thư mục của component tương ứng thay vì tranh chấp một đường dẫn.
Nơi cấu hình một provider
Cấu hình của một provider — một khối provider — được ghi ở gốc, không bao giờ nằm trong module của một component. Tài liệu của Terraform nói rằng một module được thiết kế để module khác gọi không được chứa các khối provider, và một module được gọi sẽ kế thừa cấu hình mặc định của gốc cho mỗi provider mà module đó dùng. Một module mang khối provider riêng không thể được gọi với depends_on, count hay for_each, và provider này ghi depends_on lên khối module của một component mỗi khi một component khác của cùng gốc mang syncWave sớm hơn, như phần Thứ tự triển khai bên dưới mô tả; khi đó Terraform từ chối toàn bộ cấu hình ngay lúc tải, trước khi lập plan cho bất cứ thứ gì.
Vì vậy, một Recipe có provider cần được cấu hình sẽ ghi cấu hình đó thành một tệp dưới spec.boundary.artifacts. Mỗi tệp như vậy được ghi một lần bên cạnh aggrega.modules.tf, nơi Terraform đọc nó cùng với cấu hình gốc, và module của component chỉ giữ lại khai báo required_providers về nguồn và phiên bản của provider:
infra/terraform/ aggrega.modules.tf provider-azurerm.tf modules/ gateway/main.tfCác Components của cùng một root khai báo cùng một tệp với cùng các byte sẽ dùng chung một bản sao; cùng tên nhưng khác byte sẽ dừng bản build. Tài nguyên của các module được ghi nhận theo cấu hình duy nhất đó, nên đó cũng là cấu hình mà Terraform dùng để hủy chúng. Một Release loại bỏ component cuối cùng khai báo tệp đó cũng sẽ loại bỏ tệp cùng với nó, và khi đó Terraform từ chối lập plan cho việc hủy những gì các module đó đã tạo, yêu cầu một khối provider cấu hình provider. Hãy hủy các tài nguyên đó trước khi loại bỏ component cuối cùng như vậy.
Nơi cung cấp các đầu vào của một component
Các đầu vào của một component là các đối số của khối module của nó trong cấu hình gốc, và đó là nơi duy nhất chúng được ghi. Một khối mang đối số khi trình biên dịch cung cấp các đầu vào của module — một Recipe vendor một module bằng source:. Khối để trống khi Recipe tự viết phần thân cấu hình và đã phân giải các giá trị của nó vào phần thân đó, nên không còn gì để trình biên dịch truyền.
Một đối số module là vị trí mà Terraform đánh giá, đó là lý do các giá trị được đặt ở đó. Một con trỏ ${ ... } do Recipe cung cấp được phân giải tại đó thay vì đến module dưới dạng chuỗi ký tự thuần. Thứ mà nó được phân giải dựa trên là cấu hình gốc: một tham chiếu chỉ tới thứ mà cấu hình đó khai báo — một trong các khối module của nó, dưới dạng module.<name>.<output> — và tham chiếu tới bất cứ thứ gì nó không khai báo là một lỗi rõ ràng lúc lập plan, nêu tên đối tượng được tham chiếu bị thiếu.
Do đó, thư mục riêng của một component không phải là cấu hình mà bạn có thể lập plan như khi được triển khai. Các đầu vào của nó được khai báo ở cấp trên, trong gốc, nên đứng trong modules/<component> và chạy engine ở đó sẽ lập plan cho một thứ khác, và nó làm điều nào trong hai điều phụ thuộc vào các khối variable riêng của module:
- Khi có ít nhất một đầu vào không khai báo
default, plan thất bại rõ ràng —No value for required variable(Không có giá trị cho biến bắt buộc), nêu tên từng biến chưa được đặt và dòng của nó, và đề xuất cách khắc phục-var/-var-filecủa chính Terraform. - Khi mọi đầu vào đều mang
default, plan thành công và build từ các giá trị mặc định của module thay vì từ các giá trị mà cấu hình gốc cung cấp. Không có cảnh báo nào, nên đây là trường hợp cần biết: một plan trông có vẻ đúng lại đang mô tả một cấu hình không ai yêu cầu.
Thay vào đó, hãy lập plan cho thư mục đầu ra riêng của boundary — thư mục chứa aggrega.modules.tf, ngay bên trên modules/. Đó là nơi có các giá trị của bản triển khai, và là nơi duy nhất một plan thấy được toàn bộ boundary.
Tiêu thụ giá trị được công bố của một component khác
Một component được nối với component khác bằng một cạnh uses đọc các giá trị được công bố của component đó qua pipe .context.inject của chính nó (hoặc qua .context.uses.<alias>.provides.<name>). Thứ nó đọc là một chuỗi mà trình biên dịch truyền qua mà không diễn giải, và nơi chuỗi đó được đặt là văn bản Terraform đánh giá trong phạm vi mà Recipe đã ghi nó vào. Một boundary terraform có hai phạm vi như vậy, và chỉ một trong số đó khai báo các lời gọi module mà một tham chiếu liên component cần:
- cấu hình gốc khai báo mọi bên đóng góp dưới dạng một khối
module, nênmodule.<name>.<output>được phân giải ở đó; - thư mục riêng của một component hoàn toàn không khai báo lời gọi module nào, nên
module.<name>.<output>không chỉ tới thứ gì ở đó — bất kể<name>là gì. Thay bằng tên đúng cũng không thay đổi gì, vì thứ bị thiếu là khai báo, không phải cách viết.
Vì vậy, loại đầu vào của Recipe tiêu thụ quyết định việc một tham chiếu được tiêu thụ có thể phân giải hay không, còn giá trị được tiêu thụ thì không quyết định điều đó.
Hãy viết một Recipe tiêu thụ dưới dạng một Recipe source:. valuesMapping: của nó trở thành các đối số của khối module riêng của nó trong cấu hình gốc — vị trí duy nhất vừa được đánh giá vừa nằm trong phạm vi mà các thành phần lân cận của nó được khai báo.
Một cặp ví dụ hoàn chỉnh
Bên cung cấp công bố một địa chỉ chỉ tới lời gọi module của chính nó, đó là dạng mà phạm vi của bên tiêu thụ khai báo. .context.instance_id nằm trên bề mặt đánh giá provides, và với một component mà Aggregate của bản triển khai khai báo, đó là tên mà khối module của component đó mang:
# 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}"Bên tiêu thụ vendor một module khai báo một đầu vào, và ánh xạ giá trị được inject vào đó:
# 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 nối chúng với nhau, nêu tên khóa được công bố mà cạnh mang theo:
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: endpointBản build xuất ra một cấu hình gốc, trong đó tham chiếu và đối tượng được tham chiếu được khai báo cùng nhau:
module "api" { source = "./modules/api"
store_endpoint = "${module.store.endpoint}"}
module "store" { source = "./modules/store"
bucket = "app-artifacts"}Terraform phân giải module.store.endpoint vì cùng cấu hình đó khai báo module "store", và giá trị đến module của bên tiêu thụ như một đầu vào bình thường.
Ví dụ aws-rds-and-ecs-service xây dựng cặp này từ các Recipes của thư viện chuẩn: một cơ sở dữ liệu PostgreSQL được cấp phát bởi module RDS đã công bố và một máy chủ chạy trên Amazon ECS, có đối số environment mang ${module.db.db_instance_address} trong cấu hình gốc khai báo module "db".
Ba cách điều này có thể sai, và biểu hiện của từng cách
Một Recipe tự viết phần thân của mình không thể tiêu thụ một tham chiếu liên component. Một Recipe artifacts: phân giải các giá trị của nó vào phần thân mà nó viết, và phần thân đó được xuất ra thư mục riêng của component. Khi đó tham chiếu nằm trong một phạm vi không khai báo lời gọi module nào:
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.Không có cách viết nào khắc phục được điều này, vì các biểu thức của một module lồng nhau hoàn toàn không thể gọi tên một module anh em — một module lồng nhau chỉ nhận giá trị của module lân cận dưới dạng một đầu vào, chính là đối số của khối module mà đường dẫn có nguồn đã cung cấp. Một component tiêu thụ giá trị được công bố của một component khác được viết dưới dạng một Recipe source:.
Một địa chỉ gọi tên thứ gì đó bên trong module riêng của bên cung cấp được phân giải theo root, không theo module đó. Một mục provides viết aws_db_instance.this.endpoint gọi tên một tài nguyên mà module của bên cung cấp khai báo; khi được viết dưới dạng nội suy, nó được đánh giá tại nơi đối số của bên tiêu thụ nằm, tức là 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.Hãy công bố ${module.<...>.<output>} và cung cấp cho module một khối output cho giá trị đó, thay vì truy cập vào các tài nguyên của nó.
Một mục provides không chứa nội suy được chuyển giao dưới dạng văn bản. Đây là trường hợp không thất bại: trình biên dịch truyền các chuỗi và không thể phân biệt một con trỏ với một giá trị literal, nên aws_db_instance.this.endpoint viết không có ${ ... } được kết xuất thành một chuỗi trong dấu ngoặc kép, bản build thành công, engine xác thực, và bên tiêu thụ nhận được các ký tự aws_db_instance.this.endpoint. Hãy viết lớp bọc ${ ... } bất cứ khi nào giá trị được dùng làm tham chiếu — chính nó đánh dấu chuỗi là thứ để Terraform đánh giá.
Một giới hạn nên biết trước khi bạn dựa vào nó
.context.instance_id biểu diễn danh tính của component, còn tên của một khối module được suy ra từ thư mục chứa các tệp của component. Với một component mà chính Aggregate của bản triển khai khai báo, hai thứ đó là cùng một tên. Với một component được kết hợp vào từ một Aggregate khác thì không: danh tính kết hợp và tên module được viết vào hai bảng chữ cái của chúng theo cách khác nhau, và khi đó tham chiếu thất bại rõ ràng tại root thay vì âm thầm:
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.Hãy khai báo một bên cung cấp có địa chỉ được một component khác phân giải trong chính Aggregate của bản triển khai, cùng với component tiêu thụ nó.
Nơi đầu ra của một Feature được gắn vào
Một phần gắn Feature kết xuất cấu hình riêng sẽ nhận được một module riêng, được khai báo trong cùng cấu hình root với các component bên cạnh nó. Đây chính là điều khiến cấu hình của nó trở thành một phần của bản triển khai: Terraform chỉ tải các tệp nằm trực tiếp trong một thư mục và coi một thư mục lồng nhau là một module hoàn toàn tách biệt cần được gọi tường minh, nên các tệp của một phần gắn được đọc vì root khai báo một khối gọi tên thư mục chứa chúng.
Thư mục module của một phần gắn nằm bên cạnh thư mục của component, ở một cấp dưới modules/, và được đặt tên theo hai yếu tố định danh nó — component chứa nó và tên mà nó được gắn, nối bằng --. Vì vậy với một component api mang một phần gắn có tên aux, cấu hình root khai báo hai module:
module "api--aux" { source = "./modules/api--aux"}
module "api" { source = "./modules/api"}Một Feature được gắn tại boundary thay vì tại một component thì không có component chủ để gọi tên, nên thư mục của nó chỉ mang tên riêng của nó: một phần gắn có tên aux trên một boundary chứa component api tạo ra ./modules/aux bên cạnh ./modules/api.
Vì sao bên cạnh thay vì bên trong. Terraform gộp mọi tệp cấp cao nhất trong một thư mục module vào một không gian tên — output, variable, resource và locals đều như nhau — nên hai bên đóng góp dùng chung một thư mục sẽ xung đột ở bất kỳ tên nào mà cả hai cùng khai báo, bất kể tệp của chúng tên gì. Mỗi bên một thư mục là điều giữ chúng tách biệt. Bên cạnh thay vì bên trong cũng là điều mà hướng dẫn của chính Terraform cho các module lồng nhau yêu cầu: chúng có thể được bên gọi kết hợp, thay vì gọi trực tiếp lẫn nhau và tạo ra một cây module lồng sâu.
Phép nối được thoát ký tự theo từng tọa độ. Mỗi tọa độ trong hai tọa độ được viết vào bảng chữ cái thư mục trước khi nối, nên một tọa độ tự chứa -- không thể bị nhầm với phép nối: một chủ có tên a--b với phần gắn c phân biệt được với một chủ a với phần gắn b--c. Chữ cái ASCII ở cả hai dạng hoa thường, chữ số, dấu chấm và dấu gạch dưới được giữ nguyên; một dấu gạch nối bạn viết được giữ lại ở bất cứ đâu ký tự theo sau nó là một trong các ký tự đó; mọi ký tự khác đều được thoát. Cùng quy tắc và cùng bảng chữ cái tạo ra các thư mục con của một target chart, nên thư mục của một phần gắn được viết giống nhau dù target nào trong hai target kết xuất nó.
Tên của một khối được suy ra từ thư mục mà source của nó trỏ tới, với mỗi ký tự nằm ngoài ngữ pháp của Terraform cho tên module được thay bằng dấu gạch dưới. Ánh xạ đó không phải một-một, nên khi hai bên đóng góp sẽ cùng dẫn tới một tên module, bản build dừng lại và gọi tên cả hai, thay vì xuất ra một cấu hình mà Terraform sẽ từ chối.
Có ba hệ quả từ việc một phần gắn là một module riêng.
Các đầu vào của nó là của ánh xạ riêng của nó. Một phần gắn có FeatureRecipe lấy nguồn một module và khai báo một valuesMapping sẽ có các giá trị mà ánh xạ đó tạo ra được viết làm đối số của khối module riêng của nó, giống như cách module có nguồn của một component nhận giá trị. Một FeatureRecipe không khai báo valuesMapping không truyền đối số nào cho module của nó: một biến mà module khai báo với default sẽ nhận giá trị đó, còn biến được khai báo không có giá trị mặc định thì bị bỏ trống, nên Terraform từ chối plan.
Các tài nguyên của nó nằm trong một đồ thị phụ thuộc duy nhất của boundary. Một tham chiếu hoặc một depends_on có thể nối giữa một phần gắn và component mà nó được gắn vào, và một terraform plan thấy được cả hai — cùng tính chất mà cấu trúc root kết hợp các module con mang lại cho các component, vì cùng lý do.
Các tên cấp cao nhất của nó là của riêng nó. Vì việc gộp không gian tên mô tả ở trên là theo từng thư mục, một bên đóng góp nằm trong thư mục riêng khai báo các tên output, variable, resource và locals mà không tranh chấp với các bên lân cận — nên một phần gắn có thể dùng lại một tên mà chủ của nó đã khai báo, và không bên nào cần biết bên kia đặt tên gì.
Lưu ý điều mà target này không yêu cầu, vì ràng buộc của một target chart thì khác và cách bố trí dùng chung có thể bị hiểu là ngụ ý nhiều hơn thực tế: một module lồng bên trong thư mục của một bên đóng góp khác vẫn truy cập được ở đây, vì cấu hình root đọc source của mỗi bên đóng góp từ vị trí mà bản build đã kết hợp thay vì dựng lại nó từ một định danh. Điều target này từ chối là hai bên đóng góp dùng chung một thư mục. Một target chart từ chối hoàn toàn vị trí lồng nhau, vì nó chỉ tìm chart con ở một cấp bên dưới và không xa hơn.
Các loại đầu vào được hỗ trợ
Provider terraform chấp nhận hai trong ba loại đầu vào của Recipe:
- Chế độ artifacts. Một Recipe viết cấu hình Terraform dưới dạng một phần thân có template; provider đánh giá template Aggrega và xuất kết quả mà không viết lại nó. HCL (
main.tf) là mặc định tiện dụng, và Terraform JSON (.tf.json) được chấp nhận tương đương. Nguồn gốc bản dựng được đóng dấu dưới dạng một khối chú thích Terraform ở đầu phần thân HCL; với phần thân JSON — vốn không có cú pháp chú thích — nguồn gốc được ghi vào một tệp đi kèm,aggrega.provenance.tf, thay vì nội tuyến. - Chế độ sourced. Một Recipe tham chiếu đến một module Terraform bằng
source:. Các tệp của module được vendor nguyên văn vào thư mục của component đó, vàvaluesMapping:của Recipe trở thành các đối số của khốimodulecủa component đó trong cấu hình gốc của boundary. Phần thân module được giữ nguyên đúng như khi viết và không có gì được ghi vào đó; các giá trị được nêu một lần, ở gốc, nơi Terraform đánh giá chúng. Khi các lávaluesđược khai báo của node trực tiếp trở thành đầu vào của module — một Recipesource:không cóvaluesMapping:— thì một đầu vào mang dữ liệu mà tác giả khai báo là nhạy cảm cũng nhận được một tệp override được sinh ra, mang thuộc tính nhạy cảm riêng của Terraform; một templatevaluesMapping:tự đặt tên đầu ra của nó, nên trường hợp đó không mang đánh dấu nào và bản dựng báo cáo nó bằng một cảnh báo tư vấn. Cả hai được mô tả trong Các đầu vào module được khai báo nhạy cảm.
Một null trong valuesMapping: là một đối số null. Một khóa mà mapping đặt thành null được ghi là <name> = null trong khối module, và engine gán cho biến của module giá trị null, ghi đè default của nó, trừ khi biến khai báo nullable = false, khi đó default của nó được áp dụng; để cho một đầu vào nhận giá trị mặc định của module, hãy bỏ khóa đó khỏi mapping.
Loại đầu vào synthesized không được cung cấp. Không có ánh xạ trung thực, không phụ thuộc vào khả năng nào từ loại Workload của nền tảng sang các tài nguyên Terraform tùy ý, nên một Recipe khai báo workload: với provider terraform là một lỗi rõ ràng thay vì một bản chuyển đổi được bịa ra.
Một Recipe khai báo omits: bị từ chối. Khóa omits: loại khỏi bản dựng các tài liệu mà một nguồn render ra, còn provider này không render gì từ một module sourced tại thời điểm dựng: nó vendor nguyên văn các tệp của module, và Terraform đánh giá chúng khi cấu hình được plan và apply. Không có gì được render thì không có gì để loại bỏ, nên provider này không khai báo rằng nó tôn trọng khóa đó, và một Recipe hoặc FeatureRecipe khai báo nó bị từ chối trước khi bất cứ thứ gì được vendor — xem The provider does not support omits (Provider không hỗ trợ omits). Với một module bạn giữ bên cạnh Recipe, một dòng trong .aggregaignore ở đó sẽ loại một tệp của module ra, kể từ lần tiếp theo Recipe được pin.
Lấy nguồn từ một module do registry công bố
Một registry module công bố mỗi phiên bản của module dưới dạng một tag trong kho git riêng của module, và khi được yêu cầu tải một phiên bản, nó trả về một nguồn git được pin vào commit mà tag đó chỉ đến. Vì vậy, một Recipe lấy một module đã công bố từ kho đó tại tag đó, với loại nguồn 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: là tag phát hành, đúng như kho đặt tên. valuesMapping: cung cấp các đầu vào của module, theo tên mà các khối variable của nó khai báo — Terraform yêu cầu một giá trị cho mọi đầu vào không khai báo default — và chúng trở thành các đối số của khối module của component này trong cấu hình gốc, như với mọi module sourced.
Những gì được pin. aggrega pin và lệnh pull phân giải tag thành commit mà nó chỉ đến và lưu trữ kho tại commit đó. Lockfile của Release sau đó ghi lại commit đó làm phiên bản đã pin của nguồn, tag làm tham chiếu bạn đã viết, và digest của bản lưu trữ. Mọi bản dựng sau đó đọc bản lưu trữ từ cache và xác minh nó với digest đó trước khi vendor bất cứ thứ gì, nên không cần mạng, và một bản lưu trữ trong cache có byte không còn khớp sẽ dừng bản dựng. Tag là một cái tên mà kho có thể chuyển sang commit khác; một lần pull sau phát hiện tag của bạn phân giải sang chỗ khác sẽ dừng lại thay vì chấp nhận commit mới, và aggrega pull --upgrade chấp nhận nó một cách có chủ ý. Đó là cách pin chặt hơn tệp khóa phụ thuộc của chính Terraform, vốn ghi lại các provider mà cấu hình đã chọn và hoàn toàn không ghi module nào, nên một module được viết vào cấu hình dưới dạng nguồn git tại một tag chỉ cố định ngang với tag đó. Ở đây, commit của module và digest các byte của nó được cố định trong lock, các byte được vendor vào đầu ra, và cấu hình gốc gọi chúng bằng đường dẫn cục bộ, nên engine không tải gì để nạp chính module — một module mà module đã vendor gọi qua registry hoặc nguồn từ xa vẫn được tải về, và bản dựng báo cáo từng lời gọi như vậy, như A module call the engine fetches when it initialises (Lời gọi module mà engine tải về khi khởi tạo) mô tả.
Những gì được vendor. Toàn bộ kho tại commit đã pin, trừ thư mục .git/, được đặt vào thư mục riêng của component dưới modules/, chính xác từng byte — các tệp cấu hình và module con của module, cùng mọi thứ khác mà kho chứa: các thư mục examples/ và wrappers/, tài liệu, cấu hình CI, và mọi test fixture, kể cả các tệp nhị phân. Engine chỉ đọc những gì module gọi: khi cấu hình gốc gọi thư mục của component, engine nạp các tệp cấu hình nằm trực tiếp trong đó và trong mỗi thư mục mà một source cục bộ trỏ đến từ đó. Do đó, một thư mục ví dụ gọi các module registry khác được vendor nhưng không bao giờ được nạp, và không thứ gì nó gọi được tải về.
Thu hẹp những gì được vendor. Một nguồn được tải về chính là bản lưu trữ mà nó được tải về, nên cách duy nhất để thu hẹp nó là module_subdir:, giúp biến một thư mục của kho thành artifact. Cách đó chỉ hữu ích khi module bạn muốn nằm trong một thư mục con: một module ở gốc kho gọi ./modules/* của chính nó cần toàn bộ cây. Cả .terraformignore mà kho chứa lẫn .aggregaignore bên cạnh Recipe đều không thay đổi những gì một nguồn được tải về vendor — cả hai định hình một module giữ bên cạnh Recipe, và không cái nào được đọc cho module tải về từ kho.
Đọc những gì module công bố. Một giá trị module công bố là một trong các khối output của nó, và bên tiêu thụ đọc nó dưới dạng ${module.<name>.<output>}, trong đó <name> là khối module của bên cung cấp — đó là lý do bên cung cấp ở trên công bố ${module.{{ .context.instance_id }}.<output>}. Engine phân giải tham chiếu dựa trên các khối output của chính module khi nó xác thực cấu hình gốc, nên một tên đầu ra mà module không khai báo sẽ bị từ chối ở đó, kèm theo tên của nó:
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".Bản dựng không đọc khối variable hay output nào của module, không ghi gì vào module, và không thêm cấu hình provider nào vào đó, nên một tên đầu ra gõ sai được engine phát hiện chứ không phải bản dựng. Xem Tiêu thụ giá trị được công bố của một component khác để biết phía bên tiêu thụ.
Phát xuất nguyên văn và vendoring
Provider terraform không chuyển mã, định dạng lại hay viết lại các phần thân Terraform. Một phần thân HCL hoặc .tf.json do tác giả viết được phát xuất đúng như template của nó đánh giá ra, với phần thân HCL mở đầu bằng các chú thích nguồn gốc, và một module có nguồn được vendor nguyên vẹn từng tệp. Đây là điều giữ cho đầu ra terraform mang tính tất định và có thể tái tạo: với cùng các đầu vào, cấu hình được kết xuất giống hệt nhau từng byte qua các lần chạy, và một module được vendor đi qua mà không thay đổi. Vì provider không bao giờ phân giải trạng thái thời gian chạy, mọi thứ phụ thuộc vào thời gian chạy vẫn là một chuỗi nội suy mà Terraform gắn giá trị tại thời điểm apply.
Annotation nền tảng
Provider terraform không đọc bất kỳ annotation aggrega.ai/ nào. Một module được vendor, các tệp artifact của một Recipe và cấu hình gốc mà provider ghi ra đều không có chỗ cho namespace, tiền tố registry, pull secret hay service account, nên một giá trị được đặt cho bất kỳ mục nào trong số đó cũng không thay đổi gì trong cấu hình được kết xuất; một module cần giá trị như vậy sẽ nhận nó như một trong các đầu vào của chính nó, thông qua values của thành phần.
Provider tuyên bố điều này trong thực thể Plugin của nó, bằng readsNoWellKnownAnnotations: true (xem thực thể Plugin), và do đó quá trình build cảnh báo về mọi annotation aggrega.ai/ đến được một lượt kết xuất thông qua nó — một lần cho mỗi khóa và mỗi lượt kết xuất, nêu tên các input kind mà lượt kết xuất đó khai báo:
warning: node "db" (provider "terraform"): target "terraform" does not support annotation aggrega.ai/namespace on sourced input and ignored itGiá trị vẫn đi qua quá trình build nguyên vẹn, và quá trình build không dừng: annotation của ranh giới được kế thừa xuống mọi thành phần bên dưới nó, và một ranh giới có các thành phần được kết xuất qua những đích khác nhau là điều bình thường chứ không phải lỗi. Cảnh báo này thuộc lớp unsupported-field và được tắt bằng cờ của lớp đó.
Các đầu vào module được khai báo là nhạy cảm
Terraform là đích duy nhất trong thư viện chuẩn có một nguyên thể nhạy cảm gốc theo từng giá trị, nên một dữ liệu mà tác giả đã khai báo là nhạy cảm có thể được kết xuất theo thuật ngữ của chính Terraform thay vì chỉ được ghi nhận theo thuật ngữ của Aggrega.
Khi một đầu vào của module được vendor mang nội dung mà tác giả đã khai báo là nhạy cảm, provider thêm một tệp nữa bên cạnh module, aggrega_override.tf.json, khai báo sensitive = true cho đầu vào đó:
{ "variable": { "db_password": { "sensitive": true } }}Terraform hợp nhất một tệp cấu hình có tên chỉ là override hoặc kết thúc bằng _override vào cấu hình trong cùng thư mục, nên khối variable của chính module nhận được thuộc tính này trong khi mọi byte được vendor vẫn giữ nguyên như khi được viết. Kiểu, giá trị mặc định và mô tả đã khai báo của đầu vào không bị động đến — tệp override chỉ mang thuộc tính nhạy cảm và không gì khác. Một nút không được đánh dấu sẽ không có tệp như vậy.
Giới hạn đó là có chủ ý chứ không phải do định dạng tệp áp đặt: không có gì trong một override từ chối thuộc tính thứ hai, và default của một khối variable là chỗ gần nhất để dùng nếu bạn muốn đưa một giá trị vào module được vendor mà không sửa các byte của nó — nhưng giá trị đó sẽ không đến nơi. Một default trong cú pháp cấu hình JSON mà tệp này được viết không phải là vị trí Terraform đánh giá, nên một giá trị mang con trỏ ${ ... } viết ở đó sẽ đến module dưới dạng các ký tự nguyên văn của con trỏ, tại một lần plan thành công và không báo gì. Cùng con trỏ đó viết vào một default trong HCL gốc thì bị từ chối ngay, điều này cho thấy sự im lặng ấy nằm ở cú pháp này chứ không phải ở bản thân các tệp override. Vì vậy override chỉ mang sensitive: ý nghĩa của nó không phụ thuộc vào việc được đánh giá.
Đầu vào nào được đánh dấu là do một khai báo quyết định, không bao giờ do một cái tên. Provider đọc dấu đánh mà quá trình biên dịch đã tính và tự nó không kiểm tra gì: nó không nhận diện password, secret hay token, và không đọc văn bản của module để đoán. Một đầu vào module tên db_password mà giá trị không mang khai báo nào sẽ được xuất ra không đánh dấu, còn một đầu vào đã khai báo tên region thì được đánh dấu.
Dấu đánh chỉ đi theo ở nơi danh tính của đầu vào có thể truy lại từ khai báo. Một Recipe vendor một module bằng source: và để các lá values đã khai báo của nút trực tiếp trở thành đầu vào của module sẽ cho mỗi đầu vào đúng cái tên mà tác giả đã khai báo, nên liên kết là chính xác — và FeatureRecipe của một Feature gắn vào một component vendor module theo cùng cách cũng vậy, trên các lá mà Feature của nó khai báo. Một Recipe hoặc một FeatureRecipe như thế mà định hình lại các giá trị đó qua một template valuesMapping: sẽ tự tạo tên đầu ra, và không khai báo nào gọi tên chúng — nên dấu đánh vắng mặt chứ không được ước chừng, và bản build báo điều đó bằng một thông báo tư vấn cho mỗi lá đã khai báo, nêu tên lá và thực thể sở hữu ánh xạ (một Feature gắn vào một ranh giới được kết xuất mà không có values nào, nên nó không có gì để đánh dấu và không phát sinh thông báo nào); xem A declared-sensitive value reaches the target through a values mapping (Một giá trị được khai báo là nhạy cảm đến đích qua một ánh xạ giá trị). Sự vắng mặt là có chủ ý: đoán xem đầu vào đã định hình lại nào mang dữ liệu được khai báo sẽ đánh dấu một đầu vào công khai là bí mật, và khi đó Terraform sẽ ẩn khỏi đầu ra plan một giá trị chưa bao giờ nhạy cảm.
Ví dụ minh họa terraform-declared-sensitivity xây dựng điều này từ đầu đến cuối và đủ nhỏ để đọc toàn bộ: một component khai báo ba lá values, trong đó hai lá mang định danh công khai và một lá mang thông tin xác thực. Đầu ra kết xuất của nó cho thấy các đối số của khối module mang cả ba đầu vào module và tệp override chỉ nêu tên đầu vào đã khai báo, nên cả hai nửa của quy tắc hiển thị trong cùng một bản build — kể cả việc một định danh thông tin xác thực nằm cạnh bí mật được để không đánh dấu. Bỏ khai báo duy nhất đó và build lại thì không có tệp override nào được xuất ra.
Những gì sensitive của Terraform đảm bảo và không đảm bảo
Aggrega hứa đúng những gì thuộc tính của chính Terraform mang lại, và không hơn.
Nó giới hạn việc hiển thị. Một giá trị nhạy cảm hiển thị là (sensitive value) trong đầu ra plan và <sensitive> trong đầu ra apply. Dấu đánh lan truyền qua các biểu thức, nên một giá trị dẫn xuất từ một đầu vào nhạy cảm cũng nhạy cảm, và Terraform từ chối xuất nó từ một output gốc mà bản thân không được đánh dấu nhạy cảm — một lỗi rõ ràng thay vì một sự tiết lộ âm thầm.
Nó không thay đổi việc lưu trữ, và nó không phải là mã hóa. Terraform ghi một giá trị nhạy cảm vào state ở dạng rõ. Hiểu sensitive = true như một lời hứa rằng state an toàn để commit hoặc chia sẻ là cách hiểu sai duy nhất cần tránh: bảo vệ state vẫn là vấn đề về cách cấu hình state backend, đúng như với một module không mang dấu đánh nào. Thuộc tính này cũng không giới hạn ai có thể đọc giá trị, không ảnh hưởng đến những gì một provider truyền đi, và không thay đổi cấu hình được kết xuất theo bất kỳ cách nào khác.
Vậy dấu đánh khiến một đầu vào được khai báo là nhạy cảm khó bị tiết lộ vô tình hơn khi ai đó đọc một plan. Nó không làm cho sản phẩm triển khai an toàn để công bố. Xem Khai báo một lá là nhạy cảm để biết từ khóa và những gì một khai báo đạt được trên mọi đích.
Kiểm tra cấu trúc đầu vào
Provider terraform kiểm tra cấu trúc của một module có nguồn trước khi render. Nó phân tích các tệp HCL và .tf.json của module và báo cáo lỗi phân tích, dừng quá trình build với một thông báo rõ ràng nêu tên node gây lỗi và provider. Việc phân tích kiểm tra hình dạng chứ không kiểm tra ngữ nghĩa — nó không phân giải các provider, không đánh giá biểu thức và không liên hệ với registry. Việc kiểm tra là khép kín: nó dùng một trình phân tích HCL độc lập được biên dịch sẵn vào provider, không cần tệp nhị phân terraform và không truy cập mạng. Một module sai định dạng được phát hiện ngay tại ranh giới soạn thảo thay vì xuất hiện như một lỗi khó hiểu ở một lần chạy terraform sau đó.
Một lời gọi module mà engine tải về khi khởi tạo
Cũng lần đọc đó báo cáo, dưới dạng một cảnh báo không từ chối điều gì, mỗi khối module có nguồn mà Terraform tải về khi cấu hình được khởi tạo. Commit và digest lưu trữ của một module được vendor được cố định trong tệp lock, nhưng một khối module bên trong nó có source là một địa chỉ registry, một URL git, Mercurial hoặc lưu trữ HTTP, một bucket S3 hoặc GCS, hoặc một đường dẫn tuyệt đối thì chỉ đến một module mà engine tải về khi khởi tạo, ở bất kỳ phiên bản nào nó chọn lúc đó — và tệp lock phụ thuộc của chính Terraform chỉ ghi lại các provider, nên không có gì ghim module đó. Một source cục bộ đi ra ngoài module được vendor cũng được báo cáo, vì nó chỉ đến các tệp mà quá trình build không vendor. Mỗi phát hiện nêu tên node và provider, sau đó là khối, tệp và dòng nơi nó nằm, và nguồn như được viết:
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 moduleNhững gì được đọc. Các tệp mà engine nạp khi module được gọi: các tệp cấu hình nằm trực tiếp trong thư mục riêng của module, sau đó là các tệp trong mỗi thư mục mà một source cục bộ — bắt đầu bằng ./ hoặc ../, hoặc cách viết bằng dấu gạch chéo ngược của chúng — dẫn tới từ đó, lần theo từ thư mục này sang thư mục khác và mỗi thư mục chỉ đọc một lần. Một thư mục không được gọi bởi gì thì không được đọc, nên các lời gọi mà thư mục examples/ hoặc tests/ của một module thực hiện không được báo cáo: engine không bao giờ nạp chúng khi module được gọi, và không gì chúng gọi được tải về. Bước kiểm tra phân tích ở trên vẫn phân tích mọi tệp cấu hình được vendor. Phần thân được soạn của một Recipe cũng được đọc theo cách tương tự khi nó render, bắt đầu từ thư mục mà phần thân được ghi vào, nên một khối module mà phần thân được soạn ghi với nguồn registry cũng được báo cáo. Một tệp thuộc spec.boundary.artifacts được chính trình biên dịch đánh giá và ghi ra, không giao cho provider nào, nên một khối module được viết trong tệp đó không được đọc và không gây ra cảnh báo.
Những gì không được đọc. Chỉ những gì một source ghi mới được đọc. Bản build không đọc module mà một lệnh gọi chỉ đến, không đánh giá module đó làm gì và không quyết định lệnh gọi đó có chấp nhận được hay không. Một source mà engine tính toán thay vì đọc nguyên văn — loại chứa một phép nội suy, hoặc một tham chiếu — được đánh giá theo phần văn bản đứng đầu của nó: loại mở đầu bằng một địa chỉ được báo cáo đúng như đã viết, còn loại mở đầu bằng một tiền tố cục bộ, hoặc bằng chính phép nội suy, thì không được báo cáo cũng không được lần theo, vì nơi nó dẫn tới không nằm trong văn bản. Một source bên trong required_providers chỉ đến một provider chứ không phải một module, và không phải là một lệnh gọi module.
Vì sao nó được báo cáo thay vì bị từ chối. Một module gọi một module khác là đầu vào hợp lệ: Terraform tải module được gọi về và cấu hình hoạt động. Điều tác giả từ bỏ là việc quá trình build ghim module được gọi, đây là một sự thật đáng biết chứ không phải một lỗi cần sửa, và việc lần tải đó có chấp nhận được hay không là do tác giả phán đoán. Một cấu hình phải được ghim hoàn toàn chỉ vendor những module không thực hiện lời gọi như vậy. Cảnh báo, mã lớp của nó và những nơi khác nó tác động được mô tả trong Warnings and Linter Output.
Ranh giới vá của FeatureRecipe
Một bước pipeline sau khi render của FeatureRecipe chỉ vá đầu ra mà provider render thành một cây có cấu trúc. Với terraform, điều này có nghĩa là:
- Terraform viết bằng JSON có thể vá được. Một module
.tf.jsonlà một tài liệu có cấu trúc, nên JSONPatch của một bước pipeline sửa các giá trị được chỉ định tại chỗ và giữ nguyên mọi byte khác — thứ tự, định dạng, các khóa xung quanh. - HCL gốc là không trong suốt. Một phần thân HCL gốc (
main.tf) không phải là đích vá có cấu trúc. Một bản vá nhắm vào phần thân không trong suốt sẽ dừng bản build kèm một chẩn đoán thay vì sửa đổi văn bản mà nó không thể định vị theo cấu trúc; viết một bước pipeline nhắm vào phần thân HCL là một lỗi thiết kế được báo bằng một lần dừng rõ ràng, không phải một thao tác im lặng không làm gì. - Các đầu vào của một module có nguồn hoàn toàn không phải là đích vá. Chúng là các đối số của khối
modulecủa component, nằm trong cấu hình gốc: là HCL gốc, do đó không trong suốt, và là sản phẩm của toàn bộ ranh giới chứ không của riêng một node nào. Một bướcpipelinevá đầu ra đã render của chính một node, nên không có vị trí nào để định vị chúng.
Vì vậy, tác giả cần một phần thân Terraform có thể vá bằng pipeline sẽ viết nó dưới dạng .tf.json. Xem FeatureRecipe để biết ranh giới đích vá chung giữa các provider.
Thứ tự triển khai
Giá trị syncWave: của một ranh giới Release sắp xếp thứ tự các khối module của cấu hình gốc mà ranh giới đó được lắp ráp vào. Mọi component trong ranh giới kế thừa wave của ranh giới, và khi nhiều ranh giới phân giải về cùng một thư mục đầu ra — tức là các component của chúng được kết hợp vào một cấu hình gốc duy nhất — thì cấu hình gốc đó chứa nhiều hơn một wave và provider biểu diễn thứ tự giữa chúng dưới dạng depends_on trên các khối module.
Mỗi module chỉ định mọi module của wave liền trước có chứa component, và không chỉ định wave nào sớm hơn thế. Terraform tự nối chuỗi phần còn lại: một module ở wave 2 phụ thuộc vào wave 1, wave này lại phụ thuộc vào wave 0, nên toàn bộ chuỗi được sắp thứ tự trong khi danh sách riêng của mỗi module chỉ có kích thước của một wave thay vì của cả ranh giới. Các wave không cần liên tiếp, và giá trị âm là bình thường — -1 là lựa chọn phổ biến cho một bucket hay một role mà phần còn lại của cấu hình đọc tới. Wave thấp nhất không chỉ định gì, vì không có gì đứng trước nó.
Thứ tự này là gì: thứ tự Terraform thực hiện các hành động của nó. Terraform xây dựng một đồ thị phụ thuộc và xử lý song song trong phạm vi đồ thị cho phép. depends_on thêm một cạnh vào đồ thị đó, nên Terraform hoàn tất các hành động trên những module được chỉ định trước khi bắt đầu các hành động trên module khai báo sự phụ thuộc. Do đó một wave chia lần chạy thành các giai đoạn: các component của wave sớm hơn được xử lý trước khi các component của wave sau được bắt đầu.
Đây không phải là thứ tự theo trạng thái sẵn sàng. Một cấu hình Terraform không biểu diễn khái niệm một tài nguyên có thể phục vụ được, nên ở đây không có gì chờ một tài nguyên trở nên sẵn sàng — chỉ chờ Terraform xử lý xong nó. Đó là một khác biệt thực sự so với cùng wave đó trên compose, nơi một service khai báo healthcheck được chờ cho đến khi báo cáo là khỏe mạnh: compose có một cơ chế cơ bản về trạng thái sẵn sàng để chặn chờ, còn một cấu hình Terraform thì không có. Thứ tự hành động là những gì target này cung cấp, và nói rõ điều đó hữu ích hơn một lời cảnh báo gắn vào một lời hứa mà nó không thể thực hiện.
Không có thứ tự gỡ bỏ nào được hứa hẹn. Điều depends_on khẳng định là Terraform hoàn tất các hành động của phần được phụ thuộc trước khi bắt đầu các hành động của phần phụ thuộc; thứ tự mà một lệnh destroy gỡ bỏ chúng không thuộc khẳng định đó, nên ở đây không có tuyên bố nào về trình tự gỡ bỏ. Đây là một lời hứa hẹp hơn so với cùng wave đó trên cloudformation, nơi thuộc tính của nó điều khiển cả hai chiều — điều đáng biết nếu bạn dựa vào một wave để sắp trình tự gỡ bỏ, vì trên target này nó không làm vậy.
Một ranh giới mà mọi component đều mang cùng một wave không nhận được gì từ cơ chế này. Một Release không khai báo syncWave nào cũng vậy: mọi thành phần đóng góp mang giá trị mặc định 0 của trường, cấu hình gốc chỉ chứa một wave, và các byte được xuất ra giống hệt như khi provider không biểu diễn thứ tự wave nào.
Thứ tự giữa hai cấu hình gốc không thể biểu diễn được, và cũng không được mô phỏng gần đúng. Một đồ thị phụ thuộc Terraform là riêng cho từng cấu hình và depends_on chỉ định một module bên trong cấu hình khai báo nó, nên một wave sắp thứ tự mọi component được kết hợp vào cấu hình gốc đó và không gì vượt ra ngoài. Việc sắp trình tự hai cấu hình là việc của người vận hành, giống như một tham chiếu remote-state được phân giải lúc triển khai chứ không phải lúc build.
Wave vừa được ghi lại vừa được thực thi: nó đi cùng phần còn lại của thông tin nguồn gốc build của node, dưới dạng aggrega.ai/sync-wave trong khối chú thích được đóng dấu, hoặc trong tệp nguồn gốc đi kèm khi phần thân là JSON hoặc một module được vendor. Vì vậy một cấu hình đã render vừa ghi lại wave mà ranh giới của nó đã khai báo, vừa được sắp thứ tự theo wave đó.
Thứ tự mà các wave không biểu diễn vẫn là việc riêng của Terraform, và các tham chiếu giữa các tài nguyên đã mang phần lớn thứ tự đó: một tham chiếu tới thuộc tính của tài nguyên khác báo cho Terraform xử lý tài nguyên đó trước. Một module cần một ràng buộc mà cả tham chiếu lẫn wave đều không ngụ ý sẽ tự viết depends_on của nó bên trong module, và provider xuất nguyên văn nó như mọi phần khác của phần thân.
Tài liệu tham khảo liên quan
- Kiến trúc Provider — cách các provider khớp vào quy trình biên dịch và việc điều phối theo từng provider.
- Chỉ mục tham chiếu Provider — những gì mỗi provider của thư viện chuẩn tạo ra, và trang nào trả lời câu hỏi nào.
- Thực thể Recipe — bề mặt soạn thảo Recipe và ba loại đầu vào.
- FeatureRecipe — mô hình vá
pipelinesau khi kết xuất và ranh giới có cấu trúc/không minh bạch của nó. - Kết hợp đầu vào Recipe — Ma trận năng lực Provider chuẩn.