Một chính sách gắn các Features mà không ai viết: các annotation được chèn tại `annotation-transform`
Một chính sách quản trị cung cấp cho mọi component của một cửa hàng khả năng giám sát của nền tảng và một vai trò AWS IAM. Nó làm điều đó bằng cách thêm annotation. Manifest gắn hai khóa annotation với hai Features, và một annotation dưới một khóa đã gắn sẽ mở rộng thành một phần gắn Feature. Vì vậy các annotation mà chính sách thêm vào mang đến cho mỗi component một Prometheus ServiceMonitor và một Kubernetes ServiceAccount, còn Aggregate và Release đều không viết thứ nào trong số đó.
Chính sách được gắn ở vai trò annotation-transform, một lần cho mỗi engine chính sách được biên dịch vào CLI: Rego và CEL. Bằng chứng trung tâm là một Release đối chứng viết tay cùng các annotation đó. Khi được build mà không có chính sách, nó render ra đúng các tệp, từng byte một, giống như Release mà chính sách gắn annotation.
Những gì ví dụ này xây dựng
| instance | Component trong catalog | những gì nó mang trong release.yaml |
|---|---|---|
api | example/compute/service | không gì cả |
worker | example/compute/service | không gì cả |
gateway | example/compute/service | annotation giám sát riêng của nó, với khoảng thời gian 10 giây |
Cả ba đều được biên dịch sang Kubernetes thông qua Helm, vào dist/shop/helm/. example/compute/service là một Component minh họa trong catalog của thư viện chuẩn. Mọi instance của nó phải mang một phần gắn core/prometheus-exporter, một yêu cầu mà Component nêu ra và bản build kiểm tra.
Hai binding chú thích
manifest.yaml gán ý nghĩa cho hai khóa chú thích:
features: type: core/prometheus-exporter: helm/prometheus-exporter:1.0.0 core/aws-irsa: helm/aws-irsa:1.0.0 annotations: feature.aggrega.ai/monitoring: feature: core/prometheus-exporter maps: infra: - interval - port - path aws-role: feature: core/aws-irsa maps: infra: - role_arnMột binding định tuyến nhiều khóa con nhận làm giá trị một đối tượng nêu tên từng khóa con, nên feature.aggrega.ai/monitoring nhận {interval: …, port: …, path: …}. Một binding định tuyến một khóa con nhận một chuỗi, nên aws-role nhận ARN của vai trò. Phần gắn kết mà một chú thích mở rộng thành được đặt tên theo khóa của nó. core/aws-irsa đặt tên ServiceAccount của nó theo phần gắn kết, đó là lý do khóa này không chứa dấu chấm hay dấu gạch chéo.
Gắn chính sách
.aggrega-config.yaml chỉ định hub làm registry của nó, không có thư mục catalog nào, và không có phần gắn kết quản trị nào. Chính sách được gắn bởi tệp mà một bản build chỉ định bằng --config: governance-rego.yaml cho engine Rego, governance-cel.yaml cho engine CEL. Tệp cho Rego như sau:
plugins: governance: - uri: governance/rego:0.9.0 role: annotation-transform with: sources: - policies/platform-defaults.rego--config chỉ định tệp cấu hình toàn cục cho lần chạy đó, thay cho tệp mà máy lẽ ra sẽ đọc, và .aggrega-config.yaml của workspace này vẫn được xếp chồng lên trên nó.
0.9.0 là một phiên bản mà hub công bố thực thể Plugin của từng engine, nên phần gắn kết được phân giải từ registry mà workspace đọc, hoặc từ binary aggrega của bản phát hành đó, vốn chứa nó. Engine chạy là engine được biên dịch vào binary aggrega đang chạy bản build, bất kể phần gắn kết nêu phiên bản nào. Đối tượng mà chú thích giám sát nhận cần một engine có thể chèn một đối tượng gồm các khóa con, và engine của các bản phát hành trước 0.8.7 không làm được điều đó.
Những gì một chính sách annotation-transform đọc
Một chính sách tại annotation-transform đọc hai thứ:
input.targetsliệt kê mọi component mà nó có thể chú thích. Mỗi đích có mộtboundary_path, mộtcomponent_namevà cácannotationsmà Release ghi trên component đó, mỗi giá trị đúng như đã viết.input.binding_keysliệt kê các khóa chú thích mà Manifest liên kết.
aggrega build --release <release> --dry-run --policy-input <dir> ghi payload mà mỗi vai trò nhận được vào <dir> và không ghi gì khác. Sau khi một bản build của release.yaml đã điền lockfile của nó:
aggrega build --release release.yaml --config governance-rego.yaml --dry-run --policy-input payloadsjq -c '.binding_keys' payloads/annotation-transform.json# ["feature.aggrega.ai/monitoring","aws-role"]jq -c '.targets[]' payloads/annotation-transform.json# {"boundary_path":"shop","component_name":"api","annotations":{}}# {"boundary_path":"shop","component_name":"worker","annotations":{}}# {"boundary_path":"shop","component_name":"gateway","annotations":{"feature.aggrega.ai/monitoring":{"interval":"10s","port":"metrics","path":"/metrics"}}}Các annotations của một đích chứa những gì Release ghi trên chính component đó. aggrega.ai/namespace của boundary không nằm trong số đó.
Chính sách
policies/platform-defaults.rego thu thập một quyết định cho mỗi chú thích dưới annotations. Mỗi quyết định nêu tên đích bằng hai trường mà nó được đọc theo, rồi đến khóa và giá trị:
annotations contains { "boundary_path": t.boundary_path, "component_name": t.component_name, "annotation_key": monitoring, "annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"},} if { monitoring in input.binding_keys some t in input.targets not monitoring in object.keys(t.annotations)}
annotations contains { "boundary_path": t.boundary_path, "component_name": t.component_name, "annotation_key": role, "annotation_value": sprintf("arn:aws:iam::123456789012:role/shop-%v", [t.component_name]),} if { role in input.binding_keys some t in input.targets not role in object.keys(t.annotations)}Mỗi quy tắc chỉ kích hoạt cho một khóa trong input.binding_keys, nên chính sách không thêm gì mà Manifest chưa gán ý nghĩa. Mỗi quy tắc cũng bỏ qua đích đã mang khóa đó. Một quyết định cho một khóa mà component đã mang sẽ thay thế giá trị Release đã ghi. Không có phép kiểm tra đó, gateway sẽ mất khoảng 10 giây của nó cho 30 giây của chính sách.
policies/platform-defaults.cel diễn đạt cùng hai quyết định thành một biểu thức, nối hai danh sách bằng +. Một khóa map được kiểm tra bằng in thay vì object.keys, và ARN của vai trò được nối bằng +, vì ngôn ngữ biểu thức không có sprintf. Nửa biểu thức dành cho vai trò như sau:
+ input.targets .filter(t, "aws-role" in input.binding_keys && !("aws-role" in t.annotations)) .map(t, { "boundary_path": t.boundary_path, "component_name": t.component_name, "annotation_key": "aws-role", "annotation_value": "arn:aws:iam::123456789012:role/shop-" + t.component_name, }),Những gì bản build render
aggrega build --release release.yaml --config governance-rego.yaml --auto-pullghi mười hai tệp dưới dist/shop/helm/: một Deployment và một Service cho mỗi component, ServiceMonitor mà chú thích giám sát của nó mở rộng thành, và ServiceAccount mà chú thích aws-role của nó mở rộng thành. spec của ServiceMonitor của api, từ chú thích mà chính sách đã chèn:
spec: selector: matchLabels: app.kubernetes.io/name: api endpoints: - port: metrics interval: 30s path: /metricsCái của gateway mang interval: 10s, giá trị mà mục Release của nó ghi. ServiceAccount mà api chạy dưới đó, từ aws-role được chèn:
apiVersion: v1kind: ServiceAccountmetadata: name: api-aws-role namespace: shop annotations: eks.amazonaws.com/role-arn: "arn:aws:iam::123456789012:role/shop-api" aggrega.ai/boundary-path: shop aggrega.ai/recipe-uri: "aws-irsa:1.0.0" [… omitted: the labels, which carry the version of the aggrega binary that built the file]Được chèn hay viết tay: cùng các tệp
release-by-hand.yaml là release.yaml với các chú thích mà chính sách chèn được viết tay trên từng component. Khi build mà không gắn chính sách nào,
aggrega build --release release-by-hand.yaml --auto-pullnó ghi ra cùng mười hai tệp, giống từng byte, như release.yaml với chính sách được gắn trên engine nào cũng vậy. Không có gì bị loại khỏi phép so sánh đó: việc một chú thích có được chèn hay không không được ghi lại trong bất kỳ tệp được render nào. check.sh so sánh các cây thư mục ở mọi lần chạy.
Bản build đọc một giá trị được chèn đúng như cách nó đọc cùng giá trị đó được viết trong Release, nên giá trị mở rộng thành cùng phần gắn kết.
Nơi việc chèn được ghi lại
Đồ thị build ghi lại nó, và --ir-graph in đồ thị ra. Mọi component nhận được một chú thích được chèn đều mang aggrega.ai/injected-by, nêu tên plugin, trong số các chú thích Release của nó. Sau aggrega build --release release.yaml --config governance-rego.yaml --auto-pull --ir-graph, api như sau:
"release_annotations": { "aggrega.ai/namespace": "shop", "aws-role": "arn:aws:iam::123456789012:role/shop-api", "aggrega.ai/injected-by": "governance/rego"},Bản ghi theo từng component, không theo từng khóa: gateway cũng mang nó, vì aws-role của nó. Mỗi phần gắn kết mà các chú thích mở rộng thành có "origin": "annotation" trong đồ thị, giống như với một chú thích viết tay.
Target Helm không render chú thích aggrega.ai/injected-by, và nó có thông báo như vậy. Trong bản build này, mỗi component nhận việc chèn sẽ thêm ba cảnh báo vào đầu ra. Cảnh báo đầu tiên của api như sau:
warning: node "api" (provider "helm"): target "helm" does not support annotation aggrega.ai/injected-by on synthesized input and ignored it--no-unsupported-field-warnings tắt loại cảnh báo đó, và không thay đổi gì trong những gì bản build ghi ra.
Vai trò này thêm chú thích, và không gì khác
Một quyết định nêu tên một component, một khóa chú thích và giá trị của nó. Không có gì trong một quyết định thêm component, thay đổi nhãn, hay gắn trực tiếp một Feature. Chính sách chỉ chạm tới một Feature thông qua một khóa mà Manifest liên kết, và Manifest quyết định đó là Feature nào.
Một quyết định cũng không thể xóa một chú thích. Giá trị của nó là một chuỗi hoặc một đối tượng gồm các khóa con, và null bị từ chối, kèm tên việc chèn, vì null là cách tác giả cho một component không nhận một chú thích mà lẽ ra nó sẽ kế thừa.
Một chuỗi ở nơi binding định tuyến ba khóa con
governance-monitoring-as-string.yaml gắn policies/monitoring-as-string.rego, chính sách này chèn chuỗi "30s" dưới khóa giám sát. Binding đó định tuyến ba khóa con, và một chuỗi không nêu tên khóa nào, nên
aggrega build --release release.yaml --config governance-monitoring-as-string.yaml --auto-pulldừng lại, thoát với 1 và không ghi dist/. Chính sách đã chèn chuỗi đó trên api và trên worker, và mỗi lần chèn đều bị từ chối. Mỗi lời từ chối nêu tên plugin đã chèn giá trị và vai trò mà nó được gắn vào, nên giá trị được truy về chính sách đã quyết định nó, thay vì về một dòng của Release mà không ai viết:
[… omitted: a warning that the attachment is in the global configuration named with --config][OPS_ERROR E0367] .spec.boundaries.shop.components.api.annotations a scalar annotation value does not route to exactly one path of its binding (Release shop-production, at .spec.boundaries.shop.components.api.annotations, "feature.aggrega.ai/monitoring", carrying the bare value "30s", whose binding routes "interval, port, path", whose value plugin "governance/rego" injected at governance role "annotation-transform")---[OPS_ERROR E0367] .spec.boundaries.shop.components.worker.annotations a scalar annotation value does not route to exactly one path of its binding (Release shop-production, at .spec.boundaries.shop.components.worker.annotations, "feature.aggrega.ai/monitoring", carrying the bare value "30s", whose binding routes "interval, port, path", whose value plugin "governance/rego" injected at governance role "annotation-transform")Khi không có chính sách
release.yaml được build mà không có phần gắn kết quản trị nào
aggrega build --release release.yaml --auto-pullsẽ dừng lại. Component của nó yêu cầu một phần gắn kết core/prometheus-exporter, và không có gì cung cấp phần đó cho api hay worker:
[DEVELOPER_ERROR E0162] aggregate.yaml at .spec.components.api missing required feature: attach a Feature of the required type to the component ("core/prometheus-exporter", required by component type "example/compute/service", under the requirement label "monitoring")---[DEVELOPER_ERROR E0162] aggregate.yaml at .spec.components.worker missing required feature: attach a Feature of the required type to the component ("core/prometheus-exporter", required by component type "example/compute/service", under the requirement label "monitoring")gateway không bị nêu tên, vì mục Release của nó tự ghi phần giám sát của mình. Khi gắn chính sách, cùng Release đó build được: một phần gắn kết mà chú thích được chèn mở rộng thành đáp ứng yêu cầu, giống như một phần gắn kết viết tay.
Lockfile ghi lại những gì
Một phần gắn kết annotation-transform thay đổi những gì bản build render, nên lockfile ghim nó. Sau bản build Rego, release.lock chứa phần gắn kết dưới mutators:, với plugin, vai trò, cùng nội dung và digest của tệp chính sách:
mutators: - plugin: governance/rego role: annotation-transform sources: - content: | [… omitted: the policy file, as written] digest: sha256:9779faf366fc131b1a56ea68ccbae811173e3642943909f8d4ca63c00df8781b path: platform-defaults.regoNó cũng ghim plugin dưới plugins::
plugins: - uri: governance/rego [… omitted: the artifact digest, which depends on the aggrega binary that built it, recorded twice] referenced_from: - governance/rego:0.9.0Phần gắn kết nêu một phiên bản mà hub công bố, nên bản ghim được phân giải qua registry mà workspace đọc, hoặc từ binary aggrega của bản phát hành đó.
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ó:
aggrega scaffold --example policy-annotation-transformSau đó 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:
cd policy-annotation-transformBuild
aggrega build --release release.yaml --config governance-rego.yaml --auto-pullaggrega build --release release.yaml --config governance-cel.yaml --auto-pullaggrega build --release release-by-hand.yaml --auto-pullCatalog thư viện chuẩn cung cấp mọi Component, Feature, Recipe và FeatureRecipe ở đây, cùng các thực thể Plugin của cả hai engine. Chúng được phân giải từ hub.aggrega.ai, registry mặc định mà .aggrega-config.yaml nêu tên. Khi một bản checkout của catalog (lấy ở đâu) được chỉ định bằng --catalog, không có gì được tải từ registry, nên các bản build chạy ngoại tuyến. --auto-pull điền lockfile của mỗi Release trong quá trình build. Lockfile và đầu ra được render được sinh ra, không được phân phối kèm.
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ỉ 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 Workspace chưa có thư mục `policy-annotation-transform`, hãy gọi công cụ `scaffold` một lần với `example` đặt thành `policy-annotation-transform` và không có `dir`: công cụ này ghi ví dụ vào một thư mục `policy-annotation-transform` mới. Sau đó gọi công cụ `cli-build`, công cụ chạy `aggrega build` và nhận cờ `--config` của lệnh đó, với `workspace_root` đặt thành `policy-annotation-transform`, `release` đặt thành `release.yaml`, `auto_pull` đặt thành true và `config` đặt thành `governance-rego.yaml`; rồi gọi lại theo cùng cách với `config` đặt thành `governance-cel.yaml`. Cuối cùng, gọi công cụ `build` với `workspace_root` đặt thành `policy-annotation-transform`, `release` đặt thành `release-by-hand.yaml`, `auto_pull` đặt thành true và `write` đặt thành true. Cho tôi biết mỗi bản dựng đã ghi những tệp nào; chúng nằm trong `policy-annotation-transform/dist/`.Kiểm tra mọi bản build
Bước tự kiểm tra này chạy trong một bản checkout của kho tài liệu, nơi chứa script trợ giúp build dùng chung mà nó sử dụng; một bản sao do aggrega scaffold --example ghi ra không có script trợ giúp đó.
./check.shcheck.sh thực hiện năm bản build thông qua trình trợ giúp build-release và đối chiếu từng kết quả với kết quả mà trang này mô tả:
release-by-hand.yamlkhông có chính sách là chuẩn tham chiếu. Nó phải render sáu tệp mà các chú thích mở rộng thành.release.yamlkhông có chính sách phải dừng vớiE0162choapivàworker, và không cho component nào khác.release.yamlcó chính sách được build một lần trên mỗi engine. Mỗi bản build phải ghi ra các tệp của chuẩn tham chiếu giống từng byte, ghim plugin trong lockfile của nó, và ghi lại cả ba component là được chèn bởi plugin đó.release.yamlvới chuỗi được cài sẵn phải dừng với lời từ chối ở trên.
Nó in một dòng cho mỗi bản build, rồi đến các tệp mà hai binding đã render, và thoát với 1 nếu có kết quả nào khác, đồng thời in đầu ra của bản build đó:
POLICY RELEASE EXIT EXPECTED VERDICT----------------------------------------------------------------------------------------------------none release-by-hand.yaml 0 reference OK: the six attachments' filesnone release.yaml 1 halt OK: E0162 for api and workerrego release.yaml 0 pass OK: byte-identical to the build by hand; pinned; injectedcel release.yaml 0 pass OK: byte-identical to the build by hand; pinned; injectedstring release.yaml 1 halt OK: refused, naming the plugin and its role
files the two annotation bindings rendered, release.yaml with governance-rego.yaml: shop/helm/api--aws-role--api-serviceaccount-shop-api-aws-role.yaml shop/helm/api--feature-zdaggrega-zdai-zsmonitoring--api-servicemonitor-shop-api-scrape.yaml shop/helm/gateway--aws-role--gateway-serviceaccount-shop-gateway-aws-role.yaml shop/helm/gateway--feature-zdaggrega-zdai-zsmonitoring--gateway-servicemonitor-shop-gateway-scrape.yaml shop/helm/worker--aws-role--worker-serviceaccount-shop-worker-aws-role.yaml shop/helm/worker--feature-zdaggrega-zdai-zsmonitoring--worker-servicemonitor-shop-worker-scrape.yaml
check: every build ended as expected.Mỗi bản build chạy trong bản sao riêng của workspace này, được tạo trong một thư mục tạm, với đường dẫn catalog trong .aggrega-config.yaml của nó được chuyển thành tuyệt đối để vẫn phân giải được từ đó. Không có gì trong thư mục này bị ghi. Nó dùng binary mà trình trợ giúp build-release phân giải, nên AGGREGA_BIN chọn binary đó, và các đối số sau -- được chuyển tới mọi bản build. Trạng thái thoát của nó là toàn bộ kết luận.
Nơi trình biên dịch không diễn giải
Trình biên dịch trao cho chính sách các component và các khóa đã liên kết. Nó thêm các chú thích mà chính sách quyết định, và mở rộng chúng qua các binding của Manifest như cách nó mở rộng bất kỳ chú thích nào. Nó không biết rằng một dịch vụ nên được giám sát, khoảng scrape là gì, hay một component nên chạy dưới vai trò IAM nào: những ý nghĩa đó thuộc về chính sách và Manifest. Về các vai trò, payload và khóa quyết định, xem socket quản trị. Về việc mở rộng chú thích không có chính sách, xem annotation-driven-monitoring.
Các tệp
aggregate.yaml— ba dịch vụ, không có chú thích.manifest.yaml— liên kết loại component và hai Features với các Helm Recipes của chúng, và hai khóa chú thích với hai Features.release.yaml— Release mà chính sách chú thích; chỉgatewayghi một chú thích.release-by-hand.yaml— đối chứng: mọi chú thích được viết tay..aggrega-config.yaml— registry mặc định; không có phần gắn kết quản trị.governance-rego.yaml,governance-cel.yaml— chính sách được gắn tạiannotation-transformqua từng engine, mỗi tệp được chỉ định bằng--config.governance-monitoring-as-string.yaml— lỗi được cài sẵn, được chỉ định bằng--config.policies/platform-defaults.rego,policies/platform-defaults.cel— chính sách, mỗi engine một bản.policies/monitoring-as-string.rego— lỗi được cài sẵn.build-release.sh— build một Release, in ra lệnhaggrega buildtương đương.check.sh— thực hiện năm bản build và kiểm tra từng kết quả.