Các chính sách định hình nhãn: một mức hỗ trợ cho mỗi môi trường, và một phán quyết đọc nó
Các plugin quản trị gắn nhãn cho mọi component mà workspace này triển khai với chủ sở hữu, mức hỗ trợ mà môi trường của nó được hưởng, lịch sao lưu và một thẻ ngắn, để không nhà phát triển nào phải tự gõ chúng. Các nhãn được suy ra trong quá trình build bởi bốn phần gắn kết quản trị:
- ba phần ở vai trò
label-transform, định hình nhãn trên các node của bản build: một chính sách Rego đọc môi trường của Release, và hai plugin gắn thẻ được biên dịch vào CLI,label-injectorvàselector-tagger; - một phần ở vai trò
ir-verdict, một chính sách Rego trên đồ thị build, dừng một bản build production trong đó có một node bị bỏ lại không có mức hỗ trợ.
Hai Releases của một Aggregate khác nhau ở môi trường, staging và production, và các node của chúng kết thúc với các nhãn khác nhau. Một bản build thứ ba, mà check.sh thực hiện từ một bản sao của workspace này có chính sách bao phủ ít hơn một hạng mục, sẽ dừng lại và nêu tên node mà nó bỏ sót.
Những gì ví dụ này xây dựng
| instance | Component trong catalog | vai trò ở đây |
|---|---|---|
db | core/datastore/mariadb | cơ sở dữ liệu của cửa hàng |
cache | core/datastore/redis | bộ đệm phiên của nó |
web | core/devtool/adminer | một giao diện quản trị cơ sở dữ liệu, được nối tới db |
Cả ba được biên dịch sang Docker Compose, vào dist/compose/docker-compose.yaml. Aggregate và cả hai Releases đều không nêu nhãn riêng nào: mọi nhãn dưới đây đều do một phần gắn kết ghi.
Bốn phần gắn kết
Chúng được gắn trong .aggrega-config.yaml của workspace này, dưới plugins.governance, nên mọi bản build chạy ở đây đều áp dụng chúng:
| plugin | vai trò | những gì nó ghi | |
|---|---|---|---|
| 1 | governance/rego:0.9.0, với policies/support-tier.rego | label-transform | ops.example.com/environment trên mọi node; ops.example.com/support-tier trên mọi node có hạng mục được liệt kê trong cài đặt của nó |
| 2 | governance/label-injector:0.9.0 | label-transform | ops.example.com/owner trên mọi node; backup.example.com/schedule trên mọi node thuộc hạng mục datastore |
| 3 | governance/selector-tagger:0.9.0 | label-transform | tag, từ map trong policies/tags.yaml |
| 4 | governance/rego:0.9.0, với policies/production-support.rego | ir-verdict | không gì cả: nó dừng bản build, hoặc để bản build hoàn tất |
0.9.0 là phiên bản của ba thực thể Plugin trong catalog thư viện chuẩn; bản thân các plugin được biên dịch vào CLI, và một bản build cung cấp chúng từ đó. aggrega build --release release-production.yaml --auto-pull --detail liệt kê cả hai, cho từng plugin trong ba:
[… omitted: the line counting what the pull resolved, and the rows for the Components, the Recipes, the Feature and the FeatureRecipes, each read from the registry] in-binary Plugin governance/label-injector ← governance/label-injector:0.9.0 in-binary Plugin governance/label-injector:0.9.0 ← .aggrega-config.yaml.plugins.governance in-binary Plugin governance/rego ← governance/rego:0.9.0 in-binary Plugin governance/rego:0.9.0 ← .aggrega-config.yaml.plugins.governance in-binary Plugin governance/selector-tagger ← governance/selector-tagger:0.9.0 in-binary Plugin governance/selector-tagger:0.9.0 ← .aggrega-config.yaml.plugins.governance[… omitted: the rows for this workspace's Aggregate and Manifest, the pull's summary, a lint notice about core/secret-value, and the build's summary]Các phần gắn kết tại một vai trò chạy theo thứ tự được liệt kê, và mỗi phần đọc các nhãn mà những phần trước nó đã ghi: bộ chèn nhãn nhận hai nhãn mà chính sách Rego đã ghi, và bộ gắn thẻ theo selector nhận các nhãn đó cùng nhãn của bộ chèn nhãn. Phán quyết chạy sau cả ba, trên đồ thị mà chúng để lại.
Những gì một chính sách label-transform đọc
Một chính sách tại label-transform đọc các node tại input.graph.nodes, được đánh khóa theo id node, mỗi node có:
component— Component mà node khởi tạo, chẳng hạncore/datastore/mariadb;resolved_version— phiên bản mà Component đó được phân giải thành;labels— các nhãn mà node mang khi chính sách chạy: nhãn riêng của Component, và các nhãn mà bất kỳ phép biến đổi nào trước đó đã ghi;values— các giá trị mà instance của node khai báo trong Aggregate, không có khi nó không khai báo giá trị nào. Ở đây chỉdbkhai báo một giá trị,database: appdb.
Nó đọc Release tại input.compilation_context: release_name và environment. Chính điều đó cho phép một chính sách quyết định khác nhau theo từng môi trường.
Ngược lại, một chính sách tại ir-verdict đọc toàn bộ đồ thị build, và các node của nó nằm sâu hơn một cấp, tại input.graph.spec.nodes. Một quy tắc được chuyển từ vai trò này sang vai trò kia phải được sửa, không phải sao chép: với đường dẫn sai, nó không đọc được gì và không bao giờ kích hoạt. Payload ir-verdict không mang compilation_context, nên một phán quyết không thể đọc môi trường từ Release. Đó là lý do chính sách đầu tiên ở đây cũng ghi ops.example.com/environment trên mọi node: phán quyết đọc môi trường từ nhãn đó.
Để xem các payload thay vì đọc về chúng, hãy build một lần để lockfile tồn tại, rồi:
aggrega build --release release-production.yaml --dry-run --policy-input payloadsghi payload mà mỗi phần gắn kết nhận được vào payloads/, mỗi phần gắn kết một tệp ở nơi nhiều phần gắn kết tại một vai trò nhận các payload khác nhau — label-transform.1.rego.json, label-transform.2.label-injector.json, label-transform.3.selector-tagger.json — bên cạnh một tệp cho mỗi vai trò khác, và không ghi gì khác.
Chính sách Rego
policies/support-tier.rego thu thập các quyết định của nó dưới labels, mỗi nhãn một quyết định, nêu tên node, khóa nhãn và giá trị:
env := input.compilation_context.environment
labels contains {"node": id, "key": "ops.example.com/environment", "value": env} if { some id, _ in input.graph.nodes}
labels contains {"node": id, "key": "ops.example.com/support-tier", "value": data.support_tiers[env]} if { some id, node in input.graph.nodes node.labels["component.aggrega.ai/category"] in data.supported_categories}Các cài đặt của nó là tài liệu data của chính sách, và chúng chứa bộ từ vựng của tổ chức:
settings: # The categories whose components get a support tier. supported_categories: [datastore, devtool] # The tier each environment gives them. support_tiers: production: on-call staging: office-hoursNhững gì mỗi plugin tích hợp sẵn ghi
label-injector áp dụng một danh sách quy tắc. Một node có nhãn bao gồm mọi cặp dưới match của một quy tắc sẽ nhận mọi cặp dưới set của nó, được thêm vào, hoặc thay thế giá trị của một nhãn mà node đã mang. Một match không có cặp nào khớp với mọi node. Nó đọc các quy tắc từ cài đặt rules của nó, như ở đây, hoặc, khi cài đặt không có quy tắc nào, từ tệp đầu tiên dưới sources có quy tắc. Hai quy tắc của nó ở đây gán cho mọi node ops.example.com/owner: shop-team, và cho db và cache, hai node trong hạng mục datastore, backup.example.com/schedule: nightly. web thuộc hạng mục devtool và không nhận lịch sao lưu.
selector-tagger ghi một nhãn, luôn dưới khóa tag. Giá trị của nó đến từ một map từ tên Component sang thẻ, được đọc từ các tệp dưới sources. Một node có Component không được map liệt kê sẽ lấy cài đặt default, và khi không có default thì nó không có tag. policies/tags.yaml ánh xạ cơ sở dữ liệu và bộ đệm:
core/datastore/mariadb: orderscore/datastore/redis: sessionsvà default của phần gắn kết là untagged, nên web được gắn thẻ untagged.
Cả hai chỉ quyết định dựa trên nhãn của node và Component của nó. Không cái nào đọc môi trường, nên chúng ghi cùng các nhãn trong cả hai Releases.
Cả hai chỉ phục vụ label-transform. Khi được gắn tại ir-verdict, cái nào cũng bị từ chối trước khi chạy; selector-tagger được gắn ở đó sẽ dừng bản build với:
[E0085] ir-verdict: plugin "governance/selector-tagger:0.9.0": call "verdict_ir": wasm: plugin "selector-tagger" does not declare export "verdict_ir" in describe(): wasm: plugin rejected by the sandboxTạ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-label-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-label-transformBuild
aggrega build --release release-staging.yaml --auto-pullaggrega build --release release-production.yaml --auto-pullCatalog thư viện chuẩn cung cấp mọi Component, Recipe và Feature ở đây cùng ba thực thể Plugin. 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-label-transform`, hãy gọi công cụ `scaffold` một lần với `example` đặt thành `policy-label-transform` và không có `dir`: công cụ này ghi ví dụ vào một thư mục `policy-label-transform` mới. Sau đó gọi công cụ `build` một lần cho mỗi Release, theo thứ tự này — `release-staging.yaml` và `release-production.yaml` — mỗi lần với `workspace_root` đặt thành `policy-label-transform`, `release` đặt thành tệp đó, `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-label-transform/dist/`.Các nhãn mà mỗi node cuối cùng mang
--ir-graph in đồ thị build ra đầu ra chuẩn, trước phần tóm tắt của bản build, và đồ thị mang nhãn của mỗi node đúng như các phép biến đổi để lại. Sau aggrega build --release release-production.yaml --auto-pull --ir-graph, web như sau:
"web": { "labels": { "component.aggrega.ai/type": "server", "component.aggrega.ai/category": "devtool", "component.aggrega.ai/upstream-licensing": "osi-approved", "ops.example.com/environment": "production", "ops.example.com/support-tier": "on-call", "ops.example.com/owner": "shop-team", "tag": "untagged" }, [… omitted: the node's Component, its version, where it is placed, its catalog metadata, the file it was declared in, and its connection to db]}Ba nhãn đầu là của chính Component; bốn nhãn cuối do ba phép biến đổi ghi. check.sh đọc đồ thị của mỗi bản build và liệt kê các nhãn mà các phần gắn kết đã ghi:
labels the attachments wrote, release-staging.yaml: db ops.example.com/environment: staging ops.example.com/support-tier: office-hours ops.example.com/owner: shop-team backup.example.com/schedule: nightly tag: orders cache ops.example.com/environment: staging ops.example.com/support-tier: office-hours ops.example.com/owner: shop-team backup.example.com/schedule: nightly tag: sessions web ops.example.com/environment: staging ops.example.com/support-tier: office-hours ops.example.com/owner: shop-team tag: untagged
labels the attachments wrote, release-production.yaml: db ops.example.com/environment: production ops.example.com/support-tier: on-call ops.example.com/owner: shop-team backup.example.com/schedule: nightly tag: orders cache ops.example.com/environment: production ops.example.com/support-tier: on-call ops.example.com/owner: shop-team backup.example.com/schedule: nightly tag: sessions web ops.example.com/environment: production ops.example.com/support-tier: on-call ops.example.com/owner: shop-team tag: untaggedChỉ hai nhãn của chính sách Rego thay đổi giữa các Releases.
Khi một bản build đã điền lockfile, aggrega inspect release-production.yaml --ir-graph in cùng đồ thị đó mà không build, trước phần hiển thị dễ đọc của Release, vì các phép biến đổi đọc tệp của chúng từ lockfile. Không có lockfile, đồ thị nó in ra không mang nhãn nào mà các tệp đó quyết định: không có ops.example.com/environment hay ops.example.com/support-tier, và tag: untagged trên mọi node.
Một phép biến đổi thay đổi nhãn và không gì khác
Một quyết định tại label-transform nêu tên một node, một khóa nhãn và giá trị của nó, hoặc yêu cầu xóa một nhãn. Không có quyết định nào thêm node, thay đổi Component hay phiên bản của một node, hay chạm vào các giá trị của nó, nên một phép biến đổi không thể diễn đạt bất kỳ điều nào trong số đó. Một quyết định nêu tên một node mà bản build không có sẽ không bị bỏ qua: bản build dừng với E0069 và nêu tên node cùng nhãn mà nó không thể đặt.
Hai bản build của release-production.yaml, có các phần gắn kết này và không có, cho thấy điều đó. Đồ thị build của chúng khác nhau ở các nhãn liệt kê ở trên và không gì khác. Đầu ra được render của chúng hoàn toàn không khác: các Recipes Compose ở đây không render nhãn nào trong số này, nên dist/compose/docker-compose.yaml là cùng một tệp, giống từng byte, dù có hay không có các phần gắn kết, và check.sh so sánh hai cây ở mọi lần chạy. Các nhãn nằm trong đồ thị build, nơi phán quyết đọc chúng.
Phán quyết, và bản build mà nó dừng
policies/production-support.rego được gắn tại ir-verdict, sau các phép biến đổi, và đọc các nhãn mà chúng đã ghi:
deny contains msg if { some id, node in input.graph.spec.nodes node.labels["ops.example.com/environment"] == "production" not node.labels["ops.example.com/support-tier"] msg := sprintf("%v is built for production and carries no ops.example.com/support-tier label", [id])}Cả hai Releases đều build được: trong staging, phán quyết không yêu cầu gì, và trong production mọi node đều mang một mức. Thu hẹp phạm vi của chính sách, và phán quyết sẽ bắt được node mà nó bỏ sót. Với supported_categories được viết là [datastore] trong .aggrega-config.yaml, web không nhận mức hỗ trợ, và aggrega build --release release-production.yaml --auto-pull dừng lại:
[… omitted: the pull's lines, which carry the refusal below once more, and a lint notice about core/secret-value][POLICY_ERROR E0005] policy plugin "rego" rejected the build: web is built for production and carries no ops.example.com/support-tier label caused by: policy violationBản build thoát với 1 và không ghi dist/. release-staging.yaml vẫn build được với chính sách đã thu hẹp: các node của nó được gắn nhãn staging, và phán quyết không yêu cầu gì ở chúng. check.sh thực hiện bản build này trong một bản sao của workspace, nên không cần sửa gì ở đây để thấy nó.
Một phán quyết chấp nhận hoặc từ chối và không làm gì khác: nó không thể thêm nhãn còn thiếu để bản build vượt qua. Một node production phải mang nhãn nào là quy tắc của tổ chức, được viết trong chính sách của nó; trình biên dịch mang các nhãn tới đồ thị dưới dạng chuỗi và không gán ý nghĩa nào cho chúng.
Lockfile ghi lại những gì
Lockfile ghi lại hai loại phần gắn kết theo cách khác nhau. Sau một bản build production, release-production.lock chứa mỗi phần gắn kết biến đổi dưới mutators: — plugin, vai trò, cài đặt, cùng nội dung và digest của từng tệp của nó — và ghim mỗi plugin biến đổi dưới plugins::
plugins: - uri: governance/label-injector [… omitted: the artifact digest, which depends on the aggrega binary that built it, recorded twice] referenced_from: - governance/label-injector:0.9.0 - uri: governance/rego [… omitted: the artifact digest, recorded twice] referenced_from: - governance/rego:0.9.0 - uri: governance/selector-tagger [… omitted: the artifact digest, recorded twice] referenced_from: - governance/selector-tagger:0.9.0Phần gắn kết phán quyết chỉ xuất hiện dưới verdict_inputs:, theo sha256 của tệp của nó:
verdict_inputs: - plugin: governance/rego:0.9.0 role: ir-verdict sources: - digest: sha256:5e01fc76f791ef00eba02f02ffb383437c87531f3927ee4a91cec9bf9c6e8cd8 path: production-support.regoMột phần gắn kết phán quyết không được ghim. Khi chỉ gắn phán quyết — ba phép biến đổi bị xóa khỏi .aggrega-config.yaml — lockfile chứa mutators: [] và plugins: [], và tệp của phán quyết dưới verdict_inputs:. Một phép biến đổi thay đổi bản build mà phần còn lại của pipeline làm việc dựa trên, nên lockfile giữ plugin đã tạo ra thay đổi; một phán quyết chỉ quyết định bản build có hoàn tất hay không.
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 bốn 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-production.yamltrong một bản sao của workspace này không có phần gắn kết quản trị nào, làm chuẩn tham chiếu;release-staging.yamlvàrelease-production.yamlở đây, mỗi cái phải hoàn tất với các nhãn liệt kê ở trên trên mỗi node, cây production phải giống từng byte với cây của chuẩn tham chiếu;release-production.yamltrong một bản sao có chính sách chỉ bao phủ hạng mụcdatastore, phải dừng vớiE0005và câu ở trên, và không có lời từ chối nào khác bên cạnh.
Nó in một dòng cho mỗi bản build, rồi đến các nhãn, 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 đó:
RELEASE GOVERNANCE EXIT EXPECTED VERDICT----------------------------------------------------------------------------------------------------release-production.yaml none 0 reference OKrelease-staging.yaml as attached 0 pass OK: the expected labelsrelease-production.yaml as attached 0 pass OK: the expected labels; byte-identical to the build with nonerelease-production.yaml narrowed 1 halt OK: E0005, the expected sentence[… omitted: the two label listings shown above]check: every build ended as expected.Hai bản sao được tạo trong một thư mục tạm, với đường dẫn catalog trong .aggrega-config.yaml của chúng được chuyển thành tuyệt đối để vẫn phân giải được từ đó. Không tệp nào trong thư mục này bị sửa; hai bản build thực hiện ở đây điền các lockfile của nó, như mọi bản build. Nó dùng binary mà ./build-release.sh 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. Nó từ chối khởi chạy khi có một dist/ nằm trong thư mục này, vì nó so sánh các cây mà các bản build ghi ra, và nó không để lại cây nào. 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 mỗi phép biến đổi các node và môi trường của Release, áp dụng các nhãn mà nó quyết định, và trao kết quả cho phán quyết. Nó không biết mức hỗ trợ là gì, rằng on-call cao hơn office-hours, hay rằng một devtool cần một mức: những ý nghĩa đó là cài đặt và quy tắc của các chính sách. Về các vai trò, payload và cách một chính sách nêu tên một nhãn, xem socket quản trị, và về vị trí của chính sách trong sản phẩm, xem Quản trị và Tuân thủ.
Các tệp
aggregate.yaml— cơ sở dữ liệu, bộ nhớ đệm và giao diện quản trị được nối với cơ sở dữ liệu; không có nhãn.manifest.yaml— liên kết mỗi loại thành phần và Feature bí mật với Docker Compose Recipe của nó. Được dùng chung bởi cả hai Releases.release-staging.yaml,release-production.yaml— hai môi trường..aggrega-config.yaml— registry mặc định và bốn attachment quản trị.policies/support-tier.rego— chính sách biến đổi nhãn.policies/production-support.rego— phán quyết.policies/tags.yaml— bản đồ từ thành phần sang thẻ của bộ gắn thẻ selector.build-release.sh— build một Release, in ra lệnhaggrega buildtương đương.check.sh— thực hiện bốn bản build và kiểm tra từng kết quả.