Các annotation phổ biến
Providers đọc các annotation cụ thể để cấu hình ngữ cảnh riêng của nền tảng — được đặt trên một ranh giới Release hoặc một mục thành phần Release, hoặc được khai báo trong Aggregate trên một hệ thống con hoặc một instance thành phần. Bản thân trình biên dịch không phụ thuộc vào giá trị của các annotation này — nó chuyển tiếp chúng dưới dạng chuỗi không tường minh. Mỗi provider khai báo những annotation nào nó đọc, ở phạm vi nào, và giá trị mặc định nào được áp dụng khi annotation vắng mặt. Khai báo đó nằm trong spec.provider.wellKnownAnnotations của một Plugin kết xuất Provider, và nó được cố ý giữ hẹp: một provider chỉ liệt kê một khóa ở nơi nó đọc khóa đó. Một provider không đọc annotation nào trong số đó thì thay vào đó khai báo spec.provider.readsNoWellKnownAnnotations: true.
Ma trận hỗ trợ trong chương này được sinh ra từ các khai báo đó, ở mức chi tiết mà khai báo mang theo — theo từng provider theo từng loại đầu vào, vì một provider có thể đọc một khóa khi tổng hợp một đơn vị triển khai nhưng không có cách nào đọc nó khi kết xuất một artifact được vendor hóa. Hãy soạn thảo dựa trên ma trận ở đây: một ô cho biết provider đó đọc gì trên đường đi đó, vì một ô không thể nói bất cứ điều gì mà provider không khai báo. Một khai báo nêu tên một loại đầu vào mà chính hợp đồng hành vi kết xuất của provider không kết xuất sẽ bị từ chối khi thực thể Plugin được đọc, nên hai tuyên bố không thể mâu thuẫn nhau.
Bộ từ vựng dành riêng là tập hợp rộng hơn, và thay vào đó nó nằm ở hai nơi — chương này, nơi nêu tên mọi khóa dành riêng kể cả những khóa không provider nào đọc, và tập tiền tố dành riêng mà công cụ lint khi xuất bản kiểm tra.
Các bất biến
- Trình biên dịch không bao giờ diễn giải hay xác thực giá trị của một annotation phổ biến của provider: nó mang khóa và giá trị của khóa qua cascade, và cảnh báo ở nơi một đích không hành động theo khóa đó.
- Mỗi provider ghi lại những annotation mà nó đọc và những giá trị mặc định mà nó áp dụng.
- Các annotation được áp dụng đồng nhất trong một boundary. Nếu một giá trị thay đổi theo từng component, nó thuộc về các annotation cấp component (ghi đè các annotation của boundary) hoặc thuộc về
infracủa component. - Các annotation well-known của Provider không bao giờ trùng lặp với các nhãn của Component. Nhãn của Component mô tả một component là gì. Annotation của boundary mô tả một component được triển khai ở đâu.
- Các Recipes không xử lý các annotation phổ biến của provider. Provider tự động áp dụng ngữ cảnh vị trí (namespace, tiền tố registry, service account) sau khi Recipe tạo ra nội dung của nó.
- Tiền tố
aggrega.ai/được dành riêng cho thư viện chuẩn. Các annotation tùy chỉnh của doanh nghiệp sử dụng tiền tố riêng của chúng. - Các annotation cấp Component trong Release ghi đè các annotation cấp boundary (deep-merge, component thắng). Khi một provider gộp đầu ra của nhiều boundary vào một artifact, nó có thể yêu cầu một annotation phải được phân giải đồng nhất trên tất cả các boundary đó — provider
helm-chartlấy tên của umbrella chart từaggrega.ai/chart-name, và khi có nhiều hơn một boundary cùng đóng góp vào một chart và chúng phân giải annotation đó thành các giá trị khác nhau, quá trình build dừng lại và nêu tên các boundary không thống nhất, vì một chart không thể mang hai tên. - Các annotation mà Aggregate khai báo đi tới cùng các khóa đó, với thứ tự ưu tiên thấp hơn annotation của Release. Một khóa được khai báo trên một hệ thống con hoặc trên một instance thành phần — trong chính Aggregate, hoặc trong một module mà nó nhập, nơi khóa đi tới các thành phần riêng của module — áp dụng cho thành phần ở bất cứ đâu Release không đặt giá trị cho khóa đó; nơi Release đặt một giá trị, trên ranh giới hoặc trên mục của thành phần, giá trị của Release là giá trị được áp dụng. Annotation riêng của một thực thể catalog không bao giờ đặt giá trị này.
aggrega.ai/chart-namelà ngoại lệ đối với phạm vi của Aggregate: nó đặt tên cho một bản lắp ráp chứ không phải một thành phần, và được đọc từ các ranh giới Release đóng góp vào bản lắp ráp đó.
Ma trận annotation đầy đủ
Cách đọc ma trận này
Sáu bảng theo danh mục dưới đây nêu mọi annotation trong bộ từ vựng dành riêng aggrega.ai/, những gì nó kiểm soát, và provider làm gì khi nó vắng mặt. Việc một provider cụ thể có áp dụng một khóa cụ thể hay không là câu hỏi chi tiết hơn, vì một provider render nhiều hơn một loại đầu vào — một artifact được vendor (sourced), một Workload do chính provider tổng hợp (synthesized), hoặc artifacts: của một Recipe làm toàn bộ đầu ra của một node (artifacts-only) — và một khóa có thể được đọc trên một trong các đường đó nhưng không thể tới được trên đường khác. Provider nào render loại đầu vào nào được nêu tại ../../architecture/16-recipe-input-composition.md; mỗi provider áp dụng những gì được nêu tại Hỗ trợ theo provider và loại đầu vào bên dưới, là phát biểu có thẩm quyền của trang này.
Mỗi ô trong lưới đó mang một trong ba cấp:
- Được áp dụng — provider áp dụng khóa trên loại đầu vào này, và đầu ra được render thay đổi một cách tất định theo đó.
- Được áp dụng có điều kiện — trình biên dịch phát ra một ghi đè bổ sung bên cạnh artifact đích thay vì chỉnh sửa artifact, nên việc giá trị có hiệu lực hay không phụ thuộc vào việc artifact đó có để lộ một khóa tương ứng của riêng nó. Có hiệu quả trong thực tế, nhưng không bao giờ là một bảo đảm. Không provider nào triển khai một ô có điều kiện, và bề mặt khai báo không có cách nào để biểu đạt nó, nên lưới được tạo bên dưới chỉ phát ra hai cấp còn lại. Cấp này được đặt tên vì đường đi đó thực sự tồn tại đối với một artifact được vendor, và một bộ từ vựng hai cấp sẽ buộc ma trận hoặc phải tuyên bố một bảo đảm mà nó không thể đưa ra, hoặc phải phủ nhận rằng đường đi đó tồn tại.
- Không được áp dụng — không provider nào áp dụng khóa trên đường này: đích không có chỗ render cho nó ở đó, nên cơ chế đặt vị trí không đóng góp gì vào những gì được render, và cột Mặc định của bảng danh mục cho biết bạn nhận được gì thay vào đó. Giá trị vẫn đi qua bản build dưới dạng một chuỗi mờ, không bị động đến. Cấp này được đặt tên theo cơ chế chứ không theo số phận của giá trị, vì đó là hai câu hỏi khác nhau và chỉ câu hỏi đầu là câu một ô có thể trả lời: những gì một provider áp dụng là thuộc tính của các chỗ render của đích đó, chính là điều mà khai báo đằng sau mỗi ô nêu ra.
Có hai phạm vi, và chỉ một trong số đó khiến loại đầu vào trở thành một trục có ý nghĩa:
- Phạm vi node —
aggrega.ai/namespace,aggrega.ai/image-registry,aggrega.ai/image-pull-secret,aggrega.ai/service-accountvàaggrega.ai/kubernetes-versionđịnh hình đầu ra được render của riêng một component, do đường đi mà loại đầu vào của nó chọn tạo ra. Đây là các cột của lưới. - Phạm vi assembly và tham chiếu —
aggrega.ai/chart-nameđược phân giải một lần khi một umbrella chart được lắp ráp, và ba khóaaggrega.ai/aws-*được phân giải khi một tham chiếu vượt qua một ranh giới. Loại đầu vào không phải là một trục cho cả hai: giá trị được đọc tại assembly hoặc tại tham chiếu, bất kể mỗi node đóng góp được render như thế nào. Chúng có bảng riêng tại Các khóa được phân giải theo assembly và theo tham chiếu.
Danh mục 1 — Đặt vị trí
| Annotation | Được áp dụng bởi | Mục đích | Mặc định |
|---|---|---|---|
aggrega.ai/namespace | helm (sourced, synthesized); compose (sourced, synthesized) | Kubernetes namespace (helm); tên mạng Docker (compose) | Không được chèn nếu vắng mặt (helm); một mạng được đặt theo đường dẫn của tệp compose, dùng chung cho mọi node trong tệp đó không có annotation (compose) |
aggrega.ai/project-name | dành riêng; không provider nào đọc nó | Dành riêng cho tên dự án Docker Compose | — |
aggrega.ai/region | dành riêng; không provider nào đọc nó | Dành riêng cho một vùng đám mây ở phạm vi đặt vị trí | — |
aggrega.ai/account-id | dành riêng; không provider nào đọc nó | Dành riêng cho một định danh tài khoản đám mây ở phạm vi đặt vị trí | — |
aggrega.ai/kubernetes-version | helm (sourced) | Phiên bản Kubernetes của cluster mà component triển khai tới, được một chart render từ mã nguồn đọc dưới dạng .Capabilities.KubeVersion | Phiên bản mà helm template gốc của cùng bản phát hành helm render cho: phiên bản của thư viện client Kubernetes mà provider được build cùng |
aggrega.ai/namespace có hai mục đích theo thiết kế. Nó biểu đạt cùng một ý định cô lập logic — “tài nguyên của ranh giới này nằm trong phạm vi có thể định địa chỉ của riêng chúng” — dưới dạng gốc của mỗi đích: một Kubernetes metadata.namespace cho helm, một tên mạng Docker cho compose. Tác giả Recipe đặt một annotation; mỗi provider hiện thực hóa nó phù hợp với đích. Với trường hợp compose, tên mạng được phân giải theo từng node từ annotation trên node đó, quay về đường dẫn của tệp compose khi node không mang annotation — nên các ranh giới không có annotation cùng dùng một tệp compose sẽ dùng chung một mạng, và aggrega.ai/namespace chính là thứ tách chúng ra. Dù nguồn nào trong hai nguồn cung cấp định danh, nó sau đó được ghi bằng các ký tự mà tên mạng compose chấp nhận — mọi ký tự khác được ghi dưới dạng thoát thay vì bị thay thế, nên hai định danh khác nhau dù chút ít vẫn nằm trên hai mạng, và chữ hoa chữ thường của định danh được giữ như khi viết. Tài liệu tham khảo về compose provider mô tả đầy đủ cách suy ra, bao gồm cách đọc một tên đã mã hóa và cái giá của việc đổi tên.
aggrega.ai/kubernetes-version nêu một thuộc tính của cluster mà component triển khai tới chứ không phải vị trí component nằm trong đó: các template của chart chọn một phiên bản API, một trường hoặc cả một cơ chế theo phiên bản mà chúng được render cho, và bản build không có cluster nào để hỏi. Helm provider đọc giá trị theo cách helm template --kube-version đọc cờ của nó và dừng bản build khi giá trị không phải là một phiên bản; khi không có phiên bản nào được nêu, chart được render cho phiên bản mà helm template của cùng bản phát hành helm render cho. Tài liệu tham khảo về helm provider mô tả các dạng được chấp nhận và giá trị mặc định.
Danh mục 2 — Registry
| Annotation | Được áp dụng bởi | Mục đích | Mặc định |
|---|---|---|---|
aggrega.ai/image-registry | helm, compose — chỉ synthesized | Tiền tố registry cho container image, áp dụng cho mọi tham chiếu container image được tổng hợp | Không có tiền tố |
aggrega.ai/image-pull-secret | helm — chỉ synthesized | Tên imagePullSecrets của Kubernetes, được hợp nhất vào các mục hiện có của pod được tổng hợp | Không có |
Danh mục 3 — Mạng
| Annotation | Được áp dụng bởi | Mục đích | Mặc định |
|---|---|---|---|
aggrega.ai/cluster-domain | dành riêng; không provider nào đọc nó | Dành riêng cho hậu tố DNS dùng để khám phá dịch vụ giữa các namespace | — |
aggrega.ai/ingress-class | dành riêng; không provider nào đọc nó | Dành riêng cho một Kubernetes IngressClass trên các tài nguyên Ingress | — |
aggrega.ai/service-mesh | dành riêng; không provider nào đọc nó | Dành riêng cho các annotation chèn sidecar của mesh | — |
Danh mục 4 — Bảo mật
| Annotation | Được áp dụng bởi | Mục đích | Mặc định |
|---|---|---|---|
aggrega.ai/service-account | helm — chỉ synthesized | Kubernetes ServiceAccount cho các Pod được tổng hợp; ghi đè workload.serviceAccount của Recipe khi cả hai đều được đặt | workload.serviceAccount của Recipe, hoặc không đặt khi Recipe không khai báo |
aggrega.ai/pod-security-standard | dành riêng; không provider nào đọc nó | Dành riêng cho một cấp Pod Security Standards | — |
aggrega.ai/iam-role | dành riêng; không provider nào đọc nó | Dành riêng cho một vai trò định danh đám mây gắn với một workload | — |
Danh mục 5 — Đóng gói
| Annotation | Được áp dụng bởi | Mục đích | Mặc định |
|---|---|---|---|
aggrega.ai/chart-name | helm-chart — theo assembly | Tên umbrella chart | Tên Aggregate và đường dẫn lắp ráp của umbrella được nối lại — xem Phân giải tên chart |
aggrega.ai/chart-version | dành riêng; không provider nào đọc nó | Dành riêng cho phiên bản Helm chart | — |
aggrega.ai/stack-name | dành riêng; không provider nào đọc nó | Dành riêng cho một stack được đặt tên tường minh | — |
aggrega.ai/tf-backend | dành riêng; không provider nào đọc nó | Dành riêng cho định danh state backend của Terraform | — |
Nhóm 6 — Đích đám mây
| Annotation | Được áp dụng bởi | Mục đích | Mặc định |
|---|---|---|---|
aggrega.ai/aws-account | cloudformation — theo từng tham chiếu vượt ranh giới | Tài khoản AWS mà stack (ranh giới) triển khai vào | Cùng tài khoản — một tham chiếu giữa các stack được phân giải qua cơ chế export/import stack trong cùng tài khoản |
aggrega.ai/aws-region | cloudformation — theo từng tham chiếu vượt ranh giới | Vùng AWS mà stack (ranh giới) triển khai vào | Cùng vùng — một tham chiếu giữa các stack được phân giải qua cơ chế export/import stack trong cùng vùng |
aggrega.ai/aws-assume-role-arn | cloudformation — theo từng tham chiếu vượt ranh giới | ARN của vai trò IAM mà một lượt đọc stack liên tài khoản đảm nhận để truy cập các giá trị được export của một stack ngang hàng | Không có vai trò nào được cung cấp trên một tham chiếu liên tài khoản |
Mỗi ranh giới CloudFormation được kết xuất thành một stack. Khi một cạnh uses đi từ ranh giới này sang ranh giới khác, provider cloudformation cần biết stack ngang hàng nằm ở đâu để định hình tham chiếu: hai stack trong cùng tài khoản và vùng trao đổi giá trị qua export và import stack; một stack ngang hàng ở tài khoản hoặc vùng khác cần một lượt đọc output stack liên tài khoản, tùy chọn dưới một vai trò được đảm nhận. Các annotation này mang ngữ cảnh vị trí đó. Mỗi annotation được đọc vào thời điểm provider định hình một tham chiếu như vậy, và được phân giải qua chuỗi kế thừa annotation thông thường tại thời điểm đó — giá trị đặt trên component thắng giá trị đặt trên ranh giới, và giá trị do Release đặt thắng giá trị do Aggregate khai báo. Vì vậy, giá trị ở cấp ranh giới là cách thông dụng để biểu đạt chúng, chứ không phải cách duy nhất. Chúng là các chuỗi con trỏ vô hướng không trong suốt — provider chuyển chúng vào tham chiếu mà nó xây dựng và không bao giờ phân giải chúng theo trạng thái AWS thực; tài khoản, vùng và vai trò do Release cung cấp hoặc được khai báo trong Aggregate, và môi trường runtime phân giải lượt đọc vật lý cuối cùng. Khi mọi annotation đều vắng mặt, provider coi stack ngang hàng là cùng tài khoản, cùng vùng và không cung cấp vai trò nào.
Mức hỗ trợ theo provider và loại đầu vào
Các khóa phạm vi node, theo từng provider và từng loại đầu vào. Tiêu đề cột bỏ tiền tố aggrega.ai/ mà mọi khóa đều có. applied và — mang các cấp đã định nghĩa ở trên, trong đó — là không được áp dụng; n/a nghĩa là provider hoàn toàn không kết xuất loại đầu vào đó, nên ở đó không tồn tại đường dẫn nào để khóa được áp dụng hay bị bỏ qua.
| Provider | Loại đầu vào | namespace | image-registry | image-pull-secret | service-account | kubernetes-version |
|---|---|---|---|---|---|---|
helm | sourced | applied | — | — | — | applied |
helm | synthesized | applied | applied | applied | applied | — |
helm | artifacts-only | — | — | — | — | — |
compose | sourced | applied | — | — | — | — |
compose | synthesized | applied | applied | — | — | — |
compose | artifacts-only | — | — | — | — | — |
helm-chart | sourced | — | — | — | — | — |
helm-chart | synthesized | n/a | n/a | n/a | n/a | n/a |
helm-chart | artifacts-only | n/a | n/a | n/a | n/a | n/a |
terraform | sourced | — | — | — | — | — |
terraform | synthesized | n/a | n/a | n/a | n/a | n/a |
terraform | artifacts-only | — | — | — | — | — |
cloudformation | sourced | — | — | — | — | — |
cloudformation | synthesized | n/a | n/a | n/a | n/a | n/a |
cloudformation | artifacts-only | — | — | — | — | — |
Mọi provider được phân phối cùng trình biên dịch đều có hàng ở đây, kể cả provider không đọc annotation vị trí nào — một tập hàng trống sẽ không thể phân biệt với một provider chưa ai mô tả. Một provider được cung cấp riêng khai báo những gì nó đọc theo cùng cách và không được liệt kê ở đây, vì một trang đã xuất bản không thể liệt kê các provider mà nó chưa từng thấy.
Một Recipe có thể khai báo nhiều loại đầu vào cùng lúc — chẳng hạn một workload: kèm theo artifacts:. Hãy đọc bảng theo từng loại: đầu ra tổng hợp của một node như vậy là hàng synthesized, còn các tệp artifact của nó là trường hợp artifacts. Hàng artifacts-only là loại đầu vào trong đó một Recipe khai báo artifacts: và không gì khác.
Bạn không cần tra bảng để biết điều này. Việc đặt một khóa mà đích của một lượt kết xuất không đọc trên bất kỳ loại đầu vào nào của lượt kết xuất đó sẽ sinh ra một cảnh báo nêu tên khóa, đích và mọi loại đầu vào mà lượt kết xuất đó khai báo, nên một ô bạn vô tình rơi vào sẽ tự báo ngay khi bạn build, thay vì chờ bạn nghĩ đến việc xem ở đây:
warning: node "frontend" (provider "helm-chart"): target "helm-chart" does not support annotation aggrega.ai/namespace on sourced input and ignored itVới một lượt kết xuất khai báo nhiều loại đầu vào, cảnh báo nói về toàn bộ lượt kết xuất đó, không phải về một nửa của nó. Vì các loại kết hợp theo phép cộng, một đích đọc khóa trên bất kỳ loại nào trong số đó đều áp dụng nó, và đầu ra của lượt kết xuất đó mang kết quả — nên không có cảnh báo nào. Cảnh báo chỉ xuất hiện khi mọi loại mà lượt kết xuất đó khai báo đều bỏ qua khóa, và nó nêu tên tất cả các loại đó:
warning: node "backend" (provider "helm"): target "helm" does not support annotation aggrega.ai/cluster-domain on sourced or synthesized input and ignored itVậy một workload: kèm theo một source: là đủ để aggrega.ai/service-account có hiệu lực trên node đó, và quá trình build không báo gì về nó — đó là báo cáo trung thực, vì giá trị đến được nửa tổng hợp và xuất hiện trong các manifest được sinh ra.
Hãy đọc bảng theo từng lượt kết xuất, không theo từng component. Một feature gắn vào một node sinh tài nguyên của nó qua đích mà chính FeatureRecipe của nó chỉ định, ở các loại đầu vào mà FeatureRecipe đó khai báo — nên nó nằm ở hàng riêng của nó trong bảng này, không nhất thiết là hàng của component chủ. Một component tổng hợp Workload của mình trong khi một feature gắn kèm đóng góp artifacts: bên cạnh sẽ đọc hàng synthesized cho các manifest của chính component và hàng artifacts-only cho các tệp của phần gắn kèm, và một khóa được áp dụng ở hàng thứ nhất có thể bị bỏ qua ở hàng thứ hai. Cảnh báo cũng tách theo cách đó và báo riêng cho từng phần, vì chúng là các tệp khác nhau. Một feature gắn vào một ranh giới thay vì một component cụ thể cũng đọc bảng theo cùng cách.
Giá trị vẫn đi qua nguyên vẹn — quá trình build không dừng, vì một ranh giới trải trên các component ở những đích không đồng nhất sẽ luôn có lượt kết xuất nào đó không thể xử lý một khóa nhất định, và đó là một Release bình thường chứ không phải lỗi. Annotation của ranh giới được kế thừa xuống, nên một dòng được viết sinh ra một cảnh báo cho mỗi lượt kết xuất không thể xử lý nó, đó là cách bạn thấy những phần nào trong đầu ra bị ảnh hưởng. Cảnh báo này thuộc lớp unsupported-field và được tắt bằng cờ của lớp đó; Warnings có chi tiết. Hai giới hạn nên biết: chỉ các khóa aggrega.ai/ trần được kiểm tra, vì khóa có tiền tố con là từ vựng riêng của bạn, và một provider hoàn toàn không khai báo mức hỗ trợ nào sẽ không sinh cảnh báo, vì không có gì để so sánh với những gì bạn đã viết. Một provider khai báo rằng nó không đọc khóa nào trong số này thì không im lặng theo cách đó: readsNoWellKnownAnnotations: true trên thực thể Plugin của nó là một tuyên bố không bao gồm khóa nào, nên mọi khóa trần đến được một trong các lượt kết xuất của nó đều kéo theo cảnh báo. Provider terraform khai báo điều này.
Vì sao một artifact được vendor áp dụng ít khóa hơn. Một annotation phạm vi node được áp dụng ở nơi provider có vị trí kết xuất cho nó. Khi provider tự tổng hợp đơn vị triển khai, nó sở hữu mọi trường của kết quả, nên tiền tố registry, pull secret và service account đều có chỗ để đặt vào. Một artifact được vendor — một Helm chart, một tệp compose, một module Terraform — thay vào đó mang giao diện cấu hình riêng của nó, và trình biên dịch không đọc giao diện đó, nên nó không thể biết khóa nào của artifact tương ứng với tiền tố registry hay service account. Vị trí do lệnh gọi kết xuất bao quanh kiểm soát vẫn được áp dụng, đó là lý do aggrega.ai/namespace được áp dụng cho một chart kết xuất từ nguồn. Vị trí đòi hỏi quyết định một giá trị thuộc về đâu bên trong artifact của người khác thì không, và tác giả cung cấp nó qua chính các values của artifact đó. Đây là lý do các hàng sourced thưa thớt trong khi các hàng synthesized đầy đủ, và đó là hình dạng cần chờ đợi ở bất kỳ khóa nào được thêm sau này.
Các khóa được phân giải theo từng lần lắp ráp và theo từng tham chiếu
Bốn trong số các khóa đi kèm không có phạm vi theo nút, vì vậy chúng nằm ngoài lưới ở trên thay vì được gộp vào đó: loại đầu vào không phải là một trục có ý nghĩa đối với chúng, và việc cho mỗi khóa một hàng theo từng loại đầu vào sẽ lặp lại một ô duy nhất ba lần và ngụ ý một sự phân biệt không tồn tại. Mỗi khóa khai báo phạm vi boundary, và bảng dưới đây được sinh ra từ các khai báo đó.
| Annotation | Được áp dụng bởi | Mục đích | Mặc định |
|---|---|---|---|
aggrega.ai/chart-name | helm-chart | Tên của Helm chart umbrella được lắp ráp. | Tên Aggregate và đường dẫn lắp ráp của umbrella chart — thư mục đầu ra của nó trong dist/, chẳng hạn boundaries/data/helm-chart — được sử dụng, mỗi phần được mã hóa rồi nối lại. |
aggrega.ai/aws-account | cloudformation | Tài khoản AWS mà stack (boundary) triển khai vào. Một tham chiếu xuyên boundary đọc giá trị này để quyết định liệu một stack ngang hàng có nằm trong cùng tài khoản hay không. | Stack ngang hàng được coi là cùng tài khoản, và một tham chiếu xuyên stack được phân giải qua một lần import stack-export cùng tài khoản thay vì một lần đọc stack-output xuyên tài khoản. |
aggrega.ai/aws-region | cloudformation | Region AWS mà stack (boundary) triển khai vào. Một tham chiếu xuyên boundary đọc giá trị này để quyết định liệu một stack ngang hàng có nằm trong cùng region hay không. | Stack ngang hàng được coi là cùng region, và một tham chiếu xuyên stack được phân giải qua một lần import stack-export cùng region. |
aggrega.ai/aws-assume-role-arn | cloudformation | ARN của IAM role mà một lần đọc stack xuyên tài khoản đảm nhận để truy cập các giá trị được export của một stack ngang hàng. | Không có role nào được cung cấp, và một tham chiếu xuyên tài khoản không mang assume-role. |
Thời điểm mỗi khóa được phân giải, điều mà bản thân khai báo không thể hiện. aggrega.ai/chart-name được phân giải một lần cho mỗi lần lắp ráp umbrella chart, từ chuỗi cascade annotation của boundary; mọi thành phần đóng góp vào một lần lắp ráp phải phân giải nó thành cùng một giá trị, và sự bất đồng sẽ dừng quá trình build, nêu tên các boundary. Ba khóa aggrega.ai/aws-* được phân giải theo từng tham chiếu xuyên boundary với thứ tự ưu tiên component trên boundary, nên giá trị của component thắng giá trị của boundary; Hạng mục 6 ở trên mô tả tham chiếu mà mỗi khóa định hình.
Các tên dành riêng không provider nào đọc
Mười một khóa trong ma trận ở trên được đánh dấu dành riêng; không provider nào đọc: aggrega.ai/project-name, aggrega.ai/region, aggrega.ai/account-id, aggrega.ai/cluster-domain, aggrega.ai/ingress-class, aggrega.ai/service-mesh, aggrega.ai/pod-security-standard, aggrega.ai/iam-role, aggrega.ai/chart-version, aggrega.ai/stack-name, và aggrega.ai/tf-backend.
Việc đặt một trong các khóa này trên một Release hoặc trong một Aggregate không có tác dụng gì đến đầu ra được render. Không provider nào đọc chúng, và không có giá trị mặc định nào được áp dụng thay cho chúng — cụ thể, không có hậu tố DNS nào được áp dụng cho aggrega.ai/cluster-domain, nên một Recipe cần cluster domain phải cung cấp nó như một giá trị thông thường thay vì dựa vào annotation này. Một tác giả Recipe cần một trong các hành vi này thể hiện nó dưới dạng một giá trị Recipe hoặc một trường infra của component.
Không provider nào khai báo mười một khóa này. wellKnownAnnotations của một provider chỉ liệt kê
những gì nó đọc, nên không khóa nào trong mười một khóa xuất hiện ở đó — người đọc mở
Plugin helm, helm-chart, compose hoặc cloudformation sẽ thấy các khóa hoạt động và
không gì khác. Đó chính là mục đích của khai báo hẹp: một khóa được khai báo là một
khóa hoạt động, và phạm vi bên cạnh nó cho biết trên đường dẫn nào.
Hai trong số các tên dành riêng gần giống các khóa đang hoạt động và không thể thay thế cho chúng. aggrega.ai/region và aggrega.ai/account-id đặt tên cho một region và một tài khoản ở phạm vi placement và không đến được provider nào; các khóa mà provider cloudformation đọc là aggrega.ai/aws-region và aggrega.ai/aws-account có namespace theo cloud trong Hạng mục 6. Khi bạn muốn nói đến ngữ cảnh placement xuyên stack của CloudFormation, hãy viết dạng aws- — cặp không có tiền tố được giữ lại để tránh xung đột, không được nối với bất cứ thứ gì. Hai tên dành riêng khác được xử lý bởi các cơ chế khác thay vì bởi annotation: aggrega.ai/stack-name được dành riêng, trong khi tên stack mà một boundary cloudformation render vào được suy ra một cách tất định từ danh tính của release và boundary; và role định danh cloud của một workload được cung cấp dưới dạng một trường thông thường do operator đặt trên Feature phát ra binding, không phải qua aggrega.ai/iam-role.
Các tên này vẫn được dành riêng, và vẫn được liệt kê ở đây, vì tiền tố aggrega.ai/ được dành riêng: một catalog doanh nghiệp không được tái sử dụng một trong các khóa này cho nghĩa riêng của mình, vì nền tảng giữ khóa đó cho một nghĩa của riêng nó. Ma trận này và tập tiền tố dành riêng mà lint xuất bản kiểm tra cùng nhau tạo thành sổ đăng ký dành riêng, và hai thứ này được giữ cùng một tập tên bởi một bước kiểm tra đọc cả hai và thất bại khi chúng khác nhau. Do đó, việc viết một trong mười một khóa không làm thất bại bước xác thực cũng không vi phạm quy định “không dùng tiền tố aggrega.ai/ trần” — nó đơn giản là không có tác dụng.
Phiên bản umbrella chart mà một boundary helm-chart phát ra luôn là 0.1.0; đó là một giá trị cố định chứ không phải giá trị mặc định của aggrega.ai/chart-version.
Lưu ý: các binding
features.annotationscủa Manifest dùng tiền tốaggrega.ai/bị từ chối khi tải; tiền tố này được dành riêng hoàn toàn cho các annotation phổ biến của provider được mô tả trong chương này. Tác giả các binding Feature dựa trên annotation dùngfeature.aggrega.ai/cho các lối tắt của thư viện chuẩn hoặc một domain tùy chỉnh cho các lối tắt của doanh nghiệp.Lưu ý:
nulltường minh trên một annotation của Release sẽ gỡ binding được kế thừa khỏi boundary hoặc component ghi đè (từ chối Feature dựa trên annotation). Các component cùng cấp trong cùng boundary không từ chối vẫn giữ binding được kế thừa; các khóa vắng mặt tiếp tục kế thừa từ cascade cha như bình thường.
Các annotation do catalog tạo mà trình biên dịch đọc
Mọi thứ ở trên đều là annotation của provider: được viết trên Release hoặc được khai báo trong Aggregate, được trình biên dịch chuyển tiếp dưới dạng một chuỗi không minh bạch, và được một provider đọc. Một bộ từ vựng thứ hai, nhỏ hơn nhiều, đi theo chiều ngược lại — được Architect viết trên metadata.annotations của chính một thực thể catalog, được trình biên dịch đọc, và không bao giờ được provider nhìn thấy. Bất biến 1 ở trên nói về bộ từ vựng của provider và không áp dụng cho các khóa này; trình biên dịch chỉ đọc đúng các khóa được liệt kê ở đây và không đọc khóa nào khác.
Các khóa này nằm dưới một tiền tố con <scope>.aggrega.ai/, không phải tiền tố trần aggrega.ai/, nên chúng nằm ngoài sổ đăng ký dành riêng mà ma trận ở trên mang, và nằm ngoài quy tắc tiền tố dành riêng mà lint xuất bản áp dụng cho các khóa dùng tiền tố trần.
| Annotation | Được viết trên | Được đọc bởi | Mục đích |
|---|---|---|---|
features.aggrega.ai/requiredType.<label> | metadata.annotations của Component | trình biên dịch, trên đồ thị đã hoàn tất | Khai báo một yêu cầu hiện diện: mọi thể hiện của Component này phải mang ít nhất một attachment có kiểu bằng giá trị của annotation. <label> là một hậu tố do tác giả chọn, dùng để đặt tên cho yêu cầu trong thông báo chẩn đoán; nó không phải tên slot và không có gì tham chiếu đến nó. Lặp lại khóa với các nhãn khác nhau để khai báo nhiều yêu cầu. |
Yêu cầu được thỏa mãn bởi một attachment ở bất kỳ phạm vi nào — một khối features: cấp component hoặc cấp subsystem, một khối cấp boundary hoặc cấp component của Release, hoặc phần mở rộng dựa trên annotation — vì nó kiểm tra tập attachment cuối cùng của thể hiện chứ không xét mỗi attachment đến từ đâu. Một yêu cầu không được đáp ứng sẽ dừng bản dựng, nêu tên nhãn và kiểu được yêu cầu; một giá trị không phải 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 thông báo chẩn đoán riêng về khai báo sai định dạng. Hướng dẫn viết đầy đủ, và cách một yêu cầu hiện diện khác với một slot featuresSchema, có tại entities/component.md “Presence mandates”.
Nhãn nguồn gốc do các provider phát ra
Các annotation ở trên đi vào bản build — Release hoặc Aggregate tạo chúng, các provider tiêu thụ chúng. Providers cũng phát ra một tập label song song đi ra khỏi bản build, gắn chúng vào đầu ra đã render để các công cụ phía sau có thể truy ngược các tài nguyên runtime về nội dung catalog đã tạo ra chúng. Các label nguồn gốc này không được viết trên Release; chúng được suy ra từ chính trạng thái của bản build (định danh Recipe, đường dẫn boundary, tên aggregate, môi trường, sync wave, phiên bản trình biên dịch) và được provider phát ra tại thời điểm render.
Tập nhãn mà các provider phát ra, được gắn vào mọi manifest Kubernetes mà provider helm render, vào mọi artifact được nạp bằng $import: mà provider helm-chart thêm vào một sub-chart, và vào mọi service được compose phát ra — các template riêng của một sub-chart helm-chart được sao chép đúng như tác giả của chúng đã viết, nên chúng mang bất cứ thứ gì tác giả đó đã viết:
| Nhãn | Nguồn | Phát ra |
|---|---|---|
app.kubernetes.io/name | Node ID (hoặc, với tài nguyên do một FeatureRecipe phát ra, định danh được suy ra cho attachment đó — xem bên dưới) | Chỉ helm và helm-chart — nhãn chuẩn của Kubernetes, không được phát ra trên các service compose |
aggrega.ai/component-id | Node ID (hoặc, với tài nguyên do một FeatureRecipe phát ra, định danh được suy ra cho attachment đó — xem bên dưới) | Cả ba provider |
aggrega.ai/recipe-uri | <recipe-name>:<recipe-version> của Recipe tạo ra (hoặc FeatureRecipe tạo ra, với các tài nguyên do FR phát ra) | Cả ba provider, khi thực thể tạo ra có đặt cả tên lẫn phiên bản; là annotation trên helm và helm-chart |
aggrega.ai/boundary-path | Đường dẫn boundary mà component được định tuyến vào | Cả ba provider, khi đường dẫn boundary không rỗng; là annotation trên helm và helm-chart |
aggrega.ai/aggregate-name | metadata.name của Aggregate | Cả ba provider, khi được đặt |
aggrega.ai/compiler-version | Phiên bản trình biên dịch được đóng dấu tại thời điểm build | Cả ba provider, khi được đặt |
aggrega.ai/provider | Provider đã render tài nguyên | Cả ba provider |
aggrega.ai/provider-version | Phiên bản của provider đó | Cả ba provider |
aggrega.ai/environment | metadata.environment của Release | Cả ba provider — mọi Release đều khai báo giá trị này |
aggrega.ai/sync-wave | Số nguyên syncWave theo từng boundary | Cả ba provider, khi khác không; là annotation trên helm và helm-chart |
Các giá trị aggrega.ai/aggregate-name, aggrega.ai/environment, aggrega.ai/compiler-version, aggrega.ai/provider và aggrega.ai/provider-version đến từ những chuỗi mà bản build không buộc phải tuân theo quy tắc giá trị nhãn của Kubernetes — một Aggregate tên là imported/flow, một môi trường tên là eu/prod, phiên bản (devel) của một bản build phát triển. Trên helm và helm-chart, mỗi nhãn này mang giá trị của nó đúng như đã viết khi giá trị đó đã là một giá trị nhãn hợp lệ: chữ cái, chữ số, -, _ và ., một chữ cái hoặc chữ số ở cả hai đầu, tối đa 63 ký tự. Nếu không, nhãn mang giá trị được viết lại theo dạng đó — mọi ký tự khác trở thành -, các chuỗi - liên tiếp được gộp thành một, hai đầu được cắt đến một chữ cái hoặc chữ số, và kết quả được cắt còn tối đa 63 ký tự — và giá trị nguyên văn được thêm vào dưới dạng annotation dưới cùng khóa. Do đó, một Aggregate tên là imported/flow được gắn nhãn aggrega.ai/aggregate-name: imported-flow và annotation aggrega.ai/aggregate-name: imported/flow; một giá trị không có ký tự nào mà nhãn giữ lại thì chỉ được mang bởi annotation. Một selector khớp với giá trị nhãn như nó xuất hiện trong đầu ra đã render, và công cụ cần tên chính xác sẽ đọc annotation khi có. Compose, với các giá trị nhãn không bị ràng buộc, mang giá trị nguyên văn làm nhãn.
Ghi chú phát ra theo từng provider
helm— các nhãn được đặt vàometadata.labelstrên mọi tài nguyên Kubernetes được render (Deployment, Service, PVC, v.v.), còn các khóa mà một giá trị nhãn không thể mang —aggrega.ai/recipe-uri,aggrega.ai/boundary-path,aggrega.ai/sync-wave, và giá trị nguyên văn của bất kỳ nhãn nào được viết lại như mô tả ở trên — được đặt vàometadata.annotations. Các luồng chế độ sourced (Helm SDK render kèm chèn nhãn sau render), chế độ synthesized (tổng hợp workload) vàartifacts:đều tạo ra cùng một tập.helm-chart— cùng các nhãn và annotation đó được đặt trên mỗi artifact được nạp bằng$import:mà provider thêm vàotemplates/của một sub-chart. Các template riêng của chart nguồn, và một artifact nội dung nội tuyến được đặt ở gốc sub-chart, không mang cái nào trong số đó — xem helm-chart.md.compose— các nhãn được đặt vàoservices.<name>.labelstrên mọi service compose được phát ra. Chế độ sourced (chèn nhãn sau merge trên tài liệu base + valuesMapping đã gộp) và chế độ synthesized (tổng hợp workload trực tiếp đặt khối labels của service) đều tạo ra cùng một tập nhãn. Nhãnapp.kubernetes.io/namedành riêng cho Kubernetes được bỏ khỏi đầu ra compose.
Với tài nguyên do một FeatureRecipe phát ra, giá trị aggrega.ai/component-id được xây dựng từ attachment thay vì từ tên của component chủ — với mọi cách mà một FeatureRecipe có thể cung cấp các tài nguyên đó, nên tài nguyên của một attachment không bao giờ bị lẫn theo nhãn với tài nguyên riêng của component chủ. Việc danh tính đó có đồng thời là thứ dùng để đặt tên cho các tài nguyên đó hay không tùy thuộc vào cách cung cấp: một workload do Aggrega tổng hợp được đặt tên theo danh tính, trong khi một chart hoặc fragment do tác giả attachment cung cấp giữ tên Helm release và tiền tố tệp đầu ra của component chủ, vì các template riêng của tác giả render theo tên đó. Cách giá trị được ghép — hai cách mở đầu, các phần và phép nối -- giữa chúng, cách viết ra một ký tự mà nhãn không chứa được, cách rút gọn một giá trị quá dài cho đích của nó, và nó là cơ sở cho những tên nào và không cho những tên nào — không phụ thuộc vào provider, nên được trình bày một lần tại vocabulary/labels-and-annotations.md “Provenance labels emitted on rendered output” thay vì lặp lại ở đây. Trang này đảm nhận nửa còn lại: các nhãn được đặt ở đâu trên đầu ra đã render của từng provider.
aggrega.ai/recipe-uri phân giải thành name:version riêng của FeatureRecipe, không phải danh tính của Recipe sử dụng nó — công cụ phía sau đọc nhãn để xác định thực thể tạo ra sẽ nhận được nguồn gốc chính xác cho cả đầu ra do component phát ra lẫn đầu ra do FR phát ra.
Các annotation sync-wave
Khóa aggrega.ai/sync-wave ở trên đi kèm với một annotation sync-wave mà công cụ hạ nguồn đọc để sắp xếp thứ tự những gì nó áp dụng. Trên compose, khóa này là một label, cung cấp giá trị wave cho các truy vấn selector; trên helm và helm-chart, nó là một annotation, và annotation đi kèm đưa giá trị ra ở vị trí mà mỗi công cụ theo quy ước đọc nó.
| Annotation | Phát ra | Được sử dụng bởi |
|---|---|---|
argocd.argoproj.io/sync-wave | helm, trên mọi tài nguyên Kubernetes mà nó render, và helm-chart, trên mỗi artifact được nạp bằng $import: — khi syncWave khác không trên boundary đóng góp | Sắp xếp thứ tự sync-wave của ArgoCD |
helm.sh/hook-weight | chỉ helm, trên các manifest được tạo từ template của chart đã mang annotation helm.sh/hook khi syncWave khác không | Sắp xếp thứ tự hook-weight của Helm trong một pha hook |
Việc phát ra helm.sh/hook-weight phụ thuộc vào đường dẫn
Một điểm tinh tế đáng lưu ý dành cho tác giả chart: helm.sh/hook-weight chỉ được phát ra trên các manifest được kết xuất qua đường chart-templating — thư mục templates/ của chart được kết xuất thông qua Helm SDK. Các Manifests được tạo qua đường artifacts — trên provider helm là mọi mục của khối artifacts: của Recipe, dù là nội dung nội tuyến hay được nạp bằng $import:, và trên helm-chart là một mục được nạp bằng $import: — mang annotation argocd.argoproj.io/sync-wave và toàn bộ tập nhãn nguồn gốc, nhưng chúng không nhận helm.sh/hook-weight — ngay cả khi artifact mang annotation helm.sh/hook.
Sự khác biệt này mang tính cấu trúc: helm.sh/hook và helm.sh/hook-weight là các nguyên thủy sắp xếp thứ tự của Helm runtime, áp dụng cho các tài nguyên hook được tạo từ template của chart. Các artifact do tác giả Recipe viết là các tài nguyên bổ sung được khai báo ở tầng Recipe; theo mặc định, chúng không tham gia vào vòng đời hook của Helm.
Nếu bạn cần sắp xếp thứ tự hook-weight của Helm trên một tài nguyên hook, hãy viết tài nguyên đó dưới dạng template của chart trong thư mục source: của một Recipe mà provider helm render, thay vì dưới dạng một mục artifacts:; các template của một sub-chart helm-chart được sao chép nguyên như đã viết và không nhận annotation nào trong hai annotation này. Template của chart sẽ nhận cả argocd.argoproj.io/sync-wave và helm.sh/hook-weight khớp với giá trị syncWave của boundary đóng góp.
Ví dụ soạn thảo
Vị trí đặt ở cấp boundary và cấu hình registry:
spec: boundaries: production: annotations: aggrega.ai/namespace: prod-east aggrega.ai/image-registry: registry.corp.com aggrega.ai/image-pull-secret: corp-registry-creds components: api: {} worker: {}Ghi đè theo từng component (component được ưu tiên hơn boundary trên cùng một khóa annotation):
spec: boundaries: production: annotations: aggrega.ai/namespace: prod-east components: api: {} legacy-thing: annotations: aggrega.ai/namespace: legacy-east # override — this component deploys elsewhereCascade annotation phía Aggregate
Annotation cũng nằm trên bề mặt soạn thảo Aggregate — ở phạm vi subsystem (spec.subsystems.<name>.annotations) và ở phạm vi instance component (spec.subsystems.<name>.components.<name>.annotations hoặc spec.components.<name>.annotations cho các component cấp cao nhất). Cascade phía Aggregate truyền các annotation do Developer soạn xuống qua cây subsystem tới các component được chứa.
Quy tắc cascade
Một annotation cấp subsystem lan truyền tới mọi subsystem lồng bên trong và mọi component được chứa trong cây con của subsystem đó. Annotation ở cấp gần hơn ghi đè annotation ở cấp ngoài hơn theo từng khóa: một annotation cấp component ghi đè mọi annotation cấp subsystem được kế thừa cho cùng khóa mà không ảnh hưởng tới các khóa ngang hàng hay các component ngang hàng.
Một khóa annotation tại một phạm vi ở một trong ba trạng thái:
- 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 giá trị chuỗi — phạm vi khai báo một giá trị. Các subsystem lồng bên trong và các component được chứa kế thừa giá trị này trừ khi chúng khai báo giá trị riêng hoặc chọn không tham gia.
- YAML
nulltường minh — phạm vi loại bỏ mọi binding được kế thừa cho khóa này khỏi cây con của nó. Các component ngang hàng và các subsystem ngang hàng giữ nguyên sự kế thừa độc lập của chúng; chỉ cây con của phạm vi chọn không tham gia mất binding.
spec: subsystems: data: annotations: feature.myco/db-pool: "shared-pool" # propagates to api and worker components: api: # inherits feature.myco/db-pool: "shared-pool" worker: annotations: feature.myco/db-pool: null # opts out for this component only special: annotations: feature.myco/db-pool: "vip-pool" # closer-level overrideCác annotation Provider được khai báo trong Aggregate
Các khóa trong ma trận ở trên cũng được truyền theo tầng qua Aggregate, và nhà cung cấp áp dụng những gì cơ chế truyền tầng để lại trên mỗi thành phần. aggrega.ai/namespace của một hệ thống con đặt mọi thành phần bên dưới nó; giá trị riêng của một thể hiện thành phần thì thay vào đó đặt chính thành phần đó. Một mô-đun mà Aggregate nhập vào mang cơ chế truyền tầng riêng của nó: các hệ thống con và thể hiện thành phần của nó tác động đến các thành phần riêng của mô-đun, và không gì mà Aggregate nhập khai báo vươn vào bên trong một mô-đun.
Release nằm trên Aggregate ở mọi khóa. Khi Release đặt một khóa cho một thành phần — trên ranh giới của nó hoặc trên mục riêng của thành phần — giá trị của Release được áp dụng; khi nó không đặt khóa nào, giá trị của Aggregate được áp dụng. Hai phía xếp lớp theo từng khóa, nên một Release chỉ đặt aggrega.ai/namespace sẽ để aggrega.ai/image-registry mà Aggregate đã khai báo tiếp tục có hiệu lực.
Một null tường minh trong Release chỉ rút lại giá trị riêng của Release. Một mục thành phần ghi aggrega.ai/namespace: null sẽ loại bỏ không gian tên mà ranh giới Release của nó lẽ ra đã trao cho nó, và khi đó thành phần nhận giá trị mà Aggregate của nó khai báo — hoặc không nhận giá trị nào, khi Aggregate cũng không khai báo giá trị nào. Một Release không thể loại bỏ một giá trị mà Aggregate khai báo; nó chỉ có thể đặt một giá trị của riêng mình đè lên giá trị đó.
# Aggregatespec: subsystems: billing: annotations: aggrega.ai/namespace: billing # api and worker render into billing components: api: type: core/server:1.0.0 worker: type: core/server:1.0.0 annotations: aggrega.ai/namespace: billing-batch # worker renders into billing-batch# Releasespec: boundaries: production: components: api: annotations: aggrega.ai/namespace: prod-billing # the Release's value wins: api renders into prod-billing worker: {}aggrega.ai/chart-name là khóa duy nhất nằm ngoài phạm vi này: nó đặt tên cho một umbrella chart được lắp ráp từ nhiều thành phần, nên nó được đọc từ các ranh giới Release đóng góp vào chart đó, không bao giờ từ các annotation của một thành phần.
Một template của Recipe hoặc FeatureRecipe đọc các nhóm annotation theo tên — .context.annotations.aggregate, .context.annotations.release và .context.annotations.catalog mỗi nhóm chứa những gì phía đó đã viết — nên một template đọc một khóa vị trí đặt từ một nhóm chỉ thấy giá trị của phía đó.
Phân chia phía và trụ cột
Bất biến Aggregate-as-Authoring-Surface giới hạn các annotation phía Aggregate vào trụ cột values. Một binding annotation của Manifest khai báo các đường dẫn định tuyến dưới maps.infra (định tuyến phía Release) hoặc maps.values (định tuyến phía Aggregate); một annotation phía Aggregate có binding chỉ khai báo các đường dẫn maps.infra sẽ dừng bản build với một chẩn đoán rõ ràng nêu tên khóa annotation, trụ cột được định tuyến và phía soạn thảo. Quy tắc đối xứng áp dụng cho phía Release: annotation phía Release chỉ được định tuyến qua maps.infra; một annotation phía Release đối với một binding chỉ có values sẽ phát ra lỗi tương ứng. Mỗi chẩn đoán được xếp vào miền của tài liệu nơi giá trị annotation được soạn — [DEVELOPER_ERROR] từ một Aggregate, [OPS_ERROR] từ một Release — để phần đầu nêu đúng bề mặt cần mở.
Các binding khai báo đường dẫn ở cả hai trụ cột sẽ định tuyến tập con tương thích với phía ở mỗi lượt: một annotation phía Aggregate chỉ kích hoạt các đường dẫn trụ cột values, và một annotation phía Release chỉ kích hoạt các đường dẫn trụ cột infra. Kết hợp chéo phía — values từ Aggregate, infra từ Release — tạo ra một Feature attachment cho mỗi cặp (Component, Feature) với cả hai trụ cột được điền và provenance theo từng lá ghi lại phía nào đã đóng góp mỗi lá.
Ví dụ soạn thảo — annotation subsystem định tuyến tới values
# Manifest bindingspec: mappings: features: type: core/db-pool: db-pool-helm:1.0.0 annotations: feature.myco/db-pool: feature: core/db-pool:1.0.0 maps: values: - pool # routes to values.pool# Aggregatespec: subsystems: data: annotations: feature.myco/db-pool: "shared-pool" components: api: type: core/server:1.0.0 worker: type: core/server:1.0.0Sau khi mở rộng annotation, cả api và worker đều mang một Feature attachment tổng hợp feature.myco/db-pool có trường values.pool đọc là "shared-pool". Đồ thị build (aggrega validate --release <release> --ir-graph) ghi lại mỗi lá với origin: annotation, side: aggregate và annotation_source: aggregate.yaml:subsystems.data.annotations.feature.myco/db-pool.
Giá trị annotation có cấu trúc
Một Feature có nhiều trường cấu hình được sẽ gợi ý dùng một khóa annotation duy nhất mang giá trị cho nhiều trường cùng lúc. Dạng annotation có cấu trúc cho phép một khóa định tuyến tới nhiều đường dẫn binding trong một lần khai báo:
# Aggregate Subsystem — Developer's intent for db-pool (values-pillar subkeys)subsystems: data: annotations: feature.myco/db-pool: db_name: "prod-db" read_replicas: 5# Release Boundary — Operator's sizing for db-pool (infra-pillar subkeys)boundaries: prod: annotations: feature.myco/db-pool: pool_size: 20 max_connections: 100Binding của Manifest khai báo định tuyến của cả bốn khóa con trong các danh sách maps: được nhóm theo trụ cột:
# Manifestspec: mappings: features: annotations: feature.myco/db-pool: feature: core/db-pool:1.0.0 maps: values: - db_name - read_replicas infra: - pool_size - max_connectionsHình dạng của giá trị annotation là một trong ba dạng:
- Chuỗi vô hướng — một giá trị đơn. Binding phải khai báo đúng một đường dẫn tổng cộng; giá trị vô hướng được định tuyến tới đường dẫn đó.
- Đối tượng có cấu trúc — một map từ khóa con tới giá trị con. Đường dẫn của mỗi khóa con phải xuất hiện trong danh sách
maps.infrahoặcmaps.valuescủa binding; giá trị con được định tuyến tới trường schema của Feature được chỉ định tại trụ cột đã khai báo. - YAML
nulltường minh — từ bỏ toàn bộ binding được kế thừa cho phạm vi cascade này.
Mỗi khóa con trong một giá trị có cấu trúc được phân giải độc lập theo danh sách maps của binding. Một khóa con không có trong cả maps.infra lẫn maps.values sẽ dừng bản build với một lỗi rõ ràng nêu tên khóa con vi phạm và các đường dẫn đã khai báo.
Hợp nhất cascade cho giá trị có cấu trúc
Annotation có cấu trúc được cascade với hợp nhất sâu theo từng khóa con. Annotation của một phạm vi cascade con được hợp nhất với annotation của cha theo từng khóa con; cấp gần hơn ghi đè cấp cha ở mức chi tiết khóa con:
subsystems: data: annotations: feature.myco/db-pool: db_name: "data-default" read_replicas: 3 components: api: annotations: feature.myco/db-pool: db_name: "api-override" # overrides parent at this subkey only # read_replicas not listed → inherits 3 from parent analytics: annotations: feature.myco/db-pool: read_replicas: null # per-subkey opt-out: removes inherited subkey # db_name not listed → inherits "data-default" from parentCác annotation có hiệu lực sau cascade:
- Component
api:{ db_name: "api-override", read_replicas: 3 } - Component
analytics:{ db_name: "data-default" }—read_replicasbị từ bỏ tại phạm vi này
Một cấp cascade con có giá trị vô hướng (so với cha có cấu trúc) sẽ thay thế toàn bộ thay vì hợp nhất. Sự không khớp hình dạng giữa các cấp cascade được giải quyết theo hướng ưu tiên giá trị ở cấp gần hơn; trình biên dịch không cảnh báo khi hình dạng không khớp.
Null toàn giá trị và null theo khóa con
Cascade có hai cơ chế từ bỏ ở các mức chi tiết khác nhau:
# Whole-value null — opts out wholesale at this scopecomponents: api: annotations: feature.myco/db-pool: nullToàn bộ binding annotation bị chặn tại component này; không có Feature attachment tổng hợp nào được tạo từ khóa annotation này tại phạm vi này. Các component cùng cấp vẫn giữ binding được kế thừa.
# Per-subkey null — opts out just one subkeycomponents: api: annotations: feature.myco/db-pool: db_name: "api-db" read_replicas: nullAnnotation vẫn tiếp tục đóng góp tại phạm vi này, nhưng khóa con read_replicas bị chặn. Các khóa con khác (được khai báo tại phạm vi này hoặc kế thừa từ các cấp cascade cha) vẫn giữ nguyên.
Hướng dẫn soạn thảo: dùng null toàn giá trị để vô hiệu hóa một Feature attachment do annotation điều khiển tại một phạm vi. Dùng null theo khóa con khi bạn muốn giữ phần lớn đóng góp của một annotation nhưng chặn một hoặc nhiều trường cụ thể.
Phân vùng phía và trụ cột theo khóa con
Bất biến Aggregate-as-Authoring-Surface áp dụng theo từng khóa con khi giá trị annotation có cấu trúc. Trụ cột của mỗi khóa con (theo khai báo maps của binding) phải tương thích với phía soạn thảo:
- Annotation phía Aggregate chỉ được mang các khóa con định tuyến tới
maps.values. - Annotation phía Release chỉ được mang các khóa con định tuyến tới
maps.infra.
Một khóa con định tuyến tới trụ cột không tương thích sẽ dừng bản build với một lỗi rõ ràng nêu cụ thể khóa con và trụ cột. Chuỗi lỗi thu thập tất cả các khóa con không tương thích của mỗi annotation trước khi dừng — người vận hành thấy mọi vấn đề trong mỗi chu kỳ build thay vì lặp đi lặp lại sửa-build-sửa-build.
Kiểm tra kiểu theo khóa con
Giá trị thời gian chạy của mỗi khóa con được kiểm tra theo kiểu được khai báo trong spec.schema của Feature đích tại trụ cột được định tuyến. Các kiểu khai báo được hỗ trợ là string, integer, number, boolean, object, array, null. Một giá trị con có kiểu YAML không khớp với kiểu khai báo của schema sẽ dừng bản build với một lỗi rõ ràng nêu tên khóa con, kiểu thực tế và kiểu đã khai báo.
Việc khớp kiểu là nghiêm ngặt — không ép kiểu. Một chuỗi "20" đặt vào trường schema kiểu integer sẽ gây dừng; tác giả khai báo kiểu chính xác trên schema của Feature hoặc dùng annotation vô hướng được truyền qua dưới dạng chuỗi.
Đòn bẩy soạn thảo cho kiểm tra nghiêm ngặt. Các thuộc tính không có type được khai báo trong spec.schema của Feature chấp nhận mọi hình dạng giá trị thời gian chạy, kể cả các map lồng nhau. Khi schema không khai báo ràng buộc, bản build không tự tạo ra ràng buộc. Tác giả muốn kiểm tra kiểu nghiêm ngặt theo khóa con sẽ khai báo type trên mọi thuộc tính trong spec.schema. Lớp render FeatureRecipe ở hạ nguồn xử lý bất kỳ hình dạng nào mà phần đóng góp của annotation mang theo.
Kết hợp xuyên phía
Khi cả một annotation phía Aggregate (khóa con values) và một annotation phía Release (khóa con infra) cùng nhắm tới cùng một Feature attachment trên cùng một Component, bản build hợp nhất các đóng góp thành một Feature attachment duy nhất với cả hai trụ cột được điền. Provenance theo từng lá ghi lại nguồn của mỗi khóa con — attachment được tổng hợp mang values.db_name được quy cho vị trí soạn thảo Aggregate và infra.pool_size được quy cho vị trí soạn thảo Release.
Mẫu kết hợp xuyên phía là hình dạng soạn thảo chuẩn cho các Features có hỗn hợp trường thể hiện ý định của Developer và trường định cỡ của Operator: Aggregate khai báo các lựa chọn nhận thức (cơ sở dữ liệu nào, bao nhiêu bản sao ở cấp ứng dụng); Release khai báo việc định cỡ vật lý (pool lớn đến đâu, bao nhiêu kết nối ở cấp hạ tầng). Một binding của Manifest gắn kết chúng với một tập khai báo maps duy nhất.
Tài liệu tham khảo liên quan
- Kiến trúc Provider — kiến trúc plugin của provider và vai trò của Plugin kết xuất provider.
- ../entities/release.md — bề mặt soạn thảo Release, nơi chứa các annotation cấp ranh giới và cấp component.
- ../entities/aggregate.md — bề mặt soạn thảo Aggregate, nơi chứa các annotation cấp hệ thống con và cấp component.
- ../entities/manifest.md — map
mappings.features.annotationscủa Manifest, nơi các binding annotation khai báo định tuyếnmaps:của chúng. - ../../architecture/11-governance-and-compliance.md — cơ chế đóng dấu nguồn gốc tại thời điểm biên dịch, bổ sung cho các annotation do tác giả kiểm soát.