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

Задача, запускаемая по требованию: одна сущность 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-fixcore/compute/taskcore/manual-triggerкто-то, вручную, на каждой цели
reportcore/compute/taskнетего расписание или, в Docker Compose, запуск стека

Присоединение находится в сущности Aggregate, рядом с задачей, которую оно меняет: выполнение по требованию — часть того, чем является data-fix, поэтому его записывает разработчик, а Feature не принимает ни значений, ни infra. Сущность Release ничего для него не записывает.

Расписание report — это параметр report_schedule, который сущность Aggregate объявляет с пустым значением по умолчанию и считывает в значение schedule задачи:

aggregate.yaml
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

ReleaseManifestreport_scheduleсборка
release-helm.yamlmanifest-helm.yaml30 2 * * 1-5завершается
release-compose.yamlmanifest-compose.yamlпустозавершается
release-terraform.yamlmanifest-terraform.yaml30 2 * * 1-5завершается
release-cloudformation.yamlmanifest-cloudformation.yaml30 2 * * 1-5завершается
release-compose-scheduled.yamlmanifest-compose.yaml30 2 * * 1-5останавливается
release-terraform-unscheduled.yamlmanifest-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 есть расписание, — роль, от имени которой расписание запускает каждое выполнение. Каждое значение, специфичное для учётной записи, там является заполнителем.

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

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

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

Terminal window
aggrega scaffold --example task-run-on-demand

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

Terminal window
cd task-run-on-demand

Сборка

Рабочее пространство считывает каталог стандартной библиотеки из реестра hub, который указывает .aggrega-config.yaml. Каждая сущность Recipe здесь рендерится только из каталога, поэтому каждая сборка работает офлайн, как только файл блокировки разрешён.

Terminal window
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 shows
release-compose.yaml 0 complete OK: completed, the files the README shows
release-terraform.yaml 0 complete OK: completed, the files the README shows
release-cloudformation.yaml 0 complete OK: completed, the files the README shows
release-compose-scheduled.yaml 1 halt OK: halted with the expected refusal
release-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, удерживаемый в приостановленном состоянии, с расписанием, которого разработчик никогда не писал:

dist/helm/data-fix-cronjob.yaml
apiVersion: batch/v1
kind: CronJob
metadata:
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: Never

CronJob требуется расписание, а 0 0 30 2 * указывает на 30 февраля — дату, которой нет ни в одном году: приостановленный CronJob не запускает выполнение, а возобновлённый всё равно не имеет момента, когда его запустить. Без присоединения задача без расписания была бы Job, который запускается сразу после развёртывания.

report — это CronJob по расписанию, которое заполнила сущность Release, и он не приостановлен:

dist/helm/report-cronjob.yaml
[… 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 под выбранным вами именем:

Terminal window
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 не несёт никакого:

dist/compose/docker-compose.yaml
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 удаляет его контейнер по завершении выполнения:

Terminal window
docker compose -f dist/compose/docker-compose.yaml run --rm data-fix

Terraform

release-terraform.yaml записывает корневую конфигурацию с одним блоком module на задачу, а рядом — модуль каждой задачи. Два блока различаются расписанием:

dist/terraform/aggrega.modules.tf
# 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 существует само по себе:

dist/terraform/modules/data-fix/main.tf
[… 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:

dist/cloudformation/cloudformation-stack.json
{
"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:

Terminal window
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 --rm

release-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.