Bỏ qua để đến nội dung
AggregaAggrega
Chọn ngôn ngữ: Tiếng Việt
Trang này được dịch bằng máy. Đọc bản gốc tiếng Anh.

Chính sách toàn tổ chức: quy tắc của một nhóm, của một tổ chức và của một pipeline

Chính sách của một nhóm, của tổ chức chứa nhóm đó và của pipeline của nhóm chạy cùng nhau trên một bản build, mỗi chính sách được gắn trong một tệp cấu hình riêng. Nhóm gắn quy tắc của mình trong workspace của mình; tổ chức thêm một quy tắc vào mọi bản build, và pipeline thêm một quy tắc nữa, mà không bên nào phải sửa tệp của nhóm. Một bản build đọc mọi tệp áp dụng cho nó và chạy mọi attachment mà các tệp đó mang.

Các quy tắc báo cáo ở cả ba mức nghiêm trọng của phán quyết: info và warn để bản build hoàn tất, còn halt dừng nó lại. Một trong số đó, quy tắc của tổ chức, được gắn hai lần và mỗi lần được báo cáo ở một mức nghiêm trọng khác nhau, thông qua một khối translation.

Những gì ví dụ này xây dựng

instanceComponent trong catalogvai trò ở đây
dbcore/datastore/mariadbcơ sở dữ liệu của cửa hàng
webcore/devtool/adminermột giao diện quản trị cơ sở dữ liệu, được nối tới db

Cả hai được biên dịch sang Docker Compose, vào dist/compose/docker-compose.yaml. Một Aggregate, một Manifest và một Release, release.yaml; không cái nào gọi tên một chính sách.

Ba tệp

aitệpcách một bản build đọc nónơi attachment được viết
nhóm.aggrega-config.yamlnó đánh dấu thư mục này là workspace, nên mọi bản build ở đây đều đọc nóplugins.governance
tổ chứcorg/config.yamllà tệp cấu hình toàn cục, được gọi tên cho một bản build bằng --config org/config.yamlplugins.governance_append
pipelinepipeline/.aggrega-config-append-ci.yamlsau khi được sao chép vào thư mục này, làm lớp phủ của pipelineplugins.governance_append

Cả ba attachment đều là engine Rego, governance/rego:0.9.0, ở vai trò ir-verdict, vai trò đánh giá đồ thị build trước khi bất cứ thứ gì được render. 0.9.0 là phiên bản của thực thể Plugin của nó trong catalog thư viện chuẩn. Bản thân engine được biên dịch vào CLI — aggrega plugin list liệt kê governance/rego trong số các thành phần dựng sẵn được nhúng — nên không bản build nào ở đây tải về plugin.

Tệp của tổ chức là tệp cấu hình toàn cục. Một máy có một tệp như vậy, được đọc trong mọi bản build: từ vị trí mặc định của nó, hoặc tệp mà biến môi trường AGGREGA_CONFIG gọi tên. --config <path> thay vào đó gọi tên một tệp cho một lần chạy, và các tệp riêng của workspace vẫn được đọc chồng lên trên nó. Trong một tổ chức, tệp này sẽ nằm ở vị trí mặc định trên máy của mọi nhà phát triển và trong mọi pipeline; ở đây nó nằm trong org/, và các bản build cần đọc nó sẽ gọi tên nó. Gọi tên tệp toàn cục một cách tường minh trình bày thứ tự thử ba cách này.

Tệp của pipeline là một lớp phủ. Một bản build đọc .aggrega-config-append-ci.yaml trong các thư mục mà nó đọc .aggrega-config.yaml, nằm cạnh tệp đó. Ở đây tệp được giữ trong pipeline/, nơi một bản build chạy trong thư mục này không đọc nó, vì nó dừng mọi bản build đọc nó; bước của pipeline là sao chép nó vào:

Terminal window
cp pipeline/.aggrega-config-append-ci.yaml .

