Tổng quan về tham chiếu thực thể
Bộ từ vựng soạn thảo của Aggrega gồm Aggregate, Component, Feature, Recipe, FeatureRecipe, Plugin, Manifest, Release, SchemaLibrary, MappingLibrary, WorkloadLibrary và ArtifactLibrary — cùng với kind Workload do nền tảng sở hữu, được nhúng bên trong đầu vào tổng hợp của một Recipe. Mỗi thực thể là một tài liệu YAML tuân theo một JSON Schema; mọi trường, từ khóa và tham chiếu liên thực thể mà tài liệu tham chiếu này mô tả đều là một phần của hợp đồng soạn thảo đó.
Nhóm chương này bao quát bề mặt soạn thảo: mỗi thực thể chấp nhận những trường nào, mỗi trường có ý nghĩa gì với người soạn thảo, các trường tương tác với nhau giữa các thực thể ra sao (implements: của một Recipe nêu tên Component mà nó hiện thực, con trỏ manifest: của một Release tới một Manifest, containers.<name>.attachments của một Workload tham chiếu tới các slot được khai báo trong featuresSchema của Component). Vai trò khái niệm của từng thực thể — vì sao hệ phân loại có hình dạng như vậy, miền nào sở hữu thực thể nào, Bốn Miền tách biệt các mối quan tâm soạn thảo ra sao — nằm trong ../architecture/04-entity-taxonomy.md. Vai trò kiến trúc của kind Workload như một trong ba kind đầu vào của Recipe nằm trong ../architecture/16-recipe-input-composition.md.
Cách tổ chức tài liệu tham chiếu này
Hai bề mặt tài liệu hóa bộ từ vựng soạn thảo, và chúng trả lời những câu hỏi khác nhau.
Mọi kind liệt kê ở trên đều có một tài liệu tham chiếu schema được sinh tự động. Các trang đó được sinh từ các schema do chính trình biên dịch công bố, và schema/README.md lập chỉ mục toàn bộ — các kind thực thể, các dạng wire của plugin lẫn các tệp workspace. Hãy dùng tài liệu tham chiếu schema để trả lời câu hỏi “tài liệu này có thể chứa gì”: mọi trường, kiểu của nó, nó có bắt buộc hay không, và các ràng buộc mà envelope áp đặt.
Các trang dưới đây là hướng dẫn soạn thảo. Chúng được viết tay để dạy những điều schema không thể: một kind dùng để làm gì, các trường của nó tương tác với các kind khác ra sao, dạng soạn thảo nào phù hợp với tình huống nào, và các quy ước mà catalog thư viện chuẩn tuân theo. Hãy dùng một hướng dẫn soạn thảo để trả lời câu hỏi “tôi viết nó thế nào, và vì sao nó có hình dạng như vậy”.
Tham chiếu theo từng thực thể
- Aggregate — artifact ý định khai báo của nhà phát triển. Khai báo các component, topology của chúng qua
uses, các hợp đồng tham số cho biến thể theo từng môi trường, và các gắn kết Feature. - Component — thực thể catalog do Platform Architect soạn thảo, định nghĩa một kind component có thể tái sử dụng. Khai báo các schema
valuesvàinfra(mỗi cái là một khai báo JSON Schema 2020-12 ở dạng gọn hoặc đầy đủ), hợp đồng đầu raprovides, hợp đồng cạnh vàousesSchema, và các slot thông tin xác thực quafeaturesSchema. - Feature — thực thể catalog do Platform Architect soạn thảo cho một mối quan tâm xuyên suốt (sidecar giám sát, che giấu dữ liệu, chính sách định tuyến). Khai báo các schema
valuesvàinfra(mỗi cái là một khai báo JSON Schema 2020-12), các bộ chọn gắn kếtappliesTo, và các ràng buộc khả năng tương tác. - Recipe — bản chuyển đổi do Ops soạn thảo từ một Component sang một provider cụ thể. Kết hợp ba kind đầu vào (
source:+valuesMapping:,workload:,artifacts:— mỗi cái chấp nhận nội dung nội tuyến hoặc$import:theo bộ từ vựng nhập tệp hợp nhất) cùng một khốiprovidestạo thành hợp đồng tiêm từ phía bên gọi. - FeatureRecipe — bản chuyển đổi do Ops soạn thảo từ một Feature sang một provider cụ thể. Dùng cùng hợp đồng ba kind đầu vào như Recipe, cùng một
injectMappingchặn đường ống inject để viết lại biến ở phía bên gọi. - Plugin — plugin WebAssembly được định địa chỉ theo nội dung. Khai báo một loại socket duy nhất mà nó triển khai —
provider,linter,pipeline-step,governance,cli,parserhoặcimporter— phiên bản ABI của nó, và các khả năng mà loại socket đó phục vụ. Một Plugin kết xuất provider (pluginType: provider) khai báo (các) tên provider mà nó phục vụ trongspec.provider.capabilitiesvà mang siêu dữ liệu provider-socket của nó —workloadSchemavàwellKnownAnnotations— trong cùng khốispec.providerđó. - Manifest — bảng ánh xạ theo từng dự án. Liên kết các kiểu Component và Feature trừu tượng với các URI Recipe và FeatureRecipe cụ thể, dưới
componentsvàfeatures, với thứ tự tra cứuname>typecó phiên bản >typekhông có phiên bản. - Release — bộ định tuyến triển khai theo từng môi trường. Liên kết một Aggregate với một Manifest, ánh xạ các component vào các ranh giới vật lý, cung cấp giá trị tham số theo từng môi trường, và gắn các Features do Ops quản lý.
Các thực thể thư viện
Bốn kind thư viện thuộc Tầng 3 — các thực thể tái sử dụng tùy chọn. Một catalog khai báo một thư viện khi cùng một nội dung lặp lại giữa các thực thể của nó, và nếu không thì phát hành mà không có chúng. Mỗi thư viện chứa một loại nội dung, và fragment trong một tham chiếu (#/schemas/, #/mappings/, #/workloads/, #/artifacts/) cho biết tham chiếu đó trỏ tới thư viện nào.
- SchemaLibrary — các định nghĩa JSON Schema 2020-12 có thể tái sử dụng cùng các helper tham số hóa tùy chọn, được tham chiếu từ các schema của một Component hoặc Feature bằng
$ref: <Library>#/schemas/<name>. - MappingLibrary — các đoạn template Go có thể tái sử dụng, được nhập vào
valuesMapping:của một Recipe hoặc FeatureRecipe bằng$import: <Library>#/mappings/<name>. - WorkloadLibrary — nội dung Workload có thể tái sử dụng, được nhập vào
workload:của một Recipe hoặc FeatureRecipe bằng$import: <Library>#/workloads/<name>. - ArtifactLibrary — các gói tệp đầu ra phụ trợ có thể tái sử dụng, được nhập vào
artifacts:của một Recipe hoặc FeatureRecipe bằng$import: <Library>#/artifacts/<name>. Một gói là đơn vị tái sử dụng: một lần nhập mở rộng thành một đầu ra cho mỗi tệp trong gói.
Các kind do nền tảng sở hữu
- Workload — kind trình biên dịch do nền tảng sở hữu (không phải thực thể catalog do người dùng soạn thảo). Được nhúng bên trong trường
workload:của một Recipe (nội tuyến hoặc qua$import:); mô tả hình dạng triển khai mà provider tổng hợp thành các manifest gốc của provider.