Bỏ qua để đến nội dung
AggregaAggrega
Chọn ngôn ngữ: Tiếng Việt
Trang này được dịch bằng máy. Đọc bản gốc tiếng Anh.

Component

Vai trò khái niệm của thực thể Component (giao diện nút tính toán trừu tượng trong Miền 2) được trình bày tại architecture/04-entity-taxonomy.md. Trang này đề cập đến bề mặt soạn thảo Component: Phân loại nhãn ngữ nghĩa mà các Kiến trúc sư dùng để xếp lớp danh tính nhận thức lên trên bản thể học vận hành cơ sở, khai báo schema: cho các trụ cột dữ liệu, các bảng khai báo usesSchema và featuresSchema cho các ổ cắm cấu trúc liên kết và các khe gắn kết, các yêu cầu bắt buộc về sự hiện diện, cơ chế kế thừa extends:, và khối quy tắc liên trường assertions:.

Phân loại nhãn ngữ nghĩa (Quy ước của thư viện chuẩn)

Nếu các kiểu cơ sở hoàn toàn là cloud-native, thì trí tuệ vận hành và nhận thức của kiến trúc được xếp lớp hoàn toàn thông qua duck-typing ngữ nghĩa.

Trình biên dịch Go lõi không diễn giải các nhãn này. Trình biên dịch xây dựng đồ thị Biểu diễn trung gian (IR) phẳng mà không diễn giải ngữ nghĩa của nhãn. Các nhãn này đại diện cho Quy ước của thư viện chuẩn—các “dấu ấn di truyền” bất biến do Kiến trúc sư nền tảng soạn trong Miền 2. Chúng cung cấp các điểm móc ngữ nghĩa tường minh mà các trình xác thực chính sách Wasm và các Recipes vận hành vật lý dùng để quản trị kiến trúc.

(A) Lớp đám mây chung Các nhãn này mô tả các hành vi phổ quát, cho phép các công cụ chính sách và các proxy L7 được sinh ra quản trị các kiến trúc doanh nghiệp tiêu chuẩn mà không cần hiểu nguyên bản các framework AI.

Tiền tố nhãnGiá trị cho phép (Quy ước)Vì sao Platform Ops cần nó (Điểm móc chính sách)
tool.aggrega.ai/impactread-only, mutatingCho phép các công cụ chính sách đánh giá AuthZ theo đặc quyền tối thiểu. Các công cụ có tác động thay đổi có thể tự động kích hoạt các chính sách yêu cầu gắn các sidecar cổng phê duyệt nghiêm ngặt.
datastore.aggrega.ai/enginerelational, document, kv, vector, graph, semantic-memory, search (tập giá trị đang ổn định dần theo catalog đã được điền)Cho phép các công cụ chính sách thực thi an toàn kiểu giữa các nút (ví dụ: ngăn một agent cố gửi payload SQL đến một Vector DB).
gateway.aggrega.ai/intelligencesemantic, l4-meshQuy định những tính năng mà một bộ định tuyến có thể hỗ trợ về mặt vật lý (ví dụ: ngăn một Feature định tuyến theo model mà yêu cầu chỉ định, chẳng hạn một chuỗi dự phòng, gắn vào một mesh TCP tiêu chuẩn).
dataplane.aggrega.ai/request-mirroringfull-rate, sampledCho phép một Feature sao chép lưu lượng trực tiếp sang một đích thứ hai chọn một proxy có khả năng sao chép, và phân biệt proxy sao chép mọi yêu cầu khớp với proxy có thể thiết lập tỷ lệ yêu cầu được sao chép.
dataplane.aggrega.ai/caller-identityclient-certificate, injected-headerCho phép một Feature cần xác định bên gọi ban đầu cho dịch vụ phía sau proxy chọn một component có thể truyền danh tính đó, và đọc cơ chế nào truyền nó — thông tin chứng chỉ TLS của chính client được chuyển tiếp, hay một header do proxy tự tạo sau khi xác thực bên gọi.
dataplane.aggrega.ai/content-maskingentity-recognition, pattern-listCho phép một Feature che văn bản nhạy cảm chọn một component có thể thay thế văn bản đó bằng một placeholder trong payload chat và completion mà nó định tuyến, trước khi văn bản đi xa hơn. Giá trị chỉ định độ trung thực: với entity-recognition, component thay thế các kết quả khớp với mẫu được cung cấp trong cấu hình của nó, và cả các loại thực thể mà một dịch vụ nhận dạng nó gọi phát hiện được; với pattern-list, nó chỉ thay thế các kết quả khớp với mẫu được cung cấp trong cấu hình và không gọi dịch vụ nhận dạng nào.
dataplane.aggrega.ai/prompt-guardpattern-list, classifierCho phép một Feature sàng lọc prompt của model chọn một component có thể kiểm tra payload chat và completion mà nó định tuyến và từ chối một yêu cầu dựa trên nội dung. Giá trị chỉ định độ trung thực: với pattern-list, việc so khớp dựa trên các mẫu được cung cấp trong cấu hình của nó, trên payload của model chứ không phải một HTTP body tùy ý; với classifier, phán quyết đến từ một bộ phân loại văn bản đã huấn luyện, thông qua một dịch vụ phát hiện mà component gọi, so với một ngưỡng được cung cấp trong cấu hình của nó.
dataplane.aggrega.ai/upstream-tlstrust-anchorCho phép một Feature yêu cầu proxy kiểm tra bên mà nó đang giao tiếp chọn một component có khả năng xác minh chứng chỉ của upstream theo một trust anchor do Release cung cấp.
dataplane.aggrega.ai/upstream-pinningpublic-keyCho phép một Feature ghim khóa mà upstream được phép trình ra chọn một component có khả năng từ chối upstream trừ khi chứng chỉ nó trình ra mang một trong các khóa công khai do Release cung cấp. Đây là một khẳng định khác với upstream-tls: pin nói chứng chỉ phải là khóa nào, còn anchor nói chứng chỉ phải ghi gì.
dataplane.aggrega.ai/period-budgetcost, tokensCho phép một Feature giới hạn lượng lưu lượng được tiêu thụ trong một khoảng thời gian chọn một component có khả năng từ chối các yêu cầu model khi lượng nó đã đếm trong khoảng thời gian đó vượt quá giới hạn đặt trong cấu hình. Giá trị chỉ định thứ được đếm: cost, chi phí của lưu lượng, tính giá theo bảng mà component lưu cho mỗi model; tokens, số token mà phản hồi của mỗi model báo đã đọc, ghi hoặc cả hai, được component đếm mà không tính giá gì.
dataplane.aggrega.ai/concurrency-captotal, per-targetCho phép một Feature giới hạn số yêu cầu mà một component mang cùng lúc chọn một component có khả năng giữ lại hoặc từ chối yêu cầu vượt quá mức trần đặt trong cấu hình. Giá trị chỉ định thứ mà một mức trần đếm: total, mọi yêu cầu component chuyển tiếp, theo một mức trần; per-target, các yêu cầu đang xử lý tới mỗi đích upstream mà nó gửi đến, với một mức trần cho mỗi đích và không có mức trần cho tổng.

Các khóa dataplane.aggrega.ai/ chỉ một vị trí trên đường đi của lưu lượng chứ không phải một loại component, nên proxy, ingress gateway và service mesh đều tự mô tả bằng một bộ từ vựng chung thay vì mỗi loại cần bộ riêng. Hai tính chất của họ khóa này đáng đọc kỹ, vì cả hai đều dễ bị hiểu ngược:

  • Giá trị mang độ trung thực, không chỉ sự hiện diện của khả năng. Hai component có thể cùng sao chép yêu cầu mà vẫn khác nhau theo cách một Feature quan tâm, nên sự phân biệt nằm trong giá trị và một Feature chọn độ trung thực nó cần. Một component cung cấp độ trung thực mạnh hơn mang giá trị mạnh hơn và không mang giá trị nào khác.
  • Một giá trị khẳng định điều sản phẩm có khả năng làm, không bao giờ là điều một triển khai đã bật. Hai điều này nghe giống nhau và chỉ điều thứ nhất là thuộc tính của component. Một proxy có thể xác minh chứng chỉ upstream mang upstream-tls: trust-anchor bất kể một triển khai cụ thể có bật việc kiểm tra hay không, vì nhãn là thứ một Feature dùng để chọn trước khi bất cứ thứ gì được cấu hình.

Một component không có gì để mô tả trên một trong các trục này thì không mang giá trị nào ở đó thay vì mang giá trị yếu nhất, đúng như ở những chỗ khác trong phân loại: sự vắng mặt nghĩa là trục đó không áp dụng cho component ấy, nên một Feature yêu cầu bất kỳ giá trị nào trên trục đó sẽ không gắn vào, và điều đó là đúng.

(B) Lớp AI chuyên biệt (Danh tính nhận thức) Các nhãn này mô tả danh tính nhận thức của workload, cho phép kiến trúc bảo mật các framework AI hiện đại.

Tiền tố nhãnGiá trị cho phép (Quy ước)Vì sao Platform Ops cần nó (Điểm móc chính sách)
model.aggrega.ai/capabilitygenerative, embedding, transcriptionĐược dùng bởi các chuỗi selector usesSchema (được trình biên dịch Go đánh giá nguyên bản trong quá trình phân tích tĩnh) để đảm bảo nhà phát triển không vô tình định tuyến một payload văn bản sinh tạo đến một endpoint embedding.
model.aggrega.ai/apiopenai, anthropic, gemini, nativeChỉ API model nào trả lời tại địa chỉ mà một component công bố: openai khi đó là OpenAI API, của chính nhà cung cấp hoặc một bản hiện thực của máy chủ, anthropic khi đó là Messages API của Anthropic, của chính nhà cung cấp hoặc một bản hiện thực của máy chủ, gemini khi đó là Gemini API của Google, và native khi đó là API riêng của sản phẩm và không phải các API trên. Mọi component model đều mang nhãn này, và một gateway có khả năng phục vụ một API model cũng vậy, nên một socket chọn component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api nhận một model hoặc một gateway như thế và từ chối gateway không phục vụ API nào, còn một socket chỉ định một giá trị, chẳng hạn model.aggrega.ai/api=anthropic, chỉ nhận thứ phục vụ API đó. Nhãn chỉ điều sản phẩm phục vụ, không phải điều một Release nối: một gateway có các model được nối vào socket riêng của nó vẫn mang nhãn này ngay cả khi chưa nối gì. Nhãn là một chuỗi mà selector so khớp; không có gì kiểm tra thứ thực sự trả lời tại địa chỉ đó.
agent.aggrega.ai/autonomyautonomous, copilotXác định rủi ro thực thi của vòng lặp nhận thức, cho phép các chính sách bắt buộc các tính năng phê duyệt của con người cho các agent hoàn toàn tự trị.

(C) Các nhãn xuyên suốt (Quản trị, Trạng thái và Phần cứng) Đây là các thẻ doanh nghiệp nền tảng thúc đẩy việc xác thực Zero-Trust và định tuyến phần cứng.

Tiền tố nhãnGiá trị cho phép (Quy ước)Vì sao Platform Ops cần nó (Điểm móc chính sách)
component.aggrega.ai/hostingself-hosted, managed, external, mixedGhi lại ai vận hành tài nguyên nền của một component — trục ranh giới tin cậy. Các công cụ chính sách đọc nó để tính rủi ro rò rỉ dữ liệu (ví dụ: dữ liệu nội bộ được định tuyến đến một API bên thứ ba managed sẽ rời khỏi ranh giới của bên vận hành). Mang tính xuyên suốt: cùng các giá trị mô tả như nhau một cơ sở dữ liệu được quản lý, một API model được quản lý và một máy chủ suy luận tự vận hành. mixed đánh dấu một component có các Recipes trải trên nhiều hơn một hình thức vận hành — một kho dữ liệu được tự lưu trữ bởi các Recipes Helm và Compose của nó và được quản lý bởi các Recipes RDS của nó — nên hình thức vận hành của một Release theo Recipe mà Manifest của nó chọn.
compliance.aggrega.ai/data-classpublic, internal, restrictedLớp dữ liệu mà một component lưu giữ. Trình biên dịch chuyển nó vào đồ thị build dưới dạng một chuỗi và không xếp hạng gì cả; một policy mà người vận hành gắn ở vai trò ir-verdict sẽ xác định thứ tự cho các lớp trong cấu hình riêng của nó và đọc nhãn dọc theo các tuyến mà trình biên dịch liệt kê — ví dụ, dừng một bản build khi một component restricted tiếp cận một component thuộc lớp khác mà trên tuyến không gắn Feature giải mật nào (policy-data-class-route). Không Component nào của thư viện chuẩn mang nhãn này: lớp dữ liệu là một tuyên bố về cách một hệ thống sử dụng một component, do chính Component của hệ thống đó mang — chẳng hạn một bản chuyên biệt hóa thông qua extends.
compliance.aggrega.ai/contains-piitrue, falseĐánh dấu tường minh các workload thuộc phạm vi GDPR/CCPA. Một policy mà người vận hành gắn vào có thể đọc nhãn này để yêu cầu các Features cụ thể trên các tuyến mà lưu lượng của workload đó đi qua — ví dụ core/data-masking trên một AI gateway mà nó gửi lưu lượng mô hình qua, đúng hình dạng mà policy-data-class-route kiểm tra đối với một lớp dữ liệu. Không Component nào của thư viện chuẩn mang nhãn này; giống như lớp dữ liệu, đây là tuyên bố của một hệ thống về chính các component của nó.
hardware.aggrega.ai/acceleratorgpu, tpu, npuĐược DevOps sử dụng trong tệp Release. Họ định tuyến tường minh các component này vào ranh giới pool phần cứng vật lý (ví dụ: một cluster có GPU) thông qua map components: {}, trong khi một vai trò phán quyết quản trị có thể bắt buộc rằng các component gắn nhãn GPU không bao giờ được đặt vào ranh giới không có GPU.
state.aggrega.ai/retentionretain, deleteGiải quyết khoảng trống xóa trong AOT. Nếu một nhà phát triển xóa một cơ sở dữ liệu khỏi Aggregate của họ, một bộ điều phối GitOps sẽ xóa ổ đĩa vật lý. Bước pipeline: của một Recipe có thể đọc nhãn retain và thêm cơ chế bảo vệ gốc của bộ điều phối vào các artifact được render (ví dụ: helm.sh/resource-policy: keep).
state.aggrega.ai/backup-tiermission-critical, standard, ephemeralHook tính sẵn sàng SOC2. Cho FeatureRecipe của Ops biết có cần sinh ra cấu hình Snapshot/Volume Backup tự động cho tài nguyên hay không.

