Перейти до вмісту
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.