Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

Zadanie uruchamiane na żądanie: jedna encja Aggregate, cztery cele

Zadanie z core/manual-trigger, wdrażane bez uruchamiania na Kubernetes, Docker Compose, Terraform i CloudFormation, obok zadania bez żadnego dołączenia, wraz z poleceniem, które uruchamia przebieg na każdym celu.

Niektóre prace są wykonywane do końca tylko wtedy, gdy ktoś o to poprosi: jednorazowa poprawka danych, kopia zapasowa na żądanie. core/manual-trigger to Feature służący właśnie do tego. Dołączony do core/compute/task bez harmonogramu wdraża zadanie bez jego uruchamiania, a każdy przebieg ktoś uruchamia ręcznie, poleceniem właściwym dla danego celu.

Ten obszar roboczy buduje jedną encję Aggregate dla czterech celów — Kubernetes przez Helm, Docker Compose, Terraform i CloudFormation — i pokazuje dla każdego, co dołączenie zmienia w wyrenderowanym wyniku, oraz polecenie, które uruchamia przebieg. Drugie zadanie nie ma dołączenia, więc różnica jest widoczna w tym samym buildzie. Dwie kolejne encje Releases mają w założeniu przerwać build, a strona cytuje, co wypisuje każda z nich.

Co powstaje

instancjaencja Component z katalogudołączenieco uruchamia przebieg
data-fixcore/compute/taskcore/manual-triggerktoś, ręcznie, na każdym celu
reportcore/compute/taskbrakjego harmonogram lub, w Docker Compose, uruchomienie stosu

Dołączenie znajduje się w encji Aggregate, obok zadania, które zmienia: uruchamianie na żądanie jest częścią tego, czym jest data-fix, więc zapisuje je deweloper, a Feature nie przyjmuje żadnych wartości ani infra. Encja Release niczego dla niego nie zapisuje.

Harmonogram report to parametr report_schedule, który encja Aggregate deklaruje z pustą wartością domyślną i wczytuje do wartości schedule zadania:

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 }}"

Jest to parametr, ponieważ cztery cele różnie traktują zadanie bez dołączenia. Kubernetes uruchamia je według harmonogramu jako CronJob albo, bez harmonogramu, raz przy wdrożeniu. Docker Compose nie ma mechanizmu planowania, więc uruchamia zadanie raz przy każdym starcie stosu i odrzuca harmonogram. W AWS nic nie uruchamia zadania Amazon ECS, gdy Terraform lub CloudFormation stosuje zmiany, więc zadanie wymaga tam harmonogramu albo dołączenia, a bez żadnego z nich jest odrzucane. Dlatego encje Releases dla Kubernetes, Terraform i CloudFormation wypełniają report_schedule, a encja Release dla Docker Compose pozostawia go pustym.

data-fix buduje się tak samo na wszystkich czterech celach, bez harmonogramu i bez parametru.

Sześć encji Releases

ReleaseManifestreport_schedulebudowanie
release-helm.yamlmanifest-helm.yaml30 2 * * 1-5kończy się powodzeniem
release-compose.yamlmanifest-compose.yamlpustykończy się powodzeniem
release-terraform.yamlmanifest-terraform.yaml30 2 * * 1-5kończy się powodzeniem
release-cloudformation.yamlmanifest-cloudformation.yaml30 2 * * 1-5kończy się powodzeniem
release-compose-scheduled.yamlmanifest-compose.yaml30 2 * * 1-5zostaje zatrzymane
release-terraform-unscheduled.yamlmanifest-terraform.yamlpustyzostaje zatrzymane

Każda encja Manifest mapuje core/compute/task na encję Recipe swojego celu i wiąże core/manual-trigger z encją FeatureRecipe swojego celu: helm/task i helm/manual-trigger, compose/task i compose/manual-trigger, terraform/task-ecs i terraform/manual-trigger oraz cloudformation/task-ecs i cloudformation/manual-trigger. Encja Manifest, która nie wiąże żadnej encji FeatureRecipe dla dołączenia, przerywa build, wskazując je.

Każda encja Release podaje w infra.image obraz, który uruchamia każde zadanie, ponieważ core/compute/task nie pakuje żadnego oprogramowania. Encje Releases dla AWS podają też w infra.overrides klaster, podsieci, grupy zabezpieczeń i rolę wykonawczą, z którymi działa każde zadanie, a tam, gdzie report ma harmonogram, rolę, z którą harmonogram uruchamia każdy przebieg. Każda wartość specyficzna dla konta jest tam symbolem zastępczym.

Generowanie przykładu

Ten przykład można zbudować za pomocą poniższych poleceń albo zlecić jego zbudowanie asystentowi AI.

Należy zapisać przykład w nowym folderze nazwanym tak jak on:

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

Następnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu:

Terminal window
cd task-run-on-demand

Kompilacja

Obszar roboczy wczytuje katalog biblioteki standardowej z rejestru hub wskazanego w .aggrega-config.yaml. Każda encja Recipe renderuje się tu wyłącznie z katalogu, więc każdy build działa offline, gdy tylko plik blokady zostanie rozwiązany.

Terminal window
aggrega build --release release-helm.yaml --auto-pull # one Release

W kopii roboczej repozytorium dokumentacji, która zawiera wspólny skrypt pomocniczy budowania, którego nie ma kopia zapisana przez aggrega scaffold --example, ./check.sh buduje wszystkie sześć encji Releases i sprawdza każdy wynik. Wypisuje jeden wiersz na encję Release i kończy działanie z kodem 0 tylko wtedy, gdy każda zakończyła się tak, jak opisuje ta strona:

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.

Z asystentem AI