(D) Ngữ cảnh nghiệp vụ động (Annotations kế thừa theo tầng) Trong khi labels định nghĩa DNA bất biến của Catalog, các ngữ cảnh nghiệp vụ động (như phạm vi kiểm toán SOC2 hay theo dõi chi phí FinOps) thay đổi tùy theo ai triển khai ứng dụng và ứng dụng chạy ở đâu. Chúng được điều khiển bởi các Annotations được chèn động bởi subsystems của nhà phát triển, các ranh giới Release của Ops, hoặc một plugin quản trị được gắn ở vai trò annotation-transform.

Tiền tố annotationGiá trị cho phép (Quy ước)Vì sao Platform Ops cần nó (Điểm móc chính sách)
business.aggrega.ai/cost-centerví dụ: finance, ai-researchĐược các plugin rendering Wasm yêu cầu để chèn thẻ vật lý (ví dụ: thẻ AWS hoặc nhãn K8s) vào các artifact được sinh ra cuối cùng cho bảng điều khiển thanh toán đám mây.
business.aggrega.ai/ownerví dụ: team-alpha@corp.comĐịnh tuyến ứng phó sự cố. Đảm bảo hạ tầng được gắn với một đội ngũ con người.
compliance.aggrega.ai/frameworksví dụ: soc2, hipaaKích hoạt phạm vi SOC2. Được chèn qua Release của môi trường. Các plugin Wasm đọc chuỗi này để tự động sinh các sidecar ghi log kiểm toán nghiêm ngặt và vô hiệu hóa các cổng debug khi một ứng dụng đi vào ranh giới tuân thủ production.

Hệ phân loại này là một quy ước của catalog, không phải một quy tắc của trình biên dịch. Doanh nghiệp có thể bỏ qua nó, xóa nó, hoặc tự tạo bộ từ vựng nhãn riêng (mycompany.com/custom-trait). Các plugin Wasm đánh giá bất kỳ khóa nhãn nào mà doanh nghiệp tạo ra.

Soạn schema

