Manifest
Vai trò khái niệm của thực thể Manifest (Miền 4 — bảng ánh xạ gắn các giao diện trừu tượng với các Recipes cụ thể) được trình bày trong architecture/04-entity-taxonomy.md. Trang này đề cập đến bề mặt soạn thảo của Manifest: cách nó đứng cạnh Release, dạng ánh xạ URI phẳng, việc kết hợp qua extends, các quy tắc viết tắt URI, các liên kết Feature dựa trên annotation, và tiền tố aggrega.ai/ được nền tảng dành riêng.
Manifest và Release: tách biệt mối quan tâm
Manifest và Release đảm nhận các trách nhiệm không chồng chéo nhau:
- Manifest quy định Recipe nào hiện thực từng loại catalog, và thông qua
spec.capabilitycủa Recipe đó là provider (ví dụ: Helm, Helm-chart, Compose) kết xuất nó. Đây là bảng ánh xạ — một bản ghi theo từng dự án, được commit vào Git, cho biết Recipe cụ thể nào triển khai mỗi giao diện trừu tượng; các phiên bản và digest mà bản dựng buộc các Recipes đó phải khớp được ghim riêng, trong lockfile của mỗi Release. - Release quy định đích đến (ví dụ: thư mục đầu ra vật lý để sinh artifact GitOps). Đây là bộ định tuyến triển khai — một mô tả theo từng môi trường về nơi các artifact đã biên dịch được đặt vào.
Schema của Release không có trường provider ở bất kỳ cấp lồng nào; việc điều phối provider thuộc về riêng Manifest.
Đường biên dịch. Khi người dùng chạy aggrega build --release release.yaml, trình biên dịch phân giải các artifact vật lý bằng cách kết hợp cả hai nguồn:
- Đọc đích đến. Trình biên dịch quét các boundary của Release — ví dụ, boundary
ovh-cluster-3chứa componentuser-db(type:core/postgres:1.0.0). - Quét Manifest. Trình biên dịch mở Manifest mà Release trỏ tới qua trường
manifest:của nó. - Tra cứu hai tầng. Trước tiên, trình biên dịch kiểm tra tầng
nameđể tìm"user-db". Nếu không tìm thấy, nó kiểm tra tầngtypeđể tìm"core/postgres:1.0.0"(có phiên bản), rồi đến"core/postgres"(không có phiên bản). - Phân giải Recipe. Giá trị của mục khớp là một URI của Recipe; Recipe mà URI đó chỉ định khai báo trong
spec.capabilityprovider nào render nó. - Sinh đầu ra. Lúc này trình biên dịch đã biết thư mục đích (
dist/boundaries/ovh-cluster-3/), provider (render Helm qua Wasm) và artifact (mã nguồn của Recipe). Các ranh giới GitOps ahead-of-time được tôn trọng từ đầu đến cuối.
Ánh xạ URI phẳng
Khối mappings: của Manifest là một ánh xạ phẳng từ URI kiểu component sang URI Recipe (và từ URI kiểu feature sang URI FeatureRecipe). Ở cấp Manifest, ánh xạ không phụ thuộc vào capability; việc xác định capability đến từ trường spec.capability của từng Recipe đã phân giải tại thời điểm kết xuất, chứ không từ hình dạng cấu trúc của Manifest. Khối này tổ chức các ánh xạ dưới hai khóa cấp cao nhất:
components.typeánh xạ một URI kiểu component sang một URI Recipe. Mọi thể hiện component của kiểu đã khai báo phân giải tới Recipe được chỉ định. Ánh xạ là một-một cho mỗi kiểu component. Một khóa không nêu đúng kiểu chính xác của một thể hiện vẫn tới được thể hiện đó thông qua phần gốc của kiểu, khi không khóa nào nêu đúng kiểu chính xác đó và không có khóa nào khác được viết cho cùng phần gốc — nên một khóa viết không kèm phiên bản (core/postgres), hoặc một khóa nêu một phiên bản khác (core/postgres:1.0.0), có thể tới được một thể hiện củacore/postgres:2.0.0— nhưng Recipe mà nó nêu tên phải triển khai đúng phiên bản riêng của từng thể hiện như vậy: một thể hiện củacore/postgres:2.0.0được tới theo cách đó và được ánh xạ tới một Recipe khai báoimplements: core/postgres:1.0.0sẽ làm dừng bản dựng. Hãy ánh xạ thể hiện như vậy bằng một khóa nêu phiên bản của nó (core/postgres:2.0.0) tới một Recipe triển khai phiên bản đó.features.typeánh xạ một URI kiểu feature sang một URI FeatureRecipe. Mọi đính kèm Feature thuộc kiểu đã khai báo đều phân giải tới FeatureRecipe được chỉ định. Các Features thông tin xác thực (gắn nhãnfeature.aggrega.ai/kind: secret) nằm trong cùng ánh xạfeatures.typevới các Features vận hành — mô hình thực thể Feature thống nhất.
Mỗi khối cũng chấp nhận một tầng name bên cạnh type, ánh xạ một tên thể hiện cụ thể sang một URI Recipe (hoặc FeatureRecipe). Tầng tên được ưu tiên hơn tầng kiểu: một thể hiện được nêu tên trong components.name phân giải tới Recipe đó, còn mọi thể hiện khác cùng kiểu phân giải qua components.type. Điều này biểu đạt việc ghi đè theo từng thể hiện — hai thể hiện của một kiểu component có thể triển khai qua hai Recipes khác nhau (ví dụ, phần lớn các thể hiện cơ sở dữ liệu dùng Recipe được ánh xạ hàng loạt trong khi một thể hiện được ghim vào một hiện thực vật lý khác), mà không cần tách nhánh kiểu component hay nhân bản Manifest. Việc ghi đè áp dụng đồng nhất: thể hiện được nêu tên vừa render qua, vừa ghim mã nguồn từ Recipe ghi đè. features.name là tầng đối xứng cho các đính kèm Feature, được khóa theo tên riêng của đính kèm — khóa mà nó được viết dưới trong features: của một component — không bao giờ theo tên của component mà nó được đính kèm vào. Ví dụ ghi đè recipe theo từng thể hiện trình bày trọn vẹn một trường hợp tối thiểu gồm hai thể hiện.
Một đính kèm do một kết nối mang theo được khóa theo tên mà nó nhận trên component tiêu thụ: <alias>.<slot>, tức là bí danh mà kết nối được viết dưới đó, một dấu chấm, và slot mà đính kèm lấp vào (xem mục kết nối của Aggregate). Nhờ vậy, thông tin xác thực của một kết nối có thể được hiện thực khác với mọi đính kèm khác cùng kiểu:
spec: mappings: features: type: core/referenced-secret:1.0.0: helm/k8s-secret-from-parameter:1.0.0 name: # The credential the "gpt" connection carries in its "credential" slot. gpt.credential: helm/k8s-external-secret:1.0.0Mục này được ghim và xác minh như mọi mục tầng tên khác, như đoạn tiếp theo mô tả. Feature mà đính kèm nêu tên cũng được ghim và xác minh, đúng như Feature của một đính kèm viết trực tiếp trên component, dưới mục kết nối mà tác giả của nó đã viết — xem Tệp khóa.
Một khóa name phải nêu tên thứ gì đó mà bản dựng có. Tầng này được khớp theo tên chính xác, nên một khóa components.name không phải là thể hiện component nào trong bản dựng, hoặc một khóa features.name không phải là đính kèm nào trong đó — thường gặp nhất là tên của component mà đính kèm nằm trên, được viết vào chỗ lẽ ra là tên riêng của đính kèm — sẽ không được thứ gì tra cứu, và các thể hiện mà nó nhắm tới sẽ lặng lẽ phân giải qua tầng type. Thay vào đó, bản dựng dừng lại ở khóa như vậy, trước khi bất cứ thứ gì được render, nêu tên Manifest, khóa, các tên thuộc loại đó mà bản dựng có, và tên mà có lẽ bạn muốn viết — xem A Manifest name mapping names nothing in the build (Một ánh xạ Manifest không nêu tên thứ gì trong bản dựng).
Một hiện thực được gắn theo tên được ghim và xác minh giống như một hiện thực được gắn theo kiểu. aggrega pull thu nhận mọi Recipe và FeatureRecipe mà một trong hai tầng gắn — từ một thư mục catalog, bộ nhớ đệm hoặc một registry — và ghi từng cái vào tệp khóa của Release cùng phiên bản đã phân giải và digest nội dung, dưới mục ánh xạ gắn nó: manifest.spec.mappings.components.name.<instance> cho một mục tầng tên, bên cạnh manifest.spec.mappings.components.type.<type> cho một mục tầng kiểu. aggrega build buộc từng cái phải khớp với bản ghim của nó. Một tệp khóa không ghi dòng nào cho một hiện thực mà Manifest gắn sẽ làm dừng bản dựng vì lỗi thời, nêu tên hiện thực và mục gắn nó; một hiện thực có nội dung thay đổi kể từ lần pull cũng làm dừng bản dựng theo cùng cách, nêu cả hai digest. Trong cả hai trường hợp, aggrega pull --release <release> ghi lại hiện thực theo trạng thái hiện tại. Giống như một mục type, một mục name được ghim dù Release có khai báo một thể hiện mang tên đó hay không, nên một mục name nêu tên một Recipe mà không catalog hay registry nào chứa sẽ làm dừng lệnh pull; một mục name không nêu tên thể hiện nào mà bản dựng có cũng được ghim, và làm dừng bản dựng như đoạn trên mô tả.
apiVersion: aggrega.ai/v1beta1kind: Manifestmetadata: name: production-manifest version: 1.0.0spec: mappings: components: type: # Component-type → Recipe URI. A Recipe URI is at most two segments: an # optional leading capability, then the recipe name. The bare one-segment # form (last line) is the common case. core/datastore/postgres: helm/postgres:1.2.0 core/api-server: helm/api-helm:0.5.0 core/python-worker: standard-python-worker:2.0.0
features: type: # Feature-type → FeatureRecipe URI. Credential Features (e.g., aws-secrets-manager) sit alongside operational ones. core/data-masking: helm/data-masking-litellm:1.0.0 core/aws-secrets-manager: helm/eso-aws-fetcher:1.0.0Xác định capability tại thời điểm kết xuất. Mục Manifest gắn một kiểu component với một URI Recipe. Một URI Recipe mang tối đa hai đoạn — một capability đứng đầu tùy chọn, rồi đến tên recipe — cộng với một :version tùy chọn; bộ phân giải chỉ tách tại dấu / đầu tiên, nên một tham chiếu có đoạn thứ ba không nêu tên recipe nào và làm dừng việc phân giải. Tại thời điểm kết xuất, bộ phân giải nạp Recipe qua tra cứu URI trực tiếp trên tệp khóa và catalog, và trường spec.capability của mỗi Recipe quyết định nhóm điều phối theo từng (đường dẫn, capability). Hình dạng cấu trúc của Manifest vẫn phẳng bất kể catalog rộng hơn hỗ trợ bao nhiêu providers.
Tra cứu URI trực tiếp
Giá trị ánh xạ của Manifest là một URI Recipe. Trình biên dịch phân giải URI trực tiếp trên tệp khóa và catalog, trả về Recipe khớp. Nó không lặp qua các khai báo spec.implements để tìm một Recipe “hiện thực” một kiểu component. Mỗi mục Manifest gắn kiểu component do nhà phát triển viết với một URI Recipe cụ thể; lựa chọn này tường minh và không mơ hồ trong nội dung Manifest.
spec.implements là một phép kiểm tra tính nhất quán trên bảng ánh xạ. Giá trị spec.implements của Recipe đã được phân giải PHẢI khớp với khóa component-type của Manifest cho mục ánh xạ đó — hoặc với một kiểu cơ sở mà khóa đó extends, ở bất kỳ độ sâu nào của chuỗi, vì một Recipe được viết cho một kiểu cơ sở sẽ triển khai mọi thứ mở rộng từ nó. Một giá trị không khớp với cả hai sẽ tạo ra một OPS_ERROR kèm chẩn đoán rõ ràng nêu tên mục Manifest, Recipe đã được phân giải và giá trị spec.implements xung đột. Phép kiểm tra chạy một lần cho mỗi mục ánh xạ của Manifest, trên Manifest đã được hợp thành và trước khi bất kỳ Recipe nào được phân giải — tĩnh, tất định, và không duyệt gì ngoài chuỗi extends của chính kiểu được ánh xạ. Một khóa components.type đến được một instance component ở phiên bản mà khóa không nêu tên sẽ được đánh giá thêm một lần cho instance đó theo cùng cách, với kiểu riêng của instance ở phiên bản mà bản build biên dịch nó đứng ở vị trí của khóa, như Ánh xạ URI phẳng mô tả. Xem ../vocabulary/inheritance-and-interface.md để biết Recipe của một kiểu cơ sở miễn và không miễn cho một kiểu chuyên biệt hóa những gì.
Mọi lệnh đọc các phụ thuộc của một Release đều chạy phép kiểm tra này, và mỗi lệnh tự quyết định ý nghĩa của một phát hiện: aggrega build và aggrega pull dừng lại, vì cả hai tạo ra thứ bạn sẽ tiếp tục sử dụng, trong khi aggrega validate và aggrega lint báo cáo nó cùng các phát hiện khác và thoát với mã khác không, còn trình soạn thảo công bố nó như một chẩn đoán giữa các chẩn đoán khác. aggrega lint là ngoại lệ đối với việc đánh giá một instance: nó đánh giá các mục ánh xạ chứ không phải các instance mà chúng đến được, nên nó không báo cáo điều này, trong khi aggrega build, aggrega pull và aggrega validate --release thì có. Xem ../errors/fatal-halts.md để biết về chẩn đoán và cách khắc phục.
Phép kiểm tra tính nhất quán là bề mặt ánh xạ duy nhất đọc chuỗi extends. Việc chọn Recipe vẫn khớp chính xác theo khóa ánh xạ: một kiểu component mở rộng từ một kiểu cơ sở đã được ánh xạ vẫn cần mục riêng của nó ở đây, và không nhận được mục nào qua kế thừa.
spec.implements cũng gợi ý các ứng viên. Một instance có type không có mapping nào trong Manifest sẽ dừng bản build với một OPS_ERROR liệt kê, như các ứng viên để pin, những recipe có spec.implements có thể triển khai type đó; tính năng hoàn thành mã của trình soạn thảo trên một giá trị mapping cũng xếp chính những recipe khớp đó lên đầu. Cả hai nơi này đều đọc spec.implements so với chính type được yêu cầu, nên một recipe triển khai một trong các base của type đó sẽ không được đưa ra làm ứng viên, dù mapping đó vẫn sẽ được đánh giá là nhất quán. Do vậy, spec.implements khai báo những gì một recipe có thể triển khai và cung cấp thông tin cho lựa chọn của con người — trong bước kiểm tra tính nhất quán, chẩn đoán khi không có mapping, và tính năng hoàn thành mã — nhưng nó không bao giờ phân giải một bản build. Mapping trong Manifest là lựa chọn triển khai tường minh của người dùng, được pin trong lockfile để đảm bảo khả năng tái lập; catalog không bao giờ thay người dùng chọn một cách triển khai.
Ba dạng cho phân đoạn phiên bản của URI
Một Recipe URI trong Manifest có thể mang phiên bản ở một trong ba dạng:
- Chính xác —
helm/postgres:1.2.0. Lockfile phải ghim đúng phiên bản này; ở lần phân giải lockfile đầu tiên, trình phân giải ghim phiên bản này; nếu catalog hoặc registry không chứa phiên bản này tại thời điểm phân giải, việc nạp workspace dừng lại với một lỗi. - Khoảng —
helm/postgres:^1.2.0. Khoảng semver với quy tắc MVS tiêu chuẩn; ở lần phân giải lockfile đầu tiên, trình phân giải ghim phiên bản cao nhất hiện có thỏa mãn khoảng đó. - Không có phiên bản —
helm/postgres. Không có hậu tố:version; ở lần phân giải lockfile đầu tiên, trình phân giải ghim phiên bản mới nhất hiện có.
Các lần build sau dùng phiên bản được ghim trong lockfile bất kể dạng người dùng đã gõ. Việc phân giải lại sang một phiên bản mới hơn đòi hỏi hành động tường minh của người dùng — aggrega pull --upgrade --release <release> <uri> phân giải lại một phụ thuộc duy nhất trong khi giữ nguyên mọi ghim khác, hoặc aggrega pull --upgrade --release <release> phân giải lại tất cả — lockfile là nguồn chân lý cho các lần build; dạng người dùng gõ là cách người dùng biểu đạt ràng buộc phiên bản lúc soạn thảo.
Tham chiếu có định danh capability
Danh tính của Recipe trong catalog được phân phạm vi theo capability: hai recipe có thể dùng chung một metadata.name và phiên bản trong khi khai báo các giá trị spec.capability khác nhau. Danh tính trong registry là recipe/{capability}/{name}:{version}, được suy ra từ kind của recipe, spec.capability của nó (không kèm bất kỳ ghim phiên bản nào mà nó mang) và tên của nó; theo quy ước, cây catalog của thư viện chuẩn phản ánh tọa độ đó tại recipe/{capability}/{name}/. Một giá trị ánh xạ trong Manifest đặt tên recipe ở một trong hai mức độ chính xác:
- Trần —
mariadb:1.0.0. Phân giải được khi đúng một recipe trong catalog mang tên đó; đây là dạng phổ biến nhất trong thực tế. - Có định danh capability —
compose/mariadb:1.0.0. Phân đoạn trước dấu/đầu tiên chỉspec.capabilitycủa recipe, không kèm ghim phiên bản — một ghim được viết vào tham chiếu sẽ bị từ chối (E0095). Bắt buộc khi có nhiều hơn một recipe cùng tên: một tham chiếu trần khớp với hai recipe là mơ hồ và dừng lại rõ ràng khi phân giải thay vì âm thầm chọn một.
Một Recipe URI không có thêm vị trí nào khác. Trình phân giải chỉ tách tại dấu / đầu tiên, nên compose/mariadb chỉ capability compose và recipe mariadb, còn một tham chiếu ba phân đoạn không khớp recipe nào ở cả hai mức độ chính xác.
Các dạng phân đoạn phiên bản ở trên áp dụng cho cả hai hình thức.
Thực thể được phát hành lên registry trong các ánh xạ
Một thực thể được dùng từ registry thay vì từ catalog cục bộ được tham chiếu bằng đúng danh tính mà một thực thể cục bộ dùng: tham chiếu không mang host của registry và không có phân đoạn kind của thực thể. Trình phân giải cung cấp cả hai — host từ registry mặc định được cấu hình của workspace, phân đoạn kind từ vị trí của tham chiếu trong schema — theo các quy tắc Context-Aware Shorthand URIs ở dưới. Khi cả thư mục catalog cục bộ lẫn cache đều không giữ bản sao, aggrega pull — hoặc một bản build chạy với --auto-pull — tải thực thể từ vị trí được suy ra, lưu vào cache, và ghim phiên bản đã phân giải cùng digest nội dung trong lockfile; các lần build sau dùng cache mà không cần truy cập mạng.
# Aggregate fragment — a registry-published Component as the type:components: db: type: core/datastore/mariadb:1.0.0Vì host và phân đoạn kind của thực thể được suy ra chứ không phải được
soạn, việc viết một trong hai vào tham chiếu không trỏ tới thực thể
đã phát hành — nó tạo ra một danh tính mà không mục catalog nào mang. Một
tham chiếu Component hoặc Feature là metadata.name nguyên văn cộng với
:version tùy chọn, dù thực thể được phân giải từ catalog cục bộ,
từ cache, hay từ registry. Một workspace dùng registry riêng
đặt tên host đó trong cấu hình của chính nó thay vì trong từng
tham chiếu.
Kiểm tra tính đầy đủ
Sau khi mọi ánh xạ được phân giải, trình biên dịch xác minh rằng mọi instance component và attachment (một Feature thông tin xác thực là một attachment như mọi attachment khác) trong Aggregate của nhà phát triển đều có một Recipe hoặc FeatureRecipe đã phân giải. Các thực thể chưa được ánh xạ gây dừng nghiêm trọng với một chẩn đoán tường minh liệt kê mọi thực thể còn thiếu và gợi ý khóa components.type hoặc features.type nào cần thêm để lấp khoảng trống.
YAML anchor cho manifest DRY
Để tránh YAML phình to trên các tập ánh xạ lớn, Manifest hỗ trợ một khối defs: tùy chọn cho các YAML anchor tiêu chuẩn (& và *):
apiVersion: aggrega.ai/v1beta1kind: Manifestmetadata: name: global-base-manifest version: 1.0.0defs: - &python_worker_recipe "helm/standard-python-worker:2.0.0"spec: mappings: components: type: core/python-worker: *python_worker_recipe core/postgres: helm/postgres:1.2.0Thương lượng Feature
Quá trình bắt tay capability dùng cùng ánh xạ URI phẳng:
- Nhà phát triển gắn
core/data-maskingvào một component trong Aggregate, dưới một tên riêng trong mapfeatures:của component đó. - Trình biên dịch tra cứu
core/data-maskingtrong mapfeatures.typecủa Manifest. - Nếu việc tra cứu phân giải ra một FeatureRecipe URI (ví dụ:
helm/data-masking-litellm:1.0.0), capability đó tồn tại và pipeline của FeatureRecipe thực thi theo thứ tự đã định. - Nếu
features.typekhông chứa mục khớp nào, trình biên dịch dừng build và liệt kê Feature chưa được ánh xạ.
Manifest cũng chấp nhận một khối features.annotations — một bề mặt soạn thảo song song cho phép một Release hoặc một phân hệ Aggregate gắn Features theo khóa annotation thay vì khai báo theo từng component. Hình dạng binding, cách phân chia side-vs-pillar quyết định bề mặt soạn thảo nào dùng đường định tuyến nào, nguyên tắc attachment tường minh được ưu tiên, và quy tắc mặc định của schema được trình bày trong mục riêng Annotation-Driven Feature Bindings ở phần dưới.
Kết hợp qua extends
Một Manifest có thể khai báo một tham chiếu extends: duy nhất, chỉ đến một Manifest cơ sở mà nó kế thừa mappings. Tham chiếu này không phải là URI và không bao giờ được phân giải qua catalog: Manifest thuộc phía triển khai, được viết cạnh Release thay vì được phát hành, nên giá trị là một đường dẫn tương đối đến một tệp Manifest — ./base-manifest.yaml — hoặc metadata.name trần của một Manifest nằm trong chính thư mục của Release. Đường dẫn tương đối phải dẫn đến một Manifest bên trong workspace — hoặc, khi Release được chỉ định bên ngoài workspace (trên dòng lệnh, hoặc bởi cấu hình workspace), thì bên trong thư mục chứa Release đó, và với một Manifest mà bạn chỉ định riêng trên dòng lệnh bên ngoài workspace, thì bên trong thư mục chứa Manifest đó: đường dẫn nào leo ra ngoài, hoặc bị một liên kết tượng trưng đưa ra ngoài, sẽ bị từ chối trước khi tệp mà nó chỉ đến được đọc (xem errors/fatal-halts.md §“A reference to another file leads out of the directory it must stay inside (Một tham chiếu đến tệp khác dẫn ra ngoài thư mục mà nó phải nằm bên trong)”). Các ánh xạ con ghi đè lên ánh xạ cơ sở khi trùng khóa, hỗ trợ các mẫu lớp phủ môi trường (tương đương staging/prod với các khác biệt chính xác theo từng môi trường) và các mẫu phát triển cục bộ mà không cần sao chép toàn bộ.
Ngữ nghĩa hợp nhất. Khi một Manifest cục bộ mở rộng một Manifest cơ sở, trình biên dịch thực hiện thay thế khóa nông theo từng tầng — các từ điển type và name được hợp nhất độc lập, không hợp nhất sâu — điều này đảm bảo tra cứu từ điển O(1) và giữ cho hành vi kế thừa có thể dự đoán được. Trong mỗi tầng, khóa của con ghi đè khóa của cha.
Mẫu cầu nối phát triển cục bộ. Một cách dùng phổ biến của extends là hoán đổi một FeatureRecipe thông tin xác thực để tạo nguyên mẫu cục bộ mà không động đến Aggregate. Trong môi trường production, Manifest cơ sở ánh xạ Feature thông tin xác thực core/aws-secrets-manager đến một FeatureRecipe production trong tầng features.type. Để tạo nguyên mẫu cục bộ, đội nền tảng cung cấp một local-manifest mở rộng Manifest cơ sở và ghi đè chính xác ánh xạ Feature thông tin xác thực để dùng host-env-injector — một FeatureRecipe cục bộ đưa thông tin xác thực vào tệp Compose dưới dạng tham chiếu biến như ${SECRET_NAME}, mà Docker Compose thay thế từ môi trường shell hoặc một tệp .env khi stack khởi động. Nhà phát triển có được quy trình làm việc cục bộ tiêu chuẩn, và Aggregate vẫn không phụ thuộc vào capability cho production.
URI viết tắt nhận biết ngữ cảnh
Trình biên dịch Aggrega sử dụng suy luận nhận biết ngữ cảnh (Context-Aware Inference) khi phân giải các URI OCI trong Manifests. Nếu kỹ sư bỏ qua tên miền đầy đủ (Fully Qualified Domain Name, FQDN) và loại thực thể kiến trúc, trình biên dịch tự động dùng registry mặc định (được cấu hình trong .aggrega-config.yaml) và suy ra loại thực thể dựa trên vị trí của chuỗi trong schema.
Các quy tắc suy luận:
- Tên miền mặc định: Mọi URI thiếu tên miền (ví dụ:
python-worker-helm:1.0) đều được thêm tiền tố làdefault_registryđã cấu hình (mặc định:hub.aggrega.ai/). - Mở rộng thực thể theo ngữ cảnh: Trình biên dịch nối thêm đường dẫn thực thể đúng dựa trên từ điển schema chặt chẽ:
- Các chuỗi nằm dưới
Aggregate.spec.components[].typeđược mở rộng thành/component/. - Các chuỗi nằm dưới
Aggregate.spec.aggregates[].typeđược mở rộng thành/aggregate/. - Các chuỗi nằm dưới
Manifest.spec.mappings.components.typehoặcManifest.spec.mappings.components.nameđược mở rộng thành/recipe/. - Các chuỗi nằm dưới
Manifest.spec.mappings.features.typehoặcManifest.spec.mappings.features.nameđược mở rộng thành/featurerecipe/. Điều này bao gồm cả các Features thông tin xác thực (được gắn nhãnfeature.aggrega.ai/kind: secret) — chúng dùng cùng đường dẫn FeatureRecipe. - Các chuỗi được gán cho
pipeline[].pluginđược mở rộng thành/plugin/.
- Các chuỗi nằm dưới
- Thứ tự ưu tiên ba tầng: Trước khi áp dụng suy luận OCI, trình biên dịch tìm trong các thư mục catalog của workspace và cache artifact (tầng workspace và cache) như được định nghĩa trong Mô hình phân giải thực thể ba tầng. Suy luận OCI chỉ được áp dụng khi thực thể đến tầng registry. Một khóa hay giá trị ánh xạ không bao giờ được đọc như đường dẫn tệp: một Recipe hay FeatureRecipe được viết cục bộ nằm trong một thư mục catalog —
catalog/ở gốc workspace, hoặc một thư mục màworkspace.catalog_dirsliệt kê — và được gọi bằng tham chiếu của nó.
Cách viết tắt trong thực tế:
# Capability-qualified — required when two recipes share the name "postgres":"core/postgres": "helm/postgres:2.0"
# Bare — resolves when one recipe carries the name:"core/postgres": "postgres:2.0"# Found in a local catalog directory or the cache; failing both, `aggrega pull`# (or a build run with --auto-pull) fetches it from the registry location derived# from the configured default registry and the Recipe kind.# A private registry is named in workspace configuration, not in the reference.Không có tiền tố ops/. Tên Recipe không mang tiền tố ops/ — thư mục loại thực thể recipe/ trong phân loại OCI đã xác định miền, và Recipes được phát hành dưới recipe/{capability}/{name} mà không cần thêm tiền tố. Manifests tham chiếu Recipes bằng {capability}/{name}, hoặc bằng tên trần để suy luận nhận biết ngữ cảnh. Xem architecture/13-catalog-and-registry.md §6 để biết đầy đủ phân loại OCI.
Liên kết Feature dựa trên annotation
Khối features.annotations của Manifest khai báo các liên kết giữa khóa annotation và kiểu Feature, cùng với các đường định tuyến mà mỗi liên kết dùng để chuyển giá trị annotation đi qua. Liên kết là bề mặt soạn thảo để nén các lần gắn Feature lặp lại theo từng component — mẫu mà hàng chục component trong một ranh giới đều mang một khối features: giống hệt nhau — thành các khai báo annotation đơn lẻ trên ranh giới Release hoặc các hệ thống con của Aggregate.
Hình dạng schema:
spec: mappings: features: type: core/rewrite-host: helm/rewrite-host-helm:1.0.0 core/db-pool: helm/db-pool-helm:1.0.0
annotations: feature.aggrega.ai/rewrite-host: feature: core/rewrite-host maps: infra: - upstream # Release-side: routes annotation value into infra.upstream
feature.aggrega.ai/db-pool: feature: core/db-pool maps: values: - pool # Aggregate-side: routes annotation value into values.poolMột liên kết mang trường feature chỉ định kiểu Feature đích và khối maps nhóm các tuyến khóa con theo đường dẫn dấu chấm theo trụ cột đích. Trường feature tham chiếu đến một kiểu Feature cũng phải xuất hiện trong phần features.type cùng cấp (nơi chứa liên kết phiên bản FeatureRecipe). Khối maps khai báo hai danh sách theo khóa trụ cột — maps.infra và maps.values — mỗi danh sách chứa các chuỗi đường dẫn dấu chấm trỏ vào các thuộc tính spec.schema.<pillar>.<path> của Feature đích. Một liên kết phải khai báo ít nhất một đường dẫn trên hai danh sách (JSON Schema áp đặt minProperties: 1 trên maps).
Tính đa hình Provider cho cùng một khóa annotation — ví dụ: feature.aggrega.ai/rewrite-host liên kết với core/k8s-dns-resolver trong một triển khai Kubernetes nhưng với core/compose-bridge trong một triển khai Compose cục bộ — được biểu đạt bằng cách chọn các kiểu Feature khác nhau trong các Manifests khác nhau; mỗi Manifest liên kết annotation với một Feature, và FeatureRecipe của Feature được chọn mang phần triển khai dành riêng cho từng nhà cung cấp.
Phân vùng phía và trụ cột. Bất biến Aggregate-as-Authoring-Surface giới hạn mỗi phía soạn thảo vào các đường định tuyến của một trụ cột. Annotation phía Aggregate chỉ định tuyến qua các đường dẫn maps.values; annotation phía Release chỉ định tuyến qua các đường dẫn maps.infra. Một liên kết khai báo đường dẫn ở cả hai trụ cột hỗ trợ kết hợp giữa hai phía: annotation phía Aggregate kích hoạt tập con của trụ cột values; annotation phía Release trên cùng khóa kích hoạt tập con của trụ cột infra; cả hai đóng góp kết hợp thành một lần gắn Feature duy nhất cho mỗi cặp (Component, Feature) với cả hai trụ cột được điền. Sự không khớp giữa phía và trụ cột — ví dụ, annotation phía Aggregate trên một liên kết chỉ khai báo maps.infra — sẽ dừng quá trình build với một chẩn đoán rõ ràng nêu khóa annotation, trụ cột được định tuyến, phía soạn thảo và vị trí nguồn, được xếp vào miền của tài liệu nơi giá trị annotation được soạn.
Xác thực đích của đường dẫn. Khi nạp catalog, trình biên dịch xác minh rằng mọi đường dẫn dấu chấm được khai báo dưới maps.infra và maps.values đều tương ứng với một thuộc tính mà spec.schema.<pillar> của Feature đích thực sự khai báo. Một liên kết định tuyến đến đường dẫn mà schema Feature không liệt kê sẽ dừng việc nạp catalog với một OPS_ERROR rõ ràng, nêu tên liên kết, Feature đích, cùng trụ cột và đường dẫn mà nó định tuyến qua. Các hình dạng schema vượt ra ngoài việc duyệt thuộc tính đơn giản ($ref, patternProperties, kết hợp oneOf / anyOf / allOf) sẽ kết thúc kiểm tra tĩnh tại nhánh đó và để bước xác thực schema phía sau phát hiện mọi sự không khớp.
Hình dạng giá trị annotation. Một liên kết tiếp nhận giá trị annotation ở ba hình dạng. Vô hướng — một giá trị YAML đơn (chuỗi, số, boolean). Một giá trị vô hướng đi cùng liên kết khai báo đúng một đường dẫn trên cả hai trụ cột sẽ định tuyến giá trị đến đường dẫn duy nhất đó; một giá trị vô hướng đi cùng liên kết khai báo nhiều hơn một đường dẫn là định tuyến mơ hồ và dừng quá trình build với một chẩn đoán rõ ràng, được xếp vào miền của tài liệu nơi giá trị annotation được soạn. Có cấu trúc — một map YAML mà mỗi khóa con cấp cao nhất khớp với một mục đường dẫn dấu chấm dưới maps.infra hoặc maps.values; mỗi khóa con định tuyến độc lập đến trụ cột đã khai báo của nó, và phân vùng phía và trụ cột áp dụng cho từng khóa con. YAML null tường minh — chọn không tham gia liên kết được kế thừa tại phạm vi cascade (với null theo từng khóa con bên trong một giá trị có cấu trúc giúp bỏ từng khóa con riêng lẻ trong khi các khóa cùng cấp vẫn giữ nguyên). Để xem hướng dẫn soạn thảo chuẩn về giá trị có cấu trúc — hợp nhất cascade theo khóa con, kết hợp giữa hai phía, xác thực kiểu theo khóa con, nguyên tắc mặc định nới lỏng cho các trường schema không khai báo type — xem providers/well-known-annotations.md §“Structured annotation values”.
Gắn tường minh thắng khi trùng khóa. Khi một component của Release hoặc component của Aggregate mang cả một mục features: tường minh và một annotation mở rộng thành cùng khóa Feature, mục tường minh được giữ lại và việc mở rộng annotation cho khóa đó trên component đó không có tác dụng. Lần gắn tổng hợp không bao giờ ghi đè một instance Feature do tác giả khai báo. Do đó, tác giả có thể dùng mở rộng annotation cho phần lớn component và ghi đè chính xác từng component riêng lẻ bằng cách viết một mục features: tường minh với cùng khóa — mục tường minh mang tùy chỉnh theo component, còn annotation lan xuống mọi component khác mà không thay đổi.
Tường minh thắng theo từng lá khi kết hợp giữa hai phía. Khi một lần gắn tường minh và một đóng góp annotation cùng điền vào một instance Feature nhưng ghi vào các lá khác nhau, cả hai đóng góp đều được giữ và Feature thu được mang cả hai lá, với nguồn gốc theo từng lá ghi lại nguồn của mỗi lá. Khi một lần gắn tường minh và một đóng góp annotation nhắm cùng một lá trong cùng một trụ cột, đóng góp tường minh thắng và IR ghi lại nguồn gốc annotation bị loại bỏ dưới dạng một dấu ghi đè trên lá đó. Việc nạp catalog hiển thị sự ghi đè này tại thời điểm build qua một cảnh báo lint mang tính tư vấn, nêu khóa annotation bị loại bỏ + nguồn.
Giá trị mặc định của schema tại thời điểm mở rộng. Lần gắn Feature tổng hợp do mở rộng annotation tạo ra chỉ mang những lá mà giá trị annotation điền qua các đường dẫn đã khai báo của liên kết. Các giá trị mặc định của schema khai báo trên spec.schema của Feature đích không được hợp nhất vào lần gắn tổng hợp tại thời điểm mở rộng. Việc hiện thực hóa giá trị mặc định là trách nhiệm của lớp render FeatureRecipe, được áp dụng đồng nhất cho cả lần gắn tường minh và tổng hợp để hai con đường tạo ra cùng đầu ra phía sau cho cùng cấu hình hiệu lực.
Phân tách không gian tên annotation:
| Tiền tố | Chủ sở hữu | Mục đích |
|---|---|---|
aggrega.ai/ | Chỉ nền tảng Aggrega | Annotation gốc của nền tảng được provider đọc trực tiếp (ví dụ: aggrega.ai/namespace). |
feature.aggrega.ai/ | Thư viện chuẩn chính thức | Lối tắt Feature-annotation được liên kết trong Manifest. |
{any-other-domain}/ | Doanh nghiệp / cộng đồng | Lối tắt Feature-annotation tùy chỉnh. |
Dành riêng tiền tố aggrega.ai/
Các binding features.annotations của Manifest không được dùng tiền tố aggrega.ai/ trần — tiền tố này được dành riêng cho các annotation gốc của nền tảng do trình biên dịch phát ra (nhãn OTel/provenance, v.v.). Các tiền tố con có phạm vi (component.aggrega.ai/*, compliance.aggrega.ai/*, acme.aggrega.ai/* của doanh nghiệp) vẫn dùng được cho người dùng khi viết. Xem providers/well-known-annotations để biết tập annotation được nền tảng dành riêng.