Mỗi tệp đều thêm vào, và lớp phủ của pipeline chỉ thêm vào

Cả tổ chức lẫn pipeline đều viết attachment của mình dưới plugins.governance_append, thiết lập đi kèm dạng nối thêm của danh sách plugins.governance. Các mục dưới thiết lập đi kèm được nối vào danh sách đã phân giải sau khi danh sách riêng của từng tệp được đọc, nên cả plugins.governance của nhóm lẫn mục của tổ chức đều chạy, và không tệp nào gọi tên tệp kia. Tổ chức viết vào thiết lập đi kèm chứ không phải chính plugins.governance, vì một danh sách plugins.governance trong tệp của workspace sẽ thay thế danh sách trong tệp toàn cục: một quy tắc của tổ chức viết ở đó bị danh sách của nhóm loại bỏ, và bản build không in ra gì về điều đó. Mở rộng một danh sách thay vì thay thế nó liệt kê thiết lập đi kèm cho từng thiết lập danh sách.

Lớp phủ của pipeline chỉ có thể thêm vào. Những gì nó viết cho một thiết lập danh sách được thêm vào những gì các tệp khác đã phân giải; nó không xóa gì, và không ghi đè một thiết lập giữ một giá trị duy nhất, chẳng hạn auto_pull. Lớp phủ này mang auto_pull: true, và một bản build đọc nó sẽ bỏ qua khóa đó và nói rõ điều đó trong một cảnh báo. Với <workspace> đại diện cho đường dẫn tuyệt đối của thư mục mà bản build chạy trong đó, dòng đó là:

warning: <workspace>/.aggrega-config-append-ci.yaml: ignoring non-additive key "auto_pull" (the CI-owned overlay is additive-only and cannot override the base config)

Các quy tắc và mức nghiêm trọng mà mỗi quy tắc được báo cáo

Một chính sách Rego thu thập mỗi quyết định dưới một khóa quyết định, và khóa chọn mức nghiêm trọng mà quyết định được báo cáo. Khi không có translation, các khóa là deny, warn và audit, được báo cáo ở halt, warn và info:

mức nghiêm trọngbản build làm gì
haltdừng, thoát với 1 và không ghi dist/
warnhoàn tất, in thông báo và ghi dist/
infohoàn tất, in thông báo và ghi dist/

Quy tắc của nhóm, policies/team.rego, thu thập dưới warn, và attachment của nó không khai báo translation, nên nó được báo cáo ở warn:

warn contains msg if {
some id, node in input.graph.spec.nodes
node.labels["component.aggrega.ai/category"] == "datastore"
input.graph.spec.infra_mapping[id].ha.enabled == false
msg := sprintf("%v runs with high availability off", [id])
}

Quy tắc của tổ chức, org/policies/estate.rego, từ chối các thành phần thuộc một danh mục mà thiết lập của nó liệt kê, và ghi lại những gì mỗi thành phần chạy:

deny contains msg if {
some id, node in input.graph.spec.nodes
category := node.labels["component.aggrega.ai/category"]
category in data.refused_categories
msg := sprintf("%v runs %v, in the %v category, which the organization does not ship", [id, node.component, category])
}
audit contains msg if {
some id, node in input.graph.spec.nodes
msg := sprintf("%v runs %v %v, upstream licensing %v", [id, node.component, node.resolved_version, node.labels["component.aggrega.ai/upstream-licensing"]])
}

refused_categories là một thiết lập của mỗi attachment, và một chính sách đọc các thiết lập của attachment của nó dưới dạng tài liệu data.

Chuyển đổi: một quy tắc, hai mức nghiêm trọng

Một khối translation trong các thiết lập của attachment khai báo những khóa quyết định nào được đọc và mức nghiêm trọng mà mỗi khóa được báo cáo. Nó thay thế ánh xạ mặc định thay vì mở rộng nó: một khóa mà nó không gọi tên sẽ không được đọc.

