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.

Một wrapper được phát hành, được phục vụ bởi Recipe của base

Ví dụ này dạy một điều: một Component extends một Component khác sẽ kế thừa toàn bộ hợp đồng dữ liệu của base đó, nên mọi Recipe viết cho base đều đã triển khai Component mở rộng. Vì vậy, phát hành một biến thể chuyên biệt của một component thuộc thư viện chuẩn chỉ tốn một thực thể catalog và một dòng Manifest — không cần Recipe riêng, và không thay đổi gì ở base.

Wrapper ở đây là example/gateway/nginx-reviewed. Nó được phân phối trong catalog bên cạnh core/gateway/nginx, component mà nó mở rộng.

Wrapper thêm gì, và kế thừa gì

Toàn bộ phần được viết của wrapper là metadata cộng với một socket:

metadata:
name: example/gateway/nginx-reviewed
labels:
component.aggrega.ai/type: server
component.aggrega.ai/category: gateway
gateway.example.com/audit-tier: reviewed # added
gateway.example.com/data-zone: eu-west # added
annotations:
governance.example.com/review-board: platform-architecture # added
governance.example.com/contact: platform-architecture@example.com
spec:
extends: core/gateway/nginx:1.0.0
schema: inherited
usesSchema:
reviewed_upstream: # added
selector: "gateway.example.com/audit-tier=reviewed"
inject: [env]

schema: inherited là dấu hiệu nguyên văn mà một Component mở rộng viết thay cho một khối schema:. Nó khẳng định rằng ba trụ cột dữ liệu — values, infra và provides — là của base, đúng như base đã viết. Wrapper không khai báo khóa trụ cột nào của riêng mình và cũng không thể: hợp đồng thuộc về base, ở mọi độ sâu của một chuỗi.

Mọi thứ wrapper không nhắc đến, nó đều kế thừa. aggrega inspect example/gateway/nginx-reviewed --resolved hiển thị thực thể đã hợp nhất, và có hai điều trong đó đáng đọc kỹ:

  • Ba socket uses, không phải một: upstream và guard (của base, trong đó upstream chọn component.aggrega.ai/type=server) và reviewed_upstream (của wrapper). Việc mở rộng thêm một socket; nó không thay thế cả tập hợp.
  • Ba trụ cột của base, nguyên văn — values.upstream_path, infra.port / engine_version / compute / overrides, và provides.host / port / protocol, mỗi mục kèm mô tả riêng của base.

Một Aggregate sử dụng viết gì

aggregate-reviewed.yaml khai báo hai tầng gateway là wrapper, đứng trước một console cơ sở dữ liệu:

components:
edge:
type: example/gateway/nginx-reviewed
values:
upstream_path: /api/ # declared by the base; the wrapper never mentions it
uses:
reviewed_upstream: # the socket the wrapper ADDS
internal: { target: internal, inject: { env: [ ... ] } }
internal:
type: example/gateway/nginx-reviewed
values:
upstream_path: /
uses:
upstream: # the socket the wrapper INHERITS
console: { target: console, inject: { env: [ ... ] } }
console:
type: core/devtool/adminer

upstream_path là khóa cần chú ý. Nó được khai báo trong pillar values của core/gateway/nginx và không xuất hiện ở đâu trong tệp của wrapper, vậy mà tác giả vẫn viết nó trên một instance của wrapper và nó đi đến tận cấu hình gateway được render. Đó là ý nghĩa thực tế của việc kế thừa trọn vẹn các pillar.

Manifest là nửa còn lại, và mỗi type là một dòng:

mappings:
components:
type:
example/gateway/nginx-reviewed:1.0.0: compose/nginx:1.0.0
core/gateway/nginx:1.0.0: compose/nginx:1.0.0
core/devtool/adminer:1.0.0: compose/adminer:1.0.0

