Політика на рівні організації: правило команди, правило організації та правило конвеєра
Політика команди, політика її організації та політика її конвеєра виконуються разом в одному збиранні, і кожна прикріплена у власному файлі конфігурації. Команда прикріплює своє правило у своєму робочому просторі; організація додає одне правило до кожного збирання, а конвеєр — ще одне, і жоден із них не редагує файл команди. Збирання читає всі файли, що до нього застосовуються, і виконує кожне прикріплення, яке вони містять.
Правила повідомляють про результати з усіма трьома рівнями серйозності вердикту: info і warn дають збиранню завершитися, а halt зупиняє його. Одне з них, правило організації, прикріплено двічі, і щоразу про нього повідомляється з іншим рівнем серйозності завдяки блоку translation.
Що він збирає
| екземпляр | Component із каталогу | що це тут |
|---|---|---|
db | core/datastore/mariadb | база даних магазину |
web | core/devtool/adminer | інтерфейс адміністрування бази даних, під’єднаний до db |
Обидва компілюються в Docker Compose, у dist/compose/docker-compose.yaml. Один Aggregate, один Manifest і один Release, release.yaml; жоден із них не називає політики.
Три файли
| хто | файл | як збирання його читає | де записано прикріплення |
|---|---|---|---|
| команда | .aggrega-config.yaml | він позначає цей каталог як робочий простір, тож кожне збирання тут його читає | plugins.governance |
| організація | org/config.yaml | як глобальний файл конфігурації, вказаний для одного збирання через --config org/config.yaml | plugins.governance_append |
| конвеєр | pipeline/.aggrega-config-append-ci.yaml | після копіювання в цей каталог, як накладка конвеєра | plugins.governance_append |
Усі три прикріплення — це рушій Rego, governance/rego:0.9.0, у ролі ir-verdict, яка оцінює граф збирання до того, як щось буде відрендерено. 0.9.0 — версія його сутності Plugin у каталозі стандартної бібліотеки. Сам рушій вкомпільовано в CLI — aggrega plugin list перелічує governance/rego серед вбудованих модулів, — тож жодне збирання тут не завантажує плагін.
Файл організації — це глобальний файл конфігурації. На машині він один і читається під час кожного збирання: з розташування за замовчуванням або з файлу, який називає змінна середовища AGGREGA_CONFIG. --config <path> натомість називає файл для одного запуску, а власні файли робочого простору й надалі читаються поверх нього. В організації цей файл лежав би в розташуванні за замовчуванням на машині кожного розробника та в кожному конвеєрі; тут він лежить у org/, і збирання, які мають його читати, називають його. Явне зазначення глобального файлу описує порядок, у якому пробуються три способи.
Файл конвеєра — це накладка. Збирання читає .aggrega-config-append-ci.yaml у тих каталогах, з яких воно читає .aggrega-config.yaml, поруч із ним. Тут він зберігається в pipeline/, де збирання, запущене в цьому каталозі, його не читає, бо він зупиняє кожне збирання, яке його читає; крок конвеєра — скопіювати його сюди:
cp pipeline/.aggrega-config-append-ci.yaml .Кожен файл додає, а накладка конвеєра лише додає
І організація, і конвеєр записують своє прикріплення в plugins.governance_append, супутнє налаштування додавання для списку plugins.governance. Записи в супутньому налаштуванні приєднуються до розв’язаного списку після того, як прочитано власні списки кожного файлу, тож виконуються і plugins.governance команди, і запис організації, і жоден файл не називає інший. Організація записує супутнє налаштування, а не сам plugins.governance, бо список plugins.governance у файлі робочого простору замінює список із глобального файлу: правило організації, записане там, відкидається списком команди, і збирання нічого про це не виводить. Розширення списку замість його заміни перелічує супутнє налаштування для кожного спискового налаштування.
Накладка конвеєра може лише додавати. Те, що вона записує для спискового налаштування, додається до того, що розв’язали інші файли; вона нічого не видаляє і не перевизначає налаштування з єдиним значенням, як-от auto_pull. Ця накладка містить auto_pull: true, і збирання, що її читає, ігнорує цей ключ і повідомляє про це в попередженні. Якщо <workspace> позначає абсолютний шлях каталогу, у якому запущено збирання, рядок виглядає так:
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)Правила та рівень серйозності, з яким повідомляється кожне
Політика Rego збирає кожне рішення під ключем рішення, і ключ вибирає рівень серйозності, з яким повідомляється рішення. Без translation ключами є deny, warn і audit, про які повідомляється з рівнями halt, warn і info:
| рівень серйозності | що робить збирання |
|---|---|
halt | зупиняється, завершується з кодом 1 і не записує dist/ |
warn | завершується, виводить повідомлення і записує dist/ |
info | завершується, виводить повідомлення і записує dist/ |
Правило команди, policies/team.rego, збирає рішення під warn, а його прикріплення не оголошує translation, тож про нього повідомляється з рівнем 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])}Правило організації, org/policies/estate.rego, відхиляє компоненти з категорії, яку перелічують його налаштування, і записує, що запускає кожен компонент:
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 — налаштування кожного прикріплення, і політика читає налаштування свого прикріплення як документ data.
Трансляція: одне правило, два рівні серйозності
Блок translation у налаштуваннях прикріплення оголошує, які ключі рішень читаються і з яким рівнем серйозності повідомляється кожен. Він замінює зіставлення за замовчуванням, а не розширює його: ключ, який він не називає, не читається.
Файл організації запроваджує її правило як пораду. Її прикріплення повідомляє deny з рівнем warn, а audit — з рівнем info:
settings: refused_categories: [devtool] translation: - key: deny severity: warn - key: audit severity: infoКонвеєр прикріплює той самий файл і робить так, що те саме правило зупиняє збирання. Його трансляція називає лише deny, тож його прикріплення не повідомляє записи audit вдруге:
settings: refused_categories: [devtool] translation: - key: deny severity: haltОтже, одне правило для того самого web є попередженням у збиранні розробника і причиною зупинки збирання в конвеєрі.
Створення прикладу
Цей приклад можна зібрати командами нижче або доручити збирання вашому ШІ-асистенту.
Запишіть приклад у нову теку, названу за ним:
aggrega scaffold --example policy-org-overlayПотім вона виводить команди, які слід виконати далі. Перша переходить у нову теку:
cd policy-org-overlayЗбирання
Каталог стандартної бібліотеки надає сутності Components, Recipes, Feature та її FeatureRecipe. Вони розв’язуються з hub.aggrega.ai — типового реєстру, який називає .aggrega-config.yaml. Якщо локальну копію каталогу (де її отримати) вказано через --catalog, нічого не завантажується з реєстру, тож збирання виконуються офлайн. --auto-pull заповнює файл блокування під час збирання; файл блокування та відрендерений результат генеруються, а не постачаються.
Лише з файлом команди:
aggrega build --release release.yaml --auto-pullзбирання виводить попередження команди і завершується. Також із файлом організації:
aggrega build --release release.yaml --auto-pull --config org/config.yamlвоно виводить записи організації з рівнем info і її правило з рівнем warn поруч із попередженням команди та все одно завершується:
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 shipPull 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]Кожен вердикт називає плагін, який про нього повідомив, rego, а не файл, який його прикріпив, тож попередження команди й попередження організації виглядають однаково; повідомлення, яке каже, чиє це правило, як повідомлення організації, — спосіб їх розрізнити.
Після копіювання накладки конвеєра та сама команда зупиняється:
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Збирання завершується з кодом 1 і не записує dist/. Про правило організації повідомляється двічі, по одному разу кожним прикріпленням: з рівнем warn прикріпленням організації та з рівнем halt прикріпленням конвеєра. Записи audit з’являються один раз, лише з прикріплення організації. Видаліть .aggrega-config-append-ci.yaml із цього каталогу, щоб знову збирати без нього.
З ШІ-асистентом
ШІ-асистент, налаштований з інструментами Aggrega, може зробити те саме: вставте йому цей промпт.
Використовуйте лише інструменти Aggrega і не створюйте жодної теки самостійно. Якщо тека Workspace ще не містить теки `policy-org-overlay`, викличте один раз інструмент `scaffold`, задавши для `example` значення `policy-org-overlay` і не задаючи `dir`: він запише приклад у нову теку `policy-org-overlay`. Потім викличте інструмент `build`, задавши для `workspace_root` значення `policy-org-overlay`, для `release` — `release.yaml`, для `auto_pull` — true і для `write` — true, і скажіть мені, що повідомила політика. Потім викличте інструмент `cli-build`, який запускає `aggrega build` і приймає його прапорець `--config`, задавши для `workspace_root` значення `policy-org-overlay`, для `release` — `release.yaml`, для `auto_pull` — true і для `config` — `org/config.yaml`, і скажіть мені, що політика повідомила цього разу. Скажіть мені, які файли записала кожна збірка; вони розташовані в `policy-org-overlay/dist/`.Перевірка кожної збірки
Ця самоперевірка виконується в робочій копії репозиторію документації, яка містить потрібний їй спільний допоміжний скрипт збирання; копія, записана aggrega scaffold --example, цього скрипту не містить.
./check.shcheck.sh збирає release.yaml п’ять разів через допоміжний скрипт build-release, щоразу в копії цього робочого простору: лише з файлом команди; з файлом організації, названим через --config; зі скопійованою накладкою конвеєра; з обома; і з копією файлу організації, яка записує своє прикріплення в plugins.governance замість супутнього налаштування, — тоді список команди замінює його і виводиться лише вердикт команди. Для кожного він перевіряє код завершення, чи було записано dist/, і кожен вердикт, виведений збиранням, — його рівень серйозності та повідомлення, без пропусків і без зайвого, — а там, де читається накладка, ще й попередження, що називає auto_pull. Він виводить по одному рядку на збирання, потім вердикти, виведені кожним, і завершується з кодом 1, якщо будь-який результат відрізняється, виводячи вивід цього збирання:
LAYERS EXIT DIST VERDICT----------------------------------------------------------------------------------------------------team 0 yes OKteam + organization 0 yes OKteam + pipeline 1 no OKall three 1 no OKteam + 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.Копії створюються в тимчасовому каталозі, а шлях до каталогу в їхньому .aggrega-config.yaml робиться абсолютним, щоб він і далі розв’язувався звідти; жоден файл у цьому каталозі не редагується і не записується. Він використовує бінарний файл, який знаходить ./build-release.sh, тож його вибирає AGGREGA_BIN, а аргументи після -- передаються кожному збиранню. Його код завершення — це весь вердикт.
Де компілятор не інтерпретує
Компілятор читає три файли, об’єднує прикріплення, які вони містять, передає кожній політиці граф збирання та її налаштування і діє відповідно до рівня серйозності, з яким повідомляється кожне рішення. Він не знає, що таке devtool, чому організація не постачала б його або що висока доступність важлива для команди: ці значення — правила й налаштування політик. Про ролі, корисні навантаження та ключі рішень див. сокет врядування.
Файли
aggregate.yaml— база даних та під’єднаний до неї інтерфейс адміністрування.manifest.yaml— прив’язує кожен тип компонента та сутність Feature для секретів до відповідного Docker Compose Recipe.release.yaml— єдиний Release..aggrega-config.yaml— файл команди: типовий реєстр і прикріплення команди.policies/team.rego— правило команди.org/config.yaml— глобальний файл конфігурації організації та її прикріплення.org/policies/estate.rego— правило організації.pipeline/.aggrega-config-append-ci.yaml— накладка конвеєра, яка читається після копіювання в цей каталог.build-release.sh— збирає сутність Release, виводячи еквівалентну командуaggrega build.check.sh— виконує п’ять збірок і перевіряє кожен результат.