Schema Component (và schema tương ứng của Feature, bao gồm các Features thông tin xác thực được gắn nhãn feature.aggrega.ai/kind: secret) khai báo hợp đồng kiểm tra hợp lệ cho các values do nhà phát triển soạn thông qua một khối spec.schema:. Khối này chấp nhận JSON Schema 2020-12 được biểu diễn hoặc ở dạng viết tắt YAML dạng gọn (mặc định; khoảng 15 từ khóa, được chuyển đổi cơ học sang JSON Schema lúc biên dịch) hoặc ở dạng YAML JSON Schema đầy đủ (dạng dài dòng), với các tham chiếu xuyên tài liệu qua $ref: cho các mục SchemaLibrary được dùng chung giữa nhiều Components.

  • Dạng gọn nội tuyến (bề mặt soạn thảo mặc định): một khối YAML nhúng chứa trực tiếp các nút lá dạng gọn trong YAML của Component. Phù hợp với phần lớn nội dung schema của catalog, chỉ với một phần nhỏ số dòng so với JSON Schema đầy đủ. Xem vocabulary/compact-form-authoring.md để biết bộ từ khóa và các quy ước soạn thảo.
  • YAML JSON Schema nội tuyến: dạng dài dòng, phù hợp khi schema cần các từ khóa JSON Schema 2020-12 mà dạng gọn không hỗ trợ trực tiếp ($dynamicRef, unevaluatedProperties lồng sâu, tổ hợp not: phức tạp). Dạng gọn và JSON Schema có thể được trộn lẫn tại bất kỳ ranh giới nút nào trong một khối schema: duy nhất thông qua lối thoát $jsonschema:.
  • Tham chiếu xuyên tài liệu ($ref: tới một mục SchemaLibrary): một $ref: thuần JSON Schema trỏ tới một mục SchemaLibrary theo định danh (Datastores#/schemas/MariaDBValues hoặc tương tự). Các schema doanh nghiệp dài hàng trăm dòng và được tái sử dụng giữa nhiều Components nằm trong các thực thể SchemaLibrary; Component tiêu thụ tham chiếu tới mục đó mà không nhúng nội dung vào. Xem entities/schemalibrary.md và vocabulary/cross-document-ref.md để biết về thực thể thư viện và ngữ nghĩa phân giải.

Ba dạng trên dùng để soạn nội dung pillar, và chúng khả dụng cho một Component không mở rộng gì cả. Một Component khai báo extends: hoàn toàn không soạn nội dung pillar: nó ghi dấu hiệu nguyên văn schema: inherited và nhận khối pillar của base đúng như base đã soạn. Dấu hiệu đó là giá trị duy nhất mà schema: nhận trên một Component như vậy. Xem “Soạn catalog: mở rộng các Components base” bên dưới.

Trình biên dịch phân giải khối schema: — mở rộng dạng gọn, giải tham chiếu các URL $ref:, áp dụng các chuỗi thư viện-tới-thư viện của SchemaLibrary — và hợp nhất JSON Schema thu được với các base được tự động sinh ra từ usesSchema và featuresSchema (xem phần bên dưới) trong lượt kiểm tra hợp lệ của Component. Việc kiểm tra hợp lệ chạy trên schema đã phân giải; con đường soạn thảo là không nhìn thấy được đối với các giai đoạn pipeline phía sau.

Các instance được soạn sẽ được kiểm tra hợp lệ theo schema đã phân giải này lúc build: các values do nhà phát triển soạn của một instance component và infra đã phân giải của Operator, cùng với values/infra trên mọi gắn kết Feature, phải tuân theo các pillar đã khai báo — một giá trị sai kiểu, một số nằm ngoài phạm vi, một chuỗi không có format đã khai báo, một trường bắt buộc bị thiếu, hoặc (đối với values, được kiểm tra ở chế độ đóng) một thuộc tính không được khai báo sẽ dừng build tại nguồn soạn của nó thay vì tạo ra một manifest hỏng lúc triển khai. Một pillar có schema nêu một format mà trình biên dịch không kiểm tra — bất cứ gì ngoài email, uri, hostname, ipv4, ipv6, uuid, date-time và date, kể cả password — sẽ bị từ chối khi catalog được nạp, kèm danh sách các tên được hỗ trợ; xem vocabulary/compact-form-authoring.md để biết mỗi tên kiểm tra điều gì. Một instance của một Component extends: một base được kiểm tra hợp lệ theo khối pillar của base, mà Component mở rộng thừa hưởng nguyên vẹn — vì vậy một instance của base và một instance của bất cứ thứ gì mở rộng nó đều đối mặt với cùng một hợp đồng pillar. Xem errors/fatal-halts.md §“Authored values or infra do not conform to the declared schema (Values hoặc infra được soạn không tuân theo schema đã khai báo)” để biết các chẩn đoán và các quy tắc theo từng pillar (bao gồm cách infra được kiểm tra hợp lệ theo hợp các khóa của Component và provider).

Các giá trị mặc định đã khai báo được hiện thực hóa vào các pillar được render. Ngoài việc kiểm tra hợp lệ, một default: được khai báo trên một trường values (hoặc một trường infra) sẽ được điền vào pillar được render lúc build cho mọi khóa mà tác giả bỏ qua — vì vậy một template Recipe đọc {{ .values.charset }} sẽ nhận utf8mb4 được khai báo trong schema thay vì một giá trị rỗng. Các giá trị do tác giả cung cấp luôn được ưu tiên; các đối tượng lồng nhau được điền theo từng phần tử con bị bỏ qua. Vì việc hiện thực hóa dùng cùng cơ chế phân giải schema như việc kiểm tra hợp lệ, các giá trị mặc định đạt được qua một $ref: xuyên tài liệu vào một SchemaLibrary cũng được hiện thực hóa — cả tham chiếu toàn pillar (values: {$ref: "BaseComponents#/schemas/BaseModelParameter"}) lẫn dạng base-cộng-biến-thể (một $ref: base đặt cạnh các properties anh em, mỗi cái mang các giá trị mặc định riêng). Các giá trị mặc định chỉ được khai báo bên trong một tham chiếu cục bộ trong tài liệu #/$defs/, hoặc dưới một nhánh allOf / oneOf / anyOf, sẽ không được hiện thực hóa; thư viện chuẩn kết hợp các pillar qua $ref: xuyên tài liệu, vốn được hiện thực hóa.

Trụ cột values

Schema của Component tách ba trụ cột theo quyền sở hữu: values do Developer điền trong Aggregate (ý định nhận thức — tên cơ sở dữ liệu, phiên bản, bảng mã ký tự), infra do Operator điền trong Release (định cỡ vận hành — tài nguyên tính toán, lưu trữ, HA), và provides do Recipe đặt (hợp đồng API công khai — host, cổng, giao thức). Developer không bao giờ thấy infra; Operator không bao giờ thấy values. Các Recipes sử dụng cả hai trụ cột trong quá trình render cơ sở, ánh xạ các trụ cột trừu tượng thành dạng cụ thể mà provider đích của chúng yêu cầu. Phần này trình bày bề mặt soạn thảo của trụ cột values. Xem vocabulary/data-pillars.md để biết phân loại trụ cột tổng quát hơn và nguyên tắc lan truyền giữa các trụ cột.

values mang ý định nhận thức của Developer — những lựa chọn mô tả ứng dụng là gì hoặc làm gì, chứ không phải nó được định cỡ hay chạy ra sao. Tên cơ sở dữ liệu, bảng mã ký tự, phiên bản engine, mức log, cờ tính năng, các tham số tầng ứng dụng thay đổi giữa các phiên bản ứng dụng nhưng giữ ổn định giữa các môi trường là nội dung điển hình của values. Operator không bao giờ ghi đè values: (schema của Release từ chối một cách cơ học khối values: theo architecture/06-data-taxonomy-and-composition.md §8 Ràng buộc 4); sự khác biệt theo từng môi trường đi qua Parameter Hoisting — Aggregate công bố các parameters.* có kiểu, template values của Component tham chiếu đến chúng, và Release cung cấp giá trị cho các tham số đó.

# Component schema declares the values shape:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/datastore/mariadb
version: 1.0.0
labels:
component.aggrega.ai/type: stateful-server
spec:
schema:
values:
database_name: { type: string, required: true }
charset: { type: string, default: utf8mb4, enum: [utf8mb4, latin1, ascii] }
engine_version: { type: string, default: "10.11" }
log_level: { type: string, default: info, enum: [debug, info, warn, error] }
# Aggregate fragment — the developer fills values:
components:
customer-db:
type: core/datastore/mariadb
values:
database_name: customers
charset: utf8mb4
engine_version: "{{ .parameters.mariadb_version }}" # Parameter Hoisting
log_level: info

Sử dụng phía Recipe. Các Recipes đọc các giá trị đã phân giải qua .values.<field> trong valuesMapping:, provides:, assertions: và các bề mặt template khác — xem entities/recipe.md để biết ma trận khả dụng theo từng template. Trình biên dịch hợp nhất schema values của Component với mọi schema values: của Feature đính kèm tại cùng nút Component, để ngữ cảnh template đã phân giải chứa mọi trường áp dụng được.

Nguyên tắc giữa các trụ cột. values là trụ cột duy nhất mà Developer soạn tại Aggregate. Các trường thuần túy dành cho developer thuộc về đây; các tham số vận hành (số bản sao, giới hạn CPU/bộ nhớ) thuộc về trụ cột infra của Component để chúng nằm trong Release; đầu ra công khai (host, cổng) thuộc về provides của Recipe. Trộn lẫn các phần này sẽ phá vỡ bất biến về quyền sở hữu; xem vocabulary/data-pillars.md “Cross-pillar mechanics” để biết những trường hợp hiếm hoi mà việc chủ ý dẫn dữ liệu giữa các trụ cột là hợp lý.

Trụ cột infra

Schema của Component tách ba trụ cột theo quyền sở hữu: values do Developer điền trong Aggregate (ý định nhận thức — tên cơ sở dữ liệu, phiên bản, bộ ký tự), infra do Operator điền trong Release (định cỡ vận hành — tính toán, lưu trữ, HA; việc sao lưu của một kho dữ liệu không được định cỡ ở đây mà là Feature core/backup do Operator gắn trong Release), và provides do Recipe thiết lập (hợp đồng API công khai — host, cổng, giao thức). Developer không bao giờ thấy infra; Operator không bao giờ thấy values. Recipes sử dụng cả hai trong quá trình render cơ sở, ánh xạ các trụ cột trừu tượng thành hình dạng cụ thể mà provider đích của chúng mong đợi.

Ba quy ước infra có ý nghĩa đối với mọi Component không phụ thuộc vào năng lực trong thư viện chuẩn: một lối thoát dạng struct mở cho các tùy chỉnh riêng của provider, một ghi đè tùy chọn cho phiên bản artifact thượng nguồn, và một bộ từ vựng dựa trên ý định cho các trường tính sẵn sàng cao. Component tham chiếu chuẩn là core/datastore/mariadb trong catalog thư viện chuẩn — có thể được hiện thực bởi Helm Recipes chạy image mariadb chính thức hoặc giao một custom resource MariaDB cho controller mariadb-operator, Terraform Recipes dựa trên AWS RDS, CloudFormation Recipes dựa trên cùng bề mặt RDS, và Compose Recipes dựa trên một container cục bộ — và khối infra của nó minh họa mẫu thứ nhất và thứ ba.

infra.overrides

Các trường infra phổ quát — compute, storage, ha — bao quát phần lớn việc định cỡ vận hành trên các provider. Phần còn lại vốn dĩ đặc thù cho từng provider: một Kubernetes Recipe cần nodeSelector, một RDS Terraform Recipe cần instance_class, một CloudFormation RDS Recipe cần DBInstanceClass, một Compose Recipe cần ghi đè image. Schema của Component cung cấp một map thực sự mở làm lối thoát để các tùy chỉnh này đi qua mà không làm phình schema:

infra:
# ... universal fields ...
# Provider-specific overrides. Accepts any nested structure.
# Each Recipe documents which keys it reads.
overrides:
type: object
additionalProperties: true # genuinely open map: arbitrary nested structure permitted

Việc khai báo tường minh type: object cùng với additionalProperties: true sẽ chọn ngữ nghĩa map mở. Compiler chuyển cấu trúc này đi qua mà không thay đổi; phần thân template của Recipe đọc những khóa mà nó biết và bỏ qua phần còn lại. Mỗi Recipe ghi lại tập khóa ghi đè trong chú thích đầu tệp, để một Operator viết Release cho một tổ hợp Component × Recipe cụ thể biết Recipe cung cấp những tùy chỉnh nào.

Một đoạn Release sử dụng overrides:

components:
main-db:
infra:
compute: { cpu: "2", memory: 8Gi }
storage: { size: 40Gi, type: balanced-csi }
overrides:
nodeSelector:
kubernetes.io/hostname: cluster1-worker1
service_type: LoadBalancer
metrics:
enabled: true
image:
repository: bitnamilegacy/mysqld-exporter

Developer không bao giờ thấy overrides — nó nằm trong Release, vốn là lĩnh vực của Operator.

infra.source_version

Trường source của một Recipe tham chiếu một artifact thượng nguồn ở một phiên bản cụ thể (Helm chart 25.0.8, Terraform module 4.2.0, tag image OCI). Việc mã hóa cứng phiên bản bên trong Recipe buộc người duy trì catalog phải phát hành một Recipe mới mỗi khi phiên bản thượng nguồn tương thích được nâng lên. Schema của Component cung cấp một ghi đè tùy chọn:

infra:
source_version:
type: string
description: |
Source artifact version. A Recipe versions its artifact from this key
where its source resolution reads it, and is unaffected where it does not.
Changing from the version a Recipe was authored against does not
guarantee value mapping compatibility.

Recipe đọc giá trị này thông qua helper optional trong khối source của nó, để khi không ghim phiên bản thì sẽ dùng phiên bản mà Recipe được viết dựa trên:

source:
kind: helm-oci-chart
url: oci://registry-1.docker.io/bitnamicharts/mariadb
version: "{{ optional .infra `source_version` `25.0.8` }}"

Các chuỗi source của Recipe (và các trường con kiểu chuỗi của một map source: có cấu trúc) được đánh giá như Go template. Một tọa độ từ xa — chẳng hạn version ở trên — được đánh giá khi aggrega pull ghim artifact, trên .values, .infra và .locals mà không có gốc .context; một source chỉ định một đường dẫn trong workspace được đánh giá khi entity được render, trên cùng ngữ cảnh tự chứa như locals của Recipe — .context.instance_id, .values, .infra, và toàn bộ .locals đã được phân giải của node. Ở cả hai trường hợp, .context.inject, .context.uses và .provides đều bị cấm. Việc .infra có trong ngữ cảnh đó là điều khiến ghi đè ở trên hoạt động, và .locals cho phép một Recipe tính một đoạn source một lần rồi đọc lại tại đây. Một template source không bao giờ đọc provides của chính node của nó: trụ cột đó không thuộc ngữ cảnh, và một template truy cập nó sẽ làm dừng bản build — đây là thuộc tính cố định của bề mặt chứ không phải một thiếu sót chờ được bổ sung sau. Xem Template Expansion Matrix hàng #5 để biết đầy đủ các quy tắc khả dụng. Việc thay đổi infra.source_version khác với giá trị mặc định của Recipe không đảm bảo rằng valuesMapping của Recipe tương thích về định dạng với phiên bản thượng nguồn mới; description trên khai báo source_version của schema Component mang cảnh báo đó.

infra.ha.*

Các trường tính sẵn sàng cao dùng từ vựng ý định, không phải từ vựng cơ chế:

infra:
ha:
enabled: { type: boolean, default: false }
read_replicas: { type: integer, min: 0, default: 0 }

infra.ha.enabled nói “hãy làm cho Component này có tính sẵn sàng cao”, và infra.ha.read_replicas nói “tôi muốn N bản sao chỉ đọc”. Mỗi Recipe quyết định ý định này trở thành gì trên provider của nó. Các Recipes của thư viện chuẩn cho core/datastore/mariadb, theo tên mà một Manifest ánh xạ chúng:

Recipeha.enabled: true ánh xạ thànhha.read_replicas: N ánh xạ thành
helm/mariadb (một StatefulSet trên image mariadb chính thức)chạy một máy chủ, nên bản build dừng và nêu tên khóachạy một máy chủ, nên N lớn hơn 0 sẽ dừng bản build
helm/mariadb-cluster (một custom resource MariaDB mà controller mariadb-operator đối soát)bật chuyển đổi dự phòng tự động (replication.primary.autoFailover: true); nó chuyển sang một bản sao đọc, nên N bằng 0 sẽ dừng bản buildđặt spec.replicas thành N + 1 và bật nhân bản; provides.host trở thành Service <name>-primary
terraform/mariadb-rds (AWS RDS)đặt multi_az = true trên aws_db_instance chínhtạo N tài nguyên bản sao đọc aws_db_instance riêng biệt
terraform/mariadb-rds-module, terraform/mariadb-rds-terraform-aws-modules (AWS RDS thông qua một module)truyền multi_az = true cho modulecấp phát một instance, nên N lớn hơn 0 sẽ dừng bản build
cloudformation/mariadb-rds (AWS RDS)đặt MultiAZ: true trên AWS::RDS::DBInstancecấp phát một instance, nên N lớn hơn 0 sẽ dừng bản build
compose/mariadb (container phát triển cục bộ)chạy một máy chủ, nên bản build dừng và nêu tên khóachạy một máy chủ, nên N lớn hơn 0 sẽ dừng bản build

Từ vựng cơ chế (infra.primary.replicas) đọc tự nhiên với một provider (các pod Kubernetes là bản sao của một StatefulSet) nhưng lại là một lỗi phạm trù ở nơi khác — RDS không có khái niệm “replicas” trên instance chính, CloudFormation phản chiếu RDS, Compose hoàn toàn không có trừu tượng bản sao theo chiều ngang. Từ vựng ý định thì chuyển dịch được: mọi provider đều có khái niệm nào đó về “làm cho cơ sở dữ liệu này có tính sẵn sàng cao” và về “tôi muốn N bản sao chỉ đọc”, và Recipe đảm nhận việc chuyển dịch theo từng provider. Khi một hiện thực không có cơ chế như vậy, Recipe của nó có thể dừng bản build và nêu tên khóa, như helm/mariadb và compose/mariadb làm với cả hai khóa và các RDS Recipes một instance làm với bản sao đọc.

infra.ha.read_replicas: 0 là mặc định; khi cả hai khóa đều ở giá trị mặc định, helm/mariadb-cluster render một MariaDB một instance không có khối replication thay vì nhân bản trên một instance. compose/mariadb chạy một máy chủ trên Docker host cục bộ, nên infra.ha.enabled: true hoặc một infra.ha.read_replicas khác 0 sẽ dừng bản build và nêu tên khóa, và thông báo chỉ tới helm/mariadb-cluster, vốn cung cấp chuyển đổi dự phòng và bản sao đọc.

Trụ cột provides

provides là API công khai do Recipe tạo ra — các giá trị mà Recipe đã phân giải của một Component đóng góp cho các bên gọi phía hạ nguồn thông qua bề mặt .context.uses.<alias>.provides.<provided-name> của chúng (hoặc, khi bên gọi khai báo một danh sách cho phép inject: trên cạnh, thông qua đường ống .context.inject của nó). Schema của Component khai báo hình dạng (tên khóa cùng kiểu); khối provides: của Recipe được liên kết cung cấp các giá trị. Developer khi viết một Aggregate sẽ thấy hình dạng provides trên trang Component như một hợp đồng mà bên gọi có thể dựa vào; tác giả Recipe thực hiện hợp đồng đó cho triển khai cụ thể mà họ bao bọc.

Việc thực hiện hợp đồng được thực thi như một Loud Guardrail: một Recipe được liên kết phải tạo ra mọi khóa provides mà Component của nó khai báo. Nếu Recipe được liên kết bỏ sót một khóa đã khai báo, quá trình build dừng lại và nêu tên khóa bị thiếu, thay vì âm thầm không cung cấp gì cho các bên gọi tham chiếu đến nó. Việc tạo thêm các khóa ngoài tập đã khai báo là được phép. Chỉ sự hiện diện của khóa được kiểm tra — các giá trị được tạo ra là những chuỗi mờ mà trình biên dịch chuyển tiếp nguyên vẹn, vì vậy kiểu đã khai báo của chúng vẫn là một hợp đồng mà bên gọi đọc, chứ không phải một giá trị mà trình biên dịch xác thực.

# Component schema declares the provides contract:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/datastore/mariadb
version: 1.0.0
labels:
component.aggrega.ai/type: stateful-server
spec:
schema:
values:
database_name: { type: string, required: true }
provides:
host: { type: string }
port: { type: integer }
database: { type: string }
# Recipe fulfills the contract:
apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: mariadb-bitnami
version: 1.0.0
spec:
capability: helm
implements: core/datastore/mariadb:1.0.0
source:
kind: helm-oci-chart
url: oci://registry-1.docker.io/bitnamicharts/mariadb
version: "25.0.8"
provides:
# The chart's primary Service, named by the fullnameOverride pinned below
host: "{{ .context.rendered_name }}"
port: "3306"
database: "{{ .values.database_name }}"
valuesMapping: |
fullnameOverride: "{{ .context.rendered_name }}"

Sự phân tách đánh giá provides-rồi-inject. Trình biên dịch đánh giá các template provides: ở giai đoạn đánh giá provides dựa trên ngữ cảnh template tự chứa (.context.instance_id, .context.rendered_name khi provider của node báo cáo giá trị này, .values, .infra, và locals: đã phân giải của Recipe trên cùng node) — không có trạng thái nào của bên gọi được nhìn thấy. Các locals của node được phân giải trong phần mở đầu của giai đoạn đó, trước provides của nó, và đó là điều cho phép một template provides: đọc .locals. Ở giai đoạn inject hydration, chạy ngay sau đó, trình biên dịch duyệt các cạnh uses: và phân giải .context.uses.<alias>.provides.<provided-name> của mỗi bên gọi dựa trên các giá trị provides đã phân giải. Việc tách hai giai đoạn đảm bảo phân giải không có chu trình: provides: không thể tham chiếu đến một bên gọi, và inject: của một bên gọi không thể tham chiếu đến đầu ra chưa được phân giải của một provider cho đến khi inject hydration chạy.

Tiến hóa hợp đồng. Việc đổi tên hoặc xóa một trường provides là một thay đổi phá vỡ tương thích đối với mọi bên gọi dựa vào tên cũ. metadata.version của Component (và khai báo implements: của Recipe) mang tín hiệu về sự tiến hóa của hợp đồng; các bên gọi phía hạ nguồn được ghim vào một phiên bản chính cụ thể sẽ thấy một hình dạng provides ổn định.

Hướng dẫn phía Recipe. Về ngữ pháp soạn template provides:, ma trận khả dụng theo từng template, và các ví dụ minh họa về định tuyến xuyên namespace và xuyên vùng, xem entities/recipe.md “Khối provides:” và architecture/06-data-taxonomy-and-composition.md §3.

Ràng buộc hiện diện: features.aggrega.ai/requiredType.<label>

Một Component có thể khai báo rằng mọi instance của nó phải mang một attachment thuộc một kiểu Feature nhất định. Đây là một ràng buộc hiện diện, và nó được khai báo dưới dạng một annotation có thể lặp lại trên metadata của chính Component:

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/payment-processor
version: 1.0.0
labels:
component.aggrega.ai/type: server
annotations:
features.aggrega.ai/requiredType.audit: core/audit-logging
features.aggrega.ai/requiredType.compliance: core/pci-compliance
spec:
schema:
values:
processor_endpoint: { type: string, required: true }

Khóa là tiền tố features.aggrega.ai/requiredType. theo sau là một nhãn do bạn chọn; giá trị là URI kiểu Feature mà ít nhất một attachment phải mang. Nhãn đặt tên cho yêu cầu trong chẩn đoán mà một ràng buộc không được đáp ứng tạo ra — audit và compliance ở trên — và đó là toàn bộ chức năng của nó. Các khóa có nhãn là cách một Component khai báo nhiều ràng buộc cùng lúc: annotations là một map chuỗi phẳng và không thể chứa khóa trùng lặp.

Trình biên dịch đánh giá từng mandate dựa trên tập attachment cuối cùng của instance, sau khi cascade của mô hình 5-Tier Onion đã gộp mọi phạm vi: các khối features: cấp component và cấp subsystem của Aggregate, các khối features: cấp boundary và cấp component của Release, và các attachment sinh ra từ việc mở rộng dựa trên annotation. Bất kỳ nguồn nào trong số đó cũng thỏa mãn mandate — quy tắc kiểm tra cái gì hiện diện, không bao giờ kiểm tra nó đến từ đâu. Vì vậy, một Component có mandate được đáp ứng chỉ nhờ một operator đặt annotation giám sát trong Release sẽ vượt qua y hệt như một Component mà developer đã gắn Feature bằng tay.

Một ràng buộc không được attachment nào đáp ứng sẽ dừng bản build với một chẩn đoán nêu tên instance của component, nhãn của yêu cầu và kiểu bắt buộc. Giá trị annotation là một chuỗi không trong suốt, nên không có gì kiểm tra hình dạng của nó trước khi trình biên dịch đọc; do đó, một giá trị không phải là URI kiểu Feature, hoặc một khóa không có nhãn sau tiền tố, sẽ dừng với một chẩn đoán riêng biệt cho biết khai báo bị sai định dạng. Hai chẩn đoán được cố ý tách biệt: một khai báo hỏng được sửa trong thực thể catalog, còn một yêu cầu chưa được đáp ứng được giải quyết bằng cách gắn Feature — và một lỗi đánh máy không bao giờ được đọc như một yêu cầu đã được đáp ứng.

Cả hai chẩn đoán được mô tả tại errors/fatal-halts.md “Required feature not attached (Feature bắt buộc chưa được gắn)”.

Ràng buộc không phải là slot. Hai bề mặt này trả lời những câu hỏi khác nhau và sự khác biệt không chỉ là hình thức:

slot featuresSchemaràng buộc hiện diện
Khai báomột điểm gắn kết có tênmột ràng buộc về những gì phải hiện diện
Tên có thể tham chiếucó — from: <slot> và .features.<slot>.provides.*không — nhãn chỉ đặt tên cho yêu cầu, không gì khác
Lực lượngđúng một lần điền cho mỗi slotít nhất một attachment thuộc kiểu đó
Ràng buộc phần điềnselector, inject, sensitivekhông gì ngoài kiểu
Được đáp ứng bởi một attachment tự dokhông — slot được điền theo têncó — ở bất kỳ phạm vi nào, dưới bất kỳ tên nào
Khi yêu cầu không được đáp ứngdừng khi required: true và không có gì gắn vào tên của slotdừng khi không có attachment nào mang kiểu đó

Cả hai yêu cầu được kiểm tra trên cùng một đầu vào — tập attachment cuối cùng của instance — và cả hai đều dừng với chẩn đoán riêng, vì chúng đặt ra những câu hỏi khác nhau: liệu một điểm gắn kết có tên đã được gắn hay chưa, so với liệu có attachment nào mang một kiểu có tên hay không. Không cái nào thay thế được cái kia.

Hãy dùng slot khi Recipe cần đọc những gì đã được gắn. Hãy dùng ràng buộc khi hợp đồng của Component đòi hỏi một năng lực phải hiện diện và không quan tâm instance nào cung cấp nó. Một Component xử lý thanh toán có ràng buộc core/audit-logging sẽ có ghi nhật ký kiểm toán trong mọi lần triển khai, dù developer có nhớ gắn nó hay không; một Component tuân thủ PCI có ràng buộc core/pci-compliance không thể phát hành nếu Feature tuân thủ chưa được gắn ở đâu đó trong lần triển khai.

Kế thừa. Một ràng buộc được khai báo trên một Component cơ sở được kế thừa bởi mọi Component extends: nó, vì các annotation trong metadata được gộp dọc theo chuỗi extends, với con thắng theo từng khóa. Do đó, con có thể nhắm lại một ràng buộc kế thừa bằng cách khai báo lại cùng nhãn với một kiểu khác, hoặc thêm ràng buộc của riêng nó dưới các nhãn mới; nó không thể bỏ một ràng buộc mà cơ sở đã khai báo.

Socket cấu trúc liên kết: usesSchema

Một Component có thể khai báo các socket cấu trúc liên kết thông qua khối usesSchema: — một map YAML khai báo song song với featuresSchema. Mỗi mục đặt tên cho một socket mà qua đó Component chấp nhận các phụ thuộc liên component, và quy định những dạng Component nào mà nhà phát triển được phép nối vào socket đó. Trình biên dịch tự động sinh các quy tắc xác thực JSON Schema 2020-12 từ các socket đã khai báo và hợp nhất chúng với schema: của Component trong quá trình phân giải Component; nhà phát triển không tự viết trụ cột uses: bên trong schema:, vì cấu trúc đến từ usesSchema.

# Component declares the sockets it accepts:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/ai-agent/orchestrator
version: 1.0.0
labels:
component.aggrega.ai/type: server
spec:
usesSchema:
primary_datastore:
required: true
selector: "datastore.aggrega.ai/engine=vector"
inject: [env]
cache:
required: false
selector: "datastore.aggrega.ai/engine=kv"
inject: [env, file]
log_destination:
required: false
selector: "component.aggrega.ai/category=messaging"
inject: []
# Aggregate fragment — developer wires the sockets:
components:
agent:
type: core/ai-agent/orchestrator
uses:
primary_datastore:
main: { target: vector-db-instance }
log_destination:
audit: { target: audit-sink }

Các dạng nối — một socket chấp nhận một hoặc nhiều đích. Các ví dụ ở trên nối mỗi socket với một đích duy nhất, nhưng một socket có thể phân nhánh tới nhiều đích. Giá trị của socket được viết theo một trong hai dạng:

uses:
# Compact form — a list of target names. Each entry produces an edge
# whose alias equals its target. Use it for the single-target case, and
# when one socket connects to several peers of the same shape.
shards: [orders-db, customers-db, inventory-db]
# Verbose form — an alias-keyed map. Each alias maps to an entry object
# carrying its own `target:`, and may carry its own inject directives.
# Use when the connections need distinct names or per-edge inject.
databases:
primary: { target: orders-db, inject: { env: [{ in: DB_URL, from: url }] } }
replica: { target: orders-db-ro, inject: { env: [{ in: DB_REPLICA_URL, from: url }] } }

Một alias luôn ánh xạ tới một đối tượng mục, không bao giờ tới một tên đích trần: databases: { primary: orders-db } bị từ chối khi tải, và một đối tượng mục bỏ qua target: cũng vậy. Để nối một đích duy nhất mà không cần đặt alias, hãy dùng dạng rút gọn — primary_datastore: [vector-db-instance] — dạng này nêu tên đích một lần và suy ra alias từ đó.

Mỗi mục — phần tử danh sách hoặc alias của map — trở thành một cạnh, được giữ theo thứ tự viết. selector: của socket áp dụng cho mọi đích được nối qua nó (mỗi cạnh được kiểm tra kiểu độc lập trong quá trình phân tích tĩnh), và required: true có nghĩa là phải nối ít nhất một đích.

Ngữ nghĩa của các trường:

TrườngLoạiMặc địnhÝ nghĩa
requiredboolfalseKhi là true, nhà phát triển phải nối ít nhất một phụ thuộc vào socket này. Khi là false, socket là tùy chọn.
selectorstring—Một label selector, theo ngữ pháp mà Feature appliesTo sử dụng, mà đích của mọi cạnh được nối qua socket này phải thỏa mãn. Nó được đọc đúng như chuỗi viết ở đây và được đánh giá với các label của đích trong quá trình phân tích tĩnh: một đích có label không thỏa mãn nó sẽ dừng bản dựng, và một selector bị ngữ pháp từ chối cũng vậy, kèm tên yêu cầu không đọc được. Selector rỗng không áp đặt ràng buộc nào lên đích.
injectstring[]—Danh sách cho phép các cơ chế phân phối inject (song song với featuresSchema[].inject). Vắng mặt, hoặc [] (rỗng), nghĩa là blackbox — không cho phép khối inject: trên mục uses: của nhà phát triển; Recipe kiểm soát việc phân phối. [env, file, arg] (không rỗng) nghĩa là transparent — nhà phát triển có thể chỉ định cơ chế nào phân phối các giá trị provides của phụ thuộc. Được thực thi: xem “Nơi danh sách cho phép inject của socket được thực thi” bên dưới.
valueSchemaobject—Hợp đồng theo từng cạnh, tùy chọn, cho values do nhà phát triển viết trên một cạnh được nối qua socket này (viết trong Aggregate). JSON Schema 2020-12 theo cùng các dạng viết như schema:. Bỏ qua nghĩa là socket không khai báo hợp đồng values nào.
infraSchemaobject—Hợp đồng theo từng cạnh, tùy chọn, cho infra do người vận hành viết trên một cạnh được nối qua socket này (viết trong Release). Cùng các dạng viết như valueSchema. Bỏ qua nghĩa là socket không khai báo hợp đồng infra nào.
featuresSchemamap—Các slot đính kèm mà mỗi kết nối được nối qua socket này có thể lấp, khóa theo tên slot, mỗi slot nhận các khóa mà một slot cấp Component nhận. Bỏ qua nghĩa là kết nối qua socket này không mang đính kèm nào. Xem “Các slot mà mỗi kết nối lấp” bên dưới.

Nơi danh sách cho phép inject của socket được thực thi. Danh sách cho phép là tuyên bố của socket về việc bên sử dụng có được chọn dạng phân phối hay không, và nếu có thì những dạng nào — vì vậy nó được kiểm tra với mọi cạnh uses: được nối qua socket, khi đã có đủ cả cạnh và khai báo của socket. Hai sự từ chối xuất phát từ một quy tắc, và cả hai đều dừng bản dựng:

  • Một cạnh chỉ định một cơ chế không có trong danh sách cho phép sẽ dừng, kèm tên socket, cơ chế vi phạm và những gì socket cho phép. Mọi cơ chế vi phạm trên cạnh được báo cáo cùng lúc.
  • Một cạnh chỉ định bất kỳ cách phân phối nào qua một socket có danh sách cho phép vắng mặt hoặc rỗng cũng dừng. Đó là khai báo blackbox đang làm đúng việc của nó: nó nói “Recipe phân phối nội bộ việc này; đừng chỉ định cách phân phối”, và danh sách cho phép rỗng không cho phép cơ chế nào thay vì cho phép tất cả.

Socket được đọc trên thực thể nào đã khai báo nó, không phải lúc nào cũng là component mà cạnh gắn vào: một cạnh viết trong uses: của một đính kèm Feature được phân giải theo usesSchema của Feature được đính kèm, còn mọi cạnh khác — viết trong Aggregate, nối từ Release, hoặc đến qua một sub-aggregate — theo của Component sử dụng. Một socket được kế thừa qua extends được đọc y như một socket do chính thực thể viết.

Một cạnh không chỉ định gì thì không bị ảnh hưởng bởi cả hai sự từ chối, bất kể socket khai báo gì: việc đọc giá trị của một phụ thuộc từ .context.uses.<alias>.provides.<name> trong Recipe sử dụng không cần khối inject: và luôn khả dụng. Xem errors/fatal-halts.md để biết cả hai chẩn đoán.

Hợp đồng kết nối theo từng cạnh — valueSchema và infraSchema. Ngoài việc quy định Components nào có thể nối vào một socket, socket còn có thể khai báo cấu hình mà mỗi kết nối mang. Hai schema tùy chọn theo từng socket xác thực cấu hình phạm vi kết nối trên mọi cạnh được nối qua socket:

  • valueSchema là hợp đồng cho khối values do nhà phát triển viết trên một cạnh uses — tinh chỉnh theo từng kết nối mà nhà phát triển thể hiện trong Aggregate (ví dụ, kích thước connection pool hoặc chế độ client).
  • infraSchema là hợp đồng cho khối infra do người vận hành viết trên một cạnh uses — định cỡ vận hành theo từng kết nối mà người vận hành thể hiện trong Release.

Cả hai chấp nhận JSON Schema 2020-12 theo cùng các dạng nội dung như trường schema: — dạng rút gọn nội tuyến, JSON Schema YAML nội tuyến, hoặc một $ref: liên tài liệu tới một mục SchemaLibrary. Chúng là các hợp đồng theo từng cạnh, được xác thực độc lập với cấu hình của từng cạnh; chúng không được hợp thành vào schema values riêng của Component sử dụng. Một socket bỏ qua schema theo cạnh cho một trụ cột thì không khai báo hợp đồng nào ở đó, và mọi cấu hình viết cho trụ cột đó không được xác thực. Cấu hình theo cạnh được xác thực ở dạng đóng, và việc xác thực có tính đến giá trị mặc định ở cả hai trụ cột: một khóa mà schema cho default: được tính là đã cung cấp ngay cả khi tác giả bỏ qua nó.

Một default: đã khai báo cũng được hiện thực hóa, ở cả hai trụ cột. Một khóa mà tác giả bỏ qua sẽ đến render context của Recipe sử dụng mang giá trị mặc định đã khai báo, y như một khóa value hoặc infra bị bỏ qua của component — vì vậy khai báo giá trị mặc định trên socket là đủ, và template của Recipe không cần biểu thức dự phòng cho nó. Giá trị được viết luôn thắng giá trị mặc định đã khai báo, và nó chỉ lấp khóa mà nó cung cấp: một cạnh viết một khóa trong hợp đồng của socket vẫn nhận các giá trị mặc định đã khai báo cho các khóa khác của hợp đồng đó. Giá trị mặc định gắn với cạnh, nên một socket không được nối không đóng góp gì.

spec:
usesSchema:
databases:
required: true
selector: "datastore.aggrega.ai/engine=relational"
inject: [env]
valueSchema: # developer per-edge values, authored in the Aggregate
pool_size: { type: integer, minimum: 1, maximum: 100, default: 10 }
tls_mode: { type: string, enum: [disable, require, verify-full], default: require }
infraSchema: # operator per-edge infra, authored in the Release
storage_class: { type: string, default: standard }

Với socket đó đã được khai báo, một cạnh có Aggregate bỏ qua pool_size sẽ render 10, và một cạnh có Release bỏ qua storage_class sẽ render standard. Giá trị được viết thắng theo từng khóa, trong trụ cột của chính nó: một Aggregate đặt pool_size: 42 sẽ render 42 trong khi tls_mode vẫn được lấp thành require, và một Release đặt storage_class: gp3 sẽ render gp3 mà không ảnh hưởng đến khóa nào của nhà phát triển.

Một Recipe cho Component sử dụng đọc cấu hình theo cạnh đã phân giải từ pipe cấu trúc liên kết đã làm giàu tại .context.uses.<alias>.values.<key> và .context.uses.<alias>.infra.<key> — xem vocabulary/topology-triad.md.

Các slot mà mỗi kết nối lấp — featuresSchema của socket. Một socket cũng có thể khai báo các slot đính kèm, và khi đó mọi kết nối được nối qua nó có thể mang đính kèm riêng trong từng slot: một gateway kết nối tới nhiều model giữ một credential khác nhau cho mỗi model, vì credential nằm trên kết nối chứ không nằm trên gateway.

spec:
usesSchema:
models:
selector: "component.aggrega.ai/category=ai-model"
featuresSchema:
credential:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]
description: The credential the consumer presents to the component this connection reaches.