Cả hai dòng gateway đều chỉ định cùng một Recipe. compose/nginx khai báo implements: core/gateway/nginx:1.0.0, và một Recipe chỉ định một base là phần triển khai cho mọi Component mở rộng base đó — nên wrapper được nó phục vụ mà không cần thay đổi. Ở đây có hai sự thật cùng đúng, và chúng tách biệt:

  • Recipe khớp. Không tồn tại Recipe nào triển khai type riêng của wrapper, và cũng không cần.
  • Ánh xạ vẫn bắt buộc. Việc chọn Recipe dựa trên khóa ánh xạ chính xác, nên wrapper cần mục type riêng; nó không kế thừa mục của base. Một instance của wrapper không có mục riêng sẽ dừng với chẩn đoán unmapped-instance ngay cả khi base của nó đã được ánh xạ.

Tạo ví dụ

Bạn có thể build ví dụ này bằng các lệnh bên dưới, hoặc để trợ lý AI của bạn build giúp bạn.

Ghi ví dụ vào một thư mục mới đặt theo tên của nó:

Terminal window
aggrega scaffold --example extends-wrapper

Sau đó nó in ra các lệnh cần chạy tiếp theo. Lệnh đầu tiên chuyển vào thư mục mới:

Terminal window
cd extends-wrapper

Build

Terminal window
aggrega build --release release-reviewed.yaml --auto-pull

Đầu ra được render và lockfile được sinh ra, không được phân phối kèm: ví dụ này commit các đầu vào và sinh lại mọi thứ khác. --auto-pull phân giải lockfile trong quá trình build; chạy aggrega pull --release release-reviewed.yaml một lần trước đó cũng làm điều tương tự và cho phép các lần build sau chạy mà không cần flag nào.

Cả wrapper lẫn base mà nó mở rộng đều nằm trong catalog dùng chung, được phân giải từ hub.aggrega.ai, registry mặc định mà .aggrega-config.yaml khai báo. Lệnh build không cần flag --catalog, và aggrega inspect chạy từ thư mục này cũng vậy.

Thao tác pull tải về core/gateway/nginx vì wrapper mở rộng nó: một base là phụ thuộc của mọi thứ mở rộng nó, nên thao tác pull đi theo extends: của wrapper và ghim base vào lockfile, dù Manifest có nêu tên nó hay không. Manifest ở đây ánh xạ base vì một lý do khác — bản phát hành đối chứng bên dưới khai báo một instance của chính base đó.

Tệp dist/compose/docker-compose.yaml được render chứa bằng chứng:

