Zum Inhalt springen
AggregaAggrega
Sprache wählen: Deutsch
Diese Seite wurde maschinell übersetzt. Das englische Original lesen.

Ein bei Bedarf ausgeführter Task: ein Aggregate, vier Ziele

Ein Task, der core/manual-trigger trägt, ohne Start auf Kubernetes, Docker Compose, Terraform und CloudFormation bereitgestellt, neben einem Task, der nichts trägt, mit dem Befehl, der auf jedem Ziel einen Lauf startet.

Manche Arbeit läuft nur dann bis zum Abschluss, wenn jemand sie anfordert: eine einmalige Datenkorrektur, ein Backup auf Anfrage. core/manual-trigger ist das Feature dafür. An einen core/compute/task ohne Zeitplan angebunden, stellt es den Task bereit, ohne ihn zu starten, und jeder Lauf ist einer, den jemand von Hand startet, mit dem eigenen Befehl des Ziels.

Dieser Workspace baut ein Aggregate für vier Ziele — Kubernetes über Helm, Docker Compose, Terraform und CloudFormation — und zeigt auf jedem, was die Anbindung an der gerenderten Ausgabe ändert, sowie den Befehl, der einen Lauf startet. Der zweite Task trägt keine Anbindung, sodass der Unterschied im selben Build sichtbar ist. Zwei weitere Releases sollen abbrechen, und die Seite zitiert, was jedes ausgibt.

Was es baut

InstanzKatalog-ComponentAnbindungwas einen Lauf startet
data-fixcore/compute/taskcore/manual-triggerjemand, von Hand, auf jedem Ziel
reportcore/compute/taskkeinesein Zeitplan oder, auf Docker Compose, der Start des Stacks

Die Anbindung steht im Aggregate, neben dem Task, den sie ändert: Die Ausführung bei Bedarf gehört zu dem, was data-fix ist, daher schreibt sie der Entwickler, und das Feature nimmt weder Werte noch infra an. Das Release schreibt nichts dafür.

Der Zeitplan von report ist ein Parameter, report_schedule, den das Aggregate mit einem leeren Standardwert deklariert und in den Wert schedule des Tasks einliest:

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

Es ist ein Parameter, weil die vier Ziele bei einem Task ohne Anbindung nicht übereinstimmen. Kubernetes führt ihn mit einem Zeitplan als CronJob aus oder ohne Zeitplan einmal bei der Bereitstellung. Docker Compose hat keinen Scheduler, daher führt es den Task bei jedem Start des Stacks einmal aus und lehnt einen Zeitplan ab. Auf AWS führt nichts einen Amazon-ECS-Task aus, wenn Terraform oder CloudFormation die Konfiguration anwendet, daher braucht ein Task dort einen Zeitplan oder die Anbindung und wird ohne beides abgelehnt. Deshalb erfüllen die Releases für Kubernetes, Terraform und CloudFormation report_schedule, und das Release für Docker Compose lässt ihn leer.

data-fix wird auf allen vier auf dieselbe Weise gebaut, ohne Zeitplan und ohne Parameter.

Die sechs Releases

ReleaseManifestreport_scheduleder Build
release-helm.yamlmanifest-helm.yaml30 2 * * 1-5schließt ab
release-compose.yamlmanifest-compose.yamlleerschließt ab
release-terraform.yamlmanifest-terraform.yaml30 2 * * 1-5schließt ab
release-cloudformation.yamlmanifest-cloudformation.yaml30 2 * * 1-5schließt ab
release-compose-scheduled.yamlmanifest-compose.yaml30 2 * * 1-5bricht ab
release-terraform-unscheduled.yamlmanifest-terraform.yamlleerbricht ab