Asystent AI skonfigurowany z narzędziami Aggrega może zrobić to samo: wystarczy wkleić mu ten prompt.

Używaj wyłącznie narzędzi Aggrega i nie twórz samodzielnie żadnego folderu. Jeśli folder obszaru roboczego nie zawiera jeszcze folderu `task-run-on-demand`, wywołaj raz narzędzie `scaffold` z `example` ustawionym na `task-run-on-demand` i bez `dir`: zapisze ono przykład w nowym folderze `task-run-on-demand`. Następnie wywołaj narzędzie `build` z `workspace_root` ustawionym na `task-run-on-demand`, `release` ustawionym na `release-helm.yaml`, `auto_pull` ustawionym na true i `write` ustawionym na true. Podaj mi, jakie pliki zapisała kompilacja; znajdują się w `task-run-on-demand/dist/`.

Kubernetes

release-helm.yaml zapisuje dwa pliki, po jednym CronJob na zadanie, i nic więcej. data-fix to CronJob utrzymywany w stanie wstrzymania, z harmonogramem, którego deweloper nigdy nie napisał:

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 wymaga harmonogramu, a 0 0 30 2 * wskazuje 30 lutego, datę, której nie ma żaden rok: wstrzymany CronJob nie uruchamia przebiegu, a wznowiony nadal nie ma chwili, w której mógłby go uruchomić. Bez dołączenia zadanie bez harmonogramu byłoby obiektem Job, który działa natychmiast po wdrożeniu.

report to CronJob działający według harmonogramu wypełnionego przez encję Release i nie jest wstrzymany:

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]

Przebieg data-fix to Job utworzony z jego CronJob, pod dowolnie wybraną nazwą:

Terminal window
kubectl create job data-fix-run-1 --from=cronjob/data-fix

To samo polecenie z --from=cronjob/report uruchamia dodatkowy przebieg report między zaplanowanymi.

Docker Compose

release-compose.yaml zapisuje jeden plik Compose. Każde zadanie jest usługą, której Compose nie uruchamia ponownie po jej zakończeniu; data-fix ma ponadto profil manual, a report nie ma żadnego:

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 uruchamia usługę z profilem tylko wtedy, gdy ten profil jest włączony lub usługa zostanie wskazana w wierszu poleceń, więc docker compose up uruchamia report raz i pozostawia data-fix zatrzymane. Przebieg data-fix uruchamia się, podając nazwę jego usługi, a --rm usuwa jego kontener po zakończeniu przebiegu:

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

Terraform

release-terraform.yaml zapisuje konfigurację główną z jednym blokiem module na zadanie, a obok niej moduł każdego zadania. Oba bloki różnią się harmonogramem:

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"]
}

Moduł deklaruje harmonogram EventBridge Scheduler tylko wtedy, gdy otrzyma wyrażenie, więc definicja zadania data-fix istnieje samodzielnie:

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]

Encja Recipe zapisuje harmonogram report we własnej formie EventBridge Scheduler: 30 2 * * 1-5 staje się cron(30 2 ? * 2,3,4,5,6 *), z dniami tygodnia numerowanymi od niedzieli jako 1, w UTC, ponieważ encja Release nie podaje strefy czasowej.

CloudFormation

release-cloudformation.yaml zapisuje jeden szablon stosu. Zawiera on definicję zadania dla każdego zadania i harmonogram tylko dla 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]
}
}
}

Nic w stosie nie odwołuje się do DataFixTaskDefinition, więc nic go nie uruchamia.

Uruchamianie przebiegu w Amazon ECS

Na obu celach AWS przebieg data-fix uruchamia się operacją Amazon ECS RunTask, podając rodzinę definicji zadania w wyrenderowanej postaci oraz konfigurację klastra i sieci, którą encja Release podaje w 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}'

Wskazana samą rodziną definicja zadania jest rozwiązywana do swojej najnowszej aktywnej rewizji.

Czego kompilacja nie robi

Build zapisuje pliki i się zatrzymuje. Nie uruchamia żadnego przebiegu na żadnym celu: nie łączy się z żadnym klastrem, nie uruchamia stosu Compose i nie wywołuje żadnego API AWS, a dołączenie zmienia tylko treść plików. Nie zapisuje też żadnego skryptu: każde polecenie na tej stronie należy do samego celu, uruchamia je ten, kto go obsługuje, i żadne nie znajduje się w dist/. Realizacje dołączenia nie dodają na żadnym celu własnego pliku; zmiana, którą wprowadza każda z nich, znajduje się we własnym wyniku zadania, pokazanym powyżej.

Dwie encje Releases, które przerywają build

release-compose-scheduled.yaml wypełnia report_schedule w Docker Compose i dodatkowo dołącza core/manual-trigger do report. W Kubernetes i AWS zadanie z harmonogramem działa według niego niezależnie od tego, czy dołączenie jest obecne; w Docker Compose, bez mechanizmu planowania, zadanie z harmonogramem nie ma realizacji, z dołączeniem czy bez. aggrega build --release release-compose-scheduled.yaml --auto-pull przerywa build:

[… 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 pozostawia report_schedule puste w Terraform, więc report nie ma ani harmonogramu, ani dołączenia i nic w AWS nigdy by go nie uruchomiło. To przypadek, dla którego istnieje core/manual-trigger, a aggrega build --release release-terraform-unscheduled.yaml --auto-pull przerywa build, wskazując go:

[… 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

Tutaj harmonogram dociera do zadania przez parametr wypełniany przez encję Release, więc nadanie komponentowi harmonogramu oznacza wypełnienie report_schedule, tak jak robi to release-terraform.yaml.