edge:
image: nginx:1.27.5-alpine
entrypoint:
- /bin/sh
- -c
- echo 'server { listen 8080; location /api/ { proxy_pass http://internal:8081; } }' > /etc/nginx/conf.d/default.conf && exec nginx -g 'daemon off;'
[… omitted: the published port]
labels:
[… omitted: the other provenance labels every rendered document carries]
aggrega.ai/recipe-uri: nginx:1.0.0
[… omitted: the service's network, its depends_on naming internal, and its healthcheck]

Ba điểm cần đọc, theo thứ tự những gì chúng chứng minh:

  • aggrega.ai/recipe-uri: nginx:1.0.0 — Recipe của base đã định hình service này. Nhãn nguồn gốc trên một instance của wrapper ghi tên Recipe của base vì đó là Recipe đã render nó.
  • location /api/ — values.upstream_path, một khóa chỉ base khai báo, được viết trên một instance của wrapper và được render.
  • proxy_pass http://internal:8081 — cạnh reviewed_upstream đã được phân giải. provides.host và provides.port của đích đến được đưa vào ngữ cảnh injection dưới các khóa phân phối mà Recipe của base đọc, nên một socket do wrapper thêm vào đi qua một Recipe chưa từng biết đến nó.

Lockfile mà quá trình build phân giải ghi nhận cùng sự thật đó từ phía resolver: một mục compose/nginx:1.0.0 tại một digest, được tham chiếu từ cả hai khóa ánh xạ — type của base và type của wrapper.

Các label và annotation của wrapper đi cùng cạnh đã phân giải: ngữ cảnh render của một node sử dụng mang theo provides, labels và annotation của từng đích đến, nên ngữ cảnh của edge biết upstream của nó là audit-tier=reviewed và ai đã review nó. Việc những thông tin đó có xuất hiện trong artifact được render hay không là lựa chọn của Recipe — các label và annotation này là danh tính component để selector và policy đọc, không phải đầu ra mà compiler đóng dấu vào.

Với trợ lý AI

Một trợ lý AI được thiết lập với các công cụ của Aggrega cũng có thể làm như vậy: hãy dán prompt này vào trợ lý.

Chỉ sử dụng các công cụ của Aggrega và không tự tạo thư mục nào. Nếu thư mục không gian làm việc chưa chứa thư mục `extends-wrapper`, hãy gọi công cụ `scaffold` một lần với `example` đặt thành `extends-wrapper` và không có `dir`: công cụ này ghi ví dụ vào một thư mục `extends-wrapper` mới. Sau đó gọi công cụ `build` với `workspace_root` đặt thành `extends-wrapper`, `release` đặt thành `release-reviewed.yaml`, `auto_pull` đặt thành true và `write` đặt thành true. Hãy cho tôi biết lần build đã ghi những tệp nào; chúng nằm trong `extends-wrapper/dist/`.

Đối chứng: label được thêm vào dùng để làm gì

aggregate-unreviewed.yaml là aggregate-reviewed.yaml với một chỉnh sửa — tầng internal được khai báo là base core/gateway/nginx trần thay vì wrapper — và nó được dự kiến sẽ thất bại:

Terminal window
aggrega build --release release-negative-unreviewed.yaml --auto-pull
# [DEVELOPER_ERROR E0007] aggregate-unreviewed.yaml at .spec.components.edge.uses.reviewed_upstream.internal
# selector violation ("gateway.example.com/audit-tier=reviewed", declared on socket "reviewed_upstream", not satisfied by the labels of "internal"). Add the labels the selector requires to the target's component type, or wire the socket to a component that already carries them.

Việc dừng lại chính là bài học. Base thỏa mãn socket upstream của chính nó — nó là component.aggrega.ai/type=server, và tầng internal được nối qua socket đó theo đúng cách như vậy — nhưng nó không mang label audit-tier, nên socket chặt chẽ hơn của wrapper từ chối nó. Label mà wrapper thêm vào là thứ khiến một instance của nó có thể được chọn, và selector là nơi điều đó thể hiện.

Còn hai trường hợp dừng nữa đáng biết, và cả hai đều là schema đang làm đúng việc của nó:

  • Một Component khai báo extends và viết nội dung trụ cột dưới schema: bị từ chối khi tài liệu được tải, kèm tên ràng buộc. Một Component bỏ hẳn schema: cũng vậy. schema: inherited là dạng duy nhất được chấp nhận, và nó được viết ra thay vì ngầm hiểu để người đọc không bao giờ nhầm một khối trụ cột được kế thừa với một khối bị bỏ quên.
  • Một khóa values mà base không khai báo sẽ bị từ chối trên một instance của wrapper, tại đường dẫn được viết, vì hợp đồng được thực thi là của base.

Vì sao điều này hữu ích

Một tổ chức đã thống nhất một hình dạng được review cho một component thuộc thư viện chuẩn cần một nơi để lưu giữ nó. Nếu lưu bằng văn xuôi, các label, annotation và socket bị viết lại trong mọi Aggregate cần đến chúng, và dần lệch nhau theo thời gian. Nếu phát hành dưới dạng một Component mở rộng base, hình dạng đó trở thành một thực thể catalog có phiên bản, có thể review và có tên: một nhóm sử dụng nó viết type: example/gateway/nginx-reviewed và một dòng Manifest, rồi kế thừa toàn bộ hợp đồng của base cùng mọi Recipe đã được viết cho nó, trên mọi target mà base hỗ trợ.

Chi phí của wrapper chính là điều khiến cách này hoạt động: nó chỉ thêm cấu trúc và metadata và không gì khác. Vì nó không khai báo trụ cột nào, một instance của wrapper và một instance của base được kiểm tra theo cùng một hợp đồng, và một Recipe viết cho base không bao giờ bị bất ngờ bởi một biến thể chuyên biệt của nó.