Jedes Manifest bildet core/compute/task auf das Recipe seines Ziels ab und bindet core/manual-trigger an das FeatureRecipe seines Ziels: helm/task und helm/manual-trigger, compose/task und compose/manual-trigger, terraform/task-ecs und terraform/manual-trigger sowie cloudformation/task-ecs und cloudformation/manual-trigger. Ein Manifest, das kein FeatureRecipe für die Anbindung bindet, bricht den Build ab und benennt sie.

Jedes Release benennt unter infra.image das Image, das jeder Task ausführt, da core/compute/task keine Software mitbringt. Die AWS-Releases benennen außerdem unter infra.overrides den Cluster, die Subnetze, die Sicherheitsgruppen und die Ausführungsrolle, mit denen jeder Task läuft, und, wo report einen Zeitplan hat, die Rolle, unter der der Zeitplan jeden Lauf startet. Jeder kontospezifische Wert dort ist ein Platzhalter.

Das Beispiel generieren

Sie können dieses Beispiel mit den folgenden Befehlen bauen oder es von Ihrem KI-Assistenten für Sie bauen lassen.

Schreiben Sie das Beispiel in einen neuen Ordner, der nach ihm benannt ist:

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

Danach gibt er die als Nächstes auszuführenden Befehle aus. Der erste wechselt in den neuen Ordner:

Terminal window
cd task-run-on-demand

Build

Der Workspace liest den Katalog der Standardbibliothek aus der Hub-Registry, die .aggrega-config.yaml benennt. Jedes Recipe hier rendert allein aus dem Katalog, sodass jeder Build offline läuft, sobald die Lockfile aufgelöst ist.

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

In einem Checkout des Dokumentations-Repositorys, das das gemeinsame Build-Hilfsskript enthält, das eine von aggrega scaffold --example geschriebene Kopie nicht mitbringt, baut ./check.sh alle sechs Releases und prüft jedes Ergebnis. Es gibt eine Zeile pro Release aus und endet nur dann mit 0, wenn jedes so ausgegangen ist, wie diese Seite es beschreibt:

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.

Mit einem KI-Assistenten

Ein KI-Assistent, der mit den Tools von Aggrega eingerichtet ist, kann dasselbe tun: Fügen Sie ihm diesen Prompt ein.

Verwenden Sie ausschließlich die Aggrega-Werkzeuge und legen Sie selbst keinen Ordner an. Wenn der Ordner des Arbeitsbereichs noch keinen Ordner `task-run-on-demand` enthält, rufen Sie das Werkzeug `scaffold` einmal auf, mit `example` auf `task-run-on-demand` gesetzt und ohne `dir`: Es schreibt das Beispiel in einen neuen Ordner `task-run-on-demand`. Rufen Sie dann das Werkzeug `build` auf, mit `workspace_root` auf `task-run-on-demand`, `release` auf `release-helm.yaml`, `auto_pull` auf true und `write` auf true gesetzt. Nennen Sie mir die Dateien, die der Build geschrieben hat; sie liegen unter `task-run-on-demand/dist/`.

Kubernetes

release-helm.yaml schreibt zwei Dateien, einen CronJob pro Task, und sonst nichts. data-fix ist ein CronJob, der ausgesetzt gehalten wird, mit einem Zeitplan, den der Entwickler nie geschrieben hat:

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

Ein CronJob braucht einen Zeitplan, und 0 0 30 2 * bezeichnet den 30. Februar, ein Datum, das kein Jahr enthält: Ausgesetzt startet der CronJob keinen Lauf, und fortgesetzt hat er immer noch keinen Zeitpunkt, zu dem er einen starten könnte. Ohne die Anbindung wäre ein Task ohne Zeitplan ein Job, der läuft, sobald er bereitgestellt ist.

report ist ein CronJob mit dem Zeitplan, den das Release erfüllt hat, und ist nicht ausgesetzt:

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]

Ein Lauf von data-fix ist ein Job, der aus seinem CronJob erstellt wird, unter einem Namen Ihrer Wahl:

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

Derselbe Befehl startet mit --from=cronjob/report einen zusätzlichen Lauf von report zwischen seinen geplanten Läufen.