Một kết nối lấp đầy một slot bằng cách mang một attachment dưới tên của slot trong features: của chính nó — trên mục kết nối của Aggregate (Aggregate) hoặc trên mục của Release (Release) — và attachment đó trở thành một trong các attachment của component tiêu thụ, có tên <alias>.<slot>.

Những gì khai báo này làm, nói một cách chính xác:

  • Tên các slot là một tập đóng. Khác với featuresSchema của chính Component, vốn chấp nhận một attachment tự do dưới bất kỳ tên nào, các slot của một socket là những tên duy nhất mà một kết nối qua socket đó có thể mang: bất kỳ tên nào khác đều dừng build khi build được nạp, và một socket không khai báo featuresSchema thì không chấp nhận attachment nào trên các kết nối của nó. Một socket ad-hoc — socket mà usesSchema này không khai báo — không khai báo slot nào, nên các kết nối của nó cũng không mang attachment nào. Mỗi kết nối tự điền các slot của mình: một attachment ở phạm vi rộng hơn không bao giờ lan xuống một kết nối, và một khóa Release viết tên ghép của một attachment của kết nối sẽ dừng build.
  • Các khóa còn lại ràng buộc từng kết nối với slot. Một slot ở đây nhận cùng các khóa như một slot cấp Component — required, selector, inject, sensitive, description — và mỗi kết nối bị ràng buộc bởi chúng một cách riêng lẻ. selector được so khớp với các nhãn của Feature mà một kết nối dùng để lấp đầy slot, và một lần lấp đầy mà nó không chấp nhận sẽ dừng build, được định vị tại mục của kết nối đó trong tài liệu đã viết lần lấp đầy. required: true áp dụng cho mọi kết nối được nối qua socket: một kết nối để trống slot sẽ dừng build, nêu tên kết nối đó, trong khi một kết nối bên cạnh lấp đầy slot thì vượt qua. sensitive được đọc đúng như trên một slot cấp Component: attachment lấp đầy slot được đánh dấu là nhạy cảm trong đồ thị build và trong aggrega inspect. Trên một kết nối, cũng như trên một component, việc giá trị nào của một attachment bị giữ lại vì nhạy cảm chỉ do schema riêng của Feature được gắn quyết định. inject ràng buộc mục Workload phân phối nội dung của slot: attachment của một kết nối không mang khối inject: riêng — không tài liệu nào chấp nhận khối này trên một mục kết nối — nên một Workload phân phối nó bằng cách nêu tên kết nối bên cạnh slot, và mục đó bị ràng buộc bởi allowlist của slot socket đúng như một mục nêu tên slot cấp Component bị ràng buộc bởi allowlist của slot đó.