Tệp của tổ chức triển khai quy tắc của mình dưới dạng lời khuyên. Attachment của nó báo cáo deny ở warn, và audit ở info:

settings:
refused_categories: [devtool]
translation:
- key: deny
severity: warn
- key: audit
severity: info

Pipeline gắn cùng tệp đó và khiến cùng quy tắc đó dừng bản build. Phần chuyển đổi của nó chỉ gọi tên deny, nên attachment của nó không báo cáo các bản ghi audit lần thứ hai:

settings:
refused_categories: [devtool]
translation:
- key: deny
severity: halt

Vậy là một quy tắc, trên cùng một web, là một cảnh báo trong bản build của nhà phát triển và là lý do khiến bản build của pipeline dừng lại.

Tạo ví dụ

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

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

Terminal window
aggrega scaffold --example policy-org-overlay

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

Terminal window
cd policy-org-overlay

Build

Catalog thư viện chuẩn cung cấp các Components, các Recipes, Feature và FeatureRecipe của nó. 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 về từ registry, nên các bản build chạy ngoại tuyến. --auto-pull điền tệp khóa trong khi build; tệp khóa và output đã render được sinh ra, không được phân phối kèm.

Chỉ với tệp của nhóm:

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

bản build in cảnh báo của nhóm và hoàn tất. Khi có thêm tệp của tổ chức:

Terminal window
aggrega build --release release.yaml --auto-pull --config org/config.yaml

nó in các bản ghi của tổ chức ở info và quy tắc của tổ chức ở warn, bên cạnh cảnh báo của nhóm, và vẫn hoàn tất:

info: policy plugin "rego": db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved
info: policy plugin "rego": web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved
policy plugin "rego" warning: db runs with high availability off
policy plugin "rego" warning: web runs core/devtool/adminer, in the devtool category, which the organization does not ship
Pull complete: release.lock (entities=11, source_artifacts=0, external_inputs=0)
notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)
[… omitted: the build's time and the line naming the dist/ directory it wrote]

Mỗi phán quyết gọi tên plugin đã báo cáo nó, rego, chứ không phải tệp đã gắn nó, nên cảnh báo của nhóm và của tổ chức trông giống nhau; một thông báo nói rõ đó là quy tắc của ai, như thông báo của tổ chức, là cách để phân biệt chúng.

Khi lớp phủ của pipeline được sao chép vào, cùng lệnh đó sẽ dừng:

Terminal window
cp pipeline/.aggrega-config-append-ci.yaml .
aggrega build --release release.yaml --auto-pull --config org/config.yaml
[… omitted: the overlay's warning shown above]
[… omitted: the lines printed while the lockfile is resolved, which carry the verdicts below once more, the refusal among them]
info: policy plugin "rego": db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved
info: policy plugin "rego": web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved
policy plugin "rego" warning: db runs with high availability off
policy plugin "rego" warning: web runs core/devtool/adminer, in the devtool category, which the organization does not ship
notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)
[POLICY_ERROR E0005]
policy plugin "rego" rejected the build: web runs core/devtool/adminer, in the devtool category, which the organization does not ship
caused by: policy violation

Bản build thoát với 1 và không ghi dist/. Quy tắc của tổ chức được báo cáo hai lần, mỗi attachment một lần: ở warn bởi attachment của tổ chức và ở halt bởi attachment của pipeline. Các bản ghi audit xuất hiện một lần, chỉ từ attachment của tổ chức. Hãy xóa .aggrega-config-append-ci.yaml khỏi thư mục này để build lại mà không có nó.

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-org-overlay`, hãy gọi công cụ `scaffold` một lần với `example` đặt thành `policy-org-overlay` và không có `dir`: công cụ này ghi ví dụ vào một thư mục `policy-org-overlay` mới. Sau đó gọi công cụ `build` với `workspace_root` đặt thành `policy-org-overlay`, `release` đặt thành `release.yaml`, `auto_pull` đặt thành true và `write` đặt thành true, rồi cho tôi biết chính sách đã báo cáo gì. Tiếp theo 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-org-overlay`, `release` đặt thành `release.yaml`, `auto_pull` đặt thành true và `config` đặt thành `org/config.yaml`, rồi cho tôi biết lần này chính sách đã báo cáo gì. Cho tôi biết mỗi bản dựng đã ghi những tệp nào; chúng nằm trong `policy-org-overlay/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 đó.

Terminal window
./check.sh

check.sh build release.yaml năm lần, thông qua script hỗ trợ build-release, mỗi lần trong một bản sao của workspace này: chỉ với tệp của nhóm, với tệp của tổ chức được gọi tên bằng --config, với lớp phủ của pipeline được sao chép vào, với cả hai, và với một bản sao tệp của tổ chức viết attachment của nó dưới plugins.governance thay vì thiết lập đi kèm — khi đó danh sách của nhóm thay thế nó, và chỉ phán quyết của nhóm được in ra. Với mỗi lần, nó kiểm tra trạng thái thoát, liệu dist/ có được ghi hay không, và mọi phán quyết mà bản build in ra — mức nghiêm trọng và thông báo của nó, không thiếu và không thừa — và, nơi lớp phủ được đọc, cảnh báo gọi tên auto_pull. Nó in một dòng cho mỗi bản build, sau đó là các phán quyết mà mỗi bản build in ra, và thoát với 1 nếu bất kỳ kết quả nào khác đi, in ra output của bản build đó:

LAYERS EXIT DIST VERDICT
----------------------------------------------------------------------------------------------------
team 0 yes OK
team + organization 0 yes OK
team + pipeline 1 no OK
all three 1 no OK
team + organization, plugins.governance 0 yes OK
team:
warn db runs with high availability off
team + organization:
info db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved
info web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved
warn db runs with high availability off
warn web runs core/devtool/adminer, in the devtool category, which the organization does not ship
team + pipeline:
ignored auto_pull
warn db runs with high availability off
halt web runs core/devtool/adminer, in the devtool category, which the organization does not ship
all three:
ignored auto_pull
info db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved
info web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved
warn db runs with high availability off
warn web runs core/devtool/adminer, in the devtool category, which the organization does not ship
halt web runs core/devtool/adminer, in the devtool category, which the organization does not ship
team + organization, plugins.governance:
warn db runs with high availability off
check: every build ended as expected.

Các 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 hoặc ghi. 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. 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 đọc ba tệp, nối các attachment mà chúng mang, giao cho mỗi chính sách đồ thị build và các thiết lập của nó, và hành động theo mức nghiêm trọng mà mỗi quyết định được báo cáo. Nó không biết devtool là gì, vì sao một tổ chức không muốn phát hành nó, hay việc tính sẵn sàng cao quan trọng với một nhóm: những ý nghĩa đó là quy tắc và thiết lập của các chính sách. Về các vai trò, payload và khóa quyết định, xem socket quản trị.

Các tệp

  • aggregate.yaml — cơ sở dữ liệu và giao diện quản trị được nối với 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ó.
  • release.yaml — Release duy nhất.
  • .aggrega-config.yaml — tệp của nhóm: registry mặc định và attachment của nhóm.
  • policies/team.rego — quy tắc của nhóm.
  • org/config.yaml — tệp cấu hình toàn cục của tổ chức và attachment của nó.
  • org/policies/estate.rego — quy tắc của tổ chức.
  • pipeline/.aggrega-config-append-ci.yaml — lớp phủ của pipeline, được đọc sau khi sao chép vào thư mục này.
  • build-release.sh — build Release, in ra lệnh aggrega build tương đương.
  • check.sh — thực hiện năm bản build và kiểm tra từng kết quả.