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.

Aggregate

Vai trò khái niệm của thực thể Aggregate (Miền 1 — bản thiết kế topo khai báo của Developer) được trình bày trong architecture/04-entity-taxonomy.md. Các mẫu kết hợp (subsystem, aggregate lồng nhau, Zero-Port Convention, Parameter Hoisting) được trình bày trong architecture/06-data-taxonomy-and-composition.md. Trang này đề cập đến bề mặt soạn thảo catalog của Aggregate — cụ thể là việc soạn các module Aggregate tái sử dụng được để phân phối qua catalog.

Phạm vi Component: subsystem mặc định

Một Aggregate tổ chức các component thành các subsystem — các nhóm được đặt tên cho những mối quan tâm xuyên suốt (một tầng dữ liệu, một tầng biên) mang chuỗi annotation cascade riêng của chúng. Hầu hết các Aggregates chỉ có một nhóm duy nhất, nên nhóm đó không cần thủ tục gì.

Phạm vi đơn (mặc định). Khai báo các component trực tiếp dưới spec.components: và bỏ qua khối subsystems::

spec:
components:
api:
type: core/server:1.0.0
worker:
type: core/worker:1.0.0

Trình biên dịch gộp các component này vào một subsystem default được tổng hợp. Định danh của node không thay đổi — api vẫn là api, không bao giờ là default.api — nên một Aggregate được viết theo cách này có thể thay thế cho dạng một subsystem tường minh, và việc tham chiếu đến nó (trong các đích uses:, trong các thông báo chẩn đoán) dùng đường dẫn spec.components.<name> trần. Phạm vi tổng hợp được ghi nhận trung thực trong IR được xuất ra (mang một dấu hiệu subsystem tổng hợp), nhưng nó không bao giờ xuất hiện trong các đường dẫn mà tác giả viết hoặc đọc.

Nhiều phạm vi. Khi các component thuộc về những nhóm xuyên suốt riêng biệt, hãy khai báo các subsystem được đặt tên dưới subsystems:. Mỗi subsystem mang các component và chuỗi annotation cascade riêng của nó, và có thể lồng thêm các subsystem khác.

Loại trừ lẫn nhau. spec.components: và spec.subsystems: loại trừ lẫn nhau ở gốc Aggregate — chỉ khai báo một trong hai, không bao giờ cả hai. Một tài liệu khai báo cả hai sẽ dừng ngay khi nạp với một lỗi envelope. (Một subsystem mà nhà phát triển đặt tên tường minh là default là một subsystem được khai báo bình thường, được tham chiếu tại đường dẫn đầy đủ spec.subsystems.default.components.<name> — việc lược bỏ phạm vi tổng hợp dựa trên nguồn gốc, không dựa trên tên.)

Các module Aggregate tái sử dụng

Các Aggregates đóng vai trò vừa là Aggregate gốc mà một Release build vừa là các mô-đun có thể tái sử dụng. Một Aggregate cha có thể khai báo một Aggregate con giống hệt như một thành phần, truyền parameters xuống nó. Để tránh liên kết chặt, các Aggregates con phơi bày một hợp đồng exportedComponents:, thiết lập một tên giao diện công khai ổn định. Cha chỉ tiếp cận các thành phần của mô-đun qua giao diện này: một đích uses: là tên của mô-đun, một dấu chấm và một trong các bí danh đã xuất của nó, và trình biên dịch nối cạnh tới thành phần nội bộ mà bí danh đó chỉ định. Một đích tiếp cận vào trong mô-đun bằng bất kỳ tên nào khác — tên của thành phần bên trong mô-đun, hoặc một đường dẫn vào một mô-đun lồng bên trong nó — sẽ dừng bản build, nêu tên mô-đun và các bí danh mà nó xuất; xem A uses target names a module’s component the module does not export (Đích chỉ định một thành phần của mô-đun mà mô-đun không xuất).

Vì sao cần một danh sách exportedComponents: tường minh. Tác giả của một mô-đun quyết định những thành phần nào của nó tạo nên giao diện công khai và những thành phần nào vẫn là chi tiết triển khai. Vì cha chỉ có thể nêu tên những gì danh sách công bố, phần bên trong của mô-đun có thể được tái cấu trúc — đổi tên một thành phần, tách một thành phần thành hai, thay một worker bằng một dịch vụ được quản lý — mà không làm hỏng cha nào, miễn là mỗi tên đã công bố vẫn trỏ tới một thành phần. Danh sách tốn một mục cho mỗi thành phần được công bố, và một thành phần có thể được công bố dưới chính tên của nó (store: store) khi đó là tên mà bên import nên dùng. Quy tắc tương tự áp dụng bên trong một tổ hợp: một mô-đun tiếp cận một mô-đun mà nó import qua các bí danh đã xuất của mô-đun đó. Một Release có thể nối hai thành phần của cùng một mô-đun với nhau, vì kết nối đó không đi qua giao diện của mô-đun nào.