usesSchema của một Feature không nhận featuresSchema: một kết nối mà một Feature tạo ra không mang attachment nào, và một Feature khai báo slot trên một socket sẽ bị từ chối khi được nạp. Một thông tin xác thực mà kết nối như vậy cần là một slot trong featuresSchema của chính Feature.

Sinh schema từ usesSchema. Trình biên dịch sinh một đoạn JSON Schema 2020-12 cơ sở từ các socket đã khai báo và kết hợp nó với khai báo schema: của người dùng — cùng mẫu mà featuresSchema sử dụng. Schema được sinh ra không bao giờ được ghi xuống đĩa; nó chỉ tồn tại trong bộ nhớ trong lượt xác thực Component. Map uses: của nhà phát triển trong Aggregate được xác thực theo schema đã hợp nhất; selector: của từng socket được đánh giá với các nhãn của Component ứng viên trong quá trình phân tích tĩnh, như phép kiểm tra an toàn kiểu giữa các node.

Ngữ nghĩa selector — cơ chế Split Schema. usesSchema[].selector: là thứ khiến topology của Aggrega không chỉ là việc truyền chuỗi không có kiểu. Một socket khai báo selector: "datastore.aggrega.ai/engine=vector" chỉ chấp nhận nối tới các Components được gắn nhãn với cặp khóa-giá trị khớp; một agent cố nối socket primary_datastore của nó tới một Component relational sẽ thất bại ở Static Analyzer với một chẩn đoán vi phạm selector rõ ràng. Selector là một chuỗi label selector kiểu Kubernetes — các yêu cầu nối AND bằng dấu phẩy trên các dạng =, !=, in (...), notin (...), khóa trần và !key — cùng ngữ pháp mà Feature appliesTo sử dụng; xem vocabulary/modifier-system.md về ngữ pháp và architecture/13-catalog-and-registry.md §2 “Kubernetes-Style Selectors” về ngữ nghĩa của engine. Một yêu cầu nằm ngoài các dạng đó sẽ bị từ chối thay vì được đọc thành một selector khác: một yêu cầu rỗng (dấu phẩy ở đầu, ở cuối hoặc lặp đôi), một khóa chứa khoảng trắng hoặc bất kỳ ký tự nào trong =, !, (, ) và dấu phẩy, hoặc một tập hợp thiếu dấu ngoặc đóng sẽ dừng mọi build nối một cạnh qua socket, nêu tên yêu cầu đó. Vì vậy, một socket nhằm loại trừ frontend được viết là selector: "tier!=frontend"; "!tier=frontend" bị từ chối, vì ! chỉ đặt tên một khóa nhãn và không gì khác.

Socket ad-hoc — khai báo một socket mang lại gì, và tác giả có thể làm gì khi không khai báo. Tác giả một Aggregate có thể viết một mục uses: trên component của chính mình dưới một tên socket mà usesSchema này không khai báo, kể cả trên một Component hoàn toàn không khai báo usesSchema. Cạnh vẫn được tạo. Việc catalog không nói gì về một socket nghĩa là kết nối đó không được dự liệu, chứ không phải bị cấm, và nhà phát triển làm chủ topology của ứng dụng.

Những gì một socket ad-hoc như vậy từ bỏ chính là những gì một socket được khai báo cung cấp, vì tất cả đều nằm trong mục usesSchema: không có selector, nên không có gì ràng buộc cạnh có thể tới component nào và phép kiểm tra an toàn kiểu giữa các node không có gì để đánh giá; không có allowlist inject:; không có valueSchema theo cạnh, nên values: theo cạnh không có hợp đồng nào để kiểm tra và không có giá trị mặc định khai báo nào để kế thừa. Nó cũng từ bỏ infraSchema, dù dù sao cũng không có gì chạm tới hợp đồng đó trên một socket như vậy: infra theo cạnh được viết trên một mục cạnh của Release, và một mục Release chỉ được nêu tên một socket mà Component tiêu thụ khai báo. Điều không thay đổi là những gì cạnh có thể mang: from: của mọi mục inject vẫn phải nêu tên một khóa mà schema.provides của Component đích khai báo, và đích vẫn phải tồn tại — cả hai đều dừng build như trên một socket được khai báo.

Hãy hiểu “không có allowlist inject:” là sự vắng mặt của một ràng buộc chứ không phải một khai báo blackbox, vì hai điều này trông giống nhau nhưng hoạt động ngược nhau. Một cạnh qua socket ad-hoc có thể tự do quy định cách phân phối: không có allowlist nào để một cơ chế nằm ngoài, và không có thực thể nào cam kết xử lý các giá trị trong nội bộ. Sự từ chối blackbox ở trên áp dụng cho một socket mà thực thể đã khai báo và để không có allowlist inject: — sự bỏ qua đó là một tuyên bố về một kết nối mà thực thể đã dự liệu, còn một socket ad-hoc không đưa ra tuyên bố nào như vậy.

Việc phân phối đi cùng một đường, và artifact được render không ghi nhận khác biệt nào. Khối inject của một cạnh ad-hoc được phân giải và phân phối đúng như của một socket được khai báo: mỗi khóa from: được đọc từ provides đã đánh giá của đích và đặt vào ngữ cảnh injection của node tiêu thụ dưới khóa phân phối mà tác giả chọn, từ đó tới artifact được render. Chỉ có một đường phân phối và không gì trên đó rẽ nhánh theo việc socket có được khai báo hay không. Điều một socket được khai báo có thể thêm vào là nội dung — các giá trị mặc định theo cạnh mà valueSchema hoặc infraSchema của nó điền vào — nên khi một socket được khai báo không mang hợp đồng như vậy, cùng một cạnh sẽ render giống hệt nhau dưới cả hai loại socket. Khai báo là một sự thật về kết nối, không phải một đầu vào cho những gì được render.

values: theo cạnh trên một socket ad-hoc được chấp nhận và tới Recipe tiêu thụ tại .context.uses.<alias>.values, không được xác thực: không có valueSchema để đối chiếu, không khóa nào được kiểm tra và không khóa nào bị từ chối. Điều đó không riêng gì socket ad-hoc — một socket được khai báo không viết hợp đồng cho pillar đó cũng xử lý cấu hình theo cạnh của nó theo cùng cách. Điều socket ad-hoc thay đổi là hợp đồng không thể được thêm vào nếu không khai báo socket. .context.uses.<alias>.infra rỗng trên một cạnh như vậy, vì bề mặt cung cấp infra theo cạnh không thể nêu tên một socket chưa được khai báo.

Mỗi cạnh trong đồ thị được xuất ra đều ghi lại nó thuộc loại nào trong hai loại, nên bên sử dụng không bao giờ phải suy đoán, và một tổ chức muốn mọi kết nối đều đi qua một socket đã khai báo có thể đặt yêu cầu đó thành một chính sách quản trị. Khai báo socket ở đây vẫn là con đường tốt hơn và là điều catalog của thư viện chuẩn làm: một socket đã khai báo mang một selector ràng buộc những component mà cạnh có thể tới, một allowlist inject:, một hợp đồng theo từng cạnh với các giá trị mặc định riêng, và một mô tả — một tuyên bố có thể xem xét về một kết nối đã được dự liệu, được quản lý phiên bản cùng với thực thể tạo ra nó. Dạng ad-hoc là một lối thoát, không phải một mặc định mới. Có hai bề mặt cố ý không mở theo cách này — uses của một attachment Feature chỉ có thể nêu tên một socket mà Feature được gắn khai báo, và uses theo từng cạnh của một Release chỉ có thể nêu tên một socket mà Component sử dụng khai báo.

Ví dụ minh họa examples/adhoc-uses-socket/ xây dựng cả hai loại cạnh trên cùng một bên sử dụng và hiển thị hai giá trị được chuyển giao cạnh nhau trong đầu ra đã render, cùng với lỗi dừng mà một khóa from: chưa khai báo gây ra.

Lỗi chính tả trong tên socket được báo dưới dạng khuyến nghị, không phải lỗi dừng. Vì một tên socket chưa khai báo là hợp lệ, một tên socket viết sai sẽ trở thành một kết nối ad-hoc riêng thay vì nối vào socket mà tác giả muốn — và bản build vẫn xanh trong khi không có gì chảy qua nó. Trình biên dịch báo một tên socket cách một tên mà usesSchema này khai báo đúng một lần chỉnh sửa dưới dạng cảnh báo nêu cả hai cách viết — xem errors/warnings.md “Uses-socket near-miss lint”. Cảnh báo không bao giờ thay đổi kết quả của bản build; trình biên dịch không kiểm soát việc tác giả đặt tên socket như thế nào.

Quan hệ giữa usesSchema và featuresSchema. Cả hai đều là bảng khai báo và đều mang một allowlist inject: với ngữ nghĩa giống hệt nhau, nhưng socket và slot là những thứ khác nhau và không thể thay thế cho nhau. usesSchema quản lý các cạnh giữa các component — đồ thị topology — khai báo những socket nào mang hợp đồng. featuresSchema quản lý các slot attachment, và một slot là một điểm liên kết có tên, không phải một phép liệt kê: một attachment dưới một tên mà không slot nào khai báo là hợp lệ trên khối riêng của component. (Các slot mà một socket khai báo cho các kết nối của nó là tập đóng duy nhất, như “Slots each connection fills” ở trên đã nêu.) Hai bề mặt đã hội tụ ở điểm đó — một mục uses: riêng của component dưới một tên socket chưa khai báo cũng hợp lệ — nhưng chúng vẫn khác biệt: một slot chưa khai báo là một attachment tự do trên một Component mà các slot đã khai báo không bị ảnh hưởng, còn một socket chưa khai báo là một cạnh không có selector và không có hợp đồng theo từng cạnh. Nhiều Components khai báo cả hai; hai bảng kết hợp độc lập với nhau.

Khe gắn: featuresSchema

Một Component có thể khai báo các khe gắn thông qua một khối featuresSchema. Mỗi khe đặt tên cho một điểm liên kết tại đó Component kỳ vọng một Feature được gắn vào — một mật khẩu root, một khóa API, một token xác thực, một liên kết danh tính — và ràng buộc Feature nào có thể liên kết với nó cũng như cách thức vật liệu của phần lấp đầy có thể được phân phối.

