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

Политика над отрисованным результатом: одно внутреннее правило, четыре цели, два движка

Одно внутреннее правило, подключённое в роли render-verdict, оценивает файлы, которые сборка записывает для четырёх целей, и отклоняет нарушение, внесённое в каждую из них. У правила два условия:

Каждый образ контейнера указывает фиксированную версию — тег, отличный от latest, или дайджест. Каждый экземпляр базы данных хранит свои данные в зашифрованном виде.

Это рабочее пространство собирает один Aggregate для четырёх целей — Kubernetes через Helm, Docker Compose, Terraform и CloudFormation. Роль render-verdict оценивает файлы, которые записывает сборка, после того как их отрисовали все цели, и правило читает собственную форму результата каждой цели: образы в объектах Kubernetes и в файле Compose, экземпляр RDS в файле Terraform и в шаблоне CloudFormation. Для каждой цели есть сущность Release, которая проходит проверку, и сущность Release с внесённым нарушением, которую правило отклоняет.

Правило написано дважды, по одному разу для каждого движка политик, скомпилированного в CLI, — Rego и CEL, — и обе копии согласуются в каждой сборке здесь. Скрипт рядом с сущностями Releases собирает все шестнадцать комбинаций и проверяет каждый результат.

aggrega build

ваша политика

подключена к компилятору

пройдено

файлы записаны

готовы к проверке и развёртыванию

не пройдено

сборка остановлена

policy plugin "rego" rejected the build: terraform/modules/db/main.tf: the RDS instance db stores its data unencrypted

Политика может остановить сборку и сказать, что исправить. Она никогда не изменяет ваши файлы, чтобы они прошли проверку.

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

экземплярсущность Component из каталогачем он является здесь
dbcore/datastore/postgresбаза данных заказов
reportcore/compute/taskзадание формирования отчётов, читающее db и запускаемое вручную: оно содержит core/manual-trigger, поэтому при развёртывании сущности Release запуск не начинается

report читает адрес, порт и имя базы данных через своё подключение database как DB_HOST, DB_PORT и DB_NAME. Aggregate — один и тот же файл для каждой сборки; каждая сущность Release называет Manifest, который выбирает цель:

Manifestdbreport
manifest-helm.yamlhelm/postgres, StatefulSethelm/task, CronJob, удерживаемый в приостановленном состоянии
manifest-compose.yamlcompose/postgres, сервисcompose/task, сервис за профилем
manifest-terraform.yamlterraform/postgres-rds, экземпляр RDSterraform/task-ecs, определение задачи Amazon ECS
manifest-cloudformation.yamlcloudformation/postgres-rds, экземпляр RDScloudformation/task-ecs, определение задачи Amazon ECS

Каждый Recipe здесь выполняет отрисовку только из каталога: база данных Kubernetes синтезируется, а не загружается как чарт, тело базы данных Terraform пишет её Recipe, а модуль задачи Terraform хранится рядом с её Recipe. Поэтому каждая сборка выполняется офлайн.

Восемь сущностей Releases

Releaseцелевая платформачто находит правилосборка
release-helm.yamlKubernetesreport запускает registry.example.com/orders-report:1.4.2завершается
release-helm-unpinned.yamlKubernetesreport запускает тот же образ с тегом latestостанавливается
release-compose.yamlDocker Composereport запускает registry.example.com/orders-report:1.4.2завершается
release-compose-unpinned.yamlDocker Composereport запускает образ без тегаостанавливается
release-terraform.yamlTerraformэкземпляр зашифрован ключом, который называет сущность Releaseзавершается
release-terraform-unencrypted.yamlTerraformсущность Release не называет ключа, поэтому экземпляр не зашифрованостанавливается
release-cloudformation.yamlCloudFormationсущность Release включает StorageEncryptedзавершается
release-cloudformation-unencrypted.yamlCloudFormationсущность Release оставляет его выключеннымостанавливается

Образ определяет сущность Release: core/compute/task не упаковывает никакого программного обеспечения, поэтому Release указывает образ, который выполняет запуск, в infra.image, включая тег. На двух целях AWS шифрование базы данных тоже определяет Release. Terraform Recipe читает infra.overrides.kms_key_id и, если он задан, отрисовывает storage_encrypted = true рядом с ключом; CloudFormation Recipe читает infra.overrides.StorageEncrypted и KmsKeyId под собственными именами свойств ресурса. Сущность Release, которая не задаёт ни того, ни другого, отрисовывает экземпляр вообще без атрибута шифрования — именно так поступают сущности Releases с внесёнными нарушениями.

