Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Политика на уровне организации: правило команды, правило организации и правило конвейера

Политика команды, политика её организации и политика её конвейера выполняются вместе в одной сборке, и каждая подключена в собственном файле конфигурации. Команда подключает своё правило в своём рабочем пространстве; организация добавляет одно правило к каждой сборке, а конвейер — ещё одно, и ни один из них не редактирует файл команды. Сборка читает все применимые к ней файлы и выполняет все подключения, которые они содержат.

Правила сообщают о результатах со всеми тремя уровнями серьёзности вердикта: info и warn позволяют сборке завершиться, а halt останавливает её. Одно из них, правило организации, подключено дважды и каждый раз сообщается с другим уровнем серьёзности благодаря блоку translation.

Что собирается

экземплярсущность Component из каталогачем он является здесь
dbcore/datastore/mariadbбаза данных магазина
webcore/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.yamlplugins.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/, где сборка, запущенная в этом каталоге, его не читает, потому что он останавливает каждую сборку, которая его читает; шаг конвейера — скопировать его сюда:

Terminal window
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 оказывается предупреждением в сборке разработчика и причиной остановки сборки конвейера.

Создание примера

Этот пример можно собрать командами ниже или поручить сборку вашему ИИ-ассистенту.

Запишите пример в новую папку, названную по его имени:

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

Затем она выводит команды, которые нужно выполнить дальше. Первая переходит в новую папку:

Terminal window
cd policy-org-overlay

Сборка

Каталог стандартной библиотеки предоставляет сущности Components, Recipes, Feature и её FeatureRecipe. Они разрешаются из hub.aggrega.ai — реестра по умолчанию, который указывает .aggrega-config.yaml. Если рабочая копия каталога (где её взять) указана через --catalog, из реестра ничего не загружается, поэтому сборки выполняются офлайн. --auto-pull заполняет файл блокировки во время сборки; файл блокировки и отрисованный результат генерируются, а не поставляются.

Только с файлом команды:

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

сборка выводит предупреждение команды и завершается. Также с файлом организации:

Terminal window
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 ship
Pull complete: release.lock (entities=11, source_artifacts=0, external_inputs=0)
notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)
[… omitted: the build's time and the line naming the dist/ directory it wrote]

Каждый вердикт называет плагин, который его сообщил, rego, а не файл, который его подключил, поэтому предупреждение команды и предупреждение организации выглядят одинаково; сообщение, в котором сказано, чьё это правило, как в сообщении организации, — способ их различить.

После копирования оверлея конвейера та же команда останавливается:

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

Сборка завершается с кодом 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, этого скрипта не содержит.

Terminal window
./check.sh

check.sh собирает release.yaml пять раз через вспомогательный скрипт build-release, каждый раз в копии этого рабочего пространства: только с файлом команды; с файлом организации, указанным через --config; со скопированным оверлеем конвейера; с обоими; и с копией файла организации, которая записывает своё подключение в plugins.governance вместо компаньона, — тогда список команды заменяет его и выводится только вердикт команды. Для каждой сборки он проверяет код завершения, был ли записан dist/, и каждый вердикт, выведенный сборкой, — его уровень серьёзности и сообщение, без пропусков и без лишнего, — а там, где читается оверлей, также предупреждение, называющее auto_pull. Он выводит одну строку на сборку, затем вердикты, выведенные каждой, и завершается с кодом 1, если какой-либо результат отличается, выводя вывод этой сборки:

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

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