Phần này nói về các khe riêng của Component. Ngược lại, các khe mà một socket khai báo cho mỗi kết nối là một tập đóng — xem “Các khe mà mỗi kết nối lấp đầy” trong mục Topology Sockets.

Việc khai báo một khe không đóng bề mặt gắn. Tác giả có thể gắn một Feature dưới một tên mà không khe nào khai báo, và phần gắn đó là một phần gắn tự do: hoàn toàn hợp lệ, chỉ đơn giản là không liên kết với một khe đã khai báo. Sự mở này là điều cho phép một thực thể catalog phục vụ hai dạng triển khai khác nhau mà không cần tách nhánh catalog:

  • Theo từng bên tiêu thụ. Mỗi instance lấp đầy khe bằng Feature riêng của nó, nên mỗi bên tiêu thụ nhận được thông tin xác thực được render riêng.
  • Dùng chung. Không instance nào lấp đầy khe; thay vào đó, một thông tin xác thực được gắn một lần ở phạm vi rộng hơn (một subsystem, hoặc ranh giới của một Release) và lan truyền xuống mọi component bên dưới, nên mọi bên tiêu thụ đều được lấp đầy từ một khai báo đó. Những gì được render phụ thuộc vào cách hiện thực: một Secret cho mỗi bên tiêu thụ, mỗi Secret mang cùng vật liệu, với cách hiện thực render một Secret; không có gì với cách hiện thực trỏ mọi bên tiêu thụ tới một Secret đã tồn tại.

Tác giả chọn giữa hai dạng bằng những gì họ gắn. Thực thể catalog là như nhau trong cả hai trường hợp.

Một dạng trên bề mặt mở đó gây dừng: một phần lấp đầy được viết trên component dưới một tên khác. Khi một phần gắn được viết trên chính component — trên khối features: của nó trong Aggregate, hoặc trên mục của Release dành cho đúng component đó — mang một tên mà không khe nào khai báo, và Feature của nó thỏa mãn selector của một khe mà không gì liên kết trên component đó sau khi mọi phạm vi đã được gộp lại, quá trình build sẽ dừng. Đó là dạng mà một phần lấp đầy dành cho khe mang khi nó bị viết dưới tên sai: nếu để nguyên, nó sẽ là một phần gắn tự do trong khi khe vẫn trống, và một khe tùy chọn bị để trống vẫn build thành công mà không phân phối gì. Thông báo nêu tên phần gắn, component, Feature và từng khe trống mà Feature đó phù hợp, và cách khắc phục là gắn nó dưới tên của khe. Điều này áp dụng cho mọi Feature, không chỉ cho thông tin xác thực. Mọi thứ khác trên bề mặt vẫn tự do: một phần gắn có Feature không phù hợp với khe đã khai báo nào, một phần gắn thêm khi mọi khe mà nó phù hợp đã được liên kết, và một phần gắn mà component kế thừa từ một subsystem hoặc ranh giới của một Release — nên dạng dùng chung ở trên không bị ảnh hưởng. Một khe không khai báo selector không nói gì về việc nó dành cho Feature nào, nên không phần gắn nào bị ràng buộc với nó theo cách này. Việc dừng được mô tả trong errors/fatal-halts.md ở mục “An attachment written under another name fits a slot its component leaves empty (Một phần gắn được viết dưới tên khác phù hợp với một khe mà component của nó để trống)”.

Hai dạng kết hợp được với nhau, và dạng gần hơn thắng. Tác giả có thể làm cả hai cùng lúc: gắn một Feature ở phạm vi rộng hơn để nó đến được mọi component trong phạm vi đó, và lấp đầy khe trên một component cần điều gì đó khác. Phần lấp đầy ở phạm vi component thắng — theo từng trường, nên nó chỉ cần khai báo lại các trường nó thay đổi và phần còn lại vẫn đến từ phần gắn rộng hơn. Các component cùng cấp không lấp đầy khe vẫn giữ nguyên phần gắn rộng hơn. Quy tắc ưu tiên đầy đủ, bao gồm cách nó tương tác với các phần gắn dựa trên annotation và với các Aggregates được kết hợp, có tại vocabulary/labels-and-annotations.md “Attachment precedence”.

Định nghĩa schema trên Component:

spec:
featuresSchema:
root_password:
inject: []
description: Root database password. Recipe controls delivery (Black-Box).
user_password:
inject: [env, file]
description: Application user password, auto-generated if omitted.
replication_password:
inject: []
description: Replication password for HA setups.

Ngữ nghĩa của các trường:

TrườngLoạiMặc địnhÝ nghĩa
requiredboolfalseKhai báo rằng khe cuối cùng phải được liên kết. Quá trình build dừng khi không gì liên kết tên của khe trên một instance của Component này, được kiểm tra dựa trên tập phần gắn mà instance nắm giữ sau toàn bộ quá trình lan truyền phần gắn — nên một phần gắn được khai báo ở phạm vi mà instance kế thừa sẽ thỏa mãn khe giống hệt như một phần lấp đầy được viết trên chính instance. Thông báo chẩn đoán nêu tên component và khe.
injectstring[]—Danh sách cho phép các cơ chế phân phối inject. [] (rỗng) nghĩa là hộp đen — Recipe kiểm soát việc phân phối bên trong và vật liệu không bao giờ được phân phối tới workload. [env, file] nghĩa là trong suốt — vật liệu của phần lấp đầy có thể được phân phối qua các cơ chế được liệt kê. Ngữ nghĩa giống như usesSchema[].inject.
descriptionstring—Tài liệu cho con người, được IDE và hub hiển thị.
selectorstring—Bộ chọn label kiểu Kubernetes tùy chọn, ràng buộc Feature nào có thể lấp đầy khe này — tương tự cho khe của selector trên một socket usesSchema, với cùng ngữ pháp và cùng engine so khớp label gốc. Được đánh giá dựa trên các label riêng của Feature được gắn trong quá trình phân tích tĩnh; một phần lấp đầy có label không thỏa mãn nó sẽ gây dừng, và một selector mà ngữ pháp từ chối cũng vậy, nêu tên yêu cầu không đọc được. Bỏ qua để không ràng buộc phần lấp đầy.
sensitiveboolfalseKhai báo rằng bất cứ thứ gì liên kết khe này đều xử lý vật liệu bí mật. Đây là phát biểu về điểm liên kết, không phải về một phần lấp đầy cụ thể nào; xem “Khai báo một khe là nhạy cảm” bên dưới.

Một khe ràng buộc phần lấp đầy nào có thể liên kết với nó, không phải những gì phần lấp đầy cấu hình. Có chủ đích không có hợp đồng values hay infra ở cấp khe: schema: riêng của Feature được gắn sở hữu các trụ cột đó, nên mỗi hợp đồng có đúng một nơi chứa.

selector của khe là cách một Component thu hẹp Feature nào có thể lấp đầy một khe — ví dụ thành một Feature thông tin xác thực đặc thù cho provider (feature.aggrega.ai/kind=secret, provider=helm) — mà không cần nêu tên một FeatureRecipe, giống hệt cách selector của một socket usesSchema thu hẹp đích của một cạnh phụ thuộc. Trình biên dịch đánh giá selector dựa trên các label của Feature được gắn và không gì khác: nó đọc các label mà phần lấp đầy mang, và báo cáo liệu selector có chấp nhận chúng hay không. Việc label nào có ý nghĩa để yêu cầu là một lựa chọn khi xây dựng catalog, không phải một quy tắc mà trình biên dịch áp đặt.

Lỗi chính tả tên khe xuất hiện dưới dạng cảnh báo, không phải dừng. Vì một tên phần gắn chưa khai báo là hợp lệ, một tên khe bị viết sai sẽ trở thành một phần gắn tự do thay vì lấp đầy khe mà tác giả muốn. Trình biên dịch báo cáo một tên phần gắn cách một tên khe đã khai báo một lần chỉnh sửa dưới dạng cảnh báo nêu cả hai cách viết — xem errors/warnings.md “Attachment-slot near-miss lint”. Cảnh báo không bao giờ thay đổi kết quả của build; trình biên dịch không kiểm soát cách tác giả đặt tên một phần gắn. Một tên cách một lần chỉnh sửa so với một khe có selector được Feature của phần gắn thỏa mãn sẽ không gây cảnh báo: khi khe đó cuối cùng bị trống, việc dừng được mô tả ở trên sẽ báo cáo phần gắn thay thế, và khi có thứ khác liên kết khe, phần gắn đó là một phần gắn thêm thông thường.

Khai báo một slot là nhạy cảm

sensitive: true trên một slot nêu yêu cầu riêng của bên tiêu thụ: bất cứ thứ gì gắn vào điểm này đều xử lý dữ liệu bí mật.

spec:
featuresSchema:
password:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]
description: "Optional database password credential."

Đây thực sự là thông tin khác với sensitive: true của một lá schema, không phải bản sao cho tiện, và catalog thư viện chuẩn cần cả hai. Một thông tin xác thực có thể tham chiếu công bố provides.name và provides.key — định vị của tài nguyên và khóa dữ liệu bên trong nó — và không cái nào là nhạy cảm: tên của một Kubernetes Secret là công khai, và khóa bên trong nó cũng vậy. Tuy nhiên, slot mà thông tin xác thực đó lấp đầy chắc chắn xử lý dữ liệu bí mật. Một lá nói dữ liệu này là dữ liệu bí mật; một slot nói điểm gắn kết này xử lý dữ liệu bí mật; hai khẳng định nói về những thứ khác nhau và có thể đúng độc lập với nhau.

Hệ quả thực tế là yêu cầu đi theo điểm gắn kết chứ không theo phần lấp đầy. Một Feature hoàn toàn không khai báo lá nhạy cảm nào — vì engine đích sở hữu thông tin xác thực và tác giả không viết gì — vẫn gắn vào một slot nhạy cảm như một attachment nhạy cảm, vì slot đã nói như vậy. Điều ngược lại cũng đúng: một phần lấp đầy khai báo một lá nhạy cảm là một attachment nhạy cảm ngay cả khi nó gắn vào một slot không có khai báo như vậy, hoặc khi nó là một attachment tự do không gắn vào slot nào.

Khai báo đi theo chuỗi kế thừa attachment chứ không theo một khối được viết riêng lẻ nào. Yêu cầu của một slot áp dụng cho phần lấp đầy nào cuối cùng được gắn sau khi mọi phạm vi đã được gộp lại, nên một phần lấp đầy ở cấp component thay thế một phần lấp đầy rộng hơn sẽ kế thừa yêu cầu đó không thay đổi.

sensitive trên một slot có cùng giới hạn như từ khóa ở cấp lá — nó chú thích, nó không mã hóa, xác thực, từ chối, ép buộc một cơ chế phân phối, hay thay đổi một byte được render. Phát biểu đầy đủ nằm tại vocabulary/compact-form-authoring.md “What the keyword does not do”.

sensitive và compliance.aggrega.ai/data-class là hai trục khác nhau, được ghi tài liệu cạnh nhau và không bao giờ bị gộp lẫn. sensitive là một giá trị boolean trên một lá hoặc một slot: dữ liệu này, hoặc điểm gắn kết này, xử lý dữ liệu bí mật. compliance.aggrega.ai/data-class là một nhãn phân cấp trên cả một nút — public, internal, restricted — trao cho dữ liệu mà một component nắm giữ một danh tính quản trị. Một cái theo từng dữ liệu và nhị phân, cái kia theo từng nút và có thứ tự; không cái nào thay thế được cái kia, và một thực thể có thể mang cả hai. Nhãn này được trình bày tại vocabulary/labels-and-annotations.md và architecture/08-credential-model.md “Data governance around credentials”.

Phép chiếu schema từ featuresSchema

Các slot đã khai báo được chiếu thành một đoạn JSON Schema 2020-12 mô tả hình dạng của khối attachment. Hai loại phần lấp đầy được xác thực theo đoạn này: khối attachment của một component do một module được import đóng góp, khi thành phần ghép import nó đã được dựng xong, và một attachment được khai báo ở một phạm vi rộng hơn, theo slot trên mỗi component mà nó chạm tới. Còn khối attachment của một component do chính Aggregate khai báo thì được đo bằng schema tài liệu của Aggregate và bằng danh sách cho phép inject của slot (xem bên dưới), và đoạn này được định hình sao cho cả hai đưa ra cùng một phán quyết đối với bất kỳ phần lấp đầy nào. Phép chiếu không bao giờ chạm tới đĩa; nó chỉ tồn tại trong bộ nhớ, và schema: của một Component không bao giờ cần tự viết tay trụ cột attachment.

Đầu vào featuresSchema:

featuresSchema:
root_password:
inject: []
user_password:
inject: [env, file]

Đoạn được chiếu (trong bộ nhớ; biểu diễn dạng rút gọn):

# The OUTER object is open: an attachment under a name no slot declares is
# admitted, because a free attachment is legal authoring.
root_password:
type: { type: string }
description: { type: string }
values:
type: object
additionalProperties: true
# inject admits only an empty block — inject: [] means the Recipe controls
# delivery, so a fill may name no mechanism
inject: {}
user_password:
type: { type: string }
description: { type: string }
values:
type: object
additionalProperties: true
inject:
env: { type: array }
file: { type: array }
# arg is absent — not in the inject allowlist

Hai tầng độc lập với nhau. Đối tượng bên ngoài là mở, nên một slot đã khai báo không bao giờ cấm các attachment mà thực thể không liệt kê. Đoạn riêng của mỗi slot đã khai báo là đóng, nên một phần lấp đầy thực sự gắn vào một slot đã khai báo vẫn bị ràng buộc theo hình dạng của slot đó.

