Политика на уровне организации: правило команды, правило организации и правило конвейера
Политика команды, политика её организации и политика её конвейера выполняются вместе в одной сборке, и каждая подключена в собственном файле конфигурации. Команда подключает своё правило в своём рабочем пространстве; организация добавляет одно правило к каждой сборке, а конвейер — ещё одно, и ни один из них не редактирует файл команды. Сборка читает все применимые к ней файлы и выполняет все подключения, которые они содержат.
Правила сообщают о результатах со всеми тремя уровнями серьёзности вердикта: 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— выполняет пять сборок и проверяет каждый результат.