provides, inject, uses
Hợp đồng injection và bản đồ đã phân giải trước
Vì Aggrega là một trình biên dịch tĩnh Ahead-of-Time (AOT, biên dịch trước), không có dữ liệu nào chảy ngược từ hạ tầng đang chạy trong quá trình biên dịch. Về mặt cơ học, trình biên dịch không thể chủ động lấy một thông tin xác thực vật lý (như một secret của AWS) rồi truyền nó “ngược lại” cho môi trường container của Developer.
Thay vào đó, nền tảng dựa vào đảo ngược kiểm soát thực sự. Khi một developer viết inject: { env: [{ in: ORACLE_PASSWORD, from: "password" }] }, họ không khởi tạo một thao tác lấy dữ liệu; họ đang áp đặt một hợp đồng chặt chẽ lên hạ tầng.
- Ý định (Miền 1): Developer khai báo một giao diện trừu tượng: “Tôi cần một secret. Tôi không biết nó nằm ở đâu. Chỉ cần tiêm nó vào môi trường của tôi dưới tên
ORACLE_PASSWORD, ánh xạ tới khóapasswordcủa catalog.” - Chuyển giao của trình biên dịch (khi render): Trình biên dịch Go lấy mục
{ in: ORACLE_PASSWORD, from: "password" }và giao nó cho Ops Recipe. Không có secret vật lý nào được lấy về. - Đầu ra của Plugin (Miền 3): Pipeline Wasm của FeatureRecipe thông tin xác thực sinh ra chính xác các artifact liên kết với nhau mà hạ tầng đích yêu cầu. Ví dụ, trong Kubernetes, nó xuất ra CRD
ExternalSecret(chỉ thị cluster lấy dữ liệu từ vault) VÀ thực thi một JSONPatch lên Pod đích để ánh xạ K8s Secret cục bộ thu được vào đúng biến môi trường"ORACLE_PASSWORD"mà developer yêu cầu. - Thực tế lúc chạy: Lúc chạy, một operator trong cluster chỉ đơn giản thực thi các artifact đã sinh này—lấy thông tin xác thực và gắn nó một cách vật lý vào container—tách hoàn toàn cơ chế bảo mật vật lý khỏi trình biên dịch AOT.
Để đưa thực tế vật lý này đến ứng dụng mà không vi phạm nguyên tắc phân tách mối quan tâm, Aggrega sử dụng hợp đồng tiêm. Tuy nhiên, hợp đồng này phân biệt chặt chẽ giữa mã ứng dụng tùy chỉnh và hạ tầng thương mại đóng gói sẵn (COTS, Commercial Off-The-Shelf):
- Hộp trắng (mã tùy chỉnh): Component là một worker chung (ví dụ: một agent Python tùy chỉnh). Trình biên dịch Go và Ops Recipe hoàn toàn không biết script tùy chỉnh của developer cần những biến nào. Do đó, ở bất cứ đâu mã đọc những tên mà Recipe của nó không phân phối theo mặc định, Developer chỉ định cách phân phối thông qua khối
inject:— cả cho các phụ thuộc giữa các component (quauses[].injectvớifrom:tham chiếu tớiprovidescủa đích) lẫn cho các giá trị riêng của component (quainjectở cấp component với các literalvalue:hoặcfrom:tham chiếu tớiprovidescủa chính nó). Những cơ chế nào được phép là do từng bề mặt khai báo, và hai khai báo này tách biệt: các giá trị riêng của component chịu sự chi phối của allowlistspec.inject(ví dụ:inject: ["env", "file"]), còn một cạnhuses:chịu sự chi phối của allowlist trên socket mà nó được nối qua,spec.usesSchema.<socket>.inject. Chỉ định một cơ chế mà allowlist chi phối không nêu tên sẽ dừng bản build trên cả hai bề mặt. - Hộp đen (tính toán đóng gói): Component là một hệ thống đóng (ví dụ: Redis, một API Gateway được quản lý). Ops Recipe đã biết chính xác hệ thống tiêu thụ dữ liệu của nó như thế nào. Do đó, thực thể catalog Component bỏ qua allowlist, điều này cấm hẳn việc chỉ định thay vì thu hẹp nó — bỏ qua
spec.injectsẽ cấm self-inject ở cấp component, và một socket được khai báo mà không có allowlistinject:sẽ cấm mọi khốiinject:trên một cạnh được nối qua nó. Developer chỉ cần cung cấp đích phụ thuộc quauses, và nền tảng xử lý việc nối nội bộ một cách tự nhiên quavaluesMappingcủa Recipe.
Quy tắc định địa chỉ tất định (vật lý mạng nội bộ)
Pipe .context.uses của Aggrega tiêm động các chuỗi đích vào container tại thời điểm biên dịch. Vì trình biên dịch Go cốt lõi hoàn toàn không phụ thuộc vào mạng vật lý, việc thế nào là một chuỗi địa chỉ hợp lệ hoàn toàn dựa vào một khế ước xã hội do Platform Ops duy trì, chứ không phải một chức năng của trình biên dịch — trình biên dịch chuyển bất kỳ chuỗi con trỏ tất định nào mà Ops Recipe tạo ra vào ngữ cảnh template phía sau mà không diễn giải.
Quy tắc: Ops Recipe phải xuất một con trỏ địa chỉ tất định, ổn định. Provider không tính toán IP. Thay vào đó, Ops Recipe của đích nên tạo ra một chuỗi có thể dự đoán và công bố nó qua hợp đồng provides: của mình (ví dụ: công bố provides.internal_host: "http://agent-b.namespace.svc.cluster.local" trong Kubernetes, hoặc một chuỗi nội suy như "${module.db.endpoint}" trong Terraform, nơi module khai báo một output tương ứng cho giá trị đó).
Dựa vào trình biên dịch để lấy các IP động sau khi cấp phát là vi phạm trực tiếp mô hình thực thi AOT. Vì trình biên dịch đánh giá topology trước khi đám mây cấp phát bất kỳ tài nguyên tính toán thực tế nào, nó không thể lấy về một cách vật lý dữ liệu chưa tồn tại. Nếu một dịch vụ cần một IP ngẫu nhiên chỉ được sinh ra sau khi tài nguyên tính toán khởi động, trình biên dịch không thể lấy nó về. Nhiệm vụ duy nhất của trình biên dịch là chuyển nguyên văn chuỗi con trỏ tất định do Ops Recipe cung cấp vào các biến môi trường của container gọi, để việc phân giải cuối cùng cho DNS của cluster hoặc trình quản lý trạng thái IaC đang hoạt động.
Việc áp dụng định địa chỉ tất định giải quyết một cách tự nhiên các phụ thuộc vòng (ví dụ: Agent A ủy quyền cho Agent B, và Agent B ủy quyền ngược lại cho Agent A). Vì URL ổn định hoặc con trỏ IaC có thể tính được dưới dạng chuỗi trước khi bất kỳ container nào thực sự khởi động, trình biên dịch nối an toàn hai agent với nhau mà không gây ra điều kiện tranh chấp về thời gian.
(Lưu ý: Quy tắc này cũng áp dụng cho ingress bên ngoài. Nếu một kiến trúc công bố một API Gateway công khai và yêu cầu URL đó được tiêm ngược vào một container nội bộ, trình biên dịch Go không thể lấy URL ngẫu nhiên do đám mây sinh ra (ví dụ: xyz123.execute-api.aws.com) vì nó chưa tồn tại tại thời điểm biên dịch. Ops phải viết Recipe của mình để hoặc ánh xạ một tên miền tùy chỉnh tất định (ví dụ: api.enterprise.com), hoặc xuất chuỗi nội suy IaC gốc, bảo đảm trình biên dịch AOT có một tham chiếu đã biết để tiêm an toàn).
Cơ chế triển khai (catalog là hợp đồng API) Để triển khai điều này mà không ràng buộc chặt Developers với Ops, Aggrega dùng Platform Catalog (Miền 2) làm hợp đồng API chặt chẽ, sử dụng ba lớp xác thực riêng biệt:
- Schema Feature thông tin xác thực (gắn nhãn
feature.aggrega.ai/kind: secret): CHỈ xác thực truy vấn vault (path,key). Nó hoàn toàn không phụ thuộc vào cách container tiêu thụ dữ liệu. - Schema
Component(allowlistspec.inject): Thực thi quy tắc hộp đen/hộp trắng qua trườngspec.inject. Nếu cóspec.inject(ví dụ:inject: ["env", "file"]), developer có thể dùng self-inject ở cấp component với các cơ chế phân phối đó. Nếu bỏ quaspec.inject, trình biên dịch cấm self-inject về mặt cấu trúc — các component hộp đen hoàn toàn dựa vàovaluesMappingcủa Recipe để nối nội bộ. Bản build thực thi điều này khi phân giải Aggregate, từ chối khốiinject:của component và nêu tên cơ chế, khác với việc xác thực nội dung theo từng trụ cột dướischema:. - Map
featuresSchema: Được định nghĩa trong Component Catalog, nó khai báo rõ ràng các slot thông tin xác thực mà Developer phải (hoặc có thể) sử dụng. Mỗi mục chỉ địnhrequired(mặc địnhfalse), allowlistinject([]= hộp đen,[env, file]= minh bạch) vàdescription. Vì các khóa này ổn định và được bảo đảm theo hợp đồng, Ops Engineer có thể dựa trực tiếp vào chúng để chỉ định một cách tin cậy các đích tất định trong Go template của mình (ví dụ:existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_admin_password }}"trên đíchhelm), xuất rõ ràng hậu tố của tên qua.locals— một local không thể đọc.context.rendered_name— để FeatureRecipe thông tin xác thực phía sau ghép cùng hai phần đó và đáp ứng yêu cầu mà không vi phạm thứ tự thực thi AOT. Xementities/component.mdđể biết thiết kế đầy đủ củafeaturesSchema.
Quy tắc vị trí chặt chẽ: Cơ chế inject: có sẵn ở ba vị trí trong Aggregate của Developer:
- Self-inject cấp component: Là phần tử ngang hàng trực tiếp với
values:trên một instance của component. Tiêm các giá trị literal của chính component hoặc các khóaprovidescủa chính nó vào đường ống phân phối. Chỉ được phép nếu catalog của Component khai báospec.injectvới các cơ chế tương ứng. - Cross-inject cấp uses: Bên trong các định nghĩa đích tường minh trong khối
uses:. Tiêm các khóaprovidescủa một đích phụ thuộc vào đường ống phân phối. - Inject cấp Feature/Secret: Là phần tử ngang hàng với
values:khi gắn các feature và secret. Inject các khóaprovidesđã được phân giải của chính phần đính kèm vào đường ống phân phối — thông tin xác thực đã phân giải đối với một secret, hoặc các giá trị do một feature cung cấp.
Cả ba dạng đều điền vào cùng một đường ống .context.inject. Recipe đọc một đường ống duy nhất, hợp nhất, bất kể có bao nhiêu nguồn đã đóng góp vào đó.
Schema inject định nghĩa các enum chuẩn (env, file, arg) cho công cụ, nhưng để additionalProperties mở, nên có thể đặt tên cho một cơ chế tùy chỉnh (ví dụ: ssm_param cho AWS Systems Manager Parameter Store). Một tên đã được dành riêng: all là khung nhìn hợp nhất của mọi cơ chế mà một Recipe đọc tại .context.inject.all, nên một khối inject đặt tên một cơ chế là all sẽ dừng bản build tại lớp vỏ tài liệu và nêu rõ điều đó.
Cú pháp mục inject: Dưới một khối inject, mỗi cơ chế phân phối — env, file, arg hoặc một cơ chế tùy chỉnh — là một danh sách các mục, và mọi vị trí đặt đều dùng cùng một dạng mục. Chính từ khóa mà một mục mang, chứ không phải vị trí đặt của nó, cho biết chuỗi của mục đó là gì, nên một mục được đọc giống nhau ở bất cứ đâu nó xuất hiện. Một cơ chế được viết dưới dạng map thay vì danh sách, hoặc một mục mang cả hai từ khóa, sẽ dừng bản build tại lớp vỏ tài liệu của Aggregate, kèm đường dẫn trong Aggregate nơi dạng bị sai.
Từ khóa của mục (from: và value:): Mỗi mục dùng từ khóa in cho định danh cục bộ — tên biến môi trường, đường dẫn tệp, cờ đối số — cộng với đúng một trong hai from: (tham chiếu khóa provides) hoặc value: (chuỗi literal). Một from: được phân giải dựa trên provides của nút mà vị trí đặt của nó chỉ tới: của chính component trong component.inject, của đích trong uses[target].inject, và của chính attachment trong features[<name>].inject:
| Từ khóa | Ý nghĩa | Được phép trong component.inject | Được phép trong uses[].inject | Được phép trong features[<name>].inject |
|---|---|---|---|---|
from: | Phân giải theo provides | ✅ Provides của chính node | ✅ Provides của node đích | ✅ provides của chính attachment |
value: | Chuỗi literal (hỗ trợ Go template) | ✅ | ❌ (value: không hợp lệ trong uses[].inject; hãy dùng inject cấp component cho self-inject) | ❌ (value: dừng bản build trong inject của một attachment; hãy dùng inject cấp thành phần cho self-inject) |
Ví dụ:
# Component-level self-inject (White-Box custom code)components: my-worker: type: core/python-worker:1.0.0 values: app_token: "xyz" inject: env: - in: MY_TOKEN value: "xyz" # Literal value - in: LOG_LEVEL value: "debug" # Literal value - in: CALLBACK_HOST from: "host" # From own provides (already evaluated) - in: APP_VERSION value: '{{"{{"}} .values.app_token }}' # Go template expanding own values uses: databases: my_db: target: postgres-db inject: env: - in: DB_HOST from: "host" # Provides key from target - in: DB_PORT from: "port" # Provides key from target - in: DB_URL from: "dsn" # From target's providesTemplate trong value: của APP_VERSION mở đầu bằng {{"{{"}} thay vì {{: toàn bộ văn bản của Aggregate được đọc một lần như một template, để nội suy tham số, trước khi bước phân giải self-inject chạy, và .values chưa tồn tại vào thời điểm đó, nên chuỗi thoát đặt lại {{ để bước phân giải self-inject đánh giá. Xem Văn bản chứa cặp ngoặc nhọn kép của riêng nó.
Ghi chú riêng cho Provider (compose). Khi các cạnh uses: được phân giải giữa các nút nhắm tới compose, provider compose suy ra các mục depends_on từ những cạnh đó. Các mục này luôn dùng ngữ nghĩa service_started bất kể khối health: của bất kỳ đích nào; việc ràng buộc chúng theo tình trạng sức khỏe của đích chưa được triển khai. Xem providers/compose.md để biết đầy đủ các quy tắc suy luận.
Quy tắc xung đột khóa inject: Việc một developer yêu cầu cùng một khóa phân phối (ví dụ: cùng một tên biến môi trường) từ hai nguồn khác nhau là lỗi nghiêm trọng, không phải một phép gộp. Trình biên dịch phát hiện xung đột và dừng bản build:
| Nguồn A | Nguồn B | Kết quả |
|---|---|---|
component.inject | uses[].inject | ❌ dừng nghiêm trọng — trùng khóa phân phối |
uses[target_A].inject | uses[target_B].inject | ❌ dừng nghiêm trọng — trùng khóa phân phối |
component.inject | features[<name>].inject | ❌ dừng nghiêm trọng — trùng khóa phân phối |
uses[].inject | features[<name>].inject | ❌ dừng nghiêm trọng — trùng khóa phân phối |
features[A].inject | features[B].inject | ❌ dừng nghiêm trọng — trùng khóa phân phối |
component.inject (cùng một khóa hai lần) | — | ❌ dừng nghiêm trọng — trùng khóa phân phối |
injectMapping của FeatureRecipe của features[A] | injectMapping của FeatureRecipe của features[B] | ❌ dừng nghiêm trọng — trùng khóa phân phối giữa hai attachment |
features[A].inject | injectMapping của FeatureRecipe của features[B] | ❌ dừng nghiêm trọng — trùng khóa phân phối giữa hai attachment |
component.inject hoặc uses[].inject | injectMapping của FeatureRecipe | ✅ Hợp lệ — chặn bắt có chủ đích: giá trị của mapping thay thế mục đó |
Bảng này đọc mọi Feature được gắn theo cùng một cách, bất kể nó được gắn ở đâu — trên component, tại biên của một subsystem hoặc một Release, qua việc mở rộng một annotation, hay trên một kết nối. injectMapping của một FeatureRecipe render sau khi mọi khối inject: đã phân phối xong, nên nó luôn là yêu cầu đến sau trong hai yêu cầu: nó có thể ghi lại những gì component hoặc một trong các kết nối của nó đã phân phối, và có thể ghi lại những gì khối inject: của chính attachment của nó đã phân phối, nhưng một khóa mà một Feature được gắn khác đã phân phối sẽ dừng bản build, kèm tên của cả hai.
Một Feature được gắn vào biên của một Release mà FeatureRecipe của nó render một lần cho biên đó (executionScope: boundary) tới được các component mà biên đó chứa qua cùng một con đường: injectMapping của nó chạy một lần cho mỗi component, trong ngữ cảnh của component đó, và chịu sự chi phối của các hàng trong bảng trên như mọi mapping khác. Cầu nối compose ghi lại biến host của một consumer để tới đích của nó qua gateway của đích là một mapping như vậy, nên một Feature được gắn khác đã phân phối cùng biến đó sẽ dừng bản build, kèm tên của cả hai.
Để tránh mã Go template lặp lại trong các Recipes, trình biên dịch cung cấp cả hai:
.context.uses: Map cạnh topo đã được làm giàu (cho logic phức tạp, tham chiếu secret và theo dõi nguồn gốc)..context.inject: Một dictionary phẳng, được phân giải trước, trong đó trình biên dịch đã phân giải mọi nguồn inject (literal self-inject, tham chiếu provides self-inject và tham chiếu provides liên component) thành các giá trị chuỗi cuối cùng, rồi áp dụng các phép chặn bắtinjectMappingcủa FeatureRecipe.
Ngữ cảnh tiêm hai trạng thái (an toàn null so với tính thuần khiết của ý định) Khi sinh cấu hình cho các Modifier (FeatureRecipe gắn với bất kỳ attachment nào, dù là thông tin xác thực hay không), trình biên dịch phải cân bằng giữa an toàn con trỏ null cho Go template, định tuyến mạng động và việc giữ nguyên một đồ thị không phụ thuộc vào năng lực. Để đạt điều này, trình biên dịch cung cấp cho template một ngữ cảnh hai trạng thái:
.inject_raw(ý định bất biến): Biểu diễn khốiinject:của chính component đúng như developer đã viết trong Domain 1. Nó bất biến. Nếu developer bỏ qua khối này, giá trị sẽ lànull. Ops dùng nó riêng cho các kiểm tra logic (ví dụ:{{ if not .inject_raw }}để áp dụng hành vi dự phòng). Vì bất biến, nó bảo vệ template của Ops khỏi dương tính giả nếu các feature định tuyến chặn bắt và biến đổi đường ống phân phối vật lý..context.inject(đường ống được hydrate trước và bị chặn bắt): Một struct song song do trình biên dịch sinh ra, biểu diễn thực tế phân phối vật lý. Nó khởi đầu là một map được hydrate trước (ví dụ: ánh xạAPI_HOSTtới chuỗi cơ sở của đích"backend-instance"). Điều quan trọng là đường ống này được thiết kế để bị chặn bắt và deep-merge bởi các Features (ví dụ: định tuyến mạng) thông qua khốiinjectMapping. Đến khi Recipe cơ sở render, đường ống này chứa các chuỗi được định dạng đầy đủ, đúng về mặt vật lý (ví dụ: một tên mạng hoàn chỉnh chính xác như"backend-instance.backend-zone.svc.cluster.local"). Nội dung của nó được cấu trúc thànhenv,file,arg(cùng mọi cơ chế phân phối tùy chỉnh mà allowlist inject của Component cho phép), kèm một dictionary.allđã gộp sẵn kết hợp mọi cơ chế để tiện tuần tự hóa toàn bộ đường ống..context.self_inject(Mỗi tên phân phối giá trị riêng nào): Được đọc từ cùng khốiinject:cấp thành phần như.inject_raw, theo dạng mà.context.uses.<alias>.injectcung cấp các tên của một kết nối: theo từng cơ chế, mỗi tên mà nhà phát triển viết được ánh xạ tới khóa riêng của thành phần mà mục của nó phân phối —provides.<key>cho một mụcfrom:,values.<key>cho một templatevalue:đọc đúng một trong các giá trị riêng của thành phần và không đọc gì khác, và một chuỗi rỗng cho mọi trường hợp khác (một giá trị cố định, hai giá trị, việc đọc bất cứ thứ gì ngoài các giá trị). Điều này cho phép một Recipe chạy image riêng của nhà phát triển coi các tên biến của chính nó là mặc định — chỉ phân phối một giá trị riêng dưới tên mặc định của nó khi chưa có mục nào ánh xạ tớivalues.<key>, nhờ đó nhà phát triển đổi tên một giá trị vẫn giữ mọi mặc định khác. Đó là quy ước của danh mục thư viện chuẩn, không phải quy tắc của trình biên dịch; một danh mục doanh nghiệp có thể phân phối các giá trị riêng của các thành phần theo bất kỳ cách nào nó chọn.
Ops chỉ dùng struct .context.inject cho việc tuần tự hóa an toàn (ví dụ: {{ toJson .context.inject.all }}) và sinh định tuyến, đảm bảo hạ tầng vật lý nhận được các tọa độ đã phân giải đầy đủ trong khi ý định gốc của developer vẫn được giữ nguyên vẹn trong .inject_raw.
Ví dụ YAML của developer (map chi tiết):
uses: databases: my-postgres-cluster: target: db-main inject: ssm_param: # Agnostic injection paradigm (AWS Systems Manager) - in: MY_DB_HOST # Local identifier from: "host" # Target provides keyTrình biên dịch phân giải phần này tại thời điểm biên dịch (ánh xạ tới các chuỗi tĩnh hoặc tên DNS nội bộ) và truyền hai đối tượng cho Recipe:
"context": { "uses": { ... raw graph ... }, "inject": { "all": { "MY_DB_HOST": "db-main.internal" }, "ssm_param": { "MY_DB_HOST": "db-main.internal" } }}Cấu hình theo phạm vi kết nối (values và infra). Ngoài việc chuyển giao provides của một đích qua inject, một cạnh có thể mang cấu hình riêng của nó — các thiết lập theo từng kết nối mà Recipe tiêu thụ đọc từ đường ống topology đã được làm giàu:
.context.uses.<alias>.values— do nhà phát triển viết, khai báo trong mụcusesdạng đầy đủ của Aggregate, được xác thực theovalueSchemacủa socket..context.uses.<alias>.infra— do người vận hành viết, khai báo trong Release, được xác thực theoinfraSchemacủa socket.
Socket (usesSchema[<socket>]) là hợp đồng của Architect về những kết nối nào có thể có và chúng được mang cấu hình gì; values và infra chia cấu hình đó theo miền tác giả, tương ứng với sự phân chia values/infra trên các component. Vì vậy một cạnh có hai tác giả: nhà phát triển nối topology và tinh chỉnh nó bằng values trong Aggregate, còn người vận hành đặt infra theo từng kết nối trong Release, trong phạm vi các socket mà Architect đã khai báo. Release cũng có thể nối một cạnh vào một socket đã khai báo nhưng chưa được gắn tới một component hiện có; nó không được đổi đích của một cạnh do nhà phát triển khai báo — xem entities/release.md §“Per-edge connection configuration”.
Cấu hình theo từng cạnh có phạm vi theo bên tiêu thụ: nó chỉ xuất hiện trong context của nút đã viết cạnh đó (nguồn của kết nối), không bao giờ trong context của đích. Do đó, đầu ra được render của chính một đích là bất biến đối với các bên tiêu thụ kết nối tới nó. Một Feature gắn vào đích là nơi duy nhất nhìn thấy các kết nối: FeatureRecipe của nó đọc những component nào sử dụng đích tại .context.used_by — danh tính của từng component, socket, provides đã công bố, namespace và ranh giới mà nó được đặt vào, và, với một FeatureRecipe khai báo rằng nó đọc chúng, các render fact mà các provider của nó đã báo cáo — không bao giờ là values hay infra riêng của kết nối. Một Feature gắn vào bên tiêu thụ cũng đọc theo cách đó những gì bản render của mỗi đích đã báo cáo, trên mục của kết nối đó tại .context.uses.<alias>.render_facts, khi FeatureRecipe của nó khai báo rằng nó đọc chúng.
Attachment của kết nối (features). Một kết nối cũng có thể mang các attachment riêng của nó — chẳng hạn một thông tin xác thực mà bên tiêu thụ xuất trình cho component mà kết nối này tới — dưới features: trên mục của nó, được khóa theo một slot mà socket khai báo trong featuresSchema. Hai tác giả đó chia chúng như sau: nhà phát triển gắn trên mục kết nối của Aggregate với type và values, còn người vận hành định cỡ attachment đó bằng infra, hoặc gắn một attachment riêng với type và infra, trên mục của Release. Một attachment trên kết nối không mang khối inject riêng, đó là lý do nó vắng mặt trong quy tắc vị trí ở trên: nó không phải là một trong những nơi nhà phát triển quy định việc chuyển giao.
Mỗi attachment trở thành một attachment của component tiêu thụ có tên <alias>.<slot>, nên nó có phạm vi theo bên tiêu thụ đúng như cấu hình theo từng cạnh: FeatureRecipe của nó render ở phía bên tiêu thụ, và đầu ra của đích không thay đổi theo nó. Nó được giữ ngoài .features của Recipe tiêu thụ, vốn chỉ chứa các attachment mà khối riêng của component khai báo; thay vào đó, Recipe đọc nó dưới kết nối của nó, tại .context.uses.<alias>.features.<slot>. Một kết nối do một attachment Feature tạo ra không mang attachment nào. Xem entities/aggregate.md §“A connection’s own attachments” và entities/component.md §“Topology Sockets”.
A. Biến môi trường (env) & phân giải đích động
Cơ chế chuyển giao tiêu chuẩn cho các ứng dụng cloud-native hiện đại. Với các cạnh topology tường minh (ví dụ: một Agent giao tiếp với một Database), Aggrega dùng .context.uses để inject ánh xạ biến môi trường.
- Trường hợp sử dụng: Nhận các tên DNS nội bộ tất định, các chuỗi nội suy Infrastructure-as-Code (ví dụ:
${module.db.endpoint}), hoặc các con trỏ Vault tĩnh. Trình biên dịch nối các tham chiếu tĩnh này theo kiểu AOT để hạ tầng runtime hoặc bộ điều khiển GitOps có thể phân giải các giá trị thực.
B. Gắn file (file)
Nhiều framework AI doanh nghiệp yêu cầu một config.json có cấu trúc hoặc một chứng chỉ .pem tồn tại tại một đường dẫn cụ thể trên đĩa, thay vì dựa vào biến môi trường.
-
Trường hợp sử dụng: Inject các cấu hình JSON phức tạp hoặc đáp ứng các SDK cũ đọc từ đĩa.
-
Ý định của Dev:
features:openai_key:type: core/aws-secrets-managervalues:path: /prod/ai/openaikey: "api_token"inject:file:- in: "/etc/secrets/openai.json" # Local pathfrom: "api_token" # The attachment's provides key -
Thực tế của Ops: Recipe của Ops tạo động các
Volume,VolumeMountvàExternalSecretcủa Kubernetes cần thiết để lấy dữ liệu vault một cách an toàn và gắn nó vào/etc/secrets/openai.json.
C. Tham số dòng lệnh (arg)
Các binary biên dịch sẵn (như các worker node viết bằng Rust hoặc Go) thường bỏ qua hoàn toàn biến môi trường, và mong đợi các giá trị được truyền dưới dạng flag runtime trong lệnh thực thi của chúng.
-
Trường hợp sử dụng: Nối thêm các thực tế vật lý vào lệnh khởi động của container.
-
Ý định của Dev:
features:public-ingress:type: core/external-ingressinject:arg:- in: "--callback-url=" # Local flagfrom: "hostname" # The attachment's provides key -
Thực tế của Ops: Hostname là tên của môi trường dành cho component, nên người vận hành viết nó,
api.enterprise.com, tronginfracủa attachment này trên mục của Release dành cho component. Wasm plugin của Feature nhận URL công khai đã phân giải qua Injection Contract và phát ra một JSONPatch để nối động vào mảngargscủa Kubernetes:["/app/binary", "--callback-url=https://api.enterprise.com"], hoàn toàn bỏ qua Base Recipe của Component.