Đoạn này chỉ mô tả HÌNH DẠNG. Nó không nêu slot nào phải được gắn, vì một slot được đánh dấu required có thể được gắn bởi một attachment kế thừa từ một phạm vi rộng hơn — khiến khối mà đoạn này mô tả trống. Do đó yêu cầu được kiểm tra dựa trên tập attachment mà một component cuối cùng có, chứ không dựa trên những gì một khối riêng lẻ khai báo, và hai câu hỏi không bao giờ mâu thuẫn nhau vì chỉ một trong hai được đặt ra cho khối được viết.

Các khóa được phép phản ánh các khóa mà một attachment có thể mang ở bất kỳ đâu, nên một khóa hợp lệ trên một attachment tự do vẫn hợp lệ trên một phần lấp đầy slot. Mỗi cơ chế phân phối trong danh sách cho phép là một danh sách các mục phân phối — cùng hình dạng mà inject: có ở mọi nơi; slot thu hẹp những TÊN cơ chế nào có thể xuất hiện, chứ không thu hẹp hình dạng của một mục.

Nơi danh sách cho phép inject được thực thi

Danh sách cho phép ràng buộc cả hai phía của slot, ở hai bước khác nhau.

Đối với Workload của Recipe, ở bước render: một Workload tham chiếu một slot qua các mục attachment của container phải nêu tên một slot mà thực thể khai báo, và phải chọn một cơ chế phân phối mà danh sách cho phép inject của slot cho phép; một tham chiếu tới một slot hộp đen (inject: []), tới một cơ chế nằm ngoài danh sách cho phép, hoặc tới một slot mà thực thể chưa bao giờ khai báo sẽ dừng bản build. Thông báo chẩn đoán nêu tên Recipe, đường dẫn container và slot vi phạm, và được phân loại là lỗi catalog — Recipe là bên làm sai.

Đối với attachment riêng của Aggregate, khi các attachment của nó được phân giải và trước mọi bước render: một khối inject: trên một phần lấp đầy gắn vào một slot đã khai báo chỉ được nêu những cơ chế mà danh sách cho phép của slot cho phép, và một slot hộp đen không cho phép cơ chế nào — danh sách cho phép trống của nó nói “Recipe phân phối cái này nội bộ; đừng quy định việc phân phối”, và việc viết phần phân phối cho nó sẽ dừng bản build. Thông báo chẩn đoán được định vị trên attachment và nêu tên slot cùng cơ chế vi phạm, kèm theo các cơ chế mà slot cho phép nếu nó cho phép cơ chế nào; nó được phân loại là lỗi của nhà phát triển, vì Aggregate là bên làm sai. Một khối inject: {} rỗng không nêu cơ chế nào, nên nó không quy định việc phân phối nào và được chấp nhận trên mọi slot, kể cả slot hộp đen — dù trên một component do Aggregate khai báo, trên một component do module được import đóng góp, hay trên một attachment được khai báo ở phạm vi rộng hơn. Một attachment tự do — attachment dưới một tên không slot nào khai báo — không mang ràng buộc như vậy, vì danh sách cho phép thuộc về slot chứ không thuộc về khối.

Luồng đầu-cuối qua pipeline biên dịch — cách một attachment của Aggregate kết nối tới một Feature thông tin xác thực (như core/secret-value) rồi tới một FeatureRecipe dành riêng cho provider phân phối thông tin xác thực tới workload đang chạy — được trình bày chi tiết trong examples/05-credential-features.

Khóa mà bên gọi xuất trình và khóa mà máy chủ xác minh

Khi một component gọi một component khác có kiểm tra khóa, mỗi đầu giữ khóa ở phía của riêng mình, trong một slot do chính nó khai báo. Đây là một quy ước mà catalog thư viện chuẩn tuân theo; trình biên dịch không thực thi bất kỳ phần nào của nó — nó kiểm tra các slot của mỗi component đối chiếu với các attachment của chính component đó, chuyển tiếp các chuỗi của chúng, và không bao giờ so sánh những gì một component giữ với những gì component khác giữ.

  • Khóa mà bên gọi xuất trình thuộc về bên gọi. Nó nằm trong một slot mà socket của bên gọi khai báo cho mỗi kết nối — xem “Slots each connection fills” ở trên — nên một bên gọi kết nối tới nhiều đích sẽ giữ một khóa cho mỗi đích. Socket model của core/ai-agent/crewai khai báo slot đó là credential, và các Recipes của nó cung cấp bất cứ thứ gì lấp vào slot đó dưới dạng OPENAI_API_KEY. Các socket models của core/gateway/litellm, core/gateway/kong và core/gateway/apisix cũng khai báo slot này, và các Recipes của chúng cung cấp khóa của mỗi kết nối dưới một biến riêng, đặt tên theo alias của kết nối, nên mỗi model mà gateway phục vụ đều giữ một khóa riêng. Ngược lại, một khóa mà một Component khai báo trong một slot của riêng nó là một khóa duy nhất cho mọi kết nối mà nó tạo ra.
  • Khóa mà máy chủ xác minh là slot của chính máy chủ. core/ai-model/vllm, core/ai-model/tei và core/ai-model/tgi mỗi cái khai báo một api_key tùy chọn, và mỗi Recipe của chúng cung cấp bất cứ thứ gì lấp vào slot đó dưới dạng biến mà máy chủ đọc khóa từ đó. Model và gateway LiteLLM khai báo api_key cho khóa mà LiteLLM gọi là master key.
  • Không đầu nào thấy các attachment của đầu kia. Một attachment trên một kết nối là một trong các attachment của bên gọi và chỉ đến được bước render của bên gọi, còn đầu ra được render của máy chủ vẫn như nhau bất kể các kết nối tới nó mang theo gì. Một slot được đánh dấu required là nghĩa vụ của component khai báo nó, không bao giờ của các component kết nối tới nó, và việc lấp slot ở một đầu không lấp gì ở đầu kia — vì vậy khai báo khóa ở cả hai đầu là mức tối thiểu chứ không phải sự trùng lặp.
  • Cả hai đầu đọc cùng một tham số, nên khóa mà bên gọi xuất trình và khóa mà máy chủ xác minh không thể bị viết khác nhau.
# Aggregate fragment — one parameter feeds both ends
spec:
parameters:
model_key_secret: { type: string }
components:
model:
type: core/ai-model/vllm
values: { model: Qwen/Qwen2.5-0.5B-Instruct }
features:
api_key: # the key the server verifies
type: core/referenced-secret
values:
origin: "{{ .parameters.model_key_secret }}"
key: api-key
agent:
type: core/ai-agent/crewai
# values (role, goal, backstory, …) elided
uses:
model:
local:
target: model
features:
credential: # the key the caller presents
type: core/referenced-secret
values:
origin: "{{ .parameters.model_key_secret }}"
key: api-key

Một máy chủ chỉ kiểm tra một khóa thì không thể phân biệt các bên gọi: vLLM, TEI và TGI mỗi cái kiểm tra một khóa duy nhất, nên mọi bên gọi đều xuất trình cùng một khóa dù có bao nhiêu kết nối tới máy chủ. Việc hai đầu tham chiếu cùng một secret hay mỗi đầu giữ secret riêng phụ thuộc vào nơi mỗi provider phân giải secret theo tham chiếu, và Manifest chọn cách hiện thực hóa cho mỗi đầu — Credential Model trình bày chi tiết cả hai trường hợp.

Một credential mà component giữ cho chính nó — chẳng hạn một khóa dùng để ký các phiên của chính nó — là một slot trong featuresSchema: của chính nó như mọi slot khác. Một mật khẩu mà nó xuất trình cho một kho dữ liệu mà nó kết nối qua một trong các socket của mình chính là khóa của bên gọi nêu trên, nên nó nằm trên kết nối đó dưới dạng credential: socket backend của core/gateway/kong khai báo nó, và các Recipes tổng hợp workload của nó cung cấp nó dưới dạng KONG_PG_PASSWORD, còn socket cache_store của core/gateway/litellm khai báo nó cho mật khẩu mà bộ nhớ đệm ngữ nghĩa của nó xuất trình cho kho, được cung cấp dưới dạng REDIS_PASSWORD. Khi một kết nối xuất trình một cặp — một định danh access key và secret của nó — nửa secret là credential và nửa định danh là credential_id, như trên socket store của core/ai-agent/agenta-api.

Tự tiêm: spec.inject

Một Component có thể khai báo một mảng spec.inject: ở cấp cao nhất, liệt kê danh sách cho phép các cơ chế phân phối tự tiêm. Khi mảng này có mặt, nhà phát triển có thể dùng một khối inject: ở cấp component trong Aggregate để tiêm trực tiếp các khóa values: hoặc provides: của chính Component vào đường ống phân phối của chính nó (biến môi trường, tệp được gắn kết hoặc đối số tiến trình của container). Khi spec.inject: vắng mặt hoặc rỗng, việc tự tiêm ở cấp component bị cấm — Recipe kiểm soát toàn bộ việc nối dây nội bộ, khớp với mẫu Black-Box mà usesSchema[].inject: [] và featuresSchema[].inject: [] áp dụng lần lượt cho việc phân phối giữa các component và phân phối thông tin xác thực.

# Component declares its self-inject allowlist:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/web-server
version: 1.0.0
labels:
component.aggrega.ai/type: server
spec:
inject: [env, file]
schema:
values:
log_level: { type: string, default: info }
tls_enabled: { type: boolean, default: false }
provides:
health_endpoint: { type: string }
# Aggregate fragment — developer dictates self-inject delivery:
components:
api:
type: core/web-server
values:
log_level: debug
tls_enabled: true
inject:
env:
- in: LOG_LEVEL
value: '{{"{{"}} .values.log_level }}'
- in: TLS_ENABLED
value: '{{"{{"}} .values.tls_enabled }}'
file:
- in: /etc/web/health-probe
from: health_endpoint