Xuất lại giao diện của một module lồng nhau. Một mục exportedComponents: có thể trỏ tới alias được xuất của một sub-aggregate lồng nhau thay vì tới một component được khai báo trực tiếp — tức là một module công bố lại một phần của module mà nó import, dưới tên giao diện của chính nó và có thể kèm một tên mới. Một cạnh uses: nhắm tới alias được xuất lại như vậy sẽ được phân giải bắc cầu qua chuỗi tới node nội bộ cụ thể, nhờ đó một module ghép các module sâu hơn vào giao diện công khai của mình mà không để lộ bố cục nội bộ của chúng, và bên sử dụng không bao giờ cần biết đích được lồng sâu đến đâu. Kỷ luật giao diện ổn định được giữ ở mọi bước: mỗi module chỉ xuất lại những gì nó chọn công bố. Một đích được xuất lại không phân giải tới node nội bộ nào sẽ dừng một cách rõ ràng giống như một đích treo trực tiếp, và một chuỗi xuất lại khép vòng về chính nó sẽ bị từ chối thay vì bị theo vô hạn.

Các khai báo của một module được kiểm tra như khai báo của Aggregate. Tài liệu của một module chỉ được đọc khi bản kết hợp nhập nó được build, và các khai báo của nó được kiểm tra từ thời điểm đó, ở mọi độ sâu lồng nhau. Khối inject: của chính một thành phần trong module phải tuân theo danh sách cho phép spec.inject của kiểu của nó, cũng như các quy tắc cấm nhận một khóa phân phối hai lần và cấm đọc một khóa mà kiểu không công bố. Một phần gắn kèm được viết tại một trong các hệ thống con của chính module chỉ có thể nêu tên một socket mà Feature của nó khai báo, và một phần gắn kèm mà Release viết cho một thành phần do module đóng góp cũng vậy.

Các phần gắn kèm hệ thống con của module áp dụng đến các thành phần của nó. Một Feature mà module gắn tại một trong các hệ thống con của chính nó sẽ lan xuống mọi thành phần mà module khai báo bên dưới hệ thống con đó, kể cả các hệ thống con lồng nhau, đúng như một phần gắn kèm hệ thống con trong Aggregate — và chỉ lên các thành phần đó, không bao giờ lên một thành phần của Aggregate nhập module nằm dưới một hệ thống con cùng tên. Nó được đánh giá ngay sau các phần gắn kèm của chính thành phần, hệ thống con ngoài trước hệ thống con trong. Với một trường mà cả hai cùng ghi, phần gắn kèm cùng tên của chính thành phần được ưu tiên, và các trường mà nó bỏ qua giữ giá trị của hệ thống con. Mỗi thành phần mà nó đến được đều kiểm tra nó theo appliesTo của Feature. Một phát hiện về các khai báo của chính module sẽ nêu tên module và khóa bên trong tài liệu của nó — chẳng hạn .spec.subsystems.<subsystem>.features.<attachment> — để việc chỉnh sửa được thực hiện trong module, nơi có khai báo, thay vì trong Aggregate nhập nó.

Vị trí trong catalog

Một module Aggregate tái sử dụng nằm dưới thư mục kind aggregate/ tại đường dẫn mà metadata.name của nó chỉ ra, từng đoạn một, với một thư mục phiên bản ở cấp lá:

aggrega-catalog/
└── aggregate/
└── {module-name}/ # the module's metadata.name, segment for segment
└── {version}/ # the module's metadata.version
└── aggregate.yaml # The module definition

Tên module có thể mang một đoạn {publisher} ở đầu để chỉ nhà cung cấp hoặc tác giả — core cho thư viện chuẩn, acme cho một doanh nghiệp — và các module thư viện chuẩn đã công bố được đặt tên theo cách đó: core/agenta nằm tại aggregate/core/agenta/1.0.0/aggregate.yaml. Một tên chỉ gồm một token nằm nông hơn một cấp, tại aggregate/{module-name}/{version}/aggregate.yaml. Cả hai dạng đều hợp lệ; tên là thứ tác giả viết, và thư mục phản chiếu nó. Việc phản chiếu đó là một quy ước của catalog chứ không phải điều trình biên dịch kiểm tra — một module được tìm thấy theo tên nó khai báo, không theo vị trí tệp của nó.

URI OCI: hub.aggrega.ai/aggregate/{module-name}:{version}, viết thường — nên một module tên core/agenta được công bố tới hub.aggrega.ai/aggregate/core/agenta:1.0.0, và một module tên db-module tới hub.aggrega.ai/aggregate/db-module:1.0.0.

Mẫu module

Module con (aggregate/child-database-module/1.0.0/aggregate.yaml, được công bố dưới dạng hub.aggrega.ai/aggregate/child-database-module:1.0.0):

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: child-database-module
version: 1.0.0
spec:
components:
internal-pg-primary:
type: core/postgres:1.0.0
exportedComponents:
# The Public Contract (Written once by the module author)
primary_db: "internal-pg-primary"

Aggregate cha:

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: parent-app
version: 1.0.0
spec:
aggregates:
finance-db-subsystem:
type: child-database-module:1.0.0
components:
billing-api:
type: core/python-worker:1.0.0
uses:
databases:
- finance-db-subsystem.primary_db

Nhãn module

