Socket quản trị
Toàn bộ socket thay vì chỉ một vai trò của nó: bốn vai trò — hai vai trò đánh giá một bản build, hai vai trò định hình nó — cả hai policy engine đi kèm trong trình biên dịch, và cách người vận hành gắn một plugin.
Người vận hành gắn một plugin quản trị Wasm để kiểm tra một bản build và hành động dựa trên những gì nó phát hiện. Host của trình biên dịch luôn trung lập về nội dung và không có quan điểm riêng: nó chuyển payload của bản build đến guest và hành động dựa trên những gì guest trả về, và nó không bao giờ diễn giải bản thân chính sách. Toàn bộ trí tuệ chính sách theo miền — ngôn ngữ chính sách, engine của nó và các quy tắc — nằm bên trong guest.
Đây cũng chính là hợp đồng thuần khiết ahead-of-time mà mọi socket đều tuân theo: guest đánh giá payload được trao cho nó và trả về một kết quả mà host tiêu thụ nguyên văn (xem hợp đồng sandbox). Host không biết gì về ngôn ngữ chính sách mà guest sử dụng và không mang mã policy engine nào của riêng nó.
Một plugin quản trị được gắn tại đúng một vai trò, và chính vai trò — chứ không phải plugin — quyết định cả payload nào được gửi đến lẫn việc phần gắn kết được phép làm gì với nó. Hai vai trò là vai trò phán quyết: phần gắn kết đánh giá bản build, và host thực hiện đúng một trong ba hành động cho mỗi phán quyết mà nó trả về. Hai vai trò là vai trò biến đổi: phần gắn kết báo cáo một thay đổi đối với labels hoặc annotations của bản build, và host áp dụng thay đổi đó. Một plugin phục vụ nhiều hơn một vai trò được gắn một lần cho mỗi vai trò, và nó không tự khai báo vai trò nào — phần gắn kết mang vai trò đó.
Trang này trình bày toàn diện về socket quản trị: bốn vai trò
và payload mà mỗi vai trò mang, các mức độ nghiêm trọng của phán quyết mà host dựa vào để hành động, kênh
đầu vào không phụ thuộc vào engine mà người vận hành cung cấp, cách viết một chính sách cho một trong
hai policy engine đi kèm bên trong trình biên dịch — một engine đánh giá Rego, một engine
đánh giá CEL — cách một guest bao bọc một policy engine bên ngoài, các guest tham chiếu
đi kèm, và cách người vận hành gắn một plugin vào một workspace. Về vị trí của socket trong pipeline và các dạng dữ liệu truyền có kiểu của nó, xem
plugin-contract.md; về việc soạn và xuất bản một
plugin dưới dạng một thực thể catalog, xem
hướng dẫn dành cho nhà phát triển plugin Wasm.
Mô hình tư duy: host định tuyến, guest quyết định
Trong một lần build, host tập hợp payload cho vai trò của attachment, chuyển nó qua ranh giới ABI và đọc lại những gì guest trả về. Ở một vai trò verdict, đó là một danh sách các verdict, mỗi verdict mang một mức độ nghiêm trọng và một thông điệp dễ đọc cho con người: host ánh xạ mỗi mức độ nghiêm trọng sang một hành động build, và nó không đọc thông điệp để tìm ý nghĩa, không biết policy đã kiểm tra gì, và không biết engine nào đã tạo ra quyết định. Ở một vai trò transform, đó là thay đổi cần thực hiện, nhắm đến các label hoặc các annotation mà vai trò đó quản lý và không nhắm đến thứ gì khác.
Vì host không diễn giải nội dung policy, toàn bộ bề mặt policy thuộc về guest: các quy tắc được viết bằng ngôn ngữ nào, engine nào đánh giá chúng, và việc một quy tắc được kích hoạt trở thành một verdict hay một thay đổi như thế nào. Hợp đồng socket hẹp theo thiết kế — một vai trò, một tập đầu vào và một kết quả — để bất kỳ công nghệ policy nào biên dịch sang Wasm cũng có thể phục vụ nó.
Một vai trò verdict chấp nhận hoặc từ chối và không làm gì khác: host chỉ đọc đầu ra của nó như một quyết định và không bao giờ áp dụng nó như một thay đổi, nên một policy không thể âm thầm đưa một build không tuân thủ trở thành tuân thủ. Một vai trò transform là ngoại lệ có chủ đích, và điều khiến nó là ngoại lệ là việc operator đã gắn nó — gắn một plugin để định hình label là một tuyên bố rằng label cần được định hình. Những gì một attachment như vậy có thể thay đổi bị giới hạn trong bề mặt của chính vai trò của nó, và build dừng lại một cách rõ ràng khi gặp bất cứ thứ gì nằm ngoài bề mặt đó.
Bốn vai trò
Một plugin được gắn tại đúng một vai trò, và vai trò đó xác định host đánh giá nó ở đâu trong pipeline, nó nhận payload nào và nó được phép trả về gì. Một plugin cần phục vụ hai vai trò sẽ được gắn hai lần — mỗi vai trò một lần.
Các vai trò phán quyết: ir-verdict và render-verdict
ir-verdict— guest suy xét trên đồ thị biểu diễn trung gian, trước khi render. Payload mang toàn bộ đồ thị IR không phụ thuộc vào capability (mọi node, cạnh và attachment mà trình biên dịch nắm giữ) cùng với các đường định tuyến mà bộ phân tích liệt kê, để một policy có thể suy xét về topology và khả năng tiếp cận mà không phải duyệt lại đồ thị. Danh sách đường đó bị giới hạn theo từng node xuất phát — một topology kết nối dày đặc hoặc có chu trình có thể chứa nhiều tuyến phân biệt hơn số tuyến mà phép liệt kê phát ra, và khi đạt đến giới hạn thì các tuyến còn lại từ node xuất phát đó không được liệt kê. Vì vậy, một đường có mặt là có thật, còn việc thiếu một đường không chứng minh rằng không có đường nào: một policy có phán quyết phụ thuộc vào việc một thứ gì đó không thể tiếp cận nên xác lập điều đó từ các node và cạnh, vốn được payload mang đầy đủ, thay vì chỉ từ danh sách đường. Có một thứ trong đồ thị không giữ nguyên như khi viết: mọi giá trị mà tác giả khai báo là nhạy cảm — trongvalueshoặcinfracủa một attachment, tronginfracủa một attachment ranh giới, trongvalueshoặcinfracủa chính một node, hoặc trongvalueshoặcinfracủa chính một kết nối — đều đến dưới dạng dấu hiệu bị giữ lại{"aggrega_withheld": "declared"}, trong khi khóa của nó, dấu hiệu nhạy cảm của nó và mọi giá trị không được khai báo bên cạnh nó đều đến như khi viết. Một policy đánh giá nơi dữ liệu được khai báo nhạy cảm di chuyển đến và không bao giờ nhận chính dữ liệu đó; xem các dữ kiện attachment mà một policy quản trị đọc. Một policyir-verdictchạy tại cổng phân tích tĩnh, trước khi bất kỳ artifact nào được tạo ra. Hãy dùng nó cho các policy về kiến trúc và đấu nối — bất biến topology, xác thực xuyên ranh giới, hình dạng luồng thông tin xác thực — cần dừng một bản build trước khi nó render bất cứ thứ gì.render-verdict— guest suy xét trên đầu ra đã render, sau khi render. Payload mang các artifact được phát ra, sắp xếp theo đường dẫn, để dữ liệu truyền đi giống hệt nhau từng byte giữa các lần chạy với cùng đầu vào. Mỗi artifact mang đường dẫn đầu ra và văn bản đã render của nó; ngoài ra nó còn mang định dạng mà nó được render, khi provider tạo ra nó đã khai báo một định dạng, và một góc nhìn có cấu trúc đã được phân tích về nội dung của nó, khi nội dung ở một định dạng đã được phân tích trước policy. Một policyrender-verdictthấy chính xác những gì bản build đã tạo ra, và không có gì trong đó bị giữ lại: một giá trị mà một Recipe đã render vào một artifact sẽ đến đúng như đã render, vì artifact chính là thứ policy đánh giá. Hãy dùng nó cho các policy về đầu ra cụ thể — chẳng hạn một quy tắc kiểm tra các service Docker Compose hoặc các đối tượng Kubernetes đã render.
Các vai trò biến đổi: annotation-transform và label-transform
-
annotation-transform— guest báo cáo các annotation cần thêm, trong quá trình phân giải và trước khi mở rộng annotation. Payload mang mọi component mà attachment có thể gắn annotation, mỗi component kèm các annotation nó đã có, cùng với các khóa annotation mà Manifest đăng ký một binding. Một annotation được chèn vào dưới một khóa đã đăng ký sẽ tiếp tục được mở rộng thành một attachment Feature, và đó là cách vai trò này thêm vào bản build một capability mà nhà phát triển đã không gõ vào.Các component mà nó có thể gắn annotation là mọi component mà một boundary nêu dưới
components:, và mọi component mà mục định tuyếnaggregates:của một boundary định tuyến vào. Một mục định tuyến đặt mọi component của module của nó, bao gồm cả các component của những module lồng bên trong, bất kểcomponents:của chính nó nêu tất cả, một số hay không nêu component nào, nhưdocuments: {}không nêu component nào; payload mang từng component. Một component được định tuyến được định địa chỉ bằng id mà nó mang trong đồ thị build — tên module, một dấu chấm, và tên của component bên trong module, như trongdocuments.backend, thêm một tên module và dấu chấm cho mỗi module lồng nhau — đó là cách đồ thị build và các chẩn đoán của nó viết id này, nên một quyết định cũng nêu tên nó theo cách đó. Một component mà mục định tuyến đặt vào mà không nêu tên không mang annotation riêng nào trên payload, và một annotation được chèn vào nó được áp dụng như một annotation được viết trên nó dưới mục định tuyến. -
label-transform— guest báo cáo các thay đổi label cần áp dụng, trong quá trình xây dựng topology: sau khi đồ thị được xây dựng và trước khi đồ thị được đánh giá. Payload mang một phép chiếu các node của bản build — mỗi node kèm Component mà nó khởi tạo, phiên bản được phân giải cho nó, các label nó hiện mang và các giá trị mà instance của nó khai báo, chỉ đọc và với mọi giá trị mà Component của nó khai báo là nhạy cảm đều bị giữ lại như phán quyết đồ thị giữ lại — cùng với tên và môi trường của Release. Hãy dùng nó cho siêu dữ liệu dẫn xuất mà nhà phát triển không bao giờ nên phải gõ vào (phạm vi tuân thủ, quyền sở hữu, phân bổ chi phí) và cho một label capability mà cấu hình do nhà phát triển khai báo xứng đáng nhận được.
Các vai trò mang những payload khác nhau vì chúng hoạt động vào những thời điểm khác nhau và trả lời những câu hỏi khác nhau. Cả bốn đều mang cùng một kênh đầu vào do operator cung cấp, được mô tả bên dưới. Để xem một payload thay vì đọc về nó, aggrega build --release <release> --policy-input <dir> ghi ra payload mà mỗi vai trò trao cho một plugin được gắn ở đó — kể cả một vai trò không gắn gì — dưới dạng một tệp JSON cho mỗi vai trò, hoặc cho mỗi lần gắn khi các lần gắn của một vai trò nhận các payload khác nhau, và khi kết hợp với --dry-run thì nó chỉ ghi các tệp đó và không làm gì khác. Ở annotation-transform, label-transform và ir-verdict, tệp đó là tài liệu input mà một chính sách đọc. Ở render-verdict, policy engine định hình lại payload trước khi một chính sách đọc nó — documents của mỗi artifact được phân tích từ đó — nên một chính sách render-verdict trên một engine nằm trong trình biên dịch được kiểm thử trong một bản build, gắn ở mức warn hoặc info, như Kiểm thử một chính sách trước khi nó chặn một bản build trình bày. Với một plugin mà bạn tự build .wasm, aggrega plugin run-local --plugin <plugin.wasm> --export verdict_render --with @<dir>/render-verdict.json chạy nó trên tệp đó.
Phán quyết và mức độ nghiêm trọng
Các mức độ nghiêm trọng dưới đây là từ vựng của các vai trò phán quyết. Một vai trò biến đổi báo cáo một thay đổi chứ không phải một phán quyết, nên nó không mang mức độ nghiêm trọng nào.
Guest trả về một danh sách phán quyết. Mỗi phán quyết mang một mức độ nghiêm trọng quyết định hành động đối với bản build:
halt— dừng bản build; host đưa thông điệp của phán quyết ra làm lý do. Bản build không tạo ra artifact nào.warn— đánh dấu phán quyết; bản build tiếp tục.info— ghi lại phán quyết; kết quả của bản build không thay đổi.
Ba mức này là toàn bộ tập hợp, và chúng cũng chính là ba mức mà chẩn đoán của mọi socket khác sử dụng, nên một mức độ nghiêm trọng mang cùng một ý nghĩa ở bất cứ đâu bạn đọc thấy nó.
Một phán quyết mang bất kỳ giá trị nào khác là một vi phạm hợp đồng chứ không phải một lộ trình thứ tư. Bản build dừng lại, và thông điệp nêu tên plugin, giá trị mà phán quyết mang, và ba giá trị mà hợp đồng khai báo — nhờ vậy một mức độ nghiêm trọng viết sai chính tả được báo cáo như một lỗi build thay vì lọt qua như một phán quyết không ai xử lý. Một guest báo cáo bằng một trong ba giá trị đó không bị ảnh hưởng.
Một lần đánh giá cho phép không trả về gì cả. Guest chỉ phát ra phán quyết khi một quy tắc được kích hoạt, nên một danh sách phán quyết rỗng nghĩa là policy đã cho phép bản build. Không có phán quyết “pass” nào để phát ra — im lặng chính là cho phép.
Guest có thể trả về nhiều phán quyết trong một lần đánh giá, với các mức độ nghiêm trọng khác nhau. Host
duyệt qua tất cả: bất kỳ halt nào cũng dừng bản build (và mọi thông điệp halt đều được
đưa ra), trong khi các phán quyết warn và info được báo cáo mà không chặn bản build. Điều này
phản ánh sự phân tách giữa dừng và khuyến nghị, vốn phân biệt một policy làm dừng bản build với
một bước kiểm tra lint mang tính khuyến nghị.
Kênh with: nguồn và thiết lập
Một guest policy thường mang tính tổng quát đối với các quy tắc cụ thể mà nó thực thi — engine
được tích hợp sẵn trong guest, nhưng các quy tắc được cung cấp theo từng lần gắn. Kênh
with mang đầu vào theo từng lần gắn đó. Nó có hai trường không phụ thuộc vào
engine:
sources— các tệp định nghĩa policy mà guest tải. Host đọc từng tệp được nêu tên tại thời điểm build và chuyển các byte của nó cho guest một cách mờ: nó không bao giờ phân tích cú pháp một nguồn, và đường dẫn nó trao cho guest là tên gốc của tệp, không bao giờ là một đường dẫn tuyệt đối trên host. Ý nghĩa của các byte hoàn toàn là việc của guest — một tệp.regođối với một guest, một định dạng policy khác đối với guest khác, và một kho lưu trữ mã hóa base64 của cả một bộ policy đối với guest đọc loại đó.settings— một map cấu hình mà guest ánh xạ vào engine của nó. Guest đọc các tham số điều chỉnh của nó (một giới hạn số replica, một khóa nhãn bắt buộc) từ map này. Theo mặc định, host chuyển nó nguyên văn mà không xử lý gì; guest có thể khai báo thêm một schema cho nó (xem bên dưới), khi đó host xác thực map theo schema đó trước khi chạy guest.
Một guest được tích hợp hoàn toàn — guest mà các quy tắc được biên dịch sẵn bên trong thay vì được cung cấp
lúc gắn — bỏ hẳn with. Kênh này là tùy chọn ở mọi vai trò.
Thiết lập có kiểu
Guest có thể khai báo một JSON Schema cho settings mà nó mong đợi. Khi đó,
host xác thực settings của lần gắn theo schema đó trước khi
chạy guest. Các thiết lập không phù hợp sẽ dừng bản build với một thông điệp
nêu tên khóa vi phạm và điều schema mong đợi — một khóa bắt buộc bị thiếu, một
giá trị sai kiểu, một khóa không xác định, hoặc một giá trị ngoài phạm vi đều được phát hiện ngay
từ đầu thay vì lộ ra dưới dạng một lỗi guest khó hiểu hoặc, tệ hơn, một
bản build sai nhưng vẫn thành công.
Thiết lập có kiểu là tùy chọn và do guest khai báo, không phải host. Một guest
không khai báo schema thiết lập nào giữ hành vi tự do: host chuyển
settings của nó mà không kiểm tra. Host chạy xác thực JSON Schema thông thường
theo bất kỳ schema nào guest đã khai báo; nó không diễn giải ý nghĩa của các
thiết lập. Điều này giữ cho bước kiểm tra trung lập với engine — mỗi guest mô tả
hình dạng của các thiết lập mà nó đọc, và host thực thi đúng hình dạng đó và
không gì hơn.
Một lần gắn không khai báo thiết lập nào được xác thực như JSON null. Chính điều đó cho phép guest làm cho thiết lập của nó trở thành bắt buộc: một schema chỉ chấp nhận một object sẽ từ chối một lần gắn không cung cấp thiết lập nào, và bản build dừng lại. Hệ quả cũng đi theo chiều ngược lại, và đó là điều cần chủ ý khi viết: một guest mà thiết lập thực sự là tùy chọn phải khai báo một schema chấp nhận null cũng như một object, nếu không nó hoàn toàn không thể được gắn mà không có thiết lập. Hai policy engine nằm sẵn trong trình biên dịch khai báo "type": ["object", "null"] chính vì lý do này — gắn một engine như vậy mà không có khối with: thì nó chạy với các giá trị mặc định. Một guest chỉ khai báo "type": "object" đã biến thiết lập của nó thành bắt buộc, dù đó có phải là ý định hay không.
ABI là của riêng Aggrega
Hợp đồng socket là ABI của riêng Aggrega, không phải của bất kỳ policy engine nào. Chính điều đó cho phép bất kỳ công nghệ policy nào được biên dịch sang Wasm đều có thể đóng vai trò một guest thay thế trực tiếp: guest giao tiếp ra bên ngoài qua bề mặt Aggrega — describe(), cùng với export mà vai trò nó phục vụ gọi tới — còn engine nào mà nó dùng chỉ là chi tiết triển khai nằm sau bề mặt đó.
Một guest bao bọc một policy engine bên ngoài sẽ hấp thụ ABI của engine đó vào bên trong chính nó. Nếu engine có Wasm ABI riêng, các entrypoint riêng, hoặc giao thức host-callback riêng, guest bao bọc sẽ khởi tạo và điều khiển nó ở bên trong, rồi ánh xạ quyết định của engine trở lại dạng verdict của socket. Host của trình biên dịch chỉ thấy bề mặt verdict quản trị chuẩn; nó không bao giờ biết engine nào đang tham gia và không chứa mã đặc thù cho engine nào. Chuyển một policy từ engine này sang engine khác là một thay đổi ở attachment, không phải một thay đổi ở host.
Hai policy engine được đóng gói sẵn trong trình biên dịch
Hai policy engine được biên dịch vào tệp nhị phân CLI, và người vận hành gắn một trong hai — hoặc cả hai — theo cùng cách gắn bất kỳ plugin quản trị nào:
| Tọa độ | Ngôn ngữ chính sách | Nguồn được gắn |
|---|---|---|
governance/rego | Rego | Các tệp .rego, hoặc một kho lưu trữ mã hóa base64 của cả một bộ chính sách |
governance/cel | Common Expression Language (CEL) | Các tệp biểu thức .cel, hoặc các tài liệu quy tắc .yaml / .yml |
Mọi thứ xung quanh ngôn ngữ đều dùng chung. Cả hai đều phục vụ cả bốn vai trò, cả hai đọc cùng một payload theo từng vai trò dưới cùng các tên trường, cả hai ánh xạ quyết định của mình lên cùng ba mức độ nghiêm trọng của phán quyết thông qua cùng thiết lập translation, và cả hai đều báo lỗi rõ ràng thay vì cho phép một bản build mà chúng không thể đánh giá. Mỗi engine lấy phiên bản là bản phát hành trình biên dịch đóng gói nó, và không engine nào cần toolchain bên ngoài hay tải về bất cứ thứ gì lúc build. Điều mỗi ngôn ngữ có thể diễn đạt thì không dùng chung: một quy tắc chỉ cần vài quy tắc phụ trợ trong Rego có thể cần thêm thiết lập và sự lặp lại trong CEL — xem Một biểu thức có thể diễn đạt những gì trước khi viết một quy tắc duyệt qua một tuyến.
Điều khác biệt là ngôn ngữ dùng để viết các quy tắc, và đó là toàn bộ cơ sở để lựa chọn. Một hệ thống đã có sẵn một kho Rego — hoặc một nhóm viết Rego cho kiểm soát admission ở nơi khác — gắn engine Rego và các chính sách của họ chạy nguyên trạng. Một nhóm diễn đạt các quy tắc của mình dưới dạng các biểu thức đơn lẻ trên một tài liệu, theo cách một validating-admission policy của Kubernetes làm, gắn engine CEL. Hai engine được gắn theo từng vai trò, nên một workspace có thể chạy Rego ở một vai trò và CEL ở vai trò khác, hoặc cả hai ở cùng một vai trò dưới dạng hai lần gắn.
Host không phụ thuộc vào việc một quyết định đến từ engine nào: nó định tuyến payload, đọc lại một phán quyết hoặc một thay đổi, và hành động theo đó. Chuyển một chính sách từ ngôn ngữ này sang ngôn ngữ kia là một thay đổi về việc gắn và một lần viết lại các quy tắc — không bao giờ là một thay đổi ở host.
Chính sách Rego: hai con đường
Rego là một ngôn ngữ chính sách phổ biến, và có hai con đường để chạy nó — một engine ít trở ngại được phát hành kèm trong trình biên dịch, và một lối thoát với độ trung thực đầy đủ.
Engine Rego trong trình biên dịch là con đường ít trở ngại. Nó mang theo một trình đánh giá Rego thuần Wasm, nên người vận hành chỉ cần thả một tệp .rego vào sources và gắn plugin — không cần toolchain bên ngoài, và không tải gì về lúc build. Nó
phục vụ cả bốn vai trò: cùng một plugin đánh giá đồ thị build, đánh giá đầu ra đã render, định hình nhãn, hoặc chèn annotation, tùy theo vai trò mà nó được gắn vào. Danh tính trong catalog của nó là tên trần rego dưới pluginType: governance —
tọa độ governance/rego — và phiên bản của nó là bản phát hành trình biên dịch đi kèm nó. Viết một chính sách cho nó là
phần tiếp theo.
Trình đánh giá tự triển khai lại Rego một cách độc lập thay vì nhúng bản triển khai tham chiếu, và nó không triển khai mọi builtin của Rego. Khi một chính sách gọi một builtin mà trình đánh giá không triển khai, attachment thất bại một cách rõ ràng: nó trả về một lỗi, không phải một sự cho phép. Khi đó build dừng lại với một lỗi nêu tên plugin — cố ý khác với một verdict halt, để “engine không thể đánh giá chính sách này” không bao giờ bị nhầm thành “chính sách cho phép build.” Một chính sách không thể đánh giá sẽ dừng build; nó không bao giờ lặng lẽ cho qua.
Lối thoát opa build -t wasm là con đường có độ trung thực đầy đủ. Khi một chính sách cần toàn bộ tập builtin hoặc ngữ nghĩa chính xác của engine tham chiếu, hãy biên dịch nó bằng toolchain của chính OPA thành một module Wasm và chạy module đó phía sau một guest adapter mỏng. Adapter hấp thụ hoàn toàn ABI Wasm của OPA bên trong chính nó (theo ABI là của riêng Aggrega ở trên): nó khởi tạo module do OPA build, đặt input, gọi việc đánh giá, và ánh xạ quyết định trở lại dạng verdict. Host chỉ thấy bề mặt verdict governance tiêu chuẩn.
Một guest adapter tham chiếu được phát hành kèm làm ví dụ minh họa. Nó nhúng một chính sách được viết bằng Rego và được biên dịch trước bằng opa build -t wasm thành một module WebAssembly — một artifact được ghim phiên bản và lưu trong kho, nên việc đánh giá chạy hoàn toàn bên trong guest, không có tiến trình OPA và không tải gì về. Ở mỗi lần build, adapter khởi tạo module đã nướng sẵn đó bên trong chính nó bằng một trình thông dịch Wasm nhúng, đáp ứng các import riêng của module (bộ nhớ tuyến tính và các callback builtin của nó), đọc payload làm tài liệu input của OPA và settings của attachment làm tài liệu data của OPA, đánh giá từng entrypoint đã biên dịch, và ánh xạ tên entrypoint deny / warn / audit của mỗi entrypoint thành một mức độ nghiêm trọng của verdict — lần lượt là halt, warn và info. Nếu một chính sách đã nướng sẵn cần một builtin do host cung cấp mà adapter không triển khai, adapter thất bại một cách rõ ràng — từ chối module thay vì trả về một sự cho phép — nên một chính sách không thể đánh giá sẽ dừng build thay vì lặng lẽ cho qua. Việc tạo lại module đã nướng sẵn từ mã nguồn Rego của nó là một bước soạn thảo được chạy bằng OPA CLI, không phải một phụ thuộc lúc build. ../examples/policy-data-class-route/ xây dựng adapter đó quanh một module của riêng nó, và đưa ra các lệnh để tạo lại cả hai.
Hai con đường dùng chung cùng một hợp đồng host, nên việc chuyển một chính sách từ engine trong trình biên dịch sang engine đầy đủ chỉ là một thay đổi attachment.
Viết policy cho engine Rego
Engine đánh giá Rego do operator viết hoàn toàn bên trong guest, tại bất kỳ vai trò nào trong bốn vai trò mà nó được gắn vào. Gắn nó hai lần, tại hai vai trò, với hai tệp policy khác nhau, là cách một engine bao quát hai thời điểm của cùng một bản build.
Payload cho vai trò của attachment là tài liệu input của policy, và
đối tượng settings của attachment là tài liệu data của policy — vì vậy một policy đọc
ngưỡng do operator cung cấp dưới dạng data.max_replicas. Mọi tệp mà attachment
khai báo dưới sources trở thành một module policy, và mọi package mà các tệp đó
khai báo đều được đánh giá.
Policy được viết bằng cú pháp rule nào
Rego được viết bằng hai cú pháp rule và engine chấp nhận cả hai, theo từng module. Do đó một bộ policy được tạo trước khi cú pháp hiện tại ra đời vẫn được đánh giá cùng với một bộ viết hôm nay, trong cùng một attachment.
Trong cú pháp hiện tại, thân rule được mở đầu bằng if, một rule thu thập
vào một tập hợp thể hiện điều đó bằng contains, và module nêu rõ nó được viết bằng cú pháp nào
bằng cách khai báo import rego.v1 trên một dòng riêng bên dưới khai báo
package:
package example
import rego.v1
deny contains msg if { count(input.graph.spec.nodes) > 20 msg := "this build declares more than twenty nodes"}Trong cú pháp cũ với phần đầu có ngoặc vuông, giá trị mà rule thu thập nằm trong ngoặc vuông trên phần đầu rule và phần thân theo ngay sau. Một module viết bằng cú pháp đó không khai báo gì, vì nó được nhận diện nhờ không parse được theo cú pháp hiện tại:
package example
deny[msg] { count(input.graph.spec.nodes) > 20 msg := "this build declares more than twenty nodes"}Một module parse được theo cú pháp hiện tại nhưng không khai báo gì sẽ bị từ chối, kèm tên. Chính khai báo là thứ cố định cách đọc, và nếu thiếu nó, cùng một văn bản rule có thể dẫn đến quyết định ngược lại: một thân rule không bao giờ thỏa mãn không đóng góp quyết định nào theo cú pháp hiện tại nhưng lại đóng góp một quyết định theo cú pháp cũ — nên một policy lẽ ra phải im lặng lại dừng bản build, và trường hợp ngược lại thì để lọt một bản build mà rule được viết ra để chặn. Thay vì chọn một cách đọc cho module như vậy, engine từ chối nó và cho biết cần thêm gì:
policy source "policy.rego" must declare `import rego.v1`. Both Rego rule syntaxes are accepted, and this module parses as either one — so without the import its rules could be read in the older syntax, where the same text can reach the opposite decision. Add `import rego.v1` on its own line below the package declaration.Việc từ chối là một lỗi build nêu tên plugin chứ không phải một verdict, nên nó dừng bản build giống như một policy không đánh giá được và không bao giờ bị hiểu là một policy đã cho phép bản build.
Có hai trường hợp biên nên biết trước khi chúng làm bạn bất ngờ. Một module hoàn toàn không có thân rule nào — chỉ khai báo dữ liệu — parse được theo cú pháp hiện tại, nên nó cũng bị yêu cầu khai báo, dù hai cách đọc không thể khác nhau đối với nó. Và một module viết bằng cú pháp cũ không bao giờ bị từ chối, vì nó không parse được theo cú pháp hiện tại: chính engine phân biệt hai cú pháp, nên một policy cố ý dùng phần đầu có ngoặc vuông không bao giờ bị nhầm là một policy cú pháp hiện tại quên khai báo.
Policy thu thập các quyết định của nó dưới một khóa quyết định
Mọi vai trò đọc các quyết định của policy từ một khóa quyết định — một rule có tên mà policy thu thập vào. Những khóa nào được đọc, và một quyết định dưới một khóa có nghĩa là gì, do vai trò quyết định.
Tại một vai trò verdict, một quyết định là một thông điệp, và khóa mà nó được thu thập dưới quyết định mức độ nghiêm trọng mà thông điệp đó được báo cáo. Theo mặc định, các khóa là các tên thu thập theo quy ước của Rego:
| Thu thập dưới | Báo cáo dưới dạng | Ảnh hưởng đến bản build |
|---|---|---|
deny | halt | dừng bản build |
warn | warn | hiển thị cùng với một bản build hoàn tất |
audit | info | được ghi lại; kết quả build không thay đổi |
Hãy tách biệt hai bộ từ vựng, vì chúng là hai bộ khác nhau: deny, warn và audit
là các tên trong policy của bạn, còn halt, warn và info là các mức độ nghiêm trọng mà
socket báo cáo. Cột bên trái bạn có thể đổi tên; cột bên phải là
tập đóng mà mọi socket dùng chung.
Một policy đặt tên các quyết định của nó khác đi sẽ khai báo ánh xạ trong settings của attachment:
with: settings: translation: - key: blocked severity: halt - key: advisory severity: warnMột ánh xạ được khai báo thay thế mặc định chứ không mở rộng nó: các khóa mà nó
nêu chính là các khóa được đọc, nên một policy vẫn thu thập vào deny sẽ không đạt được
verdict nào khi ánh xạ trên được khai báo. Thứ tự khai báo các rule là
thứ tự báo cáo các verdict. Một khóa mà policy không khai báo là một quyết định vắng mặt
chứ không phải lỗi, nên một tệp policy có thể phục vụ nhiều attachment.
Một mức độ nghiêm trọng nằm ngoài ba mức trên, và một ánh xạ được khai báo rỗng, bị từ chối bởi schema settings mà plugin khai báo — host xác thực settings của attachment theo schema đó trước khi dispatch. Cùng một khóa được ánh xạ hai lần bị từ chối khi ánh xạ được đọc, cũng là trước khi bất kỳ policy nào chạy. Dù thế nào, bản build cũng dừng trước khi đạt được quyết định, không bao giờ với một ánh xạ áp dụng dở dang.
Ngoài ra, settings là dữ liệu riêng của policy: ánh xạ được đọc ra khỏi đối tượng
và đối tượng đến tài liệu data của policy mà không thay đổi, nên một policy viết
cho các khóa mặc định thấy đúng tài liệu dữ liệu mà nó sẽ thấy khi hoàn toàn không
cấu hình ánh xạ nào.
Tại một vai trò transform, một quyết định là thay đổi cần thực hiện chứ không phải thông điệp, nên
không có mức độ nghiêm trọng nào cần cố định và thay vào đó khóa được cố định: labels tại
vai trò định hình label, annotations tại vai trò chèn annotation. Thiết lập translation
chỉ được đọc ở nơi verdict được báo cáo, nên một attachment transform
khai báo nó là đang mang một thiết lập mà vai trò của nó không sử dụng.
Khóa quyết định được đọc từ mọi package mà attachment tải, nên một bộ policy
có thể trải các rule ra nhiều package và mỗi package đóng góp những gì nó thu thập. Mặt
kia của điều đó nên biết trước khi gặp rắc rối: trong một attachment, khóa
quyết định là tên rule dành riêng trong mọi package, nên một package hỗ trợ
tình cờ thu thập vào labels cho mục đích riêng sẽ bị đọc các mục của nó như các quyết định
label. Điều đó thất bại rõ ràng chứ không âm thầm — attachment báo rằng
thứ gì đó thu thập dưới khóa không phải là quyết định có dạng đó — nhưng cách nhanh nhất
để hiểu thông điệp như vậy là xem nó như một xung đột tên, vì vậy hãy giữ khóa cho quyết định
và đặt cho rule hỗ trợ một tên khác.
Payload của mỗi vai trò cung cấp những gì
Payload là tài liệu input của policy, vì vậy policy đọc nó dưới các tên mà giao thức truyền đặt cho nó.
Đồ thị build nằm ở một đường dẫn khác nhau trong hai vai trò có mang đồ thị. Một verdict trên đồ thị nhận toàn bộ tài liệu đồ thị, nên các nút của nó nằm ở input.graph.spec.nodes; vai trò định hình nhãn nhận một phép chiếu của các nút, nên các nút của nó nằm ở input.graph.nodes. Do đó, một rule được chuyển giữa hai vai trò này phải được sửa, không phải sao chép — và triệu chứng của việc quên là một rule không bao giờ kích hoạt chứ không phải một lỗi, vì một đường dẫn không tồn tại đơn giản là không xác định.
| Vai trò | Policy đọc gì |
|---|---|
ir-verdict | input.graph — toàn bộ tài liệu đồ thị build: các nút ở input.graph.spec.nodes theo khóa là id nút, các cạnh ở input.graph.spec.edges. Một giá trị mà tác giả đã khai báo là nhạy cảm được đọc là {"aggrega_withheld": "declared"}. input.precalculated_paths — các đường định tuyến được liệt kê, mỗi đường mang danh sách nodes có thứ tự và attached_features, các kiểu Feature được gắn ở bất kỳ đâu trên đường đó (xem bên dưới). Danh sách này luôn có mặt: một build không có tuyến nào giữa các component mang một danh sách rỗng. |
render-verdict | input.artifacts — một mục cho mỗi tệp được xuất ra, mỗi mục có path, content, format và documents, các tài liệu đã được phân tích của tệp. format là định dạng mà nhà cung cấp đã render tệp khai báo cho nó — nhà cung cấp Terraform khai báo hcl cho mọi tệp .tf nó xuất ra và json cho mọi tệp .tf.json, kể cả các tệp của một module được vendor — và là chuỗi rỗng khi không nhà cung cấp nào khai báo, như với một tệp mà một Recipe đóng góp vào đầu ra dùng chung của một ranh giới. Một tệp như vậy vẫn được phân tích theo phần mở rộng của nó, nên documents của nó có mặt trong cả hai trường hợp. Một artifact không thể đọc theo cấu trúc mang parse_error và không có tài liệu nào, nên policy có thể từ chối dựa trên chính lỗi đó thay vì để một tệp không đọc được lọt qua mà không bị kiểm tra. |
label-transform | input.graph.nodes — các nút của build theo khóa là id nút, mỗi nút có component, resolved_version, labels và values: các giá trị mà instance của nút khai báo trong Aggregate, với các template đã được đánh giá theo tham số của nó, và vắng mặt khi nó không khai báo giá trị nào. Một giá trị mà Component của nút khai báo là nhạy cảm được đọc là {"aggrega_withheld": "declared"}, như tại ir-verdict, còn các giá trị anh em không được khai báo được đọc như đã viết. Một rule đọc input.graph.nodes[id].values để quyết định một nhãn; nó không thể thay đổi một giá trị. input.compilation_context — release_name và environment của Release, để policy có thể quyết định khác nhau theo từng môi trường. |
annotation-transform | input.targets — mọi component mà attachment có thể chú thích, mỗi component có boundary_path, component_name — với một component do mục định tuyến đặt vào, đó là id của nó trong đồ thị build, chẳng hạn metrics.query — và các annotations mà Release viết trên chính component đó, mỗi giá trị như đã viết: một chuỗi, một đối tượng gồm các khóa con, hoặc null khi component từ chối một annotation mà lẽ ra nó sẽ kế thừa. Mọi khóa mà component mang đều có mặt bất kể giá trị của nó, nên một rule có thể để nguyên một khóa mà ai đó đã viết. input.binding_keys — các khóa annotation mà Manifest đăng ký một binding cho chúng. |
Một tài nguyên Terraform được đọc ở một đường dẫn khác nhau trong mỗi dạng của hai dạng Terraform. Trong documents của một tệp .tf gốc, một block lồng dưới kiểu của nó rồi dưới từng nhãn của nó, và nhãn cuối cùng chứa một danh sách block, vì các block có cùng kiểu và nhãn được gom vào một danh sách theo thứ tự nguồn. Do đó, một thuộc tính tài nguyên được đọc ở input.artifacts[_].documents[_].resource.<type>.<name>[_].<attr> — với một instance RDS có tên bất kỳ là input.artifacts[_].documents[_].resource.aws_db_instance[_][_].allocated_storage. Một tệp .tf.json được đọc đúng như Recipe đã viết, nên dạng đối tượng thông thường của nó, nơi tên chứa chính block, được đọc ở resource.<type>.<name>.<attr>, và một policy dành cho cả hai dạng sẽ đọc cả hai đường dẫn. Điều đó đúng với cả hai engine policy bên trong compiler. Một rule Rego viết cho dạng kia sẽ thấy đường dẫn nó nêu là không xác định: một rule kiểm tra một giá trị ở đó không bao giờ kích hoạt, còn một rule từ chối khi vắng giá trị, bằng not, sẽ kích hoạt trên mọi tài nguyên; một biểu thức CEL đánh chỉ mục hoặc chọn vào dạng kia sẽ dừng build với một lỗi đánh giá nêu tên tệp policy của nó. Adapter render Rego tham chiếu, được mô tả ở Các adapter policy giai đoạn render bên dưới, tự phân tích một tệp .tf gốc và đọc một block đơn lẻ như một đối tượng, nên một đường dẫn Terraform phải được sửa, không phải sao chép, khi một policy chuyển giữa adapter đó và một engine bên trong compiler.
Ngoài ra, mọi vai trò đều mang input.sources — các tệp riêng của attachment, mỗi tệp có path là tên cơ sở và content của nó. Một policy chỉ chạy như một trong các tệp đó, nên ở bất cứ đâu một rule đọc danh sách này, danh sách đều chứa ít nhất tệp đó.
input.settings là đối tượng settings của attachment, cùng là đối tượng với tài liệu data của policy, và có mặt khi attachment khai báo settings. Khi attachment không khai báo gì, điều mà rule tìm thấy phụ thuộc vào vai trò: tại ir-verdict, label-transform và annotation-transform trường này vắng mặt, nên input.settings không xác định như bất kỳ đường dẫn nào mà payload không mang, còn tại render-verdict nó là đối tượng rỗng. Vì vậy, một rule phụ thuộc vào việc một thiết lập đã được cấu hình hay chưa sẽ kiểm tra chính thiết lập mà nó đọc thay vì đối tượng, và cách này hoạt động như nhau ở mọi vai trò — một max_nodes đã cấu hình sẽ được đọc, còn một thiết lập chưa cấu hình để input.settings.max_nodes không xác định và rule im lặng:
package example
import rego.v1
deny contains msg if { limit := input.settings.max_nodes count(input.graph.spec.nodes) > limit msg := sprintf("this build declares more than %v nodes", [limit])}Engine CEL xử lý một đối tượng settings không được khai báo theo cách khác, và nói rõ điều đó trong phần riêng của nó bên dưới.
attached_features và binding_keys là danh sách chứ không phải đối tượng, nên policy kiểm tra tư cách thành viên bằng in:
package security
import rego.v1
deny contains msg if { some path in input.precalculated_paths some gateway in path.nodes input.graph.spec.nodes[gateway].labels["dataplane.aggrega.ai/content-masking"] not "core/data-masking" in path.attached_features msg := sprintf("path %v passes through %v with no masking Feature attached.", [concat(" -> ", path.nodes), gateway])}attached_features là hợp của các kiểu Feature của mọi attachment do bất kỳ nút nào trên đường đó nắm giữ — kể cả một attachment được viết trên một trong các kết nối của nút đó, bất kể nó được viết trên kết nối nào — nên rule được thỏa mãn bởi một attachment core/data-masking trên chính gateway, vốn là nơi Feature đó được gắn: nó chọn theo khả năng che nội dung mà gateway khai báo. Thứ mà attachment che là văn bản chat và completion đi qua gateway đó; rule kiểm tra rằng attachment tồn tại, chứ không kiểm tra nó liệt kê gì.
Vì đây là hợp trên toàn bộ đường, danh sách cho biết một Feature được gắn ở đâu đó trên một tuyến chứ không bao giờ cho biết ở đâu. Một rule cần biết liệu một Feature có nằm giữa hai component cụ thể của một tuyến hay không — component nắm giữ dữ liệu hạn chế và component mà nó đi tới — sẽ đọc nodes của tuyến theo thứ tự và các attachment riêng của từng nút, tại input.graph.spec.feature_values_mapping[<node>]; nếu hỏi attached_features, cùng câu hỏi đó sẽ cho qua một tuyến mà trên đó Feature nằm ở phía sau component thứ hai. ../examples/policy-data-class-route/ được viết theo cách đó, cho engine Rego, engine CEL và OPA.
Một đối tượng nút không mang id của riêng nó: id là khóa mà nó nằm dưới trong input.graph.spec.nodes, đó là lý do rule ở trên đưa các id nó đọc từ path.nodes vào thông điệp thay vì đọc một trường id.
Thứ tự policy gặp các khóa của một map
Đồ thị giữ thứ tự mà tác giả đã viết: các nút theo thứ tự các component được khai báo, và nhãn của mỗi nút theo thứ tự nút mang chúng. Thứ tự đó đi vào guest nguyên vẹn — payload mang cả hai dưới dạng các mục có thứ tự (xem các map giữ thứ tự của chúng). Việc policy có gặp thứ tự đó hay không được quyết định bởi cách engine đánh giá policy lưu giữ một đối tượng, chứ không phải bởi payload:
- Engine Rego lưu các khóa của đối tượng theo thứ tự đã sắp xếp. Một rule duyệt
input.graph.spec.nodes,labelscủa một nút, hoặc bất kỳ đối tượng nào khác — kể cả đối tượng được viết ngay trong policy — gặp các khóa theo thứ tự đã sắp xếp: các component được khai báoweb,api,metricsđược gặp theo thứ tựapi,metrics,web. - Engine CEL không cố định thứ tự nào cho một map. Một comprehension trên
input.graph.spec.nodeshoặc trênlabelscủa một nút có thể gặp các khóa theo thứ tự khác nhau ở hai lần build với đầu vào giống hệt nhau, và hai lần duyệt cùng một map trong một biểu thức có thể khác nhau. Đó là lý do các thông điệp dưới một khóa quyết định được sắp xếp: hãy viết rule mà quyết định không phụ thuộc vào vị trí của một khóa. - Một guest được viết dựa trên một plugin kit gặp thứ tự của tác giả. Khi được giải mã qua kit của nó, các nút và nhãn của mỗi nút đến trong container giữ thứ tự của kit theo thứ tự payload mang chúng, và bộ khung adapter quản trị mà mỗi kit cung cấp đưa cho engine của nó một tài liệu JSON được viết theo cùng thứ tự đó. Một engine chuyển tài liệu đó thành một kiểu giá trị của riêng nó thì sẽ gặp thứ tự của kiểu đó, như các map giữ thứ tự của chúng mô tả.
Định hình nhãn: policy nêu tên nhãn, và engine định địa chỉ nó
Ở vai trò định hình nhãn, policy thu thập một quyết định cho mỗi nhãn dưới labels, nêu tên nút, khóa nhãn và giá trị mà nhãn nhận:
package tagging
import rego.v1
labels contains {"node": id, "key": "compliance.example.com/tier", "value": "gold"} if { some id, node in input.graph.nodes node.labels["component.aggrega.ai/type"] == "stateful-server"}Đặt một khóa đã có sẵn sẽ thay thế giá trị của nó. Thay vào đó, một quyết định có thể yêu cầu loại bỏ một khóa:
labels contains {"node": id, "key": "draft.example.com/scratch", "op": "remove"} if { some id, node in input.graph.nodes node.labels["draft.example.com/scratch"]}Policy nêu tên nhãn thay vì viết chỉ thị chỉnh sửa mà build áp dụng, và lý do đáng biết: chỉ thị định địa chỉ một nhãn bằng đường dẫn, và khóa nhãn của Aggrega thường chứa /, vốn là dấu phân cách đường dẫn — nên một đường dẫn viết tay sẽ định địa chỉ một vị trí lồng nhau thay vì một nhãn. Engine định địa chỉ nhãn mà quyết định nêu tên, nên việc thoát ký tự được viết một lần thay vì trong mọi policy, và policy vẫn dễ đọc như một phát biểu về nhãn chứ không phải về đường dẫn.
Một quyết định chỉ có thể thay đổi một nhãn. Mọi chỉ thị mà engine phát ra định địa chỉ một nhãn trên một nút, nên policy không có cách nào diễn đạt thay đổi đối với Component của nút, phiên bản đã phân giải của nó, tập hợp các nút, hoặc một giá trị nhãn không phải chuỗi. Một quyết định nêu tên một nút mà build không có, hoặc loại bỏ một nhãn mà nút không mang, sẽ bị build từ chối với một thông điệp nêu tên chỉ thị — không bao giờ bị âm thầm bỏ qua.
../examples/policy-label-transform/ gắn một policy như vậy bên cạnh hai plugin gắn thẻ tích hợp sẵn, cùng một verdict trên đồ thị đọc các nhãn mà chúng viết. Mỗi plugin đó đọc và viết gì được trình bày tại Các plugin gắn thẻ tích hợp sẵn.
Chèn annotation
Ở vai trò chèn annotation, policy thu thập một quyết định cho mỗi annotation dưới annotations, nêu tên đích bằng tọa độ mà chính đích mang, cùng với khóa và giá trị của nó:
package tagging
import rego.v1
annotations contains { "boundary_path": target.boundary_path, "component_name": target.component_name, "annotation_key": "backup.example.com/schedule", "annotation_value": "nightly",} if { some target in input.targets not target.annotations["backup.example.com/schedule"]}Tên trường mà một quyết định viết là tên trường mà nó đã đọc các đích dưới đó, nên quy ước có thể học được chỉ từ payload. Đọc input.binding_keys cho phép policy chỉ chèn những khóa mà Manifest đã đăng ký một ý nghĩa — đó là những khóa được mở rộng thành một attachment của Feature.
Giá trị của một quyết định là giá trị mà bạn có thể tự viết trên annotation đó: một chuỗi, hoặc một đối tượng gồm các khóa con. Một binding định tuyến một khóa con nhận một chuỗi; một binding định tuyến nhiều khóa con nhận một đối tượng nêu tên từng khóa, đúng như cách người vận hành viết nó trong Release:
annotations contains { "boundary_path": target.boundary_path, "component_name": target.component_name, "annotation_key": "feature.aggrega.ai/monitoring", "annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"},} if { some target in input.targets not target.annotations["feature.aggrega.ai/monitoring"]}Build đọc một giá trị được chèn đúng như cách nó đọc cùng giá trị đó khi được viết trong Release, nên giá trị được mở rộng theo cùng cách và được kiểm tra đối với Feature được bind theo cùng cách. Engine giữ các khóa của một đối tượng ở dạng đã sắp xếp, nên các khóa con đến build theo thứ tự đã sắp xếp. Một giá trị có bất kỳ dạng nào khác — null, một danh sách, một số, một boolean, hoặc một đối tượng không có khóa con — bị build từ chối, kèm tên lần chèn: vai trò này thêm annotation, và null hoặc một đối tượng rỗng được đọc là sự từ chối mà tác giả viết để gỡ bỏ một annotation. Một quyết định nêu tên một component mà payload không mang cũng bị từ chối theo cùng cách, kèm tên tọa độ và annotation.
Khi build từ chối một annotation được chèn vì cách nó định tuyến hoặc nội dung nó mang — một chuỗi được đưa vào một binding định tuyến nhiều khóa con, một giá trị khóa con mà schema của Feature được bind không chấp nhận, hoặc một khóa con được định tuyến qua trụ cột values, thứ mà annotation phía Release không được dùng — lời từ chối nêu tên plugin đã chèn nó và vai trò governance mà plugin được gắn vào, nên giá trị được truy về policy đã quyết định nó thay vì về một dòng trong Release mà không ai viết.
../examples/policy-annotation-transform/ gắn một policy như vậy, chèn một chuỗi dưới một binding và một đối tượng gồm các khóa con dưới một binding khác, và build ra cùng các tệp như một Release viết các annotation đó bằng tay.
Đính kèm toàn bộ một tập chính sách dưới dạng một tệp lưu trữ
Một tập chính sách được đính kèm từng tệp một, hoặc dưới dạng một tệp lưu trữ duy nhất chứa cả các tệp chính sách và các tài liệu dữ liệu của nó — đúng hình dạng mà một bộ công cụ Rego tạo ra. Nội dung của một tệp đính kèm được truyền tới guest dưới dạng văn bản, còn một tệp lưu trữ nén là các byte tùy ý chứ không phải văn bản, nên tệp lưu trữ được đính kèm ở dạng mã hóa base64, và được đặt tên sao cho tên của nó kết thúc bằng .base64:
tar czf bundle.tar.gz policy.rego data.jsonbase64 -w0 bundle.tar.gz > bundle.tar.gz.base64with: sources: - ./policies/bundle.tar.gz.base64Chính tên tệp là thứ đánh dấu một tệp là tệp lưu trữ chứ không phải văn bản chính sách, nhờ đó lựa chọn này vẫn là tuyên bố của chính người vận hành: khi đó một tệp lưu trữ bị hỏng được báo cáo là một tệp lưu trữ bị hỏng, nêu tên tệp và bước bị lỗi, thay vì bị đọc như một tệp chính sách không phân tích được. Mã hóa tệp lưu trữ là một bước người vận hành thêm vào sau khi bộ công cụ của họ đã tạo ra nó.
Bên trong tệp lưu trữ, mỗi thành phần .rego là một mô-đun chính sách, và mỗi thành phần data.json hoặc data.yaml là một tài liệu dữ liệu được lồng dưới thư mục chứa nó — một limits/data.json chứa {"max": 3} được chính sách đọc là data.limits.max. Các thành phần thuộc bất kỳ loại nào khác được tệp lưu trữ mang theo cho bộ công cụ của chính nó và không phải là đầu vào chính sách.
Một tệp lưu trữ không mở được là một lỗi nêu tên tệp đính kèm: một bản mã hóa không giải mã được, một luồng không giải nén được, một tệp lưu trữ bị cắt cụt, một tệp dữ liệu không đọc được, hoặc một tệp lưu trữ không chứa chính sách nào. Không trường hợp nào trong số đó cho ra một tập chính sách rỗng, vì một tập chính sách rỗng không đưa ra quyết định nào — và “tệp lưu trữ không đọc được” không bao giờ được phép không phân biệt được với “chính sách đã cho phép bản dựng”.
Viết một policy cho engine CEL
Engine đánh giá CEL do người vận hành viết hoàn toàn bên trong guest, tại bất kỳ vai trò nào trong bốn vai trò mà nó được gắn vào. Định danh catalog của nó là tên trần cel
dưới pluginType: governance — tọa độ governance/cel — và phiên bản của nó là
bản phát hành compiler đi kèm nó. Gắn nó hai lần, tại hai vai trò, với hai
tệp policy khác nhau, là cách một engine bao quát hai thời điểm của cùng một bản build.
plugins: governance: - uri: governance/cel:<version> role: ir-verdict with: sources: - ./policies/topology.cel settings: max_nodes: 20Một policy truy cập toàn bộ payload qua một tên duy nhất, input, nên các tên nó đọc
chính là các tên mà wire đặt cho chúng: đồ thị build tại input.graph, các đường định tuyến
đã liệt kê tại input.precalculated_paths, các tệp đã render tại
input.artifacts, các đích annotation tại input.targets. Các đường dẫn theo vai trò đó
chính là các đường dẫn được lập bảng trong Payload của mỗi vai trò cung cấp những gì
ở trên, và chúng giống hệt nhau cho cả hai engine — một wire, được đọc dưới một tên gốc.
Các tệp riêng của attachment nằm tại input.sources và các thiết lập của nó tại input.settings, nên một ngưỡng do người vận hành cung cấp được đọc là input.settings.max_nodes. Không có tài liệu thứ hai nào phải học: các thiết lập là một phần của input như mọi thứ khác. Cả hai luôn có mặt dưới dạng một giá trị — các thiết lập là đối tượng rỗng ở mọi vai trò khi attachment không khai báo gì — nên một biểu thức truy cập chúng không phải phòng trường hợp chúng vắng mặt, và việc một thiết lập đã được cấu hình hay chưa là một phép kiểm tra trên khóa của nó: has(input.settings.max_nodes).
Hai dạng viết, và tên tệp quyết định giữa chúng
Một policy được gắn ở một trong hai dạng, và tên tệp cho biết là dạng nào:
| Tên tệp kết thúc bằng | Được đọc là |
|---|---|
.cel | một biểu thức, được đánh giá nguyên trạng |
.yaml hoặc .yml | một tài liệu quy tắc — một danh sách các quy tắc |
| bất kỳ thứ gì khác | một biểu thức |
Tên tệp là toàn bộ quy tắc. Không có thiết lập nào chọn dạng, và nội dung tệp không được xem xét để đoán dạng — dù sao nó cũng không thể trả lời câu hỏi, vì giá trị ngoài cùng của một biểu thức là một map và của một tài liệu quy tắc cũng vậy, khiến hai dạng không thể phân biệt bằng hình dạng.
Vì vậy quy tắc này áp dụng theo cả hai chiều, và cả hai lỗi đều bị từ chối chứ không
bị đọc sai. Một tài liệu quy tắc tên policy.cel bị từ chối, vì một danh sách quy tắc YAML
không phải là một biểu thức; một biểu thức tên policy.yaml bị từ chối, vì một
biểu thức không phải là một danh sách quy tắc. Mỗi lần từ chối đều nêu tên tệp. Đổi tên tệp là
cách sửa theo cả hai chiều.
Một tập policy gồm bao nhiêu tệp tùy nhu cầu, và hai dạng có thể trộn lẫn tự do trong một attachment.
Một biểu thức, trong tệp có tên .cel
Một ngôn ngữ biểu thức không có tên quy tắc để gom các quyết định, nên các quyết định chính là giá trị mà biểu thức tạo ra: một map từ khóa quyết định đến những gì khóa đó thu thập. Tại một vai trò phán quyết, một khóa thu thập các thông điệp đạt được dưới nó; tại một vai trò definh hình bản build, nó thu thập các quyết định cần áp dụng.
{ "deny": input.graph.spec.nodes .filter(n, input.graph.spec.nodes[n].resolved_version == "latest") .map(n, "component " + n + " tracks the latest version; pin it"), "warn": size(input.graph.spec.nodes) > input.settings.max_nodes ? ["this build declares a lot of components"] : [],}Một khóa mà tệp bỏ qua thì không đạt quyết định nào ở đó, nên một tệp không cần nêu mọi khóa — và mỗi vai trò chỉ đọc khóa liên quan đến nó, nên một tập policy có thể phục vụ một vai trò phán quyết và một vai trò định hình bản build từ cùng các tệp. Một khóa mang một danh sách những gì nó thu thập, một phần tử duy nhất trong số đó, hoặc giá trị null nếu không có gì.
Một biểu thức đánh giá ra bất kỳ thứ gì khác ngoài một map đều bị từ chối, kèm theo hình dạng
cần viết. Một size(input.graph.spec.nodes) <= 5 trần là lỗi đáng lường trước:
nó là một boolean, và đọc false như một lệnh dừng đồng nghĩa với việc bịa ra một thông điệp mà
tác giả chưa từng viết.
Một tài liệu quy tắc, trong tệp có tên .yaml hoặc .yml
Một tài liệu quy tắc là một danh sách các quy tắc, mỗi quy tắc nêu khóa quyết định mà nó đạt tới, biểu thức quyết định nó có được đạt tới hay không, và những gì được báo cáo khi nó được đạt tới:
- key: deny expression: size(input.graph.spec.nodes) > 20 message: this build declares a lot of components- key: warn expression: has(input.settings.max_nodes) message: a component ceiling is configured for this environmentNhững gì một quy tắc báo cáo phụ thuộc vào khóa quyết định mà nó đạt tới, đúng như trong một biểu thức. Văn bản là thông điệp mà một phán quyết mang theo. Một mapping là các trường của một quyết định mà một vai trò định hình bản build đọc:
- key: labels expression: input.compilation_context.environment == "production" message: node: app key: compliance.example.com/tier value: goldQuy tắc viết dạng nào trong hai dạng là do riêng quy tắc quyết định — không có thiết lập nào chọn nó — và một quy tắc viết sai dạng cho khóa của nó sẽ bị từ chối, kèm tên.
Một chi tiết YAML nên biết trước khi gặp rắc rối: một biểu thức bắt đầu bằng dấu ngoặc
kép phải được đặt trong ngoặc cho trình đọc tài liệu, vì một giá trị mở đầu bằng " được
đọc là một scalar có ngoặc chứ không phải văn bản bắt đầu bằng dấu ngoặc.
- key: annotations expression: '"backup.example.com/schedule" in input.binding_keys' message: boundary_path: main component_name: app annotation_key: backup.example.com/schedule annotation_value: nightlyMột tài liệu quy tắc được đọc thành biểu thức mà nó đại diện trước khi bất cứ thứ gì được đánh giá. Mỗi quy tắc trở thành khóa quyết định của nó, mang báo cáo của nó khi biểu thức đúng và không mang gì khi sai, và các quy tắc chung một khóa được gộp lại. Vì vậy một bộ đánh giá chạy cả hai dạng, và một tài liệu quy tắc quyết định đúng những gì biểu thức nó đại diện quyết định — tại mọi vai trò, cả phán quyết lẫn các quyết định định hình bản build. Hai hệ quả rút ra. Một tài liệu và biểu thức viết tay mà nó đại diện đạt cùng các quyết định, vì chúng là cùng một lần đánh giá. Và các quy tắc sắp thứ tự dưới đây thuộc về dạng đã đánh giá chứ không phải của tài liệu — các quy tắc của một tài liệu không được báo cáo theo thứ tự chúng được viết.
Dạng nào phù hợp — chúng không thể thay thế cho nhau
Cả hai dạng chạy qua một bộ đánh giá, nên không dạng nào nhanh hơn hay đáng tin hơn dạng kia. Điều khác biệt là những gì mỗi dạng có thể diễn đạt, và vì hai dạng là hai thứ phải học, nên sự phân chia đáng được nêu rõ thay vì để tùy sở thích. Hãy chọn theo những gì quy tắc báo cáo.
- Một tài liệu quy tắc, khi báo cáo là cố định. Thông điệp hoặc quyết định được viết một lần, bên cạnh biểu thức đạt tới nó, và tệp đọc như một danh sách các điều kiện chặn. Đây là dạng ngắn hơn cho “nếu điều này đúng, hãy nói chính xác điều này”.
- Một biểu thức, khi báo cáo nêu tên những gì nó tìm thấy. Một biểu thức lọc các
component của một bản build và tạo ra một thông điệp — hoặc một quyết định — cho mỗi component, nên
người đọc nhận được
component payments tracks the latest version; pin itcho từng đối tượng vi phạm thay vì một câu về một con số đếm.
Việc thứ hai đó là việc mà một tài liệu quy tắc không làm được: mỗi quy tắc của nó mang một báo cáo, được viết trước, nên nó không thể nói gì về component nào đã kích hoạt nó. Chọn dạng tài liệu rồi sau đó muốn có tên đối tượng vi phạm trong thông điệp là con đường kết thúc bằng việc viết lại quy tắc thành một biểu thức, nên đáng chọn dựa trên câu hỏi đó ngay từ đầu.
Những gì một biểu thức có thể diễn đạt
Các biểu thức mà engine này đánh giá dùng các comprehension filter, map và exists,
+ trên chuỗi và trên danh sách, size, in, startsWith, string(),
toán tử điều kiện, và một danh sách được đánh chỉ số bằng một số nguyên tính toán. Chúng không
cung cấp các hàm mở rộng mà một số môi trường CEL bổ sung: join, split,
substring, indexOf, flatten, cel.bind và lists.range đều bị từ chối như một
tham chiếu chưa khai báo, và một comprehension nhận một biến, nên dạng hai biến
như exists(i, v, …) cũng bị từ chối theo cùng cách. Một lần từ chối là một lỗi build nêu tên
tệp và tham chiếu:
policy source "routes.cel" could not be evaluated: Undeclared reference to 'join'Ba hệ quả định hình một quy tắc duyệt qua một tuyến:
- Không có cách nào đặt tên cho một giá trị trung gian. Một biểu thức con dùng hai lần thì
được viết hai lần, hoặc được gán bằng cách map một danh sách một phần tử:
[value].map(name, …)[0]đánh giá thân của nó một lần vớinameđược gán chovalue. - Không có cách nào duyệt qua các vị trí của một danh sách. Một quy tắc so sánh các
component của một tuyến theo vị trí lấy các vị trí từ thiết lập của nó — một danh sách
positionsnhư[0, 1, 2, …]— và đánh chỉ số tuyến tại mỗi vị trí, nên nó phải chặn một tuyến dài hơn chính danh sách đó, bằng cách dừng khi gặp, thay vì chỉ đọc một phần. - Một khóa quyết định thu thập các thông điệp, không phải danh sách các thông điệp. Một biểu thức tạo ra một danh sách thông điệp cho mỗi tuyến sẽ bị từ chối dưới một khóa quyết định — lỗi nói rằng nó đã thu thập một giá trị kiểu list thay vì một thông điệp — nên một quy tắc tạo một bản ghi cho mỗi tuyến và xây dựng thông điệp từ đó. Và một thông điệp mà biểu thức tạo ra hai lần sẽ được báo cáo hai lần: phép sắp xếp mô tả bên dưới sắp thứ tự những gì một khóa đã thu thập, và không loại bỏ bản lặp.
../examples/policy-data-class-route/ chứa một quy tắc CEL được viết theo cả ba hệ quả trên, bên cạnh cùng quy tắc đó cho engine Rego.
Khóa quyết định và mức độ nghiêm trọng
Các khóa quyết định, ánh xạ mặc định sang các mức độ nghiêm trọng và thiết lập translation
dùng để đổi tên chúng đều giống như với engine Rego — xem
Một policy thu thập các quyết định của nó dưới một khóa quyết định
ở trên. Theo mặc định, deny báo cáo ở mức halt, warn ở mức warn, và audit ở mức info; một
translation được khai báo sẽ thay thế mặc định đó thay vì mở rộng nó, và thứ tự mà nó
khai báo là thứ tự các phán quyết được báo cáo.
Cả hai engine khai báo cùng một lược đồ thiết lập cho nó, nên một khối translation mang
cùng một ý nghĩa bất kể ngôn ngữ nào diễn đạt các quyết định, và một khối sai định dạng sẽ bị
từ chối trước khi bất kỳ policy nào chạy.
Ở một vai trò định hình bản build, khóa là cố định thay vì được ánh xạ: labels ở
vai trò định hình nhãn, annotations ở vai trò chèn chú thích.
Thứ tự: sắp xếp trong một khóa, và một thứ tự toàn phần trên các quyết định
Các thông điệp dưới một khóa quyết định được báo cáo theo thứ tự đã sắp xếp. Đó là một phần của
hợp đồng chứ không phải lựa chọn trình bày, và lý do đáng ghi nhớ: một
comprehension trên một map — .filter(...) và .map(...) trên input.graph.spec.nodes,
vốn là cách tự nhiên nhất để viết một quy tắc theo từng component — duyệt map đó theo một
thứ tự mà trình đánh giá không cố định. Nếu để nguyên, cùng một đầu vào sẽ báo cáo cùng các
thông điệp theo một trình tự khác nhau ở mỗi bản build. Việc sắp xếp loại bỏ điều đó.
Hai điều sau đây dễ bị hiểu là lỗi nhưng không phải:
- Các quy tắc của một tài liệu quy tắc cũng được báo cáo theo thứ tự đã sắp xếp, không theo thứ tự chúng được viết — vì tài liệu được đánh giá như biểu thức mà nó đại diện, và việc sắp xếp áp dụng cho những gì một khóa đã thu thập.
- Một danh sách viết tay cũng được sắp xếp. Một khóa mang
["second", "first"]báo cáofirsttrướcsecond. Không có gì trong một kết quả đã đánh giá phân biệt một danh sách do tác giả gõ ra với một danh sách do comprehension tạo ra, nên không có thứ tự do tác giả viết nào cần giữ lại.
Giữa các khóa, thứ tự là thứ tự được khai báo của translation. Giữa các tệp, đó là
thứ tự tên tệp, vì các nguồn của một attachment đến theo thứ tự sắp xếp theo tên
thay vì theo thứ tự attachment liệt kê chúng.
Ở một vai trò định hình bản build, cùng lập luận đó áp dụng cho chính các quyết định, và thứ tự còn chặt chẽ hơn: các quyết định được báo cáo theo thứ tự tăng dần của mọi thứ chúng nêu tên, đây là một thứ tự toàn phần trên những gì một quyết định có thể diễn đạt — node, rồi khóa nhãn, rồi việc nhãn được thêm hay bỏ, rồi giá trị; và với một lần chèn, là boundary, rồi component, rồi khóa chú thích, rồi giá trị của nó. Một thay đổi về nhãn hoặc chú thích đi tới đầu ra được render, nên một thứ tự tùy ý sẽ khiến cùng một đầu vào render khác nhau từ bản build này sang bản build khác.
Định hình nhãn
Ở vai trò định hình nhãn, policy thu thập một quyết định cho mỗi nhãn dưới labels, nêu tên nút, khóa nhãn và giá trị mà nhãn nhận:
{ "labels": input.graph.nodes .filter(n, input.graph.nodes[n].labels["component.aggrega.ai/type"] == "stateful-server") .map(n, { "node": n, "key": "compliance.example.com/tier", "value": input.compilation_context.environment == "production" ? "gold" : "bronze", }),}Đặt một khóa đã có sẵn sẽ thay thế giá trị của nó. Thay vào đó, một quyết định có thể yêu cầu
bỏ một khóa, bằng cách đặt op là remove:
{ "labels": input.graph.nodes .filter(n, "draft.example.com/scratch" in input.graph.nodes[n].labels) .map(n, {"node": n, "key": "draft.example.com/scratch", "op": "remove"}),}Một quyết định đơn lẻ không cần danh sách bao quanh, và một tệp không nêu khóa labels thì không quyết định
nhãn nào.
Một policy nêu tên nhãn thay vì viết chỉ thị chỉnh sửa mà bản build áp dụng,
vì lý do được nêu trong
phần định hình nhãn của engine Rego:
một khóa nhãn của Aggrega thường chứa /, và một đường dẫn viết tay sẽ trỏ tới một
vị trí lồng nhau thay vì một nhãn. Engine trỏ tới nhãn mà quyết định
nêu tên.
Đọc một nhãn mà node có thể không mang là một lỗi thay vì một giá trị rỗng, đó là lý do ví dụ thứ hai kiểm tra xem khóa có tồn tại hay không trước khi đọc nó. Đó là quy tắc riêng của ngôn ngữ biểu thức về việc đọc một khóa vắng mặt, và nó báo rõ ràng: một policy tìm tới một nhãn mà không node nào mang sẽ báo rằng nó không thể được đánh giá thay vì lặng lẽ không quyết định gì.
Một quyết định chỉ có thể thay đổi một nhãn. Một quyết định nêu tên một node mà bản build không có, hoặc bỏ một nhãn mà node không mang, sẽ bị bản build từ chối kèm một thông điệp nêu tên chỉ thị — không bao giờ bị lặng lẽ bỏ qua.
Đưa ra một quyết định cho mỗi node và khóa nhãn. Một quy tắc có thể tạo ra hai giá trị khác nhau cho cùng một nhãn trên cùng một node là chưa được xác định đủ: hãy giải quyết giá trị bên trong biểu thức — bằng một điều kiện, hoặc bằng một filter chỉ chấp nhận một nhánh — thay vì phát ra cả hai quyết định.
../examples/policy-label-transform/ trình bày vai trò định hình nhãn từ đầu đến cuối, với policy được viết cho engine Rego.
Chèn chú thích dưới một khóa đã đăng ký
Ở vai trò chèn chú thích, một policy thu thập một quyết định cho mỗi chú thích dưới
annotations, nêu tên đích bằng tọa độ mà chính đích đó mang, cùng với
khóa và giá trị của nó:
{ "annotations": input.targets .filter(t, "backup.example.com/schedule" in input.binding_keys) .map(t, { "boundary_path": t.boundary_path, "component_name": t.component_name, "annotation_key": "backup.example.com/schedule", "annotation_value": "nightly", }),}Tên các trường mà một quyết định viết chính là tên các trường mà nó đã đọc các đích của mình, nên
quy ước này có thể học được chỉ từ payload. Đọc input.binding_keys cho phép một
policy chỉ chèn những khóa mà Manifest đã đăng ký một ý nghĩa — đó là những
khóa được mở rộng thành một attachment Feature. Mọi trường đều bắt buộc: một chú thích với
khóa rỗng hoặc tên component rỗng không phải là thứ một policy định yêu cầu. Boundary
mà một component nằm dưới có thể được nêu tên hợp lệ bằng chuỗi rỗng, nên trường
đó phải có mặt nhưng có thể rỗng.
Giá trị là giá trị mà bạn có thể tự viết trên annotation đó: một chuỗi, hoặc một map gồm các khóa con, là thứ cung cấp cho một binding định tuyến nhiều khóa con cùng lúc — "annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"}. Engine viết các khóa con của một map theo thứ tự đã sắp xếp, vì ngôn ngữ biểu thức không cố định thứ tự cho map, và chuyển tiếp giá trị đúng như biểu thức đã tạo ra; một giá trị mà mô hình JSON không thể chứa — byte, timestamp, duration — bị từ chối thay vì bị chuyển thành văn bản. Sau đó build đọc giá trị đúng như cách nó đọc cùng giá trị đó khi được viết trong Release, và từ chối null, một danh sách, một số, một boolean hoặc một map rỗng, kèm tên lần chèn. Hai quyết định cho cùng một component và khóa với giá trị khác nhau được sắp thứ tự theo JSON của giá trị. annotations của một đích mang mỗi giá trị hiện có như đã viết — một chuỗi, một map, hoặc null cho sự từ chối — nên kiểm tra "feature.aggrega.ai/monitoring" in t.annotations sẽ tìm thấy một khóa bất kể giá trị của nó.
Một quyết định nêu tên một component mà payload không mang sẽ bị bản build từ chối, kèm tên tọa độ và chú thích. Khi build từ chối một annotation được chèn vì cách định tuyến, các giá trị khóa con hoặc trụ cột của nó, lời từ chối nêu tên plugin đã chèn nó và vai trò mà plugin được gắn vào. Cũng như với nhãn, đưa ra một quyết định cho mỗi component và khóa chú thích, giải quyết giá trị bên trong biểu thức thay vì phát ra hai quyết định cho một khóa.
../examples/policy-annotation-transform/ trình bày vai trò chèn annotation từ đầu đến cuối, với policy được viết cho cả hai engine.
Khi một policy hoặc một quyết định không thể đọc được
Một policy mà engine không thể đọc, không thể đánh giá, hoặc tạo ra thứ gì đó khác
với các quyết định theo dạng đã mô tả sẽ khiến bản build thất bại thay vì trả về một
phán quyết hay một thay đổi. Thất bại được báo cáo dưới dạng một lỗi build nêu tên tệp và,
khi lỗi thuộc về một phần của tệp, vị trí bên trong nó — được cố ý
phân biệt với một phán quyết halt, để “policy này không thể được đánh giá” không bao giờ
bị nhầm với “policy này cho phép bản build”.
Với một biểu thức, điều đó bao gồm một nguồn không phân tích cú pháp được — được báo cáo kèm dòng và cột của chính trình phân tích cùng một dấu mũ dưới vị trí gây lỗi — và một nguồn đánh giá ra thứ gì đó khác với một map từ khóa quyết định tới những gì khóa đó thu thập.
Với một tài liệu quy tắc, nó bao gồm văn bản không phải là một danh sách quy tắc, một danh sách không có quy tắc nào, một quy tắc thiếu một trường hoặc mang một trường rỗng, một trường mà dạng này không định nghĩa, một báo cáo không phải văn bản cũng không phải ánh xạ từ văn bản sang văn bản, và một biểu thức không thể đọc được. Một lỗi thuộc về một quy tắc nêu vị trí của quy tắc đó — đếm từ một, theo cách tác giả đếm tệp của chính mình — và khóa quyết định của nó. Một quy tắc có biểu thức không phân tích cú pháp được sẽ bị từ chối trước khi đánh giá, nên dấu mũ nằm bên trong biểu thức mà tác giả đã viết thay vì ở một vị trí trong văn bản đã chuyển đổi mà họ chưa từng thấy.
Với một quyết định ở một vai trò định hình bản build, nó bao gồm một thông điệp ở chỗ
đáng lẽ là một quyết định, một tọa độ bị thiếu, và một trường mà dạng quyết định của engine này không
định nghĩa. Trường hợp cuối đáng được nêu riêng: một annotation_valu viết sai chính tả
sẽ bị từ chối, không bị bỏ qua, nên lỗi được báo cáo thay vì lặng lẽ chèn
một giá trị rỗng và để lại một bản build hoàn tất mà không có thay đổi. Mọi lần từ chối như vậy
đều nêu tên tệp và kết thúc bằng việc nêu những gì một quyết định thuộc loại đó phải nêu.
Các adapter chính sách ở giai đoạn render
Một adapter ở giai đoạn render suy luận trên đầu ra đã render của bản build thay vì đồ thị IR của nó. Payload render mang các artifact đã xuất — mỗi artifact kèm đường dẫn đầu ra và nội dung đã render, và, khi áp dụng được, định dạng mà nó được render và một dạng xem có cấu trúc đã phân tích của nó — cùng với các nguồn và thiết lập riêng của attachment, mỗi thứ khi attachment khai báo nó. Một adapter đọc nội dung đó theo dạng đầu ra mà nó nhắm tới, đánh giá một chính sách trên kết quả có cấu trúc, và ánh xạ kết quả thành các verdict halt / warn / info. Vì payload không tự nêu dạng đầu ra nào, một mẫu adapter phục vụ được mọi đích render; một dạng đầu ra mới là một adapter mới, không phải một thay đổi ở host.
Mỗi adapter ở giai đoạn render là một adapter theo nghĩa nêu trên: nó nói ABI của Aggrega ra bên ngoài và hấp thụ vào bên trong một định dạng riêng của đích hoặc hợp đồng của một engine chính sách bên ngoài, nhờ đó compiler không chứa bất kỳ logic định dạng đầu ra hay chính sách nào. Các engine Rego và CEL trong compiler phục vụ trực tiếp vai trò render-verdict; ngoài chúng, hai adapter render tham chiếu được phát hành làm ví dụ minh họa trong số các ví dụ Rust của bộ công cụ phát triển plugin, mỗi adapter cho một dạng đầu ra phổ biến.
../examples/policy-render-verdict/ gắn một rule tại render-verdict lên đầu ra của bốn đích — các đối tượng Kubernetes, một tệp Docker Compose, một cấu hình gốc Terraform và một template CloudFormation — được viết một lần cho mỗi engine trong compiler, và kiểm tra rằng vi phạm được cài sẵn của mỗi đích làm dừng build còn mẫu đối chứng của nó thì qua.
Để viết adapter của riêng bạn, ở vai trò này hoặc bất kỳ vai trò nào khác, hãy bắt đầu từ khung adapter governance mà mỗi bộ công cụ phát triển plugin cung cấp: Viết plugin governance của riêng bạn dẫn dắt từ khung đó đến một build mà adapter từ chối.
Đầu ra YAML, JSON và Terraform HCL — adapter render Rego tham chiếu
Adapter render Rego tham chiếu chạy Rego do người vận hành cung cấp trên mọi đầu ra render YAML hoặc
JSON, và trên đầu ra HCL gốc của Terraform. Đây là một ví dụ minh họa
cho dạng giai đoạn render: cùng bộ đánh giá Rego chạy gốc trên Wasm như engine trong
compiler, và cùng quy ước thu thập deny / warn / audit được ánh xạ lên
cùng ba mức độ nghiêm trọng của verdict, suy luận trên các tệp đã render thay vì trên
đồ thị build.
Nó độc lập với dạng đầu ra trên các đích YAML/JSON. Adapter phân tích
nội dung của mỗi artifact thành một hoặc nhiều tài liệu YAML hoặc JSON — YAML là một
tập bao của JSON, nên một template JSON như một stack CloudFormation được phân tích
qua cùng một parser — và cung cấp các tài liệu đã phân tích cho chính sách
bên cạnh nội dung thô. Một chính sách suy luận trên đầu ra render có cấu trúc của
bất kỳ đích nào như vậy bằng Rego thông thường: input.artifacts[_].documents[_] trả về
các tài liệu đã phân tích (services của một tệp Docker Compose, Resources của một template CloudFormation),
input.artifacts[_].content trả về văn bản thô, và
đối tượng settings của attachment là tài liệu data của Rego. Ví dụ, một chính sách
yêu cầu registry được phê duyệt trên đầu ra Docker Compose sẽ từ chối mọi service
mà image không mang tiền tố registry.
Adapter cũng suy luận trên đầu ra render HCL gốc của Terraform. Một tệp
.tf gốc không phải YAML cũng không phải JSON, nên adapter chiếu nó vào cùng
đối tượng chuẩn mà một tệp Terraform-JSON (.tf.json) vốn được phân tích thành: một chính sách
đọc một thuộc tính tài nguyên tại
input.artifacts[_].documents[_].resource.<type>.<name>.<attr> — với một instance RDS,
input.artifacts[_].documents[_].resource.aws_db_instance[_].allocated_storage
— theo cùng một cách bất kể compiler xuất dạng Terraform nào. Kiểu thuộc tính được
giữ nguyên (số vẫn là số, boolean vẫn là boolean), và một biểu thức Terraform
chưa được giải quyết vẫn là một chuỗi ở dạng ${ ... }. Các thân Terraform-JSON
(.tf.json, .auto.tfvars.json) được phân tích qua đường YAML/JSON không thay đổi, và
một tệp template Terraform (.tftpl) — văn bản template chứ không phải cấu hình
độc lập — không được chiếu và hiện ra parse_error như mọi nội dung
không có cấu trúc.
Danh sách đó nói parser của adapter chấp nhận gì, không phải compiler xuất ra gì. Hai tập này không giống nhau, và tệp biến được tự động nạp là trường hợp chúng khác nhau: compiler không xuất overlay như vậy trên bất kỳ đường nào — đầu vào của một module có nguồn là các đối số của khối module của component đó trong cấu hình gốc của boundary — nên dạng này chỉ đến được tầm nhìn của chính sách khi một module được vendor mang theo một tệp của riêng nó, mà đường có nguồn sao chép nguyên văn vào đầu ra. Một chính sách được viết với kỳ vọng compiler tạo ra tệp đó sẽ không bao giờ kích hoạt.
Khi nội dung của một artifact không phân tích được, adapter không âm thầm cho phép nó: nó giữ nội dung thô, không cung cấp tài liệu đã phân tích nào cho artifact đó, và ghi thông báo của parser vào input.artifacts[_].parse_error, để một chính sách có thể dừng bản build một cách tường minh trên một artifact bị lỗi định dạng. Như với engine Rego trong compiler, một chính sách gọi một builtin mà bộ đánh giá nhúng không triển khai sẽ thất bại rõ ràng — một lỗi nêu tên plugin, không bao giờ là một sự cho phép âm thầm.
Đầu ra Kubernetes — adapter render Kubewarden
Adapter render Kubewarden chạy các chính sách admission kiểu Kubewarden trên
các manifest Kubernetes đã render. Nó hấp thụ vào bên trong hợp đồng admission-review
của Kubernetes: một chính sách Kubewarden nhận một yêu cầu bao một đối tượng duy nhất
và trả về một phản hồi chấp nhận hoặc từ chối. Ở giai đoạn render, đầu ra của bản build
vốn đã là một tập tài nguyên Kubernetes, khiến giai đoạn đó là nơi tự nhiên
để chạy một chính sách dạng admission. Với mỗi đối tượng đã render, adapter
suy ra các trường admission từ chính đối tượng đã phân tích, bao đối tượng trong
một yêu cầu dạng admission-review bên trong guest, chạy chính sách, và ánh xạ
phản hồi thành một verdict: một sự từ chối trở thành một verdict; một sự chấp nhận không phát ra
gì. Chính sách tham chiếu đi kèm là một quy tắc yêu cầu nhãn — mọi đối tượng phải
mang một khóa nhãn do settings nêu tên — một mẫu Kubewarden phổ biến.
Phạm vi chung của các adapter ở giai đoạn render
- Giai đoạn render, một dạng đầu ra cho mỗi adapter. Một adapter ở giai đoạn render suy luận trên các artifact đã render, không phải đồ thị IR, và nhắm tới dạng đầu ra mà nó phân tích — YAML/JSON và HCL gốc của Terraform cho adapter render Rego tham chiếu, các đối tượng Kubernetes cho adapter Kubewarden. Một chính sách ở giai đoạn đồ thị, hoặc một chính sách trên một dạng đầu ra mà không adapter phát hành nào phân tích, là một guest khác.
- Chỉ kiểm tra hợp lệ. Một adapter ở giai đoạn render chấp nhận hoặc từ chối; nó không bao giờ trả về một đối tượng đã bị biến đổi. Đối tượng đã biến đổi của một chính sách biến đổi bị bỏ qua — compiler không bao giờ viết lại đầu ra đã render từ một verdict chính sách. Một chính sách quyết định; nó không chỉnh sửa.
Gắn một chính sách
Người vận hành gắn một plugin quản trị thông qua danh sách plugins.governance trong
cấu hình workspace (.aggrega-config.yaml). Mỗi mục nêu tên một plugin, role
mà nó được gắn vào, và, tùy chọn, kênh with cung cấp các quy tắc và tham số
tinh chỉnh của nó:
plugins: governance: - uri: <resolvable-plugin-reference> role: ir-verdict with: sources: - ./policies/replicas.rego settings: max_replicas: 3uri phân giải tới plugin. Host đọc từng tệp sources tại thời điểm build
và chuyển các byte của nó cho guest, còn settings thì được chuyển qua nguyên văn. Một build
không gắn plugin quản trị nào sẽ chạy socket như một thao tác rỗng, nên việc gắn
hoàn toàn chỉ bổ sung thêm cho một workspace.
Một plugin phục vụ nhiều vai trò được gắn một lần cho mỗi vai trò, mỗi lần gắn có quy tắc riêng và thiết lập riêng:
plugins: governance: - uri: governance/rego:<version> role: label-transform with: sources: - ./policies/tagging.rego - uri: governance/rego:<version> role: ir-verdict with: sources: - ./policies/topology.rego settings: translation: - key: blocked severity: haltPhiên bản mà một attachment nêu tên. Một uri nêu tên một thực thể Plugin — tọa độ <pluginType>/<name> và, sau dấu hai chấm, một phiên bản — và phiên bản tham gia vào quá trình phân giải. Với hai engine được biên dịch vào CLI, thực thể đến từ một trong hai nơi. Mỗi bản phát hành compiler công bố các thực thể Plugin của governance/rego và governance/cel ở phiên bản của chính nó, và catalog thư viện chuẩn chứa chúng, mỗi thực thể ở phiên bản của bản phát hành đã công bố nó; một workspace đọc chúng từ các thư mục catalog mà nó liệt kê. Tệp nhị phân aggrega mang một thực thể cho mỗi engine, ở phiên bản của chính bản phát hành của nó và không phiên bản nào khác. Một attachment nêu tên một phiên bản mà cả hai nơi đều không mang, và chưa có lần pull nào tải về content cache, sẽ dừng build với E0137, kèm tên tham chiếu.
Vì vậy, một attachment nêu tên một phiên bản mà catalog workspace đọc có mang. Phiên bản đó cũng được phân giải từ catalog dưới một bản phát hành aggrega khác với bản của chính nó, trong khi một phiên bản chỉ tệp nhị phân mang — phiên bản của chính bản phát hành của nó — chỉ được phân giải với bản phát hành đó, ở vai trò verdict cũng như ở vai trò transform. Ở vai trò transform, pull ghim phiên bản nó đã phân giải vào lockfile, và từ chối với E0103 một phiên bản mà cả catalog workspace đọc lẫn tệp nhị phân đều không mang. Phiên bản chọn thực thể Plugin, thứ ghi lại các export và giới hạn runtime của plugin, chứ không chọn engine: khi tham chiếu đã được phân giải, engine chạy là engine được biên dịch vào tệp nhị phân đang chạy build, vì các plugin tích hợp trong tệp nhị phân là nơi đầu tiên mà module của một plugin được đọc. Một plugin governance do workspace tự khai báo — một thực thể Plugin trong thư mục catalog riêng của nó, với .wasm nằm bên cạnh — được nêu tên ở phiên bản mà thực thể đó ghi lại.
Mỗi vai trò chọn một hàm đầu vào mặc định — verdict_ir cho vai trò đánh giá
đồ thị, verdict_render cho vai trò đánh giá các artifact đã render,
mutate cho vai trò định hình nhãn, transform_annotations cho
vai trò chèn annotation — và một lần gắn có thể trỏ một vai trò tới một export khác
bằng function:. Host từ chối điều phối tới một export mà guest không khai báo
trong bản tự báo cáo describe() của nó, nên một lần gắn nêu một vai trò mà guest không
phục vụ sẽ được báo cáo theo tên, trước khi guest chạy, thay vì lặng lẽ không làm gì.
function: nêu một export trên plugin mà uri nêu. Một mục gắn ở vai trò phán quyết — ir-verdict hoặc render-verdict — nêu function: mà không có uri: là nêu một hàm không thuộc plugin nào, nên cấu hình bị từ chối ngay khi được đọc, dưới mã E0224, kèm tên tệp và vị trí của mục trong danh sách của nó: hãy thêm uri của plugin xuất ra hàm đó.
Danh sách plugins.governance có một danh sách đi kèm mang tính bổ sung, plugins.governance_append:
các mục trong danh sách đi kèm được nối vào danh sách governance đã phân giải ở mỗi
tầng cấu hình, nên một cấu hình workspace hoặc cấu hình toàn cục kết hợp các lần gắn
chính sách thay vì che khuất một danh sách gốc.
Lớp phủ do CI sở hữu
Bên cạnh .aggrega-config.yaml do con người viết, một pipeline tự động có thể sở hữu một
tệp lớp phủ riêng, .aggrega-config-append-ci.yaml. Tệp này tồn tại để pipeline
có thể gắn các chính sách (hoặc cấu hình dạng danh sách khác) mà nó kiểm soát mà không bao giờ
phải sửa cấu hình gốc do nhà phát triển viết — pipeline có thể ghi đè
toàn bộ tệp lớp phủ của chính nó.
Lớp phủ hoàn toàn mang tính bổ sung. Nó được xác thực theo cùng lược đồ
cấu hình như tệp gốc, và với mỗi trường dạng danh sách, các mục của nó được
nối vào danh sách đã phân giải. Nó chỉ có thể thêm: nó không thể xóa một mục
gốc và không thể ghi đè vô hướng một giá trị gốc — một khóa vô hướng hoặc khóa map mà nó mang
không có ý nghĩa bổ sung và bị bỏ qua (và được nêu tên trong một cảnh báo phân giải)
thay vì được áp dụng. Và nó không bao giờ neo gốc của một workspace: chỉ một
.aggrega-config.yaml mang khối workspace: mới làm điều đó, nên việc thả
lớp phủ vào một thư mục sẽ thêm các lần gắn mà không thay đổi nơi workspace
bắt đầu.
Điều này cho pipeline một điểm nối gọn gàng để thực thi chính sách toàn tổ chức:
pipeline thả một .aggrega-config-append-ci.yaml nêu tên các plugin chính sách
bắt buộc, và những lần gắn đó được hợp nhất lên trên bất cứ thứ gì nhà phát triển đã viết,
không bao giờ thay thế nó.
# .aggrega-config-append-ci.yaml — owned by the pipeline, additive onlyplugins: governance_append: - uri: <organization-policy-plugin-reference> role: render-verdict with: settings: required_label: app.kubernetes.io/nameexamples/policy-org-overlay/ build một workspace với attachment của một nhóm, attachment của một tổ chức được thêm qua governance_append của một tệp cấu hình toàn cục, và attachment của một pipeline được thêm qua overlay này, rồi kiểm tra mỗi tổ hợp in ra gì và có hoàn tất hay không.
Kiểm thử một policy trước khi nó chặn build
Một rule Rego nêu tên một đường dẫn mà payload của vai trò nó không mang thì không phải là lỗi: đường dẫn không xác định, rule không bao giờ thỏa, và build hoàn tất như thể policy đã cho phép. Vì vậy, một policy mới đạt tới halt qua ba bước: gắn nó ở một mức độ nghiêm trọng chỉ báo cáo mà không dừng, kiểm tra mọi đường dẫn nó nêu với payload mà vai trò của nó nhận, và đọc những gì nó báo cáo trên các build mà nó sẽ đánh giá.
Các lệnh dưới đây chạy trong một bản sao của examples/policy-org-overlay/ mà .aggrega-config.yaml của nó gắn một policy mới thay cho policy của nhóm. Policy này nhằm từ chối một kho dữ liệu chạy với tính sẵn sàng cao bị tắt, và rule của nó được sao chép từ một policy định hình nhãn:
package datastores
import rego.v1
deny contains msg if { some id, node in input.graph.nodes node.labels["component.aggrega.ai/category"] == "datastore" input.graph.spec.infra_mapping[id].ha.enabled == false msg := sprintf("%v is a datastore running with high availability off", [id])}Gắn nó để nó báo cáo. Policy thu thập dưới deny, vốn mặc định dừng build. Một translation chỉ nêu tên deny, ở mức warn, sẽ báo cáo mỗi quyết định của nó như một cảnh báo và để build hoàn tất; info thì thay vào đó ghi nhận chúng. Bản thân policy giữ nguyên như khi nó sẽ được thực thi:
plugins: governance: - uri: governance/rego:0.9.0 role: ir-verdict with: sources: - policies/datastore-ha.rego settings: translation: - key: deny severity: warnGhi payload ra và tra các đường dẫn trong đó. Khi một build đã điền lockfile của Release,
aggrega build --release release.yaml --dry-run --policy-input payloadssẽ ghi payload mà mỗi vai trò trao cho các attachment của nó vào payloads/ và không ghi gì khác, đồng thời báo cáo như sau, với <workspace> đại diện cho thư mục mà build đã chạy:
policy input: 4 file(s) written to <workspace>/payloads[… omitted: a lint notice about core/secret-value, the rendered files the run prints in place of writing them, the build's time, and the line saying only the policy inputs were written]Bốn tệp đó là annotation-transform.json, ir-verdict.json, label-transform.json và render-verdict.json; một vai trò không có gì được gắn cũng được ghi ra, nên một policy có thể được kiểm tra với vai trò của nó trước khi được gắn vào bất cứ đâu. Tại ir-verdict, label-transform và annotation-transform, tệp chính là tài liệu input mà policy đọc, nên mỗi đường dẫn mà rule nêu có thể được đọc ra từ đó bằng bất kỳ công cụ JSON nào trước khi tin tưởng rule:
jq '.graph.nodes' payloads/ir-verdict.json# nulljq -c '.graph.spec.nodes | keys' payloads/ir-verdict.json# ["db","web"]jq -c '.graph.spec.infra_mapping.db.ha' payloads/ir-verdict.json# {"enabled":false,"read_replicas":0}Các nút mà rule tìm không có ở đó: input.graph.nodes là nơi vai trò định hình nhãn mang chúng, còn tại ir-verdict chúng nằm ở input.graph.spec.nodes (xem Payload của mỗi vai trò cung cấp gì). Tệp cũng cho biết rule đã sửa phải quyết định điều gì: db là một kho dữ liệu, tính sẵn sàng cao của nó bị tắt, và nó cần được báo cáo.
Khi OPA đã được cài đặt, một policy Rego được đánh giá trực tiếp trên cùng tệp đó: opa eval -i payloads/ir-verdict.json -d policies/datastore-ha.rego 'data.datastores.deny'. Engine Rego trong compiler là một triển khai độc lập, nên phép đánh giá quyết định vẫn là phép đánh giá trong build: một builtin mà nó không triển khai sẽ dừng build thay vì được đánh giá.
Tại render-verdict, tệp không phải là input của policy. Mỗi artifact trong đó mang path, content và format của nó; các documents mà rule đọc được engine policy phân tích từ nội dung khi nó nhận payload, nên một rule trên documents không tìm thấy gì trong tệp. Một policy ở vai trò đó được kiểm thử nơi engine phân tích chúng: trong một build, như bước tiếp theo cho thấy.
Build, và so sánh những gì nó báo cáo với những gì payload nói. Với đường dẫn đã sao chép,
aggrega build --release release.yaml --auto-pullhoàn tất và không báo cáo gì:
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]Payload có một kho dữ liệu với tính sẵn sàng cao bị tắt, và policy không nói gì về nó: sự im lặng đó chính là lỗi, và không có gì khác trong build chỉ ra nó. Khi rule đọc input.graph.spec.nodes, cùng lệnh đó báo cáo db và hoàn tất:
policy plugin "rego" warning: db is a datastore running with high availability offPull 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]Thêm --dry-run sẽ báo cáo cùng các verdict và không ghi dist/ nào, nên vòng lặp chạy trên một workspace mà không làm xáo trộn đầu ra của nó.
Cùng rule đó viết cho engine CEL không thất bại một cách im lặng. Ở đó, đọc một khóa mà payload không mang là một lỗi đánh giá, nên với đường dẫn đã sao chép, trong policies/datastore-ha.cel được gắn với cùng translation,
{ "deny": input.graph.nodes .filter(n, input.graph.nodes[n].labels["component.aggrega.ai/category"] == "datastore" && input.graph.spec.infra_mapping[n].ha.enabled == false) .map(n, n + " is a datastore running with high availability off"),}sẽ dừng build ngay cả ở mức warn. Nó thoát với 1, và dòng cuối cùng nêu tên tệp policy và khóa:
ir-verdict: plugin "governance/cel:0.9.0": call "verdict_ir": wasm: plugin "cel" call to verdict_ir: policy source "datastore-ha.cel" could not be evaluated: No such key: nodesMột policy render-verdict được kiểm thử theo cùng cách. Được gắn tại render-verdict trong cùng workspace, với cùng translation, một rule từ chối một service Compose công bố một cổng trên host
package published
import rego.v1
deny contains msg if { some artifact in input.artifacts some doc in artifact.documents some name, service in doc.services count(service.ports) > 0 msg := sprintf("%v publishes a port on the host", [name])}sẽ báo cáo service duy nhất làm vậy:
policy plugin "rego" warning: web publishes a port on the host[… omitted: the pull's line, a lint notice about core/secret-value, the build's time and the line naming the dist/ directory it wrote]Sau đó thực thi nó. Gỡ bỏ translation sẽ đưa deny trở lại halt, và build đã báo cáo db giờ dừng lại vì nó, thoát với 1 và không ghi dist/ nào:
[… omitted: the lines printed while the lockfile is resolved, which carry the refusal below once more, and a lint notice about core/secret-value][POLICY_ERROR E0005] policy plugin "rego" rejected the build: db is a datastore running with high availability off caused by: policy violationKhông cần gỡ bỏ attachment chỉ báo cáo ở mọi nơi cùng lúc. Một tệp cấu hình có thể giữ translation của attachment ở warn trong khi overlay của một pipeline gắn cùng policy đó với deny ở halt, và đó là cách examples/policy-org-overlay/ triển khai rule của một tổ chức: một cảnh báo trên build của nhà phát triển, và lý do khiến build của pipeline dừng lại.
Chạy policy trong CI, trên đầu ra của bản build
Mọi điều ở trên đều gắn một policy bên trong một bản build. Có một con đường thứ hai, và nó không cần gì từ socket: chạy công cụ của riêng bạn trong pipeline, trên các tệp mà bản build đã ghi ra.
Cách này hoạt động được nhờ những gì một bản build xuất ra. Các target Kubernetes và Compose ghi ra
YAML; target Terraform ghi ra HCL gốc, hoặc JSON ở dạng .tf.json.
Đó là những định dạng mà các công cụ cấu hình trong hệ sinh thái vốn đã đọc được — và
aggrega build ghi các tệp thuần vào một thư mục, không có định dạng bao bọc, không có
chỉ mục, và không có gì cần giải nén. Vì vậy, một công cụ đọc YAML, JSON hoặc HCL chạy trên
đầu ra của bản build theo đúng cách nó chạy trên cấu hình do con người viết tay,
và Aggrega không cần thêm socket, loại plugin hay khóa cấu hình nào cho việc đó.
Vì vậy, một bộ quy tắc sẵn có không cần chuyển đổi. Nếu bạn đã lưu quy tắc trong Conftest, Kyverno CLI, kubeconform, Checkov hoặc OPA, các quy tắc đó chạy trên đầu ra của một bản build Aggrega đúng như hiện có, và công cụ đánh giá chúng chính là công cụ mà pipeline của bạn đã cài đặt sẵn.
Hai script quy tắc dùng ngay được, mỗi script kèm bước pipeline gọi nó và cả hai lần từ chối mà chúng đã tạo ra trên các bản build thực, có tại examples/policy-in-ci/. Chúng dùng yq và không gì khác, nên chúng chạy được mà không cần cài bộ công cụ policy nào; khuôn mẫu chúng thể hiện — đọc thư mục đầu ra, quyết định, thoát với mã khác 0 kèm tên các artifact vi phạm — là khuôn mẫu mà bất kỳ công cụ nào ở vị trí này cũng áp dụng.
Một quy tắc thuộc về con đường nào
Cả hai con đường đều là hạng nhất, và một workspace thường dùng cả hai. Điều quyết định là quy tắc cần thấy gì và khi nào nó cần hành động.
Gắn nó vào socket khi:
- bản build hoàn toàn không được tạo ra artifact. Một policy
ir-verdictchạy tại cổng phân tích tĩnh, trước khi bất cứ thứ gì được render, nên một lần dừng ở đó không để lại gì được ghi ra — không có tệp đầu ra nào để xem xét, cách ly, hay vô tình áp dụng. Một bước kiểm tra trong pipeline tất yếu chạy sau khi các tệp đã tồn tại. - quy tắc cần những dữ kiện mà chỉ bản build nắm giữ. Vai trò
ir-verdictđọc đồ thị đã được lắp ráp: các nút, các cạnh và socket của chúng, mọi attachment cùng slot mà nó đã lấp đầy, những giá trị mà tác giả đã khai báo là nhạy cảm, các đường định tuyến. Không thứ nào trong số đó còn lại trong đầu ra đã render — một manifest Kubernetes không ghi lại socket nào đã chuyển một giá trị hay Feature nào đã đóng góp một tài nguyên — nên một quy tắc về topo hay về nguồn gốc chỉ có một chỗ, và đó là socket. - quy tắc phải đúng ở bất cứ nơi nào bản build chạy. Một attachment governance nằm trong cấu hình workspace, nên nó áp dụng cho bản build cục bộ của nhà phát triển cũng như cho bản build của pipeline. Một bước kiểm tra trong pipeline áp dụng ở nơi pipeline chạy.
- quy tắc nên định hình bản build thay vì phán xét nó. Chỉ một vai trò transform làm được điều đó, và chỉ vì một người vận hành đã gắn nó.
Chạy nó trong CI khi:
- quy tắc đã tồn tại, trong một công cụ mà nhóm của bạn chạy và xem xét, trên một định dạng mà công cụ đó vốn đã phân tích được. Diễn đạt lại nó thành nội dung policy của socket là công việc mà cuối cùng không mang lại phạm vi bao phủ mới nào.
- quy tắc nói về các artifact đúng như target sẽ nhận chúng — tập tệp
cuối cùng, sau mọi transform, ở dạng được áp dụng. Đó cũng là đối tượng của vai trò
render-verdict, nên chỉ xét riêng điểm này thì hai con đường thấy cùng một thứ và lựa chọn phụ thuộc vào các điểm còn lại. - kết quả phát hiện dành cho người xem xét thay vì cho bản build. Một pipeline công bố các artifact và các kết quả phát hiện song song sẽ cho người xem xét cả hai; một bản build bị dừng chỉ cho họ một thông báo.
- bước kiểm tra vươn ra ngoài một bản build — so sánh đầu ra của bản build này với bản trước, với trạng thái đang chạy của một cluster, hoặc với một danh mục mà không payload build nào mang theo. Một policy ở một trong hai vai trò verdict chỉ thấy bản build mà nó được gắn vào, và đó là tất cả những gì nó thấy.
Các con đường kết hợp với nhau thay vì cạnh tranh: một bất biến topo dừng bản build từ
ir-verdict, rồi cùng pipeline đó chạy các quy tắc artifact sẵn có của hệ thống
trên những gì bản build đó đã ghi ra.
Tham chiếu chéo
plugin-contract.md— vị trí của socket trong pipeline, các dạng dữ liệu truyền có kiểu mà nó mang, và sandbox mà mọi plugin chạy bên trong.plugin-developer-guide.md— viết một plugin, bản tự mô tảdescribe(), và vòng đời publish → pull → build.../entities/plugin.md— thực thểPluginđưa một plugin vào catalog.../cli/aggrega-build.md— lệnh build điều phối socket.../schema/other/aggrega-config.md— schema cấu hình workspace, bao gồm bề mặt gắn kếtplugins.governance.../examples/policy-in-ci/— hai script quy tắc có thể chạy trên đầu ra của một bản build, kèm bước pipeline cho từng script.../examples/policy-data-class-route/— một quy tắcir-verdicttrên các route, được viết cho engine Rego, engine CEL và OPA đứng sau guest adapter tham chiếu, gắn theo từng bản build bằng một tệp--configcho mỗi engine, kèm một script kiểm tra rằng cả ba đều cho cùng một kết quả trên mọi Release.