Mỗi template value: bắt đầ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 phân giải tự tiêm chạy, và tại thời điểm đó .values chưa tồn tại; phần thoát đặt lại {{ để phân giải tự tiêm đánh giá. Xem Văn bản tự mang dấu ngoặc nhọn kép.

Ngữ nghĩa của trường. spec.inject: là một mảng tên cơ chế. Có ba giá trị được định nghĩa:

  • env — biến môi trường trong container.
  • file — đường dẫn tệp được gắn kết.
  • arg — đối số dòng lệnh của tiến trình.

Ngữ nghĩa này phản chiếu chính xác usesSchema[].inject và featuresSchema[].inject — cùng bộ từ vựng, cùng mẫu Black-Box khi bị bỏ qua, cùng hình thức soạn thảo ở phía Aggregate. Điểm khác biệt là nguồn: usesSchema[].inject quy định cách provides của một phụ thuộc giữa các component chảy vào đường ống phân phối của bên tiêu thụ; featuresSchema[].inject quy định cách một thông tin xác thực đến được container; spec.inject quy định cách values và provides của chính Component đến được container của chính Component đó.

Nguyên tắc soạn thảo. Một Component core/web-server khai báo spec.inject: [env, file] sẽ chọn phân phối minh bạch — tác giả Aggregate quyết định tên biến môi trường nào mang giá trị nào. Một Component khai báo spec.inject: [] (hoặc bỏ qua trường này) giữ việc phân phối ở dạng mờ — valuesMapping: của Recipe quyết định trường nào chảy vào biến container nào, và nhà phát triển không thể ghi đè tại Aggregate. Mẫu Black-Box phù hợp với các Components có hợp đồng ổn định (một Component core/postgres-db mà Recipe của nó biết cách nối mật khẩu DB vào biến môi trường POSTGRES_PASSWORD); mẫu minh bạch phù hợp với các Components mà ý định của nhà phát triển chính đáng cần chỉ định chi tiết phân phối (một core/web-server có ứng dụng đọc LOG_LEVEL từ một tên biến không chuẩn mà nhà phát triển muốn tùy chỉnh).

Các chế độ lỗi. Một Aggregate của nhà phát triển dùng khối inject: trên một Component có spec.inject: bị thiếu hoặc rỗng sẽ dừng quá trình build khi nạp workspace (“Self-inject on a component without an allowlist (Tự tiêm trên một component không có danh sách cho phép)”). Một khối inject: dùng cơ chế không nằm trong danh sách cho phép sẽ dừng với cùng điều kiện, nêu tên cơ chế đó và các cơ chế mà danh sách cho phép (“Self-inject mechanism not in the component’s allowlist (Cơ chế tự tiêm không nằm trong danh sách cho phép của component)”). Một xung đột khóa phân phối giữa tự tiêm, tiêm giữa các component và tiêm thông tin xác thực cũng dừng (“Duplicate delivery key across inject sources (Khóa phân phối trùng lặp giữa các nguồn tiêm)”). Xem errors/fatal-halts.md để biết dạng thông báo của từng lỗi.

Soạn catalog: mở rộng các Components cơ sở

Các kiến trúc sư nền tảng dùng từ khóa extends để xếp lớp các giao diện chuyên biệt lên trên các nền tảng cơ sở của doanh nghiệp hoặc cộng đồng. Việc mở rộng kết hợp cấu trúc và kế thừa nguyên vẹn các trụ dữ liệu. Trình biên dịch duyệt chuỗi từ cơ sở trở xuống; hai nửa này hoạt động khác nhau, và sự khác biệt đó chính là toàn bộ mô hình soạn thảo.

Những gì việc mở rộng kết hợp. Các bề mặt sau được hợp nhất dọc theo chuỗi, với Component mở rộng thắng theo từng khóa và các danh sách được nối với phần cơ sở đứng trước, không trùng lặp:

Bề mặtCách kết hợp
metadata.labelshợp nhất theo từng khóa; giá trị của Component mở rộng thắng khi trùng khóa
metadata.annotationshợp nhất theo từng khóa, cùng thứ tự ưu tiên — đó là lý do yêu cầu hiện diện của một cơ sở đến được mọi Component mở rộng nó
spec.featuresSchemahợp các khe gắn kết; một khe mà Component mở rộng khai báo lại sẽ thay thế mục cùng tên của cơ sở
spec.usesSchemahợp các socket topology, cùng quy tắc thay thế theo tên
spec.injecthai danh sách cho phép self-inject được nối lại, mục của cơ sở đứng trước, bỏ các mục trùng lặp
spec.assertionscác quy tắc có tên được tích lũy, quy tắc của cơ sở đứng trước — và riêng bề mặt này không cho phép thay thế theo tên; xem “Kế thừa assertion mang tính cộng dồn” bên dưới

Một socket mà Component mở rộng thêm vào có thể mang valueSchema và infraSchema riêng theo từng cạnh; đó là các hợp đồng trên các cạnh của socket đó, không phải phần bổ sung vào các trụ riêng của Component.

Phần còn lại của metadata: ở lại với tài liệu khai báo nó. labels và annotations là metadata duy nhất được truyền xuống theo chuỗi. name, version, description, maintainers, license, repository, home và keywords là của riêng Component mở rộng, được đọc đúng như nó đã soạn — một Component bỏ qua description: sẽ không có mô tả thay vì mượn của cơ sở. Danh tính và nguồn gốc thuộc về tài liệu bạn đang đọc, nhờ vậy một lớp bao không bao giờ bị nhầm với thứ mà nó bao bọc.

Những gì việc mở rộng kế thừa nguyên vẹn. Ba trụ dữ liệu — values, infra, provides — không được kết hợp. Một Component mở rộng không soạn nội dung trụ nào: nó viết dấu hiệu nguyên văn schema: inherited và nhận khối schema: của cơ sở đúng như cơ sở đã soạn. Dọc theo một chuỗi ở bất kỳ độ sâu nào, mọi Component trong đó đều mang khối của gốc chuỗi không thay đổi, vì vậy aggrega inspect --resolved trên một lá cho thấy cùng các trụ như gốc.

Schema Component đã công bố xác định kết quả nào trong ba kết quả có thể là hợp lệ, và từ chối hai kết quả còn lại khi tài liệu được nạp — với một chẩn đoán khác nhau cho mỗi trường hợp, vì chúng là những lỗi khác nhau:

  • extends: có nội dung trụ dưới schema: bị từ chối. Hợp đồng của Component là hợp đồng của cơ sở; một hợp đồng thứ hai, khác biệt, không có chỗ để tồn tại.
  • extends: mà bỏ hoàn toàn schema: bị từ chối. Một sự bỏ sót sẽ khiến người đọc không thể phân biệt một khối trụ được kế thừa với một khối bị quên.
  • schema: inherited mà không có extends: bị từ chối. Dấu hiệu này chỉ ra các trụ đến từ đâu, và Component này không có cơ sở nào để lấy chúng.

Một Component mở rộng không thể định hình lại tập khóa. Nó không khai báo khóa trụ nào, nên không thể ẩn, bỏ hay đổi kiểu một khóa mà cơ sở khai báo, và cũng không thêm khóa nào của riêng mình. Một khóa trụ mới thuộc về Component có hợp đồng sở hữu nó. Bất cứ gì cơ sở phơi ra, mọi thứ mở rộng nó đều phơi ra y hệt.

Một chuyên biệt hóa siết chặt thông qua assertions:. Khi một chuyên biệt hóa phải chấp nhận ít hơn các trụ của cơ sở — một khoảng số hẹp hơn, một tập con của một enum: được kế thừa — nó nêu điều đó trong khối assertions: riêng: một quy tắc ở đó từ chối một giá trị mà schema được kế thừa chấp nhận. Đó là bề mặt nơi việc siết chặt diễn ra; xem “Khối assertions:” bên dưới.

Hai đoạn vừa rồi là một quy tắc, và chỉ một nửa riêng lẻ sẽ gây hiểu lầm: không thể thu hẹp tập khóa, có thể siết chặt ràng buộc. Chỉ đọc đoạn đầu, bạn sẽ kết luận một chuyên biệt hóa không thể ràng buộc gì; chỉ đọc đoạn sau, bạn sẽ kết luận nó có thể định hình lại hợp đồng. Cả hai đều không đúng — tập khóa do cơ sở cố định, và các giá trị được chấp nhận trong đó có thể được thu hẹp bằng vị từ.

Kế thừa assertion mang tính cộng dồn, và sự tích lũy bắt đầu từ gốc. Một thể hiện của Component mở rộng được kiểm tra theo mọi quy tắc mà chuỗi của nó khai báo cũng như các quy tắc mà chính Component khai báo, với các quy tắc được kế thừa được đánh giá trước. Dọc theo một chuỗi ở bất kỳ độ sâu nào, các quy tắc tích lũy từ gốc chuỗi trở xuống, vì vậy khi một thể hiện vi phạm nhiều hơn một quy tắc, quy tắc được khai báo cao nhất trong chuỗi là quy tắc được báo cáo — hợp đồng cơ bản nhất trả lời trước.

Vì kế thừa là cộng thêm chứ không thay thế, một Component mở rộng không được dùng lại tên một quy tắc được kế thừa để khai báo một quy tắc khác: điều đó bị từ chối khi chuỗi extends được phân giải theo catalog, với một chẩn đoán nêu tên cả hai Components và tên dùng chung. Việc kiểm tra cần có Component cơ sở, nên nó báo cáo khi catalog được xác thực hoặc khi một bản build phân giải chuỗi — việc xác thực riêng tài liệu mở rộng không thể phát hiện nó. Tên quy tắc là một định danh ổn định, nên cả việc bỏ quy tắc của cơ sở lẫn việc âm thầm đổi tên nó đều không phải là lựa chọn, và cách sửa là đổi tên trong Component mở rộng. Việc nêu lại nguyên văn từng byte một quy tắc được kế thừa dưới chính tên của nó được chấp nhận như một thao tác không có tác dụng.

aggrega pull tải thực thể cơ sở. Một thực thể cơ sở là phụ thuộc của mọi Release chạm tới một Component mở rộng nó, dù có thứ gì khác nêu tên nó hay không. aggrega pull đi theo từng extends: đến cuối chuỗi, tải từ registry thực thể cơ sở mà không thư mục catalog nào chứa, và ghi mọi thực thể cơ sở vào lockfile của Release, được tham chiếu từ spec.extends của Component nêu tên nó; một bản build đọc thực thể cơ sở từ đó. Vì vậy, một Manifest chỉ ánh xạ kiểu riêng của một wrapper và không gì hơn — thực thể cơ sở chỉ cần một dòng ánh xạ riêng ở nơi một Aggregate cũng khai báo một thể hiện của thực thể cơ sở đó. Một lệnh aggrega validate trên toàn bộ catalog đọc thực thể cơ sở theo cùng cách, nên một thực thể cơ sở được xuất bản lên registry sẽ bị từ chối ở đó, kèm tên aggrega pull, cho đến khi một lần pull đã tải nó về.

Xem architecture/13-catalog-and-registry.md §3 để biết các định dạng nội dung schema.

Ví dụ A: Component cơ sở (nền tảng cơ sở của doanh nghiệp) Kiến trúc sư nền tảng định nghĩa một máy chủ doanh nghiệp nền tảng. Cơ sở này đặt nhãn nguyên thủy đám mây vận hành bắt buộc và thiết lập các ràng buộc bảo mật trong schema. Vì khối trụ được kế thừa không thay đổi, mọi ràng buộc ở đây đến được từng Component mở rộng đúng như đã soạn.

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/base-enterprise-server
version: 1.0.0
labels:
component.aggrega.ai/type: "server"
spec:
inject: [env]
schema:
values:
# The corporate baseline constraint. Every Component extending this base
# receives this leaf verbatim; none of them can restate or loosen it.
tls_enabled: { type: boolean, enum: [true], default: true }
# An open range at the baseline. A specialization that needs a tighter
# bound expresses it as an assertion, not as a redeclared schema leaf.
timeout_ms: { type: integer, default: 5000 }
assertions:
# A baseline invariant. It is evaluated for instances of this Component AND
# for instances of every Component extending it, under this same name.
audit-window-is-observable: |
{{- if lt (int .values.timeout_ms) 100 -}}
{{- fail "the corporate baseline needs timeout_ms of at least 100 so requests are observable" -}}
{{- end -}}

Ví dụ B: Component mở rộng (chuyên biệt hóa nền tảng cơ sở) Một gateway được chuyên biệt hóa từ nền tảng cơ sở đó. Nó nhận nguyên vẹn các trụ của cơ sở, thêm cấu trúc của riêng mình — một nhãn, một cơ chế self-inject, một socket topology có một khe gắn kết trên đó — và siết chặt timeout được kế thừa thông qua một assertion. Nó không nêu lại quy tắc audit-window-is-observable của nền tảng cơ sở: quy tắc đó được kế thừa và được đánh giá trước, nên một thể hiện của gateway này phải thỏa mãn cả hai giới hạn — ít nhất 100 và nhiều nhất 2000.

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/gateway/kong
version: 1.0.0
labels:
# Every Component declares the reserved base-ontology key, including one
# that extends: the envelope requires it on the document itself.
component.aggrega.ai/type: "server"
api.aggrega.ai/protocol: "http" # merged with the base's labels
spec:
extends: core/base-enterprise-server
schema: inherited # values, infra and provides are the base's, verbatim
inject: [file] # concatenates with the base's [env] -> [env, file]
usesSchema: # a socket of its own; the base declared none
backend:
required: true
selector: "component.aggrega.ai/type=stateful-server"
inject: [env]
featuresSchema: # a slot each connection through it fills
credential:
sensitive: true
inject: [env]
description: Password the gateway presents to the configuration backend this connection reaches.
assertions:
# The tightening. The inherited schema admits any integer for timeout_ms;
# this gateway admits only 2000 or less, so the rule rejects a value the
# inherited pillar block would accept.
timeout-within-gateway-budget: |
{{- if gt (int .values.timeout_ms) 2000 -}}
{{- fail "the gateway must answer within 2000ms: set timeout_ms to 2000 or less" -}}
{{- end -}}

Về Recipe hiện thực giao diện core/gateway/kong này dựa trên một Helm chart vật lý, xem Ví dụ C (kong-gateway) trong entities/recipe.

Khối assertions:

Component.spec.assertions: là một map tùy chọn gồm các quy tắc có tên biểu đạt các bất biến kiến trúc của hợp đồng Component — các quy tắc liên trường mà nội dung do nhà phát triển soạn phải thỏa mãn bất kể Recipe nào liên kết với Component. Mỗi khóa là một định danh quy tắc xuất hiện trong thông báo lỗi; mỗi giá trị là phần thân của một Go template. Trình biên dịch đánh giá chúng theo từng thể hiện sau khi xác thực schema và trước khi liên kết Recipe, theo thứ tự chúng được viết, và quy tắc đầu tiên thất bại sẽ dừng bản build với thông báo lỗi riêng của quy tắc đó theo hợp đồng Loud Guardrails.

spec:
assertions:
replication-needs-two-secondaries: |
{{- if eq .values.architecture "replication" -}}
{{- if lt (int .values.secondary.replicaCount) 2 -}}
{{- fail "architecture=replication requires secondary.replicaCount >= 2" -}}
{{- end -}}
{{- end -}}

Quy tắc ở trên là một thuộc tính của hợp đồng Component — bất kể Recipe nào liên kết (chart Bitnami, phương án tự viết, hiện thực trong tương lai), chế độ replication đều đòi hỏi ít nhất hai bản sao phụ.

assertions: là nơi một Component mở rộng siết chặt. Một Component dùng extends: một cơ sở sẽ kế thừa nguyên văn khối trụ của cơ sở và không khai báo nội dung trụ nào của riêng mình, vì vậy một chuyên biệt hóa phải chấp nhận ít hơn schema được kế thừa sẽ nêu giới hạn tại đây dưới dạng một vị từ thay vì một lá schema bị thu hẹp — một quy tắc từ chối một giá trị mà các trụ được kế thừa chấp nhận. Cặp ví dụ minh họa và toàn bộ hành vi kế thừa nằm ở “Soạn catalog: mở rộng các Components cơ sở” bên trên: các quy tắc tích lũy dọc theo chuỗi bắt đầu từ gốc, và việc dùng lại tên một quy tắc được kế thừa cho một quy tắc khác bị từ chối thay vì được phép thay thế nó.

Trình biên dịch không kiểm tra liệu hai quy tắc có thể cùng được thỏa mãn hay không. Một quy tắc là một vị từ template, không phải một ràng buộc mà trình biên dịch suy luận, nên một cặp quy tắc mà không giá trị nào có thể thỏa mãn đồng thời — một cơ sở đòi ít nhất 100 và một chuyên biệt hóa đòi nhiều nhất 50 — không tạo ra cảnh báo nào khi catalog được nạp. Nó lộ ra theo cách thông thường: một thể hiện được soạn, bản build dừng ở quy tắc nào trong hai quy tắc kích hoạt trước, và thông báo của quy tắc đó là thứ người soạn đọc được. Đừng mong một mâu thuẫn được báo cáo trước; hãy kiểm tra việc siết chặt của một chuyên biệt hóa so với những gì cơ sở của nó đã đòi hỏi.

Hãy dùng assertions: cho các quy tắc liên trường thực sự. Các ràng buộc theo từng trường (khoảng, mẫu, enum) thuộc về các từ khóa schema:; các vị từ tùy chỉnh theo từng trường thuộc về validate: của dạng rút gọn; hình dạng có điều kiện (các ràng buộc của một cây con có áp dụng hay không) thuộc về when:. Để biết toàn bộ ngữ pháp soạn thảo — các trường ngữ cảnh template, quy ước thông báo {{ fail }}, giai đoạn đánh giá, và các ví dụ minh họa trải rộng vai trò Component và Recipe — xem templates/assertions-block.md.