Встроенные плагины разметки
Два плагина управления, встроенные в 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: orderscore/datastore/redis: sessionsЧитаются все файлы в порядке имён, и запись в более позднем файле заменяет запись той же сущности Component в более раннем. Каждый тег — строка: значение, которое YAML читает как другой тип, например 3, останавливает сборку, поэтому заключите его в кавычки — "3".
| Настройка | Тип | По умолчанию | Действие |
|---|---|---|---|
default | string | пусто | тег, который получает узел, когда отображение не содержит его сущность 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, а два других помечены, как выше.
Где компилятор не интерпретирует
Ни плагин, ни компилятор не знают, что означает владелец, расписание резервного копирования или тег. Ключи и значения меток — это строки, которые задаёт подключение; компилятор передаёт каждому плагину узлы, применяет метки, о которых тот сообщает, и переносит их в граф сборки, где смысл им придаёт политика, которая их читает.