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

Встроенные плагины разметки

Два плагина управления, встроенные в CLI, которые записывают метки на узлы сборки без написания политики: что каждый читает, что каждый записывает, и пример подключения каждого с записанными им метками.

CLI содержит два плагина управления, которые формируют метки только на основе конфигурации, без написания кода на языке политик:

PluginЗаписывает
governance/label-injectorметки, которые список правил устанавливает на каждом узле, чьи метки соответствуют правилу
governance/selector-taggerодну метку, tag, значение которой каждому узлу задаёт отображение имён сущностей Component

Оба подключаются так же, как любой плагин управления, через plugins.governance в конфигурации рабочего пространства (см. Подключение политики), и оба перечислены среди встроенных плагинов. Подключения на этой странице указывают 0.9.0 — версию сущности Plugin каждого плагина в каталоге стандартной библиотеки; сборка использует плагин, встроенный в CLI.

Что у них общего

Они обслуживают роль label-transform и никакую другую. Каждый сообщает об изменениях меток в роли формирования меток — после того как граф сборки построен и до того как он оценивается (см. роли преобразования). При подключении к любой другой роли любой из них отклоняется до запуска, поскольку не объявляет экспорт для этой роли. На ir-verdict сборка останавливается с сообщением:

[E0085]
ir-verdict: plugin "governance/label-injector:0.9.0": call "verdict_ir": wasm: plugin "label-injector" does not declare export "verdict_ir" in describe(): wasm: plugin rejected by the sandbox
[E0085]
ir-verdict: plugin "governance/selector-tagger:0.9.0": call "verdict_ir": wasm: plugin "selector-tagger" does not declare export "verdict_ir" in describe(): wasm: plugin rejected by the sandbox

На render-verdict и annotation-transform отказ — тот же E0085, но с указанием verdict_render и transform_annotations соответственно.

Они читают метки узла и его сущность Component — и ничего больше. Метки узла — это те, которые он несёт в момент запуска плагина: собственные метки его сущности Component и метки, записанные любыми преобразованиями, перечисленными раньше. Его сущность Component — это имя, которое ему даёт type: сущности Aggregate, например core/datastore/mariadb. Ни один из плагинов не читает значения узла, сущность Release или её окружение: то, что любой из них записывает на узел, определяется только метками и сущностью Component этого узла.

Они записывают метки, и только метки. Каждое изменение, о котором сообщает любой из плагинов, указывает одну метку на одном узле сборки со строковым значением. Запись метки, которую узел уже несёт, заменяет её значение — включая собственную метку сущности Component. Ни один не удаляет метки и не может изменить значение, сущность Component или версию узла либо набор узлов: роль формирования меток не предлагает изменений такого рода (см. Формирование меток).

Их настройки не проверяются до запуска. Ни один не объявляет схему для своих settings, поэтому сборка передаёт их плагину в том виде, в каком они написаны. Ключ, который плагин не читает, игнорируется — rules с опечаткой ничего не устанавливает, и сборка завершается, — тогда как ключ, который плагин читает, со значением другого типа останавливает сборку с сообщением, в котором указан плагин, затем decode settings: и причина.

Они читают файлы из sources как YAML в порядке имён файлов. Плагин получает файлы, отсортированные по имени, в каком бы порядке их ни перечисляло подключение. Файл, не являющийся корректным YAML, останавливает сборку с сообщением, в котором указан плагин, затем parse source "<file>": и причина от парсера; файл, содержимое которого не соответствует форме, читаемой плагином, останавливает её с decode source "<file>": и причиной.

Входные данные, которые применяет сборка, хранит lock-файл. Pull, разрешающий lock-файл сущности Release, — aggrega pull или сборка с --auto-pull — записывает настройки каждого подключения и содержимое каждого его файла, а сборка применяет записанное. После изменения настроек подключения или одного из его файлов разрешите lock-файл заново; сборка без этого продолжит записывать метки, которые дают записанные входные данные.

При подключении без блока with: любой из них ничего не записывает, и сборка завершается.

Несколько подключений к label-transform выполняются в порядке перечисления, и каждое читает метки, записанные предыдущими, поэтому правило может соответствовать метке, установленной более ранним подключением. examples/policy-label-transform/ подключает оба плагина после политики Rego, а также вердикт, который читает то, что записали все три.

governance/label-injector

Инжектор меток добавляет метки на каждый узел, чьи метки соответствуют правилу.

Настройки инжектора меток

НастройкаТипПо умолчаниюДействие
rulesсписок правилнетправила, применяемые к каждому узлу; без правил плагин ничего не записывает

Каждое правило содержит два отображения ключей меток в строковые значения:

КлючПо умолчаниюДействие
matchнет парузел соответствует, если несёт каждую перечисленную пару, каждую с этим значением; правило без пар соответствует каждому узлу
setнет паркаждая пара записывается на каждый узел, которому соответствует правило

Метка, которой у узла нет, сравнивается как пустая строка, поэтому пара в match со значением "" соответствует и узлу, у которого этого ключа нет.