Базы данных Kubernetes и Compose запускают образ postgres:16 с фиксированным тегом, поэтому правило оценивает их и пропускает в каждой сущности Release.

Подключение правила

.aggrega-config.yaml указывает хаб в качестве своего реестра и не объявляет ни одного каталога сущностей и ни одного подключения управления. Правило подключается файлом, который сборка указывает через --config: governance-rego.yaml для движка Rego, governance-cel.yaml для движка CEL. Файл для Rego выглядит так:

plugins:
governance:
- uri: governance/rego:0.9.0
role: render-verdict
with:
sources:
- policies/house-rule.rego

--config указывает глобальный файл конфигурации для этого запуска вместо того, который иначе прочитала бы машина, и .aggrega-config.yaml этого рабочего пространства по-прежнему накладывается поверх него. Список plugins.governance в файле рабочего пространства заменил бы список из указанного файла, поэтому файл рабочего пространства его не объявляет. 0.9.0 — версия сущности Plugin каждого движка в каталоге стандартной библиотеки. Оба движка скомпилированы в CLI — aggrega plugin list перечисляет governance/rego и governance/cel среди встроенных модулей, — поэтому ни одна сборка здесь не загружает плагин.

Что читает политика render-verdict

Политика в роли render-verdict читает файлы, которые записывает сборка, в input.artifacts, по одной записи на файл, отсортированные по пути. Каждая запись содержит:

  • path — путь файла внутри dist/, например terraform/modules/db/main.tf;
  • content — текст файла в том виде, в каком он записан;
  • format — формат, который провайдер цели объявил для файла: yaml для файла Compose, json для шаблона CloudFormation, hcl для каждого файла Terraform, включая тело базы данных, которое пишет её Recipe. Там, где ничего не объявлено, это пустая строка, как для файлов Kubernetes здесь;
  • documents — содержимое файла, разобранное в структуру, в виде списка документов: здесь по одному на каждый файл;
  • parse_error — присутствует только у файла, который не удалось разобрать, вместо documents.

Помимо файлов, input.sources содержит собственный файл политики подключения, а input.settings — его настройки: здесь это пустой объект, поскольку это подключение их не объявляет.

aggrega build --release <release> --dry-run --policy-input <dir> записывает полезную нагрузку, которую получает каждая роль, в <dir> и больше ничего не записывает. В роли render-verdict этот файл — то, что получает движок, а не то, что читает политика: каждый файл в нём содержит свои path и content и format, объявленный его провайдером, а движок разбирает documents из содержимого после получения полезной нагрузки. Поэтому файл перечисляет файлы, которые будут показаны правилу, но не их документы. После того как сборка release-terraform.yaml заполнила свой файл блокировки:

Terminal window
aggrega build --release release-terraform.yaml --config governance-rego.yaml --dry-run --policy-input payloads
jq -c '[.artifacts[].path]' payloads/render-verdict.json
# ["terraform/aggrega.modules.tf","terraform/modules/db/main.tf","terraform/modules/report/aggrega.provenance.tf","terraform/modules/report/main.tf","terraform/modules/report/variables.tf"]

Путь, который правило читает внутри documents, проверяется в сборке, где движок их разобрал. Ни один файл, который пишут эти сущности Recipes, не проваливает разбор, поэтому ни один файл здесь не содержит parse_error. Каждое условие этого правила читает documents, поэтому файл, который не удалось разобрать, прошёл бы его непроверенным; правило, которое не должно этого допускать, добавляет условие, отклоняющее файл с parse_error.

Как каждое условие читает форму своей цели

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

Compose записывает один файл, документ которого задаёт каждый сервис по имени в services:

deny contains msg if {
some artifact in input.artifacts
some doc in artifact.documents
some name, service in doc.services
unpinned(service.image)
msg := sprintf("%v: service %v runs %v, an image with no tag or the tag latest", [artifact.path, name, service.image])
}

Объекты Kubernetes содержат свои контейнеры в шаблоне pod, который CronJob держит на один уровень глубже, чем другие рабочие нагрузки, в spec.jobTemplate.spec:

pod_template(doc) := doc.spec.jobTemplate.spec.template if doc.kind == "CronJob"
pod_template(doc) := doc.spec.template if doc.kind != "CronJob"

Terraform в нативном HCL вкладывает блок под его тип, а затем под каждую из его меток, и последняя метка содержит список блоков, потому что блоки с общими типом и метками собираются в один список. Поэтому атрибуты экземпляра находятся на один индекс ниже его имени, и условие обходит этот список:

deny contains msg if {
some artifact in input.artifacts
native_hcl(artifact)
some doc in artifact.documents
some name, blocks in doc.resource.aws_db_instance
some block in blocks
not block.storage_encrypted == true
msg := sprintf("%v: the RDS instance %v stores its data unencrypted", [artifact.path, name])
}

Список здесь важнее, чем для правила, которое ищет значение, потому что это условие отклоняет по отсутствию. Если написать его для одного блока — some name, block in doc.resource.aws_db_instance, — то block будет списком, block.storage_encrypted на нём не определён, а not выполняется для всего неопределённого: условие отклонит и release-terraform.yaml, экземпляр которого зашифрован, с тем же сообщением, что и сущность Release с внесённым нарушением.

Файл .tf.json читается так, как его записал Recipe, где имя содержит сам блок, поэтому правило, написанное для одной формы, не читает другую. Вот почему условие сначала читает format: native_hcl принимает файл с форматом hcl или с пустым форматом и именем, оканчивающимся на .tf, — файл, для которого ни один провайдер не объявил формат, разбирается по имени, поэтому и правило распознаёт его по имени, а не пропускает. Каждый файл Terraform, собранный здесь, объявлен как hcl, поэтому ни один файл здесь не распознаётся по имени. Эти сущности Recipes не пишут файлов .tf.json, поэтому правило не читает другую форму. Что раскрывает полезная нагрузка каждой роли описывает обе формы.

CloudFormation записывает один шаблон, ресурсы которого заданы по логическому ID в Resources, каждый со своими Type и Properties:

deny contains msg if {
some artifact in input.artifacts
some doc in artifact.documents
some id, resource in doc.Resources
resource.Type == "AWS::RDS::DBInstance"
not resource.Properties.StorageEncrypted == true
msg := sprintf("%v: the RDS instance %v stores its data unencrypted", [artifact.path, id])
}

Экземпляр без свойства StorageEncrypted или с этим свойством, равным чему-либо, кроме true, отклоняется: not … == true выполняется в обоих случаях.

Почему правило CEL написано иначе

policies/house-rule.cel формулирует те же два условия и выносит тот же вердикт в каждой сборке здесь. Оно написано иначе в трёх местах, каждое — по причине, связанной с движком.

Оно проверяет каждый ключ, прежде чем его читать. Чтение ключа, которого нет в значении, в CEL — это ошибка вычисления, а не неопределённый путь, а ошибка останавливает сборку. В файлах каждой цели нет ключей, которые есть у других, — у объекта Kubernetes нет services, у файла Compose нет kind, — поэтому каждое условие сначала проверяет читаемые ключи с помощью has():

