Задача, запускаемая по требованию: одна сущность Aggregate, четыре цели
Задача с core/manual-trigger, развёрнутая без запуска в Kubernetes, Docker Compose, Terraform и CloudFormation, рядом с задачей без какого-либо присоединения, вместе с командой, запускающей выполнение на каждой цели.
Некоторая работа выполняется до завершения только тогда, когда кто-то об этом просит: разовое исправление данных, резервное копирование по запросу. core/manual-trigger — это Feature именно для этого. Присоединённый к core/compute/task без расписания, он развёртывает задачу, не запуская её, и каждое выполнение кто-то запускает вручную собственной командой цели.
Это рабочее пространство собирает одну сущность Aggregate для четырёх целей — Kubernetes через Helm, Docker Compose, Terraform и CloudFormation — и показывает для каждой, что присоединение меняет в отрендеренном выводе, а также команду, запускающую выполнение. Вторая задача не несёт присоединения, поэтому разница видна в той же сборке. Ещё две сущности Releases, как ожидается, останавливают сборку, и страница приводит то, что выводит каждая из них.
Что собирается
| экземпляр | сущность Component из каталога | присоединение | что запускает выполнение |
|---|---|---|---|
data-fix | core/compute/task | core/manual-trigger | кто-то, вручную, на каждой цели |
report | core/compute/task | нет | его расписание или, в Docker Compose, запуск стека |
Присоединение находится в сущности Aggregate, рядом с задачей, которую оно меняет: выполнение по требованию — часть того, чем является data-fix, поэтому его записывает разработчик, а Feature не принимает ни значений, ни infra. Сущность Release ничего для него не записывает.
Расписание report — это параметр report_schedule, который сущность Aggregate объявляет с пустым значением по умолчанию и считывает в значение schedule задачи:
spec: parameters: report_schedule: type: string default: "" [… omitted: the parameter's description]
components: [… omitted: data-fix with its attachment, and the comment above each task] report: type: core/compute/task values: schedule: "{{ .parameters.report_schedule }}"Это параметр, потому что четыре цели по-разному обращаются с задачей без присоединения. Kubernetes запускает её по расписанию как CronJob или, без расписания, один раз при развёртывании. В Docker Compose нет планировщика, поэтому он запускает задачу один раз при каждом запуске стека и отклоняет расписание. В AWS ничто не запускает задачу Amazon ECS, когда Terraform или CloudFormation применяет изменения, поэтому задаче там нужно расписание или присоединение, а без того и другого она отклоняется. Поэтому сущности Releases для Kubernetes, Terraform и CloudFormation заполняют report_schedule, а сущность Release для Docker Compose оставляет его пустым.
data-fix собирается одинаково на всех четырёх целях, без расписания и без параметра.
Шесть сущностей Releases
| Release | Manifest | report_schedule | сборка |
|---|---|---|---|
release-helm.yaml | manifest-helm.yaml | 30 2 * * 1-5 | завершается |
release-compose.yaml | manifest-compose.yaml | пусто | завершается |
release-terraform.yaml | manifest-terraform.yaml | 30 2 * * 1-5 | завершается |
release-cloudformation.yaml | manifest-cloudformation.yaml | 30 2 * * 1-5 | завершается |
release-compose-scheduled.yaml | manifest-compose.yaml | 30 2 * * 1-5 | останавливается |
release-terraform-unscheduled.yaml | manifest-terraform.yaml | пусто | останавливается |
Каждая сущность Manifest сопоставляет core/compute/task с сущностью Recipe своей цели и привязывает core/manual-trigger к сущности FeatureRecipe своей цели: helm/task и helm/manual-trigger, compose/task и compose/manual-trigger, terraform/task-ecs и terraform/manual-trigger, а также cloudformation/task-ecs и cloudformation/manual-trigger. Сущность Manifest, которая не привязывает никакой сущности FeatureRecipe для присоединения, останавливает сборку, называя его.
Каждая сущность Release указывает в infra.image образ, который запускает каждая задача, поскольку core/compute/task не упаковывает никакого программного обеспечения. Сущности Releases для AWS также указывают в infra.overrides кластер, подсети, группы безопасности и роль выполнения, с которыми работает каждая задача, а там, где у report есть расписание, — роль, от имени которой расписание запускает каждое выполнение. Каждое значение, специфичное для учётной записи, там является заполнителем.
Создание примера
Этот пример можно собрать командами ниже или поручить сборку вашему ИИ-ассистенту.
Запишите пример в новую папку, названную по его имени:
aggrega scaffold --example task-run-on-demandЗатем она выводит команды, которые нужно выполнить дальше. Первая переходит в новую папку:
cd task-run-on-demandСборка
Рабочее пространство считывает каталог стандартной библиотеки из реестра hub, который указывает .aggrega-config.yaml. Каждая сущность Recipe здесь рендерится только из каталога, поэтому каждая сборка работает офлайн, как только файл блокировки разрешён.
aggrega build --release release-helm.yaml --auto-pull # one ReleaseВ рабочей копии репозитория документации, которая содержит общий вспомогательный скрипт сборки, отсутствующий в копии, записанной aggrega scaffold --example, ./check.sh собирает все шесть сущностей Releases и проверяет каждый результат. Он выводит по одной строке на каждую сущность Release и завершается с кодом 0, только если каждая завершилась так, как описывает эта страница:
RELEASE EXIT EXPECTED VERDICT----------------------------------------------------------------------------------------------------release-helm.yaml 0 complete OK: completed, the files the README showsrelease-compose.yaml 0 complete OK: completed, the files the README showsrelease-terraform.yaml 0 complete OK: completed, the files the README showsrelease-cloudformation.yaml 0 complete OK: completed, the files the README showsrelease-compose-scheduled.yaml 1 halt OK: halted with the expected refusalrelease-terraform-unscheduled.yaml 1 halt OK: halted with the expected refusal
check: every build ended as expected.С ИИ-ассистентом
ИИ-ассистент, настроенный с инструментами Aggrega, может сделать то же самое: вставьте в него этот промпт.
Используйте только инструменты Aggrega и не создавайте папки самостоятельно. Если папка рабочей области ещё не содержит папку `task-run-on-demand`, вызовите один раз инструмент `scaffold` с параметром `example` со значением `task-run-on-demand` и без `dir`: он запишет пример в новую папку `task-run-on-demand`. Затем вызовите инструмент `build` с параметрами `workspace_root` — `task-run-on-demand`, `release` — `release-helm.yaml`, `auto_pull` — true и `write` — true. Сообщите мне, какие файлы записала сборка; они находятся в `task-run-on-demand/dist/`.Kubernetes
release-helm.yaml записывает два файла, по одному CronJob на задачу, и ничего больше. data-fix — это CronJob, удерживаемый в приостановленном состоянии, с расписанием, которого разработчик никогда не писал:
apiVersion: batch/v1kind: CronJobmetadata: name: data-fix [… omitted: the labels and annotations the build writes on every resource]spec: schedule: 0 0 30 2 * suspend: true jobTemplate: spec: template: [… omitted: the pod template's metadata, the same labels again] spec: containers: - name: main image: registry.example.com/orders-data-fix:2.0.1 [… omitted: the container's CPU and memory requests and limits] restartPolicy: NeverCronJob требуется расписание, а 0 0 30 2 * указывает на 30 февраля — дату, которой нет ни в одном году: приостановленный CronJob не запускает выполнение, а возобновлённый всё равно не имеет момента, когда его запустить. Без присоединения задача без расписания была бы Job, который запускается сразу после развёртывания.
report — это CronJob по расписанию, которое заполнила сущность Release, и он не приостановлен:
[… omitted: apiVersion, kind and metadata, as in data-fix-cronjob.yaml under report's name]spec: schedule: 30 2 * * 1-5 jobTemplate: [… omitted: the job template, as in data-fix-cronjob.yaml with report's image]Выполнение data-fix — это Job, созданный из его CronJob под выбранным вами именем:
kubectl create job data-fix-run-1 --from=cronjob/data-fixТа же команда с --from=cronjob/report запускает дополнительное выполнение report между запланированными.
Docker Compose
release-compose.yaml записывает один файл Compose. Каждая задача — это сервис, который Compose не запускает снова после его завершения; data-fix также несёт профиль manual, а report не несёт никакого:
services: data-fix: image: registry.example.com/orders-data-fix:2.0.1 [… omitted: the labels the build writes on every service, and the service's network] restart: "no" [… omitted: the CPU and memory limits and reservations] profiles: - manual report: image: registry.example.com/orders-report:1.4.2 [… omitted: the labels and the network, as on data-fix] restart: "no" [… omitted: the CPU and memory limits and reservations, as on data-fix][… omitted: the network the services join]Compose запускает сервис с профилем, только когда этот профиль включён или сервис назван в командной строке, поэтому docker compose up запускает report один раз и оставляет data-fix остановленным. Выполнение data-fix запускается указанием имени его сервиса, а --rm удаляет его контейнер по завершении выполнения:
docker compose -f dist/compose/docker-compose.yaml run --rm data-fixTerraform
release-terraform.yaml записывает корневую конфигурацию с одним блоком module на задачу, а рядом — модуль каждой задачи. Два блока различаются расписанием:
# Root configuration for this boundary. Each component rendered here is one# module block below, and the directory that block points at holds that# component's own files. One configuration means one dependency graph, which is# what lets a reference or a depends_on reach from one component to another.
module "data-fix" { source = "./modules/data-fix"
assign_public_ip = false cluster = "arn:aws:ecs:eu-west-1:123456789012:cluster/example-cluster" cpu = "256" environment = {} execution_role_arn = "arn:aws:iam::123456789012:role/example-ecs-task-execution" image = "registry.example.com/orders-data-fix:2.0.1" memory = "512" name = "data-fix" security_groups = ["sg-0fedcba9876543210"] subnet_ids = ["subnet-0123456789abcdef0"]}
module "report" { source = "./modules/report"
assign_public_ip = false cluster = "arn:aws:ecs:eu-west-1:123456789012:cluster/example-cluster" cpu = "256" environment = {} execution_role_arn = "arn:aws:iam::123456789012:role/example-ecs-task-execution" image = "registry.example.com/orders-report:1.4.2" memory = "512" name = "report" schedule_expression = "cron(30 2 ? * 2,3,4,5,6 *)" schedule_expression_timezone = "UTC" scheduler_role_arn = "arn:aws:iam::123456789012:role/example-scheduler" security_groups = ["sg-0fedcba9876543210"] subnet_ids = ["subnet-0123456789abcdef0"]}Модуль объявляет расписание EventBridge Scheduler только тогда, когда ему передано выражение, поэтому определение задачи data-fix существует само по себе:
[… omitted: the provider requirement, the Region lookup, the task definition and the comments on each]resource "aws_scheduler_schedule" "this" { count = var.schedule_expression == null ? 0 : 1[… omitted: the rest of the schedule]Сущность Recipe записывает расписание report в собственной форме EventBridge Scheduler: 30 2 * * 1-5 становится cron(30 2 ? * 2,3,4,5,6 *), дни недели нумеруются начиная с воскресенья как 1, в UTC, поскольку сущность Release не указывает часовой пояс.
CloudFormation
release-cloudformation.yaml записывает один шаблон стека. Он содержит определение задачи для каждой задачи и расписание только для report:
{ "AWSTemplateFormatVersion": "2010-09-09", "Resources": { "DataFixTaskDefinition": { [… omitted: the provenance metadata the build writes on every resource] "Properties": { "ContainerDefinitions": [ { "Essential": true, "Image": "registry.example.com/orders-data-fix:2.0.1", "Name": "main" } ], "Cpu": "256", "ExecutionRoleArn": "arn:aws:iam::123456789012:role/example-ecs-task-execution", "Family": "data-fix", "Memory": "512", "NetworkMode": "awsvpc", "RequiresCompatibilities": [ "FARGATE" ] }, "Type": "AWS::ECS::TaskDefinition" }, "ReportSchedule": { [… omitted: the provenance metadata] "Properties": { "FlexibleTimeWindow": { "Mode": "OFF" }, "ScheduleExpression": "cron(30 2 ? * 2,3,4,5,6 *)", "ScheduleExpressionTimezone": "UTC", "Target": { "Arn": "arn:aws:ecs:eu-west-1:123456789012:cluster/example-cluster", "EcsParameters": { [… omitted: the launch type, the network configuration and the task count each run starts with] "TaskDefinitionArn": { "Ref": "ReportTaskDefinition" } }, "RoleArn": "arn:aws:iam::123456789012:role/example-scheduler" } }, "Type": "AWS::Scheduler::Schedule" }, "ReportTaskDefinition": { [… omitted: the same shape as DataFixTaskDefinition, with report's image and family] } }}Ничто в стеке не ссылается на DataFixTaskDefinition, поэтому ничто его не запускает.
Запуск выполнения в Amazon ECS
На обеих целях AWS выполнение data-fix запускается операцией Amazon ECS RunTask, которой передаётся семейство определения задачи в отрендеренном виде, а также конфигурация кластера и сети, которую сущность Release указывает в infra.overrides:
aws ecs run-task \ --cluster arn:aws:ecs:eu-west-1:123456789012:cluster/example-cluster \ --task-definition data-fix \ --launch-type FARGATE \ --network-configuration 'awsvpcConfiguration={subnets=[subnet-0123456789abcdef0],securityGroups=[sg-0fedcba9876543210],assignPublicIp=DISABLED}'Указанное только семейством, определение задачи разрешается в свою последнюю активную ревизию.
Чего сборка не делает
Сборка записывает файлы и останавливается. Она не запускает ни одного выполнения ни на одной цели: не обращается ни к одному кластеру, не запускает ни одного стека Compose и не вызывает ни одного API AWS, а присоединение меняет только содержимое файлов. Она также не записывает никаких скриптов: каждая команда на этой странице принадлежит самой цели, её запускает тот, кто эту цель обслуживает, и ни одной из них нет в dist/. Реализации присоединения не добавляют собственных файлов ни на одной цели; изменение, которое вносит каждая, находится в собственном выводе задачи, показанном выше.
Две сущности Releases, которые останавливают сборку
release-compose-scheduled.yaml заполняет report_schedule в Docker Compose и, кроме того, присоединяет core/manual-trigger к report. В Kubernetes и AWS задача с расписанием выполняется по нему независимо от того, есть ли присоединение; в Docker Compose, где нет планировщика, у задачи с расписанием нет реализации, с присоединением или без. aggrega build --release release-compose-scheduled.yaml --auto-pull останавливает сборку:
[… omitted: what resolving the lockfile prints, the same halt among it][CATALOG_ERROR E0033] Recipe/FeatureRecipe assertions caused by: Recipe "task" instance "report" assertion "schedule_refused": [… omitted: the template position and the assertion's own source]: error calling fail: assertion failed: the component "report" is scheduled "30 2 * * 1-5", and Docker Compose has no scheduler: nothing in a compose file starts a service at a time, so the run would happen at none of the times written. Map core/compute/task to helm/task in the Manifest, which runs it on its schedule as a Kubernetes CronJob; or remove the schedule from the component in the Aggregate to run it once at each docker compose up, or attach core/manual-trigger to it there to start each run with docker compose run --rmrelease-terraform-unscheduled.yaml оставляет report_schedule пустым в Terraform, поэтому у report нет ни расписания, ни присоединения, и ничто в AWS никогда его не запустит. Именно для этого случая существует core/manual-trigger, и aggrega build --release release-terraform-unscheduled.yaml --auto-pull останавливает сборку, называя его:
[… omitted: what resolving the lockfile prints, the same halt among it][CATALOG_ERROR E0033] Recipe/FeatureRecipe assertions caused by: Recipe "task-ecs" instance "report" assertion "schedule_translates": [… omitted: the template position and the assertion's own source]: error calling fail: assertion failed: the component "report" has no schedule and carries no core/manual-trigger attachment, so it runs once, and nothing on AWS starts a run that happens once: neither Terraform nor CloudFormation runs an Amazon ECS task when it applies, so the run would never happen. Give the component a schedule in the Aggregate; attach core/manual-trigger to it there to deploy its task definition alone, for the operator to start each run with aws ecs run-task; or map core/compute/task to helm/task in the Manifest, which runs it once on KubernetesЗдесь расписание попадает в задачу через параметр, который заполняет сущность Release, поэтому задать компоненту расписание означает заполнить report_schedule, как это делает release-terraform.yaml.