Khi một Aggregate được phát hành lên catalog như một mô-đun có thể tái sử dụng, nó có thể mang metadata.labels trên envelope YAML của mình — ví dụ aggregate.aggrega.ai/tier: infrastructure hoặc aggregate.aggrega.ai/compliance: pci-dss. Các nhãn này mô tả danh tính của mô-đun và được mang theo trên tài liệu mô-đun như khi phát hành; hiện chưa có lệnh nào đọc chúng. Tìm kiếm catalog không lập chỉ mục các Aggregates, và đồ thị build không mang nhãn của mô-đun cũng như tên catalog của nó, nên một chính sách quản trị không thể chọn các thành phần của mô-đun theo mô-đun mà chúng đến từ.

Khác biệt then chốt. Nhãn của Aggregate mô tả danh tính của module tái sử dụng trong catalog. Chúng không lan truyền xuống các node component con. Nhãn của component chỉ đến từ thực thể catalog Component trong Domain 2. Nếu một nhà phát triển import một module có nhãn aggregate.aggrega.ai/tier: infrastructure, các component riêng lẻ bên trong module đó chỉ giữ các nhãn do Catalog định nghĩa của riêng chúng (ví dụ: component.aggrega.ai/type: stateful-server). Nhãn của Aggregate không bao giờ được chèn vào từ điển labels của node IR.

Xem architecture/06-data-taxonomy-and-composition.md §6 để có phần thảo luận đầy đủ về Composite Aggregates / Module Pattern (bao gồm quy định không có sub-component đối với Components), và về cơ chế nhóm xuyên suốt subsystems. Xem vocabulary/data-pillars để biết bề mặt soạn thảo hợp đồng parameters có kiểu.

Hợp đồng tham số có kiểu

Khối spec.parameters: của Aggregate khai báo hợp đồng có kiểu cho các tham số mà Release đáp ứng. Mỗi ô tham số mang một type đã khai báo, một description tùy chọn, một default tùy chọn, các ràng buộc tùy chọn về không gian giá trị, và (với các ô kiểu đối tượng) cấu trúc lồng nhau. Trình biên dịch kiểm tra từng giá trị do Release cung cấp theo hợp đồng trong quá trình phân giải, trước khi chạy nội suy tham số.

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: web-app
version: 1.0.0
spec:
parameters:
region:
type: string
description: Cloud region the deployment targets
enum: [us-east-1, us-west-2, eu-west-1, ap-northeast-1]
default_locale:
type: string
description: Default UI locale presented to end users
enum: [en-US, en-GB, fr-FR, ja-JP]
default: en-US
enable_debug:
type: boolean
description: Toggle verbose request logging
default: false
feature_flags:
type: object
description: Per-feature enablement map
valuesType: { type: boolean }
default: {}
allowed_hosts:
type: array
description: Hostnames the ingress accepts
items: { type: string, format: hostname }
min: 1
default: ["web-app.example.com"]
components:
web:
type: core/web-server:1.0.0
values:
default_locale: "{{ .parameters.default_locale }}"
region: "{{ .parameters.region }}"
debug: {{ .parameters.enable_debug }}

Cách đặt dấu ngoặc kép trên mỗi tham chiếu là có chủ ý: nó quyết định kiểu mà giá trị được đưa lên mang theo khi đến nơi. Xem templates/parameters-context.md.

Từ vựng của ô tham số

Khối parameters: có kiểu chấp nhận từ vựng dạng rút gọn: type, description, default, enum, min, max, pattern, minLength, maxLength, format, validate và validateMessage (một phép kiểm tra tùy chỉnh và thông báo mà nó đưa ra), items (cho mảng), properties (cho đối tượng), valuesType (cho map giá trị có kiểu), và required: true (dấu đánh trên từng ô). Ba trong số các từ khóa đó nhận một hợp đồng làm giá trị thay vì một thiết lập đơn thuần — items, valuesType, và mỗi mục dưới properties — và trên một ô tham số, hợp đồng lồng nhau đó được viết ở cùng dạng có kiểu như ô bao quanh nó: valuesType: { type: boolean }, không phải valuesType: boolean. Trước khi nội suy, trình biên dịch kiểm tra trực tiếp map tham số đã hợp nhất theo các khai báo này: một tham số không có ô nào khai báo sẽ bị từ chối, một ô được đánh dấu required: true mà Release không điền và cũng không có default cung cấp sẽ dừng bản build, và mọi giá trị được cung cấp đều được kiểm tra theo type đã khai báo của ô, tư cách thành viên trong enum, các giới hạn minLength và maxLength, biểu thức chính quy pattern và format trên ô chuỗi, cùng các giới hạn min và max — giá trị của ô số, độ dài của ô chuỗi và số phần tử của ô mảng. Các ô đối tượng và mảng được kiểm tra đệ quy: mỗi mục dưới properties và mỗi phần tử theo items được kiểm tra theo cùng cách, một hợp đồng valuesType chi phối các khóa mà properties không nêu tên, và một khóa lồng nhau không có khai báo nào nêu tên sẽ bị từ chối. Xem vocabulary/compact-form-authoring.md để biết toàn bộ từ vựng từ khóa, bao gồm cả những chỗ mà một pillar schema: viết các từ khóa này khác đi.

Các từ khóa dưới đây cũng được kiểm tra trên chính khai báo, trước khi đọc bất kỳ giá trị Release nào, nên một ô không thể ràng buộc gì sẽ dừng bản build ngay cả khi không có Release nào cung cấp nó:

  • Giới hạn độ dài là từ không trở lên. Một minLength hoặc maxLength âm trên chính khai báo của tham số sẽ bị schema của Aggregate từ chối khi Aggregate được nạp, kèm tên tham số và khóa. Bên trong một hợp đồng lồng nhau — dưới items, properties hoặc valuesType — giới hạn độ dài được đọc đúng như đã viết và không bị ràng buộc theo mức sàn đó khi Aggregate được nạp, vì vậy ở đó cũng hãy viết nó từ không trở lên: một minLength âm không áp đặt gì, còn một maxLength âm từ chối mọi giá trị.
  • min và max phải giới hạn một điều gì đó. Trên một ô boolean hoặc đối tượng, cặp này không giới hạn gì cả, nên một min hoặc max được viết ở đó sẽ bị từ chối khi Aggregate được tải, kèm tên tham số và khóa.
  • Một pattern phải biên dịch được. Mọi pattern đều được biên dịch thành biểu thức chính quy khi hợp đồng tham số được đọc — trên chính ô đó và bên trong mọi hợp đồng lồng nhau, ở bất kỳ độ sâu nào — và pattern nào không biên dịch được sẽ bị từ chối, kèm tên tham số, pattern và lý do. Hợp đồng được đọc cho mọi lần build, pull và kiểm tra Release chạm tới Aggregate, dù đó là Aggregate của chính Release hay một module mà Aggregate đó import. Sau đó, phép kiểm tra giá trị so khớp từng giá trị được cung cấp với chính biểu thức đã biên dịch đó.
  • Một format phải là loại mà trình biên dịch kiểm tra. format nêu tên một trong số email, uri, hostname, ipv4, ipv6, uuid, date-time và date, viết đúng như JSON Schema viết. Bất kỳ tên nào khác — một lỗi chính tả như emial, hoặc một tên mà JSON Schema không định nghĩa như password — đều bị từ chối khi Aggregate được nạp, kèm tên tham số và danh sách các tên được hỗ trợ: trên chính ô đó thì do schema của Aggregate từ chối, còn bên trong một hợp đồng lồng nhau, ở bất kỳ độ sâu nào, thì khi hợp đồng tham số được đọc. Sau đó, một chuỗi được cung cấp không có format đã nêu sẽ bị từ chối, kèm tên tham số, giá trị và format. Mỗi tên kiểm tra điều gì được trình bày trong vocabulary/compact-form-authoring.md.

Tham số kiểu đối tượng và kiểu mảng

Các ô tham số chấp nhận mọi kiểu mà dạng rút gọn hỗ trợ, bao gồm đối tượng lồng nhau và mảng các phần tử có kiểu:

spec:
parameters:
database_config:
type: object
description: Database connection configuration
properties:
host: { type: string, required: true }
port: { type: integer, min: 1, max: 65535, default: 5432 }
ssl_mode: { type: string, enum: [disable, require, verify-full], default: require }
pool_size: { type: integer, min: 1, max: 100, default: 10 }
metric_labels:
type: array
description: Custom Prometheus labels to attach to scraped metrics
items:
type: object
properties:
name: { type: string, required: true }
value: { type: string, required: true }

Release đáp ứng các tham số kiểu đối tượng bằng YAML có cấu trúc; trình biên dịch kiểm tra cấu trúc theo schema đã khai báo trước khi nội suy. Các template tham chiếu đến các trường của đối tượng dùng cú pháp template Go tiêu chuẩn: {{ .parameters.database_config.host }}, {{ .parameters.database_config.port }}, v.v.

Xác thực hợp đồng tham số

Bản thân hợp đồng được kiểm tra trước tiên, khi nó được đọc — các kiểm tra giới hạn độ dài và pattern trong “Parameter slot vocabulary” ở trên. Sau đó trình biên dịch chạy ba bước con trong quá trình xử lý tham số:

  1. Điền giá trị mặc định — các slot có định nghĩa default: và không có giá trị do Release cung cấp sẽ nhận giá trị mặc định của chúng. Các tham số đối tượng lồng nhau mang ngữ nghĩa soạn thảo ba trường hợp cho slot cha bị bỏ qua, rỗng tường minh và được soạn một phần: bỏ qua slot cha sẽ điền giá trị mặc định của các slot con, soạn slot cha là {} sẽ giữ nguyên giá trị rỗng tường minh (chặn giá trị mặc định của các slot con), và soạn slot cha là một map không rỗng chỉ điền những slot con mà Release không cung cấp. Xem templates/parameters-context.md để có các ví dụ YAML và hướng dẫn quyết định “khi nào dùng từng dạng”.
  2. Xác thực hợp đồng — mỗi giá trị trong map đã hợp nhất, dù do Release cung cấp hay do default: điền vào, đều được xác thực theo các ràng buộc type / enum / min / max / pattern / cấu trúc lồng nhau đã khai báo. Lỗi xác thực sẽ dừng bản build với một thông báo lỗi rõ ràng nêu tên slot vi phạm, giá trị được cung cấp và ràng buộc bị vi phạm. Các tham số bắt buộc bị thiếu mà không có default: cũng gây dừng tương tự, kèm tên slot.
  3. Nội suy — trình biên dịch đánh giá toàn bộ văn bản của Aggregate như một template, trước khi đọc nó dưới dạng YAML, và thay thế mọi tham chiếu {{ .parameters.<slot> }} — thường nằm trong các chuỗi values: của component / feature / sub-aggregate — bằng giá trị đã được phân giải; mọi {{ khác trong văn bản cũng được đọc là cú pháp template, vì vậy một giá trị tự mang dấu ngoặc nhọn kép — chẳng hạn định nghĩa được xuất ra của một nền tảng luồng — phải viết mỗi {{ thành {{"{{"}}, như Văn bản tự mang dấu ngoặc nhọn kép mô tả. Sau lượt này, các bề mặt value-template sử dụng các literal đã được nội suy và không nhận .parameters trong ngữ cảnh template của chúng.

Map tham số đã hợp nhất vẫn tồn tại trong suốt quá trình render để hỗ trợ đánh giá path-template. Các template directory: và subDirectory: do operator soạn trên ranh giới Release đọc trực tiếp .parameters.<slot> tại thời điểm render theo một allowlist đóng; việc phát sinh đường dẫn cần từ vựng region / environment cho bố cục artifact theo từng môi trường, và quyền cấp bất đối xứng này giữ mối quan tâm đó của operator bên trong bề mặt của operator mà không phải đi vòng qua values của Aggregate. Map vẫn đọc được cho đến khi mọi giai đoạn render hoàn tất và chỉ truy cập được từ lần biên dịch mà nó được phân giải cho; các recipe sử dụng values: do nhà phát triển soạn thấy các chuỗi sau nội suy, trong khi path template thấy dữ liệu .parameters trực tiếp trong suốt quá trình render. Xem templates/expansion-matrix.md hàng 3 để có ma trận khả dụng của path-template và path-template-variables.md để có allowlist biến path-template.

Để xem danh sách kiểm tra parameter-hoisting đầy đủ hơn (khai báo Aggregate → tham chiếu values → Release đáp ứng → Recipe sử dụng) và cơ chế liên pillar, xem vocabulary/data-pillars.md §“Parameters” và §“The parameter-hoisting checklist”. Để xem các trường template-context được cung cấp trong quá trình nội suy và ngoại lệ dành cho path-template, xem templates/parameters-context.md.

Một cạnh uses là một lời gọi mà Aggregate khai báo

Một cạnh uses là tuyên bố của Aggregate rằng một component gọi một component khác. Trình biên dịch chuyển các giá trị mà đích công bố vào bên gọi và không hạn chế gì: tự bản thân nó, một cạnh không cho phép bên gọi cũng không từ chối bất kỳ ai khác, và một workload truy cập tới địa chỉ của đích mà không có cạnh vẫn truy cập được như thường.

Việc hạn chế ai được gọi một component, và component đó được gọi những gì, là quyết định của người vận hành, được đưa ra theo từng môi trường trong Release. Khi một Release gắn Feature core/caller-allowlist của danh mục thư viện chuẩn vào một component, bản build sẽ ghi một network policy cho phép chính xác các component có cạnh uses trỏ tới nó, các pod của chính component đó và các nguồn mà phần gắn kèm nêu ra. Đối ứng chiều ra của nó, core/egress-allowlist, chỉ cho phép component mà nó được gắn vào truy cập tới các component mà chính các cạnh uses của nó trỏ tới, các pod của chính nó, DNS của cluster và các dải địa chỉ mà Release liệt kê. Khi đó, một lời gọi mà Aggregate không khai báo thành cạnh có thể bị cluster từ chối ở bất kỳ đầu nào, ở bất cứ nơi nào network plugin của nó thực thi network policy. Vì vậy, hãy viết một cạnh cho mọi lời gọi mà các component của bạn thực hiện, kể cả lời gọi không inject giá trị nào: một cạnh bị thiếu là một lời gọi mà một component đã được rào chắn có thể từ chối. model-server-caller-allowlist cho thấy một model server chỉ truy cập được thông qua gateway đứng trước nó.

Các đính kèm riêng của một kết nối: features trên một mục uses

Một kết nối mà một component vẽ ở dạng uses: đầy đủ là một mục riêng, và bên cạnh target, inject và values, nó có thể mang các đính kèm, dưới features:. Mỗi đính kèm được khóa theo một slot mà socket khai báo: Component tiêu thụ liệt kê, trong featuresSchema của socket, các slot mà mọi kết nối nối qua socket đó có thể lấp đầy (xem Topology Sockets). Đây là cách một component giữ một thông tin xác thực khác nhau cho mỗi component mà nó kết nối tới — một gateway gọi hai mô hình bằng hai khóa, hoặc một agent trình một khóa riêng của nó cho một mô hình.

spec:
parameters:
openai_key_secret: { type: string }
components:
router:
type: core/gateway/litellm # its `models` socket declares a `credential` slot
values: { model: gpt } # the alias it publishes as its model
uses:
models:
gpt:
target: gpt
features:
credential:
type: core/referenced-secret
values:
origin: "{{ .parameters.openai_key_secret }}"
key: api-key
plain:
target: plain # this connection carries no attachment
gpt:
type: core/ai-model/openai
values: { model: gpt-4o-mini }
plain:
type: core/ai-model/ollama
values: { model: llama3.1 }

Một đính kèm trên một kết nối mang type (bắt buộc), một description tùy chọn, và values cho Feature. Nó không mang uses và không mang inject: một đính kèm trên một kết nối không lồng nhau, và cách nội dung của nó đến được bên tiêu thụ là do Recipe của component tiêu thụ quyết định chứ không phải do một khối inject. Một tài liệu viết một trong hai khóa này sẽ bị từ chối khi được nạp, kèm tên của khóa.

Chỉ các slot mà socket khai báo. Một đính kèm dưới một tên mà featuresSchema của socket không liệt kê sẽ dừng bản build khi được nạp, nêu tên kết nối, socket, component và các slot mà socket có khai báo — và, khi tên đó chỉ cách một trong số chúng một lần sửa, nêu slot đó như cách viết có khả năng được dự định. Sau đó, một slot đã được lấp đầy phải tuân theo khai báo riêng của slot trên từng kết nối: một selector mà nhãn của Feature không thỏa mãn sẽ dừng tại mục này, và một slot required bị bỏ trống trên bất kỳ kết nối nào sẽ dừng, nêu tên kết nối đó. Một socket không khai báo slot nào thì không chấp nhận đính kèm nào trên các kết nối của nó, và một socket tùy biến cũng vậy — socket mà Aggregate nối mà Component không khai báo — vì nó không khai báo slot nào cả. Một component do một module con đóng góp cũng tuân theo cùng quy tắc, và kết quả phát hiện trỏ vào chính tài liệu của module con đó. Xem A connection carries an attachment under a name its socket declares no slot for (Một kết nối mang một đính kèm dưới một tên mà socket của nó không khai báo slot nào).

Một kết nối do một Feature vẽ không mang đính kèm nào. Khối uses: riêng của một Feature được đính kèm — trên một component hay trên một subsystem — được viết theo cùng hình dạng nhưng từ chối features: khi tài liệu được nạp. Một thông tin xác thực mà kết nối như vậy cần sẽ lấp đầy một slot mà Feature khai báo trong featuresSchema của chính nó, được đính kèm bên cạnh Feature; xem A Feature’s Own Credential.

Tên mà đính kèm nhận. Mỗi đính kèm của kết nối trở thành một đính kèm của component tiêu thụ, được đặt tên <alias>.<slot> — alias mà kết nối được viết dưới đó, một dấu chấm, và slot: gpt.credential ở trên. Dấu chấm là ký tự phân tách dành riêng cho các tên do trình biên dịch ghép, mà không alias, slot hay tên đính kèm nào trong một Aggregate được chứa, nên tên ghép không bao giờ trùng với một tên được viết trên khối features: riêng của component; một Release viết tên đó trên một component hay một boundary sẽ bị từ chối (xem Per-edge connection configuration). Đó là tên mà tầng theo từng instance của Manifest dùng làm khóa cho đính kèm (xem Flat URI mapping), tên mà các chẩn đoán và đồ thị IR báo cáo nó, và là giá trị mà FeatureRecipe của đính kèm đọc dưới dạng .attachment_name (xem Names derived from a connection’s attachment).

Từ đó nó được phân giải như mọi đính kèm khác: Manifest gắn kiểu Feature của nó với một FeatureRecipe, các values của nó được kiểm tra theo schema của Feature — một lỗi được báo cáo tại mục kết nối đã viết chúng — và FeatureRecipe của nó render theo values và infra riêng của đính kèm. Có hai điểm phân biệt nó với các đính kèm riêng của component:

  • Nó không nằm trong .features của Recipe tiêu thụ. Trụ cột đó chỉ mang các đính kèm được viết trên khối riêng của component, nên một Recipe tìm trong .features các đính kèm của chính nó theo kiểu sẽ không bao giờ nhận được thông tin xác thực của một kết nối. Một Recipe đọc đính kèm của một kết nối từ chính kết nối đó, tại .context.uses.<alias>.features.<slot>, theo hình dạng mà .features mang — bao gồm cả provides đã được phân giải của nó (xem A connection’s attachments).
  • Nó chỉ đặt lên bên tiêu thụ. Đầu ra được render của một đích là như nhau bất kể các kết nối đến nó mang gì.

Bản sao của khối đã viết trong đồ thị. Đồ thị IR giữ khối uses: của mỗi component đúng như đã viết, và ở đó một đính kèm của kết nối giữ type và description của nó và không giữ values nào. Các giá trị xuất hiện một lần, trên đính kèm mà bên tiêu thụ mang, nơi một giá trị mà Feature khai báo là nhạy cảm sẽ bị giữ lại.

Một Release có thể định cỡ một đính kèm được khai báo ở đây bằng infra, hoặc đính kèm một đính kèm của riêng nó trên một kết nối mà nó tác động tới — xem Per-edge connection configuration.

Tắt một component hoặc module: active:

Một instance component và một module sub-aggregate đều chấp nhận một công tắc active: quyết định thực thể đó có thuộc topology đã biên dịch hay không. Nếu bỏ qua nó, thực thể sẽ có mặt; đó là mặc định và là trường hợp thông thường.

spec:
parameters:
enable_cache:
type: boolean
default: false
components:
api:
type: core/server:1.0.0
redis:
type: core/redis:1.0.0
active: "{{ .parameters.enable_cache }}"
aggregates:
reporting:
type: my-catalog/reporting-module:1.0.0
active: false

Hãy viết trực tiếp một giá trị boolean, hoặc một template trên .parameters phân giải thành một giá trị boolean. Dạng template chính là lý do công tắc này tồn tại: nó cho phép một Release quyết định sự có mặt của một thực thể bằng cách đáp ứng một tham số, nhờ đó một Aggregate bao quát được các môi trường khác nhau ở những phần mà chúng triển khai — mà Release không phải khai báo bất cứ điều gì Aggregate chưa khai báo.

Công tắc false loại bỏ những gì. Thực thể bị cắt bỏ trước khi đồ thị được xây dựng, và việc cắt bỏ lan truyền theo tầng: một component kéo theo các cạnh uses: của chính nó và các Features được gắn vào nó, còn một module kéo theo mọi thứ nó đã đóng góp — các component của nó, các cạnh của chúng, các attachment của chúng. Không gì do thực thể bị cắt bỏ mang đến được render. Điều mà việc cắt bỏ không chạm tới là một tham chiếu đến nó từ một nơi vẫn còn tồn tại, đó là nội dung của đoạn tiếp theo.

Một component còn lại mà vẫn trỏ tới một component đã bị loại bỏ sẽ dừng bản build. Nếu api khai báo một cạnh uses: tới redis và redis bị tắt, bản build sẽ dừng lại thay vì để cạnh đó biến mất, vì điều đó sẽ khiến các giá trị được inject của api âm thầm rỗng khi triển khai. Hãy quyết định component nào trong hai component thuộc về môi trường này: bật lại target, đặt consumer phụ thuộc vào cùng tham số đó để cả cặp cùng bị loại bỏ, hoặc bỏ cạnh đó khỏi khối uses: của consumer.

Một toggle đã được viết phải phân giải thành một giá trị boolean, và một giá trị rỗng không phải là boolean. Toggle được đọc một cách nghiêm ngặt sau khi template của nó được phân giải, và một literal không phân tích được thành boolean sẽ dừng bản build thay vì nhận một giá trị mặc định nào đó. Trường hợp cần chú ý là một toggle đọc một tham số không có giá trị: nó phân giải thành rỗng, và việc hiểu rỗng là “có mặt” sẽ triển khai chính thực thể mà bạn đã đặt phụ thuộc vào tham số đó. Vì vậy, viết active: mà không có gì phía sau không giống với việc bỏ khóa đi — chỉ một toggle không ai viết mới mặc định là có mặt. Hãy cho tham số một default: trong spec.parameters để mọi môi trường đều có câu trả lời, hoặc cung cấp giá trị cho nó trong Release. Để một thực thể luôn có mặt vô điều kiện, hãy xóa khóa active: thay vì để trống nó. Việc dừng này được mô tả dưới mục “An active: toggle does not resolve to true or false (Một toggle active: không phân giải thành true hoặc false)” trong tài liệu tham khảo về các điều kiện dừng.

Một component đã bị tắt vẫn có thể được gọi tên từ một Release. Một Release vẫn có thể gọi tên nó trong một boundary, và điều đó là có chủ ý: tắt một component là một hành động soạn thảo, và Release cấu hình nó không bị kỳ vọng phải được viết lại trong cùng một lần chỉnh sửa.

Annotation trên subsystem và component

Cả subsystem và instance component đều có trường annotations:. Các annotation do nhà phát triển viết trên Aggregate điều khiển cascade annotation phía Aggregate — một annotation của subsystem lan truyền tới mọi subsystem lồng bên trong và mọi component được chứa trong đó, với giá trị ở cấp gần hơn ghi đè theo từng khóa. Map mappings.features.annotations của Manifest khai báo các binding chuyển các khóa annotation thành các Feature attachment tổng hợp tại thời điểm build. Bất biến Aggregate-as-Authoring-Surface giới hạn các annotation này chỉ được định tuyến qua các đường dẫn maps.values của binding; một binding chỉ khai báo các đường dẫn maps.infra sẽ kích hoạt từ phía Release, không phải từ phía Aggregate.

Dạng giá trị

Mỗi khóa annotation nhận một trong bốn dạng, phân biệt “tôi không nói gì” với “tôi khai báo một giá trị” — một giá trị vô hướng hoặc một đối tượng có cấu trúc — với “tôi từ chối tham gia”:

  • Khóa vắng mặt — phạm vi không khai báo giá trị nào cho annotation này. Các subsystem lồng bên trong và các component được chứa kế thừa mọi binding từ một phạm vi tổ tiên.
  • Một chuỗi vô hướng — một giá trị duy nhất. Binding của Manifest phải khai báo tổng cộng đúng một đường dẫn; giá trị vô hướng được định tuyến tới đường dẫn đó.
  • Một đối tượng có cấu trúc — một map từ khóa con tới giá trị con. Mỗi khóa con của đối tượng được định tuyến qua maps của binding trong Manifest tới trường schema tương ứng của Feature tại pillar đã khai báo.
  • YAML null tường minh — phạm vi loại bỏ mọi binding kế thừa cho khóa này khỏi cây con của nó. Các component và subsystem anh em vẫn giữ phần kế thừa của chúng; chỉ phạm vi từ chối tham gia mất binding.
spec:
subsystems:
data:
annotations:
feature.myco/db-pool: "shared-pool" # scalar value — propagates to api and worker
components:
api:
type: core/server:1.0.0
# inherits feature.myco/db-pool: "shared-pool"
worker:
type: core/server:1.0.0
annotations:
feature.myco/db-pool: null # opts out for this component only
special:
type: core/server:1.0.0
annotations:
feature.myco/db-pool: "vip-pool" # closer-level override

Giá trị có cấu trúc cho Features nhiều trường

Một Feature có nhiều trường cấu hình được phù hợp với một giá trị annotation có cấu trúc: một khóa annotation mang giá trị cho nhiều trường schema của Feature trong một khai báo. Phía Aggregate chỉ kích hoạt các khóa con có pillar trong binding map là values; các khóa con định tuyến tới infra thuộc về các annotation phía Release.

spec:
subsystems:
data:
annotations:
feature.myco/db-pool:
db_name: "prod-db"
read_replicas: 5
components:
api:
type: core/server:1.0.0
annotations:
feature.myco/db-pool:
db_name: "api-override" # closer-level override at subkey granularity
# read_replicas not listed → inherits 5 from parent
analytics:
type: core/server:1.0.0
annotations:
feature.myco/db-pool:
read_replicas: null # per-subkey opt-out

Giá trị có cấu trúc cascade với deep merge theo từng khóa con: khóa con ở cấp gần hơn ghi đè khóa con của cấp cha; một null tường minh tại một khóa con chặn khóa con kế thừa cho phạm vi đó trong khi các khóa con anh em vẫn giữ nguyên. Để xem toàn bộ hướng dẫn về giá trị có cấu trúc — kết hợp giữa hai phía với các khóa con infra phía Release, kiểm tra kiểu theo từng khóa con, nguyên tắc mặc định nới lỏng cho các trường schema không khai báo type — xem providers/well-known-annotations.md §“Structured annotation values”.

Tính độc lập theo từng khóa

Mỗi khóa annotation kế thừa, ghi đè và từ chối tham gia một cách độc lập. Một component khai báo annotations.feature.myco/db-pool: null chỉ từ chối tham gia khóa đó; các khóa khác kế thừa từ subsystem bao quanh vẫn tiếp tục lan truyền tới component đó. Các component anh em trong cùng subsystem giữ map annotation của riêng chúng một cách độc lập — việc từ chối tham gia của một component không ảnh hưởng tới các component anh em.

Annotation của component cấp cao nhất

Các component cấp cao nhất (khai báo trực tiếp dưới spec.components thay vì bên trong một subsystem) không có cascade kế thừa. Trường annotations: của chúng khai báo giá trị trực tiếp trên phạm vi component; quá trình mở rộng tổng hợp các Feature attachment từ mỗi annotation đã khai báo mà Manifest có binding tương ứng.

Để xem quy tắc cascade phía Aggregate áp dụng cho binding, cách phân chia giữa phía và pillar, cùng một ví dụ đầy đủ từ đầu đến cuối cho thấy các binding chuyển annotation thành các Feature attachment tổng hợp, xem providers/well-known-annotations.md §“Aggregate-side annotation cascade”.

Các mẫu anchor YAML (khối defs:)

Schema của Aggregate chấp nhận một khối defs: tùy chọn ở cấp gốc — một danh sách các chuỗi YAML chỉ dùng làm nơi chứa các anchor YAML tiêu chuẩn (&anchor) và các tham chiếu (*anchor). Trình biên dịch không bao giờ đọc nội dung của khối này; khối tồn tại để tác giả có thể khai báo các định nghĩa anchor ở một chỗ và tham chiếu chúng trong phần còn lại của Aggregate, giúp các giá trị lặp lại tuân theo DRY mà không đánh mất từ điển phẳng O(1) mà trình biên dịch duyệt qua. Cơ chế này tương ứng với khối defs: tương đương trên thực thể Manifest.

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: anchored-app
version: 1.0.0
defs:
- &default_log_level "info"
spec:
components:
primary:
type: core/compute/api-server:1.0.0
values:
log_level: *default_log_level
secondary:
type: core/compute/python:1.0.0
values:
log_level: *default_log_level

Các anchor được phân giải tại thời điểm phân tích cú pháp YAML, nên *default_log_level đã là chuỗi "info" khi trình biên dịch đọc khối values. Theo quy ước, khối defs: là nơi đặt các định nghĩa anchor; YAML cho phép khai báo anchor ở bất kỳ đâu, nhưng đặt chúng cùng một chỗ giúp phần còn lại của Aggregate dễ đọc. Khối này là tùy chọn — các Aggregates không cần anchor thì bỏ hẳn khối này.