// Docker Compose: a service whose image names no fixed version.
input.artifacts
.filter(a, has(a.documents) && a.documents.exists(d,
has(d.services) && d.services.exists(s,
has(d.services[s].image)
[… omitted: the image test, and the rest of the clause]

Без проверки has(d.services) команда aggrega build --release release-helm.yaml --config governance-cel.yaml --auto-pull останавливается, какие бы образы ни запускали объекты Kubernetes, завершается с кодом 1 и не записывает dist/, а строка, сообщающая об ошибке, называет файл политики и ключ:

render-verdict: plugin "governance/cel:0.9.0": call "verdict_render": wasm: plugin "cel" call to verdict_render: policy source "house-rule.cel" could not be evaluated: No such key: services

Оно сообщает об одном нарушителе на файл. Ключ решения собирает сообщения, а у выражения CEL нет способа объединить списки, которые оно строит для каждого файла, в один список. Поэтому каждое условие CEL сообщает об одном нарушителе в каждом файле: о первом контейнере шаблона pod или, среди сервисов, экземпляров и ресурсов, которые файл задаёт по имени, о том, чьё имя идёт первым при сортировке. Включение обходит отображение в произвольном порядке, поэтому именно выбор по имени сохраняет сообщение одинаковым от сборки к сборке. Правило Rego сообщает о каждом нарушителе. При двух незафиксированных сервисах в одном файле Compose движок Rego останавливается с двумя сообщениями, а движок CEL — с одним, для сервиса, чьё имя идёт первым при сортировке; при одном, как в каждой сущности Release здесь, оба останавливаются с одним и тем же сообщением.

Оно повторяется. CEL не позволяет дать имя подвыражению, поэтому проверка, используемая дважды, пишется дважды, а проверка образа расписана в каждом условии, а не вызывается, как unpinned в Rego.

Эти два файла — намеренный почти-дубликат: каждый написан самостоятельно по приведённому выше правилу, а не сгенерирован один из другого, чтобы сборка, в которой движки расходятся, показала это расхождение.

Вердикт никогда не изменяет результат

Политика в роли render-verdict принимает сборку или отклоняет её. Ей передаются файлы, записанные сборкой, и она возвращает вердикты; ничто из возвращённого ею к ним не применяется. Поэтому контрольная сборка создаёт одни и те же файлы, байт в байт, с подключённым правилом и без него, и check.sh сравнивает два дерева при каждом запуске. Отклонённая сборка вообще не записывает dist/. Чтобы устранить отклонение, меняется сущность Release — зафиксированный тег, ключ шифрования, — и следующая сборка оценивается заново.

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

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

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

Terminal window
aggrega scaffold --example policy-render-verdict

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

Terminal window
cd policy-render-verdict

Сборка

Terminal window
aggrega build --release release-terraform.yaml --config governance-rego.yaml --auto-pull
aggrega build --release release-terraform-unencrypted.yaml --config governance-rego.yaml --auto-pull # halts; exits 1

Замените governance-rego.yaml на governance-cel.yaml, чтобы запустить то же правило на движке CEL, а terraform в имени файла сущности Release — на helm, compose или cloudformation, с их сущностями Releases с внесёнными нарушениями release-helm-unpinned.yaml, release-compose-unpinned.yaml и release-cloudformation-unencrypted.yaml.

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

Контрольная сборка Terraform завершается. Сущность Release с внесённым нарушением останавливается:

[… omitted: the lines printed while the lockfile is resolved, which carry the refusal below once more and say the render that discovers external inputs could not finish]
[POLICY_ERROR E0005]
policy plugin "rego" rejected the build: terraform/modules/db/main.tf: the RDS instance db stores its data unencrypted
caused by: policy violation

Каждое сообщение называет файл, который оценило правило, его путём внутри dist/, и нарушителя в нём. Другие сущности Releases с внесёнными нарушениями останавливаются так же:

policy plugin "rego" rejected the build: helm/report-cronjob.yaml: container main runs registry.example.com/orders-report:latest, an image with no tag or the tag latest
policy plugin "cel" rejected the build: compose/docker-compose.yaml: service report runs registry.example.com/orders-report, an image with no tag or the tag latest
policy plugin "cel" rejected the build: cloudformation/cloudformation-stack.json: the RDS instance Db stores its data unencrypted

Каждая строка — это строка после [POLICY_ERROR E0005] в выводе её сборки, показанная от левого края. Первая получена от движка Rego, а две другие — от движка CEL, и каждая называет движок, который её сообщил; другой движок выводит то же сообщение под своим именем.

С ИИ-ассистентом

ИИ-ассистент, настроенный с инструментами Aggrega, может сделать то же самое: вставьте в него этот промпт.

Используйте только инструменты Aggrega и не создавайте папки самостоятельно. Если в папке Workspace ещё нет папки `policy-render-verdict`, вызовите один раз инструмент `scaffold`, задав для `example` значение `policy-render-verdict` и не задавая `dir`: он запишет пример в новую папку `policy-render-verdict`. Затем вызовите инструмент `cli-build`, который запускает `aggrega build` и принимает его флаг `--config`, по одному разу для каждой сущности Release в таком порядке — `release-terraform.yaml` и `release-terraform-unencrypted.yaml` — каждый раз задавая для `workspace_root` значение `policy-render-verdict`, для `release` — этот файл, для `auto_pull` — true и для `config` — `governance-rego.yaml`. Вторая сборка должна быть отклонена, поэтому прочитайте мне отказ. Сообщите мне, какие файлы записала первая сборка; они находятся в `policy-render-verdict/dist/`.

Проверка каждой сборки

Эта самопроверка выполняется в рабочей копии репозитория документации, которая содержит используемый ею общий вспомогательный скрипт сборки; копия, записанная aggrega scaffold --example, этого скрипта не содержит.

Terminal window
./check.sh

check.sh через вспомогательный скрипт build-release сначала собирает каждую контрольную сборку один раз без подключённой политики в качестве эталона, а затем все восемь сущностей Releases на каждом движке. Контрольная сборка должна завершиться и записать те же файлы, байт в байт, что и её эталон; сущность Release с внесённым нарушением должна остановиться с E0005 и ожидаемым для неё сообщением, без других отклонений рядом, и не записать dist/. Оба движка должны выдавать одно и то же сообщение. Он выводит одну строку на сборку и завершается с кодом 1, если какой-либо результат отличается, выводя вывод этой сборки:

ENGINE RELEASE EXIT EXPECTED VERDICT
--------------------------------------------------------------------------------------------------------------
none release-helm.yaml 0 reference OK
none release-compose.yaml 0 reference OK
none release-terraform.yaml 0 reference OK
none release-cloudformation.yaml 0 reference OK
rego release-helm.yaml 0 pass OK: completed, byte-identical to the build with no policy
rego release-helm-unpinned.yaml 1 halt OK: E0005, the expected sentence
rego release-compose.yaml 0 pass OK: completed, byte-identical to the build with no policy
rego release-compose-unpinned.yaml 1 halt OK: E0005, the expected sentence
rego release-terraform.yaml 0 pass OK: completed, byte-identical to the build with no policy
rego release-terraform-unencrypted.yaml 1 halt OK: E0005, the expected sentence
rego release-cloudformation.yaml 0 pass OK: completed, byte-identical to the build with no policy
rego release-cloudformation-unencrypted.yaml 1 halt OK: E0005, the expected sentence
cel release-helm.yaml 0 pass OK: completed, byte-identical to the build with no policy
cel release-helm-unpinned.yaml 1 halt OK: E0005, the expected sentence
cel release-compose.yaml 0 pass OK: completed, byte-identical to the build with no policy
cel release-compose-unpinned.yaml 1 halt OK: E0005, the expected sentence
cel release-terraform.yaml 0 pass OK: completed, byte-identical to the build with no policy
cel release-terraform-unencrypted.yaml 1 halt OK: E0005, the expected sentence
cel release-cloudformation.yaml 0 pass OK: completed, byte-identical to the build with no policy
cel release-cloudformation-unencrypted.yaml 1 halt OK: E0005, the expected sentence
check: every build ended as expected.

Он использует бинарный файл, который находит ./build-release.sh, поэтому его выбирает AGGREGA_BIN, а аргументы после -- передаются каждой сборке. Он отказывается запускаться, пока в этом каталоге находится dist/, потому что перемещает дерево каждой сборки, чтобы сравнить его, и не оставляет ни одного после себя; сборки заполняют файлы блокировки этого каталога, как любая сборка. Его код завершения — это весь вердикт.

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

Компилятор отрисовывает файлы каждой цели, передаёт их подключённому движку как текст с форматом, объявленным их провайдером, и действует в соответствии с уровнем серьёзности, который несёт каждый вердикт. Он не знает, что такое тег образа, что latest меняется или что экземпляр RDS должен быть зашифрован: эти смыслы принадлежат правилу. О ролях, полезных нагрузках и ключах решений см. сокет управления.

Файлы

  • aggregate.yaml — база данных и подключённое к ней задание формирования отчётов.
  • manifest-helm.yaml, manifest-compose.yaml, manifest-terraform.yaml, manifest-cloudformation.yaml — привязывают каждый тип компонента и сущность Feature ручного запуска к их Recipes на одной целевой платформе.
  • release-<target>.yaml, release-<target>-unpinned.yaml, release-<target>-unencrypted.yaml — контрольный вариант и подложенное нарушение для каждой целевой платформы.
  • .aggrega-config.yaml — реестр по умолчанию; без подключения управления.
  • governance-rego.yaml, governance-cel.yaml — правило, подключённое к render-verdict через каждый движок; каждый из файлов указывается через --config.
  • policies/house-rule.rego, policies/house-rule.cel — правило, по одному разу для каждого движка.
  • build-release.sh — собирает одну сущность Release и выводит эквивалентную команду aggrega build.
  • check.sh — выполняет двадцать сборок и проверяет результат каждой.