Правила применяются к каждому узлу в порядке перечисления, и метка, записанная более поздним правилом, заменяет значение, записанное более ранним правилом для того же ключа.

Откуда берутся правила

Плагин читает rules из своих настроек, если в них есть хотя бы одно правило. Если правил нет, он читает файлы из sources в порядке имён файлов и берёт правила из первого файла, чей список rules верхнего уровня содержит хотя бы одно правило, в той же форме:

rules:
- match: {}
set:
ops.example.com/owner: shop-team

Правила из последующих файлов не читаются. Файл перед ним, который не удаётся разобрать, останавливает сборку.

Подключённый инжектор меток и записанные им метки

Это подключение устанавливает владельца на каждом узле, а затем расписание резервного копирования и другого владельца на узлах категории datastore:

plugins:
governance:
- uri: governance/label-injector:0.9.0
role: label-transform
with:
settings:
rules:
- match: {}
set:
ops.example.com/owner: shop-team
- match:
component.aggrega.ai/category: datastore
set:
backup.example.com/schedule: nightly
ops.example.com/owner: data-team

При подключении только его к сущности Aggregate из examples/policy-label-transform/ — db это core/datastore/mariadb, cache это core/datastore/redis, web это core/devtool/adminer — aggrega build --release release-production.yaml --auto-pull --ir-graph выводит граф сборки, узлы которого несут:

"db": {
"labels": {
"component.aggrega.ai/type": "stateful-server",
"component.aggrega.ai/category": "datastore",
"component.aggrega.ai/upstream-licensing": "osi-approved",
"backup.example.com/schedule": "nightly",
"ops.example.com/owner": "data-team"
},
[… omitted: the node's Component, its version and the rest of the node]
},
"cache": {
"labels": {
"component.aggrega.ai/type": "server",
"component.aggrega.ai/category": "datastore",
"datastore.aggrega.ai/engine": "kv",
"component.aggrega.ai/hosting": "mixed",
"component.aggrega.ai/upstream-licensing": "mixed",
"backup.example.com/schedule": "nightly",
"ops.example.com/owner": "data-team"
},
[… omitted: the node's Component, its version and the rest of the node]
},
"web": {
"labels": {
"component.aggrega.ai/type": "server",
"component.aggrega.ai/category": "devtool",
"component.aggrega.ai/upstream-licensing": "osi-approved",
"ops.example.com/owner": "shop-team"
},
[… omitted: the node's Component, its version and the rest of the node]
}

Каждый узел соответствовал первому правилу и получил shop-team; db и cache из категории datastore соответствовали и второму, которое заменило значение на data-team. Все остальные метки — собственные метки сущности Component.

governance/selector-tagger

Тегировщик по селектору записывает на каждый узел метку tag, значение которой ищется по сущности Component узла.

Отображение и настройки тегировщика по селектору

Он всегда записывает ключ tag; ключ не настраивается.

Отображение берётся из файлов в sources. Каждый файл — это YAML-отображение имени сущности Component в тег, который получают её узлы:

core/datastore/mariadb: orders
core/datastore/redis: sessions

Читаются все файлы в порядке имён, и запись в более позднем файле заменяет запись той же сущности Component в более раннем. Каждый тег — строка: значение, которое YAML читает как другой тип, например 3, останавливает сборку, поэтому заключите его в кавычки — "3".

НастройкаТипПо умолчаниюДействие
defaultstringпустотег, который получает узел, когда отображение не содержит его сущность Component; если пусто, такой узел остаётся без tag

Без sources каждый узел получает default.

Подключённый тегировщик по селектору и записанные им метки

Это подключение помечает базу данных и кеш по tags.yaml — отображению выше, — а каждый другой узел помечает как untagged:

plugins:
governance:
- uri: governance/selector-tagger:0.9.0
role: label-transform
with:
sources:
- tags.yaml
settings:
default: untagged

При подключении только его к той же сущности Aggregate aggrega build --release release-production.yaml --auto-pull --ir-graph выводит граф сборки, узлы которого несут:

"db": {
"labels": {
"component.aggrega.ai/type": "stateful-server",
"component.aggrega.ai/category": "datastore",
"component.aggrega.ai/upstream-licensing": "osi-approved",
"tag": "orders"
},
[… omitted: the node's Component, its version and the rest of the node]
},
"cache": {
"labels": {
"component.aggrega.ai/type": "server",
"component.aggrega.ai/category": "datastore",
"datastore.aggrega.ai/engine": "kv",
"component.aggrega.ai/hosting": "mixed",
"component.aggrega.ai/upstream-licensing": "mixed",
"tag": "sessions"
},
[… omitted: the node's Component, its version and the rest of the node]
},
"web": {
"labels": {
"component.aggrega.ai/type": "server",
"component.aggrega.ai/category": "devtool",
"component.aggrega.ai/upstream-licensing": "osi-approved",
"tag": "untagged"
},
[… omitted: the node's Component, its version and the rest of the node]
}

core/devtool/adminer нет в отображении, поэтому web получил default. Без настройки default у web нет tag, а два других помечены, как выше.

Где компилятор не интерпретирует

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