Kiến trúc Provider
Một provider kết xuất các loại đầu vào của một Recipe thành các tệp manifest gốc của provider. Khi một Recipe khai báo capability: helm, capability: compose hoặc bất kỳ tên provider nào khác, trình biên dịch điều phối việc kết xuất tới provider phục vụ tên đó. Chương này trình bày cách một provider được hiện thực hóa dưới dạng một Plugin kết xuất provider, cách hoạt động của việc điều phối, và hợp đồng plugin-socket gắn kết trình biên dịch với từng provider.
Những gì chương này không đề cập: mô hình kết hợp ba loại đầu vào (source: + valuesMapping:, workload:, artifacts: — mỗi loại chấp nhận nội dung nội tuyến hoặc $import:) mà một Recipe dùng để tạo ra đầu ra của nó. Mô hình đó áp dụng xuyên suốt mọi provider và được trình bày trong ../../architecture/16-recipe-input-composition.md, bao gồm cả Ma trận khả năng của Provider cho biết mỗi provider hỗ trợ loại đầu vào nào.
Plugin kết xuất provider
Provider rendering được phục vụ bởi một Plugin có pluginType: provider. Plugin provider-rendering:
- phục vụ một hoặc nhiều tên provider — được khai báo trong
spec.provider.capabilities. Tên provider mà một Recipe chỉ định (spec.capability: helm) được liên kết với Plugin kết xuất provider có danh sáchspec.provider.capabilitieschứa tên đó. Khi có nhiều hơn một Plugin phục vụ cùng một đích, workspace chọn giữa chúng thông qua một liên kết provider trong.aggrega-config.yaml, được phân giải khi chạyaggrega pullvà ghi lại trong lockfile; nếu không có liên kết và chỉ có đúng một ứng viên thì ứng viên đó được dùng, còn nếu không có liên kết và có nhiều hơn một ứng viên thì quá trình build dừng lại kèm thông báo rõ ràng, nêu tên các plugin ứng viên. - mang siêu dữ liệu provider-socket của nó trong cùng một khối —
spec.providerchứa danh sách capability ở trên cùng với các khai báo còn lại của provider.spec.provider.workloadSchemalà một khai báo JSON Schema 2020-12 mô tả cách kiểu Workload do nền tảng sở hữu được chuyển đổi thành đầu ra gốc của provider này; catalog thư viện chuẩn khai báo nó trên các provider có tổng hợp, như hợp đồng chuyển đổi được tài liệu hóa.spec.provider.wellKnownAnnotationsliệt kê các annotation ranh giớiaggrega.ai/mà provider đọc. Việc hỗ trợ đầu vào tổng hợp (workload:) là một thuộc tính của provider, được thực thi tại thời điểm kết xuất — không được xác định bởi sự hiện diện củaworkloadSchema.
Xem ../entities/plugin.md để biết toàn bộ bề mặt soạn thảo ở cấp trường của thực thể Plugin, bao gồm khối spec.provider.
Điều phối theo từng provider
Mỗi Recipe khai báo đúng một capability: ở đầu spec của nó. Trình biên dịch đọc trường này và điều phối việc kết xuất đến provider phục vụ tên đó. Một Recipe không thể nhắm đến nhiều provider cùng lúc. Việc kết hợp nhiều provider diễn ra ở cấp Release: một boundary có thể chứa các component thuộc nhiều provider khác nhau, và các thành phần đóng góp của mỗi provider tại đường dẫn lắp ráp đã được đánh giá của boundary được lắp ráp độc lập — mỗi bộ (path, provider) một lần lắp ráp.
Đường điều phối cho một nút:
- Trình biên dịch phân giải URI của Recipe cho nút này thông qua cơ chế tra cứu ba tầng của Manifest dưới mục ánh xạ của provider đích. Chính cách nhóm theo trục provider của Manifest khiến “cùng một Component, các Recipes khác nhau cho các provider khác nhau” trở thành một mẫu tự nhiên.
spec.capabilitycủa Recipe đã được phân giải xác định tên provider cần điều phối đến.- Trình biên dịch liên kết provider cho tên đó: nó phân giải Plugin kết xuất provider có danh sách
spec.provider.capabilitieschứa tên này và kết xuất thông qua guest của Plugin đó. Việc kết xuất chỉ dùng Wasm — không có trình kết xuất nội bộ trong host để dự phòng, nên một tên provider không phân giải được tới Plugin nào phục vụ sẽ dừng bản dựng một cách rõ ràng ngay tại thời điểm định tuyến. - Provider được gọi với ngữ cảnh kết xuất của từng nút (các giá trị trụ cột, các phép chiếu
.context.*, các loại đầu vào của Recipe). - Provider trả về đầu ra đã kết xuất. Trình biên dịch định tuyến các tệp đã kết xuất đến bộ lắp ráp theo từng
(path, provider), được định khóa theodirectory:đã đánh giá của boundary nối vớisubDirectory:của từng component. Hai boundary được đánh giá ra cùng một đường dẫn dưới cùng một provider sẽ dùng chung một bộ lắp ráp — mẫu chuẩn là một boundary cha cùng hai boundary con vớidirectory: "{{ .parent_boundary.directory }}"gộp lại thành một bản lắp ráp hợp nhất.
Xem ../entities/manifest.md để biết dạng điều phối theo trục provider của Manifest, và ../entities/recipe.md để biết khai báo một provider duy nhất phía Recipe. Mô hình lắp ráp theo từng (path, provider) và danh sách cho phép các biến mẫu đường dẫn kiểm soát các đường dẫn đã đánh giá được mô tả trong ../path-template-variables.md.
Hợp đồng plugin Wasm
Việc kết xuất của Provider chạy bên trong một sandbox WebAssembly. Trình biên dịch Go là host; Plugin kết xuất provider (provider-rendering Plugin) là guest. Với mỗi nút, trình biên dịch trao cho plugin ngữ cảnh kết xuất của nút đó, và plugin trả về các tệp mà nó đã kết xuất. Hợp đồng này đồng nhất cho mọi provider:
- Một mã hóa nhị phân chuẩn tắc theo cả hai chiều. Trình biên dịch mã hóa ngữ cảnh kết xuất — các giá trị và phần đính kèm của nút,
.workloadđã được phân tích cú pháp, các mục artifact đã được đánh giá, danh sách chỉ gồm tên của một.sourceđã được phân giải, và siêu dữ liệu của boundary — dưới dạng CBOR chuẩn tắc (RFC 8949 §4.2.1) và trao nó cho plugin. Plugin trả lời bằng cùng cách mã hóa đó với danh sách các tệp nó đã kết xuất — mỗi tệp gồm một đường dẫn tương đối so với thư mục gốc đầu ra của nút và chính xác các byte cần ghi vào đó, tùy chọn kèm định dạng của tệp — bên cạnh mọi chẩn đoán. Mọi export của socket, từ việc kết xuất một nút đến việc lắp ráp một boundary và nối một liên kết xuyên boundary, đều mang cách mã hóa này theo cả hai chiều, và bộ công cụ phát triển plugin của mỗi ngôn ngữ giải mã và mã hóa nó cho plugin. Một câu trả lời không có hình dạng đầu ra của export theo cách mã hóa này sẽ làm dừng bản build. Hợp đồng plugin mô tả payload của từng export. - Không truy cập hệ thống tệp. Plugins không thể đọc các tệp tùy ý từ hệ thống tệp của host. Một nguồn mà một Recipe chỉ định — một chart trong registry, một module trong repository — được trình biên dịch phân giải trước khi plugin chạy; plugin nhận một danh sách chỉ gồm tên của nguồn đó và yêu cầu trình biên dịch cung cấp các tệp mà nó chọn thông qua một hàm host, hàm này chỉ trả lời cho các tệp nằm dưới nguồn của nút đó.
- Không truy cập mạng. Plugins có tính tất định và khép kín, và không tự mở bất kỳ kết nối nào. Một đầu vào bên ngoài mà plugin cần trong khi kết xuất — một schema từ xa mà các giá trị của một chart tham chiếu — được yêu cầu thông qua hàm host đầu vào bên ngoài của trình biên dịch, hàm này trả lời từ nội dung mà workspace đã ghim cho tham chiếu đó.
- Đầu ra tất định. Với đầu vào giống hệt nhau và cùng một phiên bản plugin, một plugin phải tạo ra đầu ra giống hệt nhau đến từng byte. Đây là hợp đồng giúp bảo đảm đầu ra giống hệt từng byte của trình biên dịch được giữ vững từ đầu đến cuối qua lớp plugin. Một lần chạy build với
--verify-determinismsẽ kết xuất mọi nút hai lần và dừng lại khi hai lần kết xuất của một nút khác nhau.
Kiến trúc plugin-socket ở cấp độ khả năng mở rộng rộng hơn, bao gồm các socket Wasm khác trong pipeline biên dịch (vai trò transform và verdict của governance socket), được trình bày trong ../../architecture/14-extensibility.md.
Các provider thuộc thư viện chuẩn của Aggrega
Các provider helm, helm-chart, compose, terraform và cloudformation cùng nhau tạo thành bộ provider của thư viện chuẩn. Chúng bao quát các đích triển khai phổ biến mà không đòi hỏi các nhóm doanh nghiệp phải tự viết provider của riêng mình.
helm hỗ trợ cả ba loại đầu vào: sourced (một Helm chart thượng nguồn được tải qua Helm SDK, với đầu ra valuesMapping của Recipe làm giá trị ghi đè cho chart), synthesized (Kubernetes YAML phẳng — một đối tượng controller được chọn theo form của Workload (Deployment, StatefulSet, DaemonSet, Job hoặc CronJob) cùng với Services và PVCs — được sinh ra từ một Workload đã phân tích cú pháp), và artifacts (các tệp YAML độc lập đi kèm đầu ra của chart). Xem Provider Capability Matrix trong ../../architecture/16-recipe-input-composition.md để biết nó chấp nhận những loại nào trong ba loại.
helm-chart hỗ trợ chế độ sourced (ghép umbrella chart: một chart cho mỗi boundary, một sub-chart cho mỗi component) và artifacts: đi kèm theo nó, ở cả hai dạng viết. Một mục artifacts: được nạp bằng $import: trước tiên được Aggrega xử lý bằng Go template, rồi được chèn vào thư mục templates/ của chart trước khi render; một mục artifacts: có nội dung nội tuyến được đánh giá theo cùng cách và được đặt tại gốc của sub-chart, không gộp thông tin nguồn gốc vào, nơi các template của chính chart đọc nó qua .Files.Get / .Files.Glob của Helm. Một Recipe độc lập chỉ có artifacts không thuộc các loại mà provider này khai báo, và loại synthesized cũng vậy: umbrella điều phối các sub-chart, còn loại Workload là một khái niệm lá thuộc về bên trong mỗi sub-chart (phạm vi của provider helm).
compose hỗ trợ sourced (nạp một tệp compose và hợp nhất sâu lớp phủ valuesMapping), synthesized (sinh ra services: + volumes: + networks: của compose từ một Workload đã phân tích cú pháp cho các dạng stateless và stateful, với cách xử lý volume bị giảm cấp cho persistentTemplate — các PVC theo từng bản sao được gộp thành một named volume dùng chung duy nhất kèm cảnh báo; các dạng daemon, scheduled và task không có ánh xạ sang compose và dừng lại kèm thông báo rõ ràng), và artifacts (các mảnh compose có các khóa cấp cao nhất services: / networks: / volumes: / configs: được hợp nhất vào tệp docker-compose.yaml kết hợp của từng boundary). Artifacts có thể đi kèm một trong hai loại kia, và một Recipe độc lập chỉ có artifacts — artifacts: không có source: và không có workload: — cũng là một loại mà provider này khai báo: các mảnh của nó được hợp nhất theo cùng các quy tắc, nên node đóng góp đúng những gì nó khai báo và không cần một Workload đứng thay cho phần tính toán mà nó không có.
terraform hỗ trợ sourced (vendor nguyên văn một Terraform module và cung cấp đầu ra valuesMapping làm đối số cho khối module của component đó trong cấu hình gốc của boundary) và artifacts (sinh ra một phần thân HCL hoặc .tf.json do người dùng viết đúng như template của nó được đánh giá, không viết lại nó). Nó không cung cấp loại đầu vào synthesized — không có ánh xạ trung thực nào từ loại Workload của nền tảng sang các tài nguyên Terraform tùy ý. Provider này sinh ra cấu hình và không bao giờ chạy Terraform; các giá trị phụ thuộc vào thời gian chạy được giữ dưới dạng chuỗi nội suy ${ ... } mà Terraform runtime phân giải vào lúc apply.
cloudformation render một boundary thành một template stack AWS CloudFormation, ghép các mảnh tài nguyên mà các component của nó viết thành một template JSON thuần duy nhất, đưa provides của mỗi component ra thành Outputs của stack, và nối các cạnh uses dưới dạng Fn::GetAtt trong cùng một stack và dưới dạng Fn::ImportValue / Fn::GetStackOutput giữa các stack. Nó hỗ trợ đầu vào sourced và artifacts, và sinh ra cấu hình mà không bao giờ chạy CloudFormation; các giá trị chỉ có ở thời gian chạy được giữ dưới dạng hàm nội tại của CloudFormation.
Chỉ mục tham chiếu provider dẫn bạn đến trang tham chiếu riêng của từng provider; mỗi provider chấp nhận những loại đầu vào nào được trả lời trong ma trận khả năng tại ../../architecture/16-recipe-input-composition.md.
Các provider tùy chỉnh
Các nhóm doanh nghiệp tự viết provider của riêng mình làm theo cùng một mẫu như thư viện chuẩn: viết một Plugin dựng provider (pluginType: provider) khai báo (các) tên provider mà nó phục vụ trong spec.provider.capabilities, cùng với phần còn lại của siêu dữ liệu spec.provider, rồi phát hành artifact Wasm triển khai hợp đồng dựng đã nêu ở trên. Trình biên dịch xử lý các provider tùy chỉnh giống hệt các provider của thư viện chuẩn; việc điều phối theo từng provider hoạt động dựa trên tên provider mà Recipe khai báo.
Việc viết một provider đã được tài liệu hóa chứ không bị hoãn lại. Viết một provider xây dựng một guest provider hoạt động được từ đầu đến cuối — phần tự báo cáo describe(), bản build, thực thể Plugin, việc gắn kết, và một lần dựng có đầu ra mà bạn có thể đọc. Hướng dẫn dành cho nhà phát triển plugin Wasm là tài liệu tham khảo về thực thể và vòng đời phát hành, còn hợp đồng plugin mô tả cấu trúc payload và kết quả của từng socket. Các guest được viết bằng Go, Rust hoặc TypeScript dựa trên bộ công cụ phát triển plugin.