Docker Compose

release-compose.yaml schreibt eine einzige Compose-Datei. Jeder Task ist ein Service, den Compose nicht erneut startet, wenn er beendet ist; data-fix trägt außerdem das Profil manual, und report trägt keines:

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 startet einen Service, der ein Profil trägt, nur dann, wenn dieses Profil aktiviert ist oder der Service auf der Befehlszeile benannt wird, sodass docker compose up den Task report einmal ausführt und data-fix gestoppt lässt. Ein Lauf von data-fix wird gestartet, indem man seinen Service benennt, und --rm entfernt seinen Container, sobald der Lauf endet:

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

Terraform

release-terraform.yaml schreibt eine Root-Konfiguration mit einem Modulblock pro Task und daneben das Modul jedes Tasks. Die beiden Blöcke unterscheiden sich im Zeitplan:

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

Das Modul deklariert den Zeitplan von EventBridge Scheduler nur, solange es einen Ausdruck erhält, sodass die Task-Definition von data-fix für sich allein steht:

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]

Das Recipe schreibt den Zeitplan von report in der eigenen Form von EventBridge Scheduler: 30 2 * * 1-5 wird zu cron(30 2 ? * 2,3,4,5,6 *), mit den Wochentagen ab Sonntag als 1 nummeriert, in UTC, weil das Release keine Zeitzone benennt.

CloudFormation

release-cloudformation.yaml schreibt ein einziges Stack-Template. Es enthält eine Task-Definition für jeden Task und einen Zeitplan allein für 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]
}
}
}

Nichts im Stack verweist auf DataFixTaskDefinition, daher startet sie nichts.

Einen Lauf auf Amazon ECS starten

Auf beiden AWS-Zielen wird ein Lauf von data-fix mit der Amazon-ECS-Operation RunTask gestartet, der die Familie der Task-Definition wie gerendert sowie die Cluster- und Netzwerkkonfiguration übergeben werden, die das Release unter infra.overrides benennt:

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

Allein über ihre Familie benannt, wird die Task-Definition zu ihrer neuesten aktiven Revision aufgelöst.

Was der Build nicht tut

Der Build schreibt Dateien und hält an. Er startet keinen Lauf, auf keinem Ziel: Er erreicht keinen Cluster, startet keinen Compose-Stack und ruft keine AWS-API auf, und die Anbindung ändert nur, was die Dateien sagen. Er schreibt auch kein Skript: Jeder Befehl auf dieser Seite ist der eigene des Ziels, ausgeführt von demjenigen, der es betreibt, und keiner liegt in dist/. Die Realisierungen der Anbindung fügen auf keinem Ziel eine eigene Datei hinzu; die Änderung, die jede vornimmt, steht in der eigenen Ausgabe des Tasks, oben gezeigt.

Die zwei Releases, die abbrechen

release-compose-scheduled.yaml erfüllt report_schedule auf Docker Compose und bindet außerdem core/manual-trigger an report an. Auf Kubernetes und AWS läuft ein Task mit Zeitplan nach diesem Zeitplan, ob die Anbindung vorhanden ist oder nicht; auf Docker Compose, ohne Scheduler, hat ein Task mit Zeitplan keine Realisierung, angebunden oder nicht. aggrega build --release release-compose-scheduled.yaml --auto-pull bricht ab:

[… 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 lässt report_schedule auf Terraform leer, sodass report weder einen Zeitplan noch die Anbindung hat und nichts auf AWS ihn je starten würde. Das ist der Fall, für den es core/manual-trigger gibt, und aggrega build --release release-terraform-unscheduled.yaml --auto-pull bricht ab und benennt es:

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

Hier erreicht der Zeitplan den Task über einen Parameter, den das Release erfüllt, sodass der Komponente einen Zeitplan zu geben bedeutet, report_schedule zu erfüllen, wie es release-terraform.yaml tut.