Feature
Vai trò khái niệm của thực thể Feature (đặc tính vận hành dạng mô-đun trong Domain 2) được trình bày trong architecture/04-entity-taxonomy.md. Sự phân biệt giữa các Features vận hành và các Features thông tin xác thực (những Feature được gắn nhãn feature.aggrega.ai/kind: secret) được mô tả trong architecture/08-credential-model.md. Bộ từ vựng nhãn ngữ nghĩa mà các bộ chọn Feature sử dụng được trình bày trong entities/component. Trang này đề cập đến bề mặt soạn thảo catalog Feature.
Vị trí trong catalog
Khác với Components (vốn dùng URI ba đoạn với các thư mục con theo danh mục), Features được tổ chức phẳng: mỗi Feature có một thư mục dưới publisher của nó, trong đó chứa một thư mục cho mỗi phiên bản.
aggrega-catalog/└── feature/ └── {publisher}/ # e.g., `core`, `acme` ├── secret-value/ │ └── 1.0.0/ │ └── feature.yaml # feature.aggrega.ai/kind: secret (credential Feature) ├── data-masking/ │ └── 1.0.0/ │ └── feature.yaml └── ...URI OCI: hub.aggrega.ai/feature/{publisher}/{feature-name}:{version} (ví dụ: hub.aggrega.ai/feature/core/data-masking:1.0.0).
Hợp đồng soạn thảo
Features khai báo:
metadata.labels: Dùngfeature.aggrega.ai/kind: secretđể đánh dấu một Feature là Feature thông tin xác thực. Nhãn này là siêu dữ liệu mô tả dành cho tác giả, cho trang catalog và cho các bộ chọn nhãn; không có nhánh nào của trình biên dịch đọc nó, và kết quả mà một lần gắn tạo ra do FeatureRecipe mà Manifest ánh xạ kiểu của nó tới quyết định, chứ không phải do nhãn. Một Feature thông tin xác thực và một Feature thông thường được gắn theo cùng một cách, trên cùng một bề mặt gắn, ở bất kỳ phạm vi nào. Họ thông tin xác thực của thư viện chuẩn được chia theo kết quả:core/secret-valueđưa một giá trị vào đường ống inject;core/referenced-secretđặt tên cho một tài nguyên bí mật có thể tham chiếu (một Kubernetes Secret, một bí mật AWS Secrets Manager, một mục Vault), do đầu ra của FeatureRecipe của nó tạo ra hoặc đã tồn tại sẵn, và khai báo một hợp đồng đầu raschema.provides—name(định vị trung lập với provider của tài nguyên) vàkey(trường dữ liệu bên trong nó) — mà bên tiêu thụ đọc dưới dạng.features.<slot>.provides.<key>để tham chiếu tài nguyên mà không phải suy ra lại tên của nó;core/referenced-secret-sethiện thực hóa một tài nguyên mang một tập khóa dữ liệu do bên gọi cung cấp và chỉ công bố định vị, dành cho bên tiêu thụ có đích đã biết sẵn tên các khóa mà nó đọc;core/secret-providedđể lộ giá trị của một bí mật có sẵn;core/generated-secretkhông tạo ra gì, vì engine đích tự sinh và quản lý thông tin xác thực, nên nó không khai báovalueslẫnprovidesvà các FeatureRecipes của nó chỉ thuần là phần nối dây không render byte nào. Hai trục phân biệt các thành viên: ai cung cấp dữ liệu — tác giả viết nó hoặc chỉ ra nơi lấy nó, hoặc engine đích sở hữu hoàn toàn, như vớicore/generated-secret— và lần gắn mang lại gì: một giá trị được chèn, một tài nguyên có thể tham chiếu, hoặc không render gì cả. Mọi thành viên đều ngang hàng với nhau trên cùng một bề mặt gắn, nên một slot thông tin xác thực luôn được liên kết và điều thay đổi giữa các Releases là thứ liên kết nó. Một Feature thông tin xác thực khai báo hợp đồngschema.providesbuộc mọi FeatureRecipe hiện thực nó phải công bố các khóa đó — nếu không bản build sẽ dừng — vàselectorcủa một slotfeaturesSchemanhắm tới thành viên trong họ mà nó cần.usesSchema(tùy chọn): Khai báo các socket tô-pô mà Feature có thể tiêu thụ (ví dụ: socketpath/keycủa một Feature thông tin xác thực nhắm tới một vault). Xem architecture/13-catalog-and-registry.md §2 về cơ chế Split Schema.schema: Kiểm tra các khốivaluesvàinfracủa lần gắn Feature — ý định nhận thức mà Developer cấu hình trên mỗi lần gắn trong Aggregate (valuesthuộc phạm vi của Developer, và schema của Release cấmvalues:trên các lần gắn Feature) và năng lực mà Operator quyết định theo từng môi trường trong Release (infra). Một trường khai báodefault:vừa được kiểm tra theo, vừa được điền vào trụ cột đã render khi không có gì khai báo nó; xem Phạm vi Feature và hình dạng khai báo. Chấp nhận JSON Schema 2020-12 được biểu diễn bằng cú pháp viết tắt YAML dạng gọn (mặc định; xemvocabulary/compact-form-authoring.md) hoặc bằng YAML JSON Schema đầy đủ, với$ref:liên tài liệu tới các mục SchemaLibrary cho các hình dạng dùng chung (xemvocabulary/cross-document-ref.md). Một lá mang dữ liệu bí mật khai báosensitive: true— các Features thông tin xác thực trong thư viện chuẩn đánh dấu lá chứa dữ liệu và cố ý để các định vị được công bố không đánh dấu, vì tên tài nguyên và khóa dữ liệu đều là công khai. Từ khóa này, và giới hạn của những gì việc khai báo nó đạt được, có tạivocabulary/compact-form-authoring.md“Khai báo một lá là nhạy cảm”.featuresSchema(tùy chọn): Khai báo các slot gắn mà Feature cần cho hoạt động của chính nó — một Feature khai báo slot đúng như một Component, nên một Feature tự nó cần thông tin xác thực (ví dụ API key của một Feature sidecar Datadog) sẽ đặt tên điểm liên kết thay vì dùng tới các slot của Component chủ. Xem Thông tin xác thực riêng của một Feature để thấy một Feature khai báo slot riêng và một FeatureRecipe đọc thứ lấp đầy nó. Mỗi slot chấp nhận cùng các trường như một slotfeaturesSchemacủa Component, với cùng ngữ nghĩa — bao gồm mộtselectortùy chọn (một bộ chọn nhãn kiểu Kubernetes ràng buộc Feature nào có thể lấp đầy slot, tương tự ở cấp slot của bộ chọn socketusesSchema; một lần lấp đầy có nhãn không thỏa mãn nó sẽ dừng, và bộ chọn chỉ được đánh giá dựa trên nhãn của Feature được gắn, không gì khác), mộtsensitivetùy chọn (khai báo rằng bất cứ thứ gì liên kết slot đều xử lý dữ liệu bí mật — một phát biểu về điểm liên kết chứ không về một lần lấp đầy cụ thể nào), và cùng tính mở: khai báo một slot không bao giờ cấm một lần gắn dưới tên mà không slot nào khai báo. Bảng trường đầy đủ, khai báo tính nhạy cảm ở cấp slot và cách nó khác với khai báo của một lá schema, cùng hai hình dạng mà một thực thể khai báo slot được triển khai theo, đều có trong entities/component.md “Attachment Slots”.appliesTo/appliesToAnyOf: Các bộ chọn nhãn kiểm soát những Components nào mà Feature có thể gắn vào. Được engine so khớp nhãn gốc của trình biên dịch đánh giá trong giai đoạn phân tích tĩnh. Xem Gắn dựa trên nhãn bên dưới và architecture/13-catalog-and-registry.md §2 “Kubernetes-Style Selectors” để tham khảo cú pháp bộ chọn.interoperability(tùy chọn): Một khối lồng nhau chứaconflictsWith— các Features mà Feature này không thể cùng đến một component. Bản build dừng trước khi render khi một component cuối cùng mang cả hai, bất kể mỗi cái được gắn ở phạm vi nào. Xem Khốiinteroperabilitybên dưới để có phần giải thích đầy đủ.
Việc render cấu trúc của một Feature được ràng buộc với FeatureRecipe tương ứng, vốn ánh xạ giao diện Feature tới một triển khai hạ tầng cụ thể.
Gắn kết dựa trên nhãn
Hai bộ chọn applies trên schema của Feature kiểm soát những Components nào mà Feature được gắn vào, được đánh giá bởi engine so khớp nhãn gốc của trình biên dịch trong giai đoạn phân tích tĩnh:
appliesTo— một chuỗi bộ chọn nhãn kiểu Kubernetes; bề mặt kết hợp AND. Các yêu cầu phân tách bằng dấu phẩy đều phải thỏa mãn, với đầy đủ bộ toán tử:key=value,key!=value,key in (v1, v2),key notin (v1, v2),keyđứng riêng (nhãn có mặt),!key(nhãn vắng mặt). Một Feature khai báoappliesTo: "datastore.aggrega.ai/engine=vector"chỉ gắn vào các Components được gắn nhãn với đúng cặp khóa-giá trị đó;appliesTo: "component.aggrega.ai/type in (server, worker), compliance.aggrega.ai/data-class notin (restricted)"diễn đạt “bất kỳ server hoặc worker nào không chứa dữ liệu bị hạn chế” trong một chuỗi bộ chọn duy nhất.appliesToAnyOf— bề mặt kết hợp OR. Một danh sách các mục bộ chọn, trong đó chỉ cần một mục bất kỳ khớp là đủ. Mỗi mục hoặc là một bộ chọn dạng chuỗi (cùng ngữ pháp vớiappliesTo; các yêu cầu bên trong chuỗi được kết hợp AND), hoặc là một map khóa-giá trị phẳng để so khớp chỉ theo đẳng thức. Được dùng khi một Feature phù hợp với nhiều dạng component không liên quan — ví dụ, một Feature quan sát áp dụng cho{ component.aggrega.ai/type: worker }HOẶC{ component.aggrega.ai/type: task }mà không buộc hai điều kiện vào một chuỗi bộ chọn duy nhất.
Nếu không có dạng any-of, các Architect sẽ phải sao chép cùng một YAML của Feature cho mỗi dạng component không liên quan mà Feature phù hợp. Hai dạng có thể kết hợp: một Feature có thể khai báo cả hai, và kết quả được kết hợp AND giữa các dạng — chuỗi appliesTo phải thỏa mãn và ít nhất một mục appliesToAnyOf phải khớp. Một bộ chọn bị bỏ qua hoặc rỗng không khai báo ràng buộc nào và khớp với mọi tập nhãn.
Một chuỗi bộ chọn được đọc theo sáu dạng mỗi khi một lần gắn của Feature được đánh giá, và một yêu cầu nằm ngoài các dạng đó sẽ dừng bản build thay vì bị đọc thành một bộ chọn khác: một yêu cầu rỗng (dấu phẩy ở đầu, ở cuối hoặc lặp đôi, hoặc một chuỗi chỉ gồm các dấu phân tách), 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, và một tập in ( hoặc notin ( không được đóng. Đó là điều bắt được những lỗi mà nếu không sẽ âm thầm chọn điều ngược lại với ý định: appliesTo: "!tier=frontend", được viết để giữ một Feature khỏi các frontend, bị từ chối vì ! chỉ đặt tên cho một khóa nhãn và không gì khác — tier!=frontend mới là cách loại trừ một giá trị — và tier in frontend bị từ chối, thay vào đó dùng tier in (frontend). Một giá trị là phần văn bản sau toán tử của nó, bất kể chứa ký tự gì, nên tier==frontend yêu cầu một nhãn có giá trị là =frontend. Thông báo dừng nêu tên Feature, bộ chọn của nó và yêu cầu không thể đọc được. Một Feature không được gắn vào đâu sẽ không bao giờ được đánh giá, nên một bộ chọn sai định dạng trên nó sẽ không được báo cáo cho đến khi có một lần gắn nêu tên nó.
Xem architecture/13-catalog-and-registry.md §2 “Kubernetes-Style Selectors” để tham khảo cú pháp bộ chọn — ngữ pháp mà một bộ chọn của Feature chấp nhận cũng chính là ngữ pháp mà các bộ chọn socket usesSchema chấp nhận, dạng chuỗi mà người dùng Kubernetes quen thuộc từ kubectl get -l.
Khối interoperability
Schema của Feature khai báo một khối spec.interoperability tùy chọn, chứa một tham số điều khiển: những Features nào khác mà Feature này có thể cùng tồn tại trên một component.
interoperability.conflictsWith — danh sách các Features loại trừ lẫn nhau với Feature đang được định nghĩa, mỗi mục được viết theo cách mà type của một attachment gọi tên một Feature. Nó ngăn việc sinh ra các cấu hình không tương thích — chẳng hạn gắn cả một mesh chỉ hỗ trợ TCP lẫn một proxy hiểu HTTP vào cùng một component.
Bản build dừng lại trước khi render bất cứ thứ gì khi một component rốt cuộc mang cả Feature này lẫn một Feature mà danh sách của nó gọi tên. Điều được tính là phạm vi với tới: một attachment với tới component mà nó được viết trên đó, và mọi component bên trong subsystem hoặc boundary mà nó được viết trên đó, kể cả các boundary lồng nhau; một attachment được viết trên một mục component của Release, hoặc được tạo ra bởi việc mở rộng dựa trên annotation, cũng với tới component của nó theo cùng cách. Vì vậy, một xung đột đã khai báo sẽ dừng build khi hai Features được gắn vào cùng một component, khi một cái nằm trên một boundary và cái kia trên một component bên trong nó, khi một cái nằm trên một boundary bên ngoài và cái kia trên một boundary lồng bên trong có chứa một component, và khi một cái nằm trên một subsystem và cái kia trên một component trong subsystem đó. Hai Features được gắn vào các boundary anh em không có chung component nào thì không bao giờ gặp nhau, và một boundary không chứa component nào thì không với tới gì cả — cả hai trường hợp đều không dừng build.
- Một khai báo là đủ. Bản build dừng lại khi danh sách của một trong hai Feature gọi tên Feature kia; Feature thứ hai không cần liệt kê ngược lại Feature thứ nhất.
- Chỉ tên, bất kể phiên bản. Mỗi mục và type của mỗi attachment được so sánh sau khi bỏ đi phiên bản, nên một mục
core/fixed-replica-controllerkhớp với một attachmentcore/fixed-replica-controller:2.0.0, và một mục có mang phiên bản khớp với mọi phiên bản của Feature mà nó gọi tên. - Chỉ đọc tên. Trình biên dịch so sánh các tên mà tác giả của Feature đã khai báo với các Features mà một component mang — cùng loại đánh giá như
appliesTo, trên dữ liệu do tác giả viết. Việc hai Features có không tương thích hay không là đánh giá của tác giả, và danh sách là nơi ghi lại đánh giá đó.
Thông báo dừng nêu tên Feature có danh sách gọi tên Feature kia, mọi nơi mà mỗi Feature trong hai Feature được gắn vào — trên component trong Aggregate, trên một subsystem, trên một boundary của Release cùng đường dẫn của nó, trên một mục component của Release, hoặc qua việc mở rộng dựa trên annotation của một annotation có tên — và component nơi chúng gặp nhau. Một cặp gặp nhau trên nhiều component được báo cáo một lần cho mỗi component. Xem errors/fatal-halts.md để biết thông báo.
Ví dụ:
apiVersion: aggrega.ai/v1beta1kind: Featuremetadata: name: core/autoscaler version: 1.0.0spec: appliesTo: "component.aggrega.ai/type=server" schema: values: metric_target: { type: string, enum: [cpu, memory, custom], required: true } infra: min_replicas: { type: integer, min: 1, required: true } max_replicas: { type: integer, min: 1, required: true } interoperability: conflictsWith: - core/fixed-replica-controllerFeature này chỉ gắn vào các Components có kiểu server và khai báo không tương thích với một Feature điều khiển replica khác: một bản build mà trong đó bất kỳ component nào rốt cuộc mang cả hai sẽ dừng lại trước khi render. Một FeatureRecipe cần tên của component mà nó được gắn vào — chẳng hạn để trỏ một autoscaler tới mục tiêu của nó — đọc tên đó từ ngữ cảnh template của mình và ghi nó vào bất cứ đâu đầu ra cần: .context.instance_id là định danh của component, và .context.rendered_name là tên mà provider riêng của component đặt cho các tài nguyên nó render cho component đó, và đây là tên dùng để nhắm tới một tài nguyên — với helm, đó là tên của Deployment mà một workload được tổng hợp phát ra, và là tên release mà một chart dùng để tạo các tên của riêng nó.
Kế thừa qua extends
Một Feature có thể khai báo spec.extends: <feature-name> trỏ đến một Feature cơ sở mà nó kế thừa bề mặt soạn thảo. Tham chiếu này gọi tên Feature cơ sở bằng metadata.name của nó, không phải bằng tọa độ registry mà Feature được phát hành dưới đó, và nhận cùng ba dạng phiên bản mà mọi tham chiếu catalog đều nhận: dạng trần (core/queue) cho bản phát hành cao nhất hiện có, dạng chính xác (core/queue:1.0.0), hoặc một khoảng caret (core/queue:^1.0.0). Trình biên dịch duyệt chuỗi cha khi nạp catalog, xác thực rằng chuỗi không có chu trình, rồi hợp nhất các spec cha vào con để tạo ra một Feature đã phân giải duy nhất. Các trường do con soạn được ưu tiên khi trùng khóa; metadata.labels và metadata.annotations của cha, các bộ chọn appliesTo / appliesToAnyOf, khối interoperability, usesSchema, featuresSchema, và các khai báo JSON Schema 2020-12 trên schema được tự động hợp nhất xuống dưới. Mọi trường metadata khác là của con, giữ nguyên văn, nên danh tính và nguồn gốc không bao giờ được kế thừa.
Những gì metadata: của một Feature kế thừa. labels và annotations hợp nhất theo từng khóa dọc theo chuỗi, cơ sở trước, với giá trị của Feature mở rộng thắng khi trùng khóa — cùng quy tắc mà Components tuân theo. Phần còn lại của metadata: không được truyền: name, version, description, maintainers, license, repository, home và keywords là của riêng Feature mở rộng, đúng như đã soạn.
# Base Feature — generic message queue intentapiVersion: aggrega.ai/v1beta1kind: Featuremetadata: name: core/queue version: 1.0.0spec: appliesTo: "component.aggrega.ai/type=worker" schema: values: qos: { type: string, enum: [at-most-once, at-least-once, exactly-once], required: true } infra: partition_count: { type: integer, min: 1 }
---# Child Feature — Kafka-specialized variantapiVersion: aggrega.ai/v1beta1kind: Featuremetadata: name: core/kafka-queue version: 1.0.0spec: extends: core/queue:1.0.0 schema: values: compression_codec: { type: string, enum: [none, gzip, snappy, lz4], default: none }core/kafka-queue sau khi hợp nhất kế thừa appliesTo từ cha, kế thừa các thuộc tính values.qos và infra.partition_count, và thêm values.compression_codec lên trên. Một con khai báo tường minh appliesTo sẽ ghi đè toàn bộ bộ chọn của cha (việc hợp nhất bộ chọn nhãn không sâu — bộ chọn của con thay thế bộ chọn của cha). schema.values.qos của một con ghi đè khai báo của cha cho thuộc tính đó.
Cách từng phần của bề mặt gắn kết được kế thừa. Hai dạng bộ chọn được kế thừa độc lập với nhau, vì chúng kết hợp chứ không thay thế nhau: mỗi dạng có mặt đều phải thỏa — chuỗi appliesTo phải khớp, và ít nhất một mục appliesToAnyOf phải khớp — còn một dạng vắng mặt thì không ràng buộc gì. Vì vậy một Feature có thể nhận bộ chọn AND của cơ sở trong khi khai báo một tập OR của riêng nó. Khối interoperability được kế thừa theo từng trường — một con khai báo khối mà không có danh sách conflictsWith vẫn mang danh sách mà cơ sở đã khai báo, còn một con khai báo conflictsWith của riêng nó thì thay thế danh sách của cơ sở chứ không bổ sung vào. Một Feature không khai báo cái nào trong ba thứ trên sẽ gắn đúng ở nơi cơ sở của nó gắn.
Kế thừa là hợp nhất schema, không phải ràng buộc giao diện. Một chuỗi extends: của Feature tạo ra một Feature đã phân giải, không phải một họ đa hình. URI của Feature cơ sở trong chuỗi không phải là thứ mà trường feature: của một ràng buộc Manifest tham chiếu — Manifests ràng buộc theo URI của Feature lá, và schema đã phân giải bao gồm các thuộc tính được kế thừa. Hợp đồng Feature mà một FeatureRecipe implements: cũng là URI lá; FeatureRecipes không duyệt chuỗi kế thừa.
aggrega pull tải thực thể cơ sở. Một Feature cơ sở là phụ thuộc của mọi Release gắn một Feature 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 Feature nêu tên nó; một bản build đọc thực thể cơ sở từ đó.
Các chế độ lỗi. Một chuỗi extends: vòng lặp, và một cha mà không entity catalog nào cung cấp, sẽ dừng bản build, nêu tên Feature mà việc phân giải bắt đầu từ đó, Feature có dòng extends: cần mở, và tham chiếu mà nó khai báo. Các thông báo có tại Cyclic extends on Components or Features (extends vòng lặp trên Component hoặc Feature) và An extends: chain cannot be assembled (Không thể lắp ráp chuỗi).
Để biết bộ từ vựng rộng hơn về kế thừa / giao diện trên Components, Features và các Features thông tin xác thực, xem vocabulary/inheritance-and-interface.md.
Khả năng kết hợp: khế ước xã hội về tính thuần nhất
Quy ước của thư viện chuẩn là một Feature, một chức năng nội bộ — một sidecar quan sát là một Feature quan sát; một sidecar proxy mạng là một Feature proxy mạng; chúng không gộp thành một thực thể tổng hợp duy nhất mang hai mối quan tâm không liên quan. Quy ước này giữ cho từng Features có thể kết hợp, được đánh phiên bản độc lập và gắn kèm độc lập.
Trình biên dịch Go lõi không thực thi quy ước này. Các định nghĩa Feature có các mối quan tâm lẫn lộn vẫn hợp lệ về cú pháp và biên dịch không lỗi. Việc thực thi là tùy chọn tham gia:
- Các doanh nghiệp xây dựng catalog nội bộ có thể viết một plugin linter tùy chỉnh để kiểm tra các định nghĩa Feature trong CI/CD và cảnh báo khi các nhãn
appliesTocủa một Feature trải rộng trên các miền năng lực không liên quan. - Một tác giả Feature ghi lại, trong
interoperability.conflictsWith, rằng hai Features sẽ chồng lấn thì sẽ tham gia vào một bước kiểm tra tại thời điểm build: trình biên dịch dừng lại ở bất cứ đâu hai Features đó cùng đến một component. Nó chỉ so sánh các tên được khai báo và không gì hơn, vì vậy nó thực thi khai báo mà tác giả đã viết chứ không phải bản thân quy ước về tính thuần nhất.
Các Features của thư viện chuẩn mã nguồn mở tuân theo quy ước về tính thuần nhất nhờ kỷ luật khi viết; các catalog doanh nghiệp được tự do đi chệch khi một thực thể tổng hợp gắn kết chặt chẽ thực sự phù hợp với mô hình triển khai.
Điều gì xứng đáng là một Feature, và nút điều chỉnh riêng của một sản phẩm thuộc về đâu
Một Feature là một phần đính kèm: nó mang đến thứ mà nhà phát triển hoặc người vận hành chủ ý đính kèm — tài nguyên, một bước pipeline, phần kết nối — và quy ước của thư viện chuẩn là nó phải được ít nhất hai sản phẩm độc lập đáp ứng. Nửa sau đó chính là phép thử cần áp dụng trước khi viết một Feature, vì tính khả chuyển là điều mà từ phần đính kèm hứa hẹn. Một phần đính kèm nói rằng năng lực đó đi theo: đính kèm nó vào một component, đính kèm nó vào một component khác, và phần hiện thực hóa của mỗi sản phẩm đáp ứng nó theo cách riêng của mình.
Một năng lực mà chỉ một sản phẩm trên thực tế có là nút điều chỉnh riêng của sản phẩm đó chứ không phải một Feature. Nó thuộc về một giá trị được viết trên bề mặt riêng của sản phẩm đó, do tác giả quyết định nó đặt trong trụ cột của chính tác giả ấy và đọc bên cạnh mọi thứ khác cấu hình cùng sản phẩm. Thay vào đó, việc công bố nó thành một Feature sẽ hứa hẹn một tính khả chuyển mà không sản phẩm nào khác có thể mang lại: theo cấu trúc, phần đính kèm chỉ gọi tên một sản phẩm, nên tác giả nào đính kèm nó vào sản phẩm tiếp theo họ dùng sẽ gặp một bản build dừng lại và nêu tên kiểu, và Feature đó đã dạy một năng lực mà nó chưa từng có.
Phép thử đếm các sản phẩm trên thực tế, không phải các component trong catalog này, mỗi sản phẩm được đọc từ tài liệu tham chiếu cấu hình hiện hành của chính nó. Hai sản phẩm độc lập hiện thực một năng lực là đủ để năng lực đó khả chuyển, bất kể có bao nhiêu sản phẩm trong số đó được cung cấp ở đây, nên một Feature có thể được khai báo trước khi bất kỳ thứ gì trong catalog hiện thực hóa nó — khi đó việc đính kèm nó sẽ dừng bản build và nêu tên kiểu — và mỗi phần hiện thực hóa được cung cấp là một FeatureRecipe cho một sản phẩm, đáp ứng phần đính kèm theo bất kỳ cách nào mà sản phẩm đó cấu hình nó.
Ghim chứng chỉ upstream là ví dụ minh họa. Một phép ghim là một biện pháp kiểm soát khóa mà một upstream được phép xuất trình: chỉ chấp nhận chứng chỉ có khóa công khai khớp với một khóa mà Release cung cấp. Đó là một khẳng định khác với việc yêu cầu chứng chỉ của upstream phải nối chuỗi tới một trust anchor mà Release cung cấp, và lại khác với việc khẳng định nội dung subject của chứng chỉ — cả hai điều đó nêu chứng chỉ phải nói gì, còn phép ghim nêu chứng chỉ phải là khóa nào. Nhiều gateway ở đây có thể xác minh dựa trên một anchor, đó là lý do dataplane.aggrega.ai/upstream-tls: trust-anchor là một giá trị mà selector có thể khớp. Ghim là một năng lực riêng, và ít nhất hai sản phẩm độc lập hiện thực nó cho các kết nối chúng mở tới upstream: Tyk nhận khóa công khai của upstream ở dạng PEM, còn Envoy nhận một giá trị băm của khóa đó. Vì vậy nó là một Feature, core/upstream-key-pinning, có selector gọi tên dataplane.aggrega.ai/upstream-pinning: public-key, và việc catalog này hiện thực hóa những gì được trả lời theo từng sản phẩm: core/gateway/tyk mang giá trị đó và một FeatureRecipe cho mỗi target của nó, còn các gateway ở đây nhúng Envoy chỉ để lộ thiết lập ghim của Envoy cho các chứng chỉ mà client xuất trình, hoặc hoàn toàn không, nên chúng không mang giá trị đó và một phần đính kèm vào chúng sẽ dừng tại selector. Phép ghim thu hẹp những gì một upstream được phép xuất trình; nó là một biện pháp kiểm soát, không phải sự bảo đảm rằng kết nối an toàn về mọi mặt khác.
Hai giới hạn của phép thử, và giới hạn thứ hai là nửa dễ bị bỏ qua nhất:
- Đây là kỷ luật khi viết, không phải một bước kiểm tra của trình biên dịch. Một Feature khai báo các tùy chọn mà không sản phẩm nào hiện thực vẫn vượt qua kiểm tra schema, linter công bố và cả quá trình render — trình biên dịch không diễn giải những gì một Feature hứa hẹn. Việc phán đoán vẫn thuộc về tác giả catalog.
- Việc một sản phẩm không thể đáp ứng một tùy chọn không phải là lý do để bỏ tùy chọn đó. Khi hai sản phẩm trở lên cung cấp một năng lực dưới các tên có thể gộp nhóm, năng lực đó là khả chuyển và Feature giữ lại nó; sản phẩm không thể đáp ứng thì từ chối nó. Một Feature bị thu hẹp chỉ còn những gì mọi sản phẩm đều hỗ trợ thì gần như chẳng còn gì để nói.
Phạm vi của Feature và hình dạng khi soạn thảo
spec.schema của một Feature định nghĩa các hình dạng values: và infra: của chính Feature — ý định nhận thức mà Developer cấu hình cho mỗi lần gắn Feature trong Aggregate (values), tách biệt với các con số về dung lượng mà Operator quyết định cho từng môi trường (infra). Các trụ cột của Feature nằm trong không gian tên riêng và được xác thực độc lập với các trụ cột của Component chủ. Khi Developer gắn một Feature autoscaler vào một Component web-server trong Aggregate, Aggregate mang values: của Component (hình dạng của chủ) cộng với values: của Feature (hình dạng ý định mở rộng quy mô — chỉ số nào điều khiển việc mở rộng); các con số dung lượng dành cho operator (min_replicas / max_replicas) đi qua khối infra: của Release trên lần gắn Feature.
# Aggregate fragment — Feature attachment with its own values:components: web-server: type: core/web-server values: log_level: "info" # the Component's own values tls_enabled: true features: autoscaler: type: core/autoscaler values: metric_target: "cpu" # the Feature's own values (dev intent: scale on CPU)# Release fragment — Feature attachment's infra block (operator-side capacity):boundaries: prod: components: web-server: features: autoscaler: infra: min_replicas: 2 max_replicas: 10schema: của Feature xác thực các khối values: và infra: riêng của lần gắn Feature. schema: của Component xác thực các khối của riêng Component. Hai thứ này được đánh giá độc lập ở giai đoạn phân tích tĩnh; một trụ cột của lần gắn không khớp với schema: của Feature sẽ dừng bản build với một lỗi có phạm vi tại vị trí gắn Feature, không phải tại Component chủ. Thứ được xác thực là cấu hình hiệu lực của lần gắn — kết quả của việc kết hợp mọi phạm vi đã cấu hình nó — nên một giá trị được làm cho hợp lệ ở một phạm vi rồi bị ghi đè thành giá trị không hợp lệ ở một phạm vi hẹp hơn vẫn bị phát hiện.
Các giá trị mặc định được khai báo sẽ hiện thực hóa vào các trụ cột được render của lần gắn. Ngoài việc xác thực, một default: được khai báo trên một trường values hoặc infra của Feature sẽ được điền vào trụ cột được render của lần gắn đó tại thời điểm build cho mọi khóa không có gì được soạn — nên một template của FeatureRecipe đọc {{ .infra.tier }} sẽ nhận giá trị do schema khai báo thay vì giá trị rỗng. Các giá trị do tác giả cung cấp luôn thắng, và giá trị mặc định chỉ điền các khóa họ bỏ qua: một lần gắn soạn một khóa của schema của Feature vẫn nhận các giá trị mặc định đã khai báo cho các khóa khác của schema đó, và một đối tượng lồng nhau được soạn một phần giữ lại những gì đã viết và nhận thêm các phần tử anh em chưa được viết.
Ba đặc tính của việc điền giá trị đáng biết khi soạn thảo:
- Giá trị mặc định không bao giờ thay thế một giá trị mà bất kỳ phạm vi nào đã cung cấp. Khi một Feature được gắn ở nhiều phạm vi — ví dụ một ranh giới Release và một trong các component của nó — giá trị của phạm vi hẹp hơn được giữ nguyên và giá trị mặc định chỉ điền những gì không phạm vi nào viết.
- Giá trị mặc định điền vào một lần gắn; nó không bao giờ tạo ra lần gắn. Khai báo giá trị mặc định trên một Feature không được gắn ở đâu sẽ không đóng góp gì vào đầu ra, nên schema của một Feature không thể thêm cấu hình mà không tác giả nào yêu cầu.
- Một lần gắn được khai báo trên ranh giới Release thay vì trên một component đơn lẻ chỉ điền
infra, vì bề mặt đó không mang khốivalues:nào để điền.
Vì việc hiện thực hóa dùng cùng cách phân giải schema như việc xác thực, một giá trị mặc định được khai báo trên Feature cha sẽ đến được các lần gắn của Feature con dùng extends:, và các giá trị mặc định đạt được qua một $ref: liên tài liệu vào một SchemaLibrary cũng được hiện thực hóa. 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.
Có một hệ quả đáng nói rõ, vì chỉ riêng việc xác thực sẽ không cho thấy nó: một trường required: đồng thời mang default: được thỏa mãn bởi giá trị mặc định đó, nên việc bỏ qua nó là hợp lệ — và giá trị mà việc kiểm tra đã chấp nhận chính là giá trị mà đầu ra được render mang theo.
Ngữ cảnh template của trình biên dịch cung cấp trạng thái thể hiện của Feature cho FeatureRecipe được gắn kết thông qua trường .features.<alias> (chứa .type, .resolved_version, .labels, .values, .infra và .provides cho mỗi lần gắn). Các template bên trong FeatureRecipe đọc values: riêng của Feature qua .values.<field> ở phạm vi template riêng của FeatureRecipe; values: của Component chủ không hiển thị trực tiếp cho các template của FeatureRecipe, trừ khi Feature khai báo tường minh một socket uses: tới Component chủ.
Sự tách biệt phạm vi này giúp các Features có thể kết hợp: một Feature autoscaler không phụ thuộc vào việc nó được gắn vào Component nào; schema: của nó mô tả ý định tự động co giãn bất kể Component chủ là gì. values: của Component chủ là việc của Component chủ; values: của Feature là việc của Feature; hai trụ cột kết hợp với nhau mà không làm rò rỉ tên trường qua ranh giới.
Đích của annotation binding
Một Feature không tự khai báo các annotation binding; map mappings.features.annotations của Manifest mang chúng. Một Feature tham gia vào quan hệ binding một cách gián tiếp với vai trò đích định tuyến: mỗi binding chỉ định một loại Feature qua trường feature:, và các danh sách maps.infra và maps.values của binding khai báo các đường dẫn dạng dấu chấm trỏ vào các thuộc tính spec.schema.infra.<path> và spec.schema.values.<path> của Feature được chỉ định.
Khi tải catalog, trình biên dịch kiểm tra rằng mọi đường dẫn dạng dấu chấm trong các danh sách maps của một binding đều tương ứng với một thuộc tính mà spec.schema của Feature đích thực sự khai báo tại trụ cột được chỉ định. Một binding định tuyến tới một đường dẫn mà schema của Feature không khai báo sẽ dừng việc tải catalog với một OPS_ERROR rõ ràng, nêu tên binding, Feature đích, cùng trụ cột và đường dẫn mà nó định tuyến qua — binding được viết trong Manifest, vốn là tài liệu của operator. Do đó, tác giả schema biết rằng mọi thuộc tính họ khai báo dưới spec.schema.values.<path> hoặc spec.schema.infra.<path> đều có thể dùng làm đích của binding; ngược lại, mọi thuộc tính mà một binding trong Manifest định tuyến qua phải tồn tại trong schema của Feature đích.
Khi một annotation phía Aggregate hoặc phía Release khớp với một binding, trình biên dịch tổng hợp một Feature attachment có các payload trụ cột định tuyến giá trị annotation vào các đường dẫn được chỉ định. Attachment được tổng hợp không thể phân biệt về mặt cấu trúc với một Feature attachment do tác giả khai báo tường minh tại cùng vị trí; việc render ở các bước sau, việc kiểm tra hợp lệ và ngữ cảnh template của FeatureRecipe đều xử lý cả hai dạng như nhau. Về dạng của binding, cách phân chia phía và trụ cột, và nguyên tắc attachment tường minh được ưu tiên, xem entities/manifest.md §“Annotation-Driven Feature Bindings”. Về quy tắc lan truyền phía Aggregate và ví dụ soạn thảo, xem providers/well-known-annotations.md §“Aggregate-side annotation cascade”.
Khối assertions:
Feature.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 Feature — các quy tắc liên trường trên values: của Feature và trạng thái đã phân giải của Component được gắn. 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 sau khi xác thực schema và trước khi FeatureRecipe được liên kết kết xuất, theo thứ tự chúng được viết, và quy tắc đầu tiên thất bại sẽ dừng bản dựng với thông báo lỗi riêng của quy tắc đó.
spec: appliesTo: "component.aggrega.ai/type=server" assertions: active-active-needs-two-replicas: | {{- if and (eq .values.mode "active-active") (lt .values.replicas 2) -}} {{- fail "mode=active-active requires replicas >= 2" -}} {{- end -}}Giống như các assertion của Component, các assertion của Feature biểu đạt các bất biến ở cấp hợp đồng — những thuộc tính mà việc gắn Feature phải thỏa mãn bất kể FeatureRecipe nào triển khai việc kết xuất. Với các quy tắc liên trường phụ thuộc vào cách triển khai cụ thể (một yêu cầu của plugin Wasm, một đặc điểm riêng của chart), hãy dùng trường assertions: của FeatureRecipe thay thế. Để biết đầy đủ ngữ pháp soạn thảo, ngữ cảnh template và sự phân chia trách nhiệm giữa các assertion của Feature và FeatureRecipe, xem templates/assertions-block.md.