Une tâche exécutée à la demande : un Aggregate, quatre cibles
Une tâche portant core/manual-trigger, déployée sans démarrer sur Kubernetes, Docker Compose, Terraform et CloudFormation, à côté d’une tâche ne portant rien, avec la commande qui lance une exécution sur chaque cible.
Certains travaux ne s’exécutent jusqu’au bout que lorsque quelqu’un le demande : une correction de données ponctuelle, une sauvegarde à la demande. core/manual-trigger est la Feature prévue pour cela. Rattachée à un core/compute/task sans planification, elle déploie la tâche sans la démarrer, et chaque exécution est lancée à la main par quelqu’un, avec la commande propre à la cible.
Cet espace de travail construit un seul Aggregate pour quatre cibles — Kubernetes via Helm, Docker Compose, Terraform et CloudFormation — et montre, sur chacune, ce que le rattachement change dans la sortie rendue et la commande qui lance une exécution. La seconde tâche ne porte aucun rattachement, si bien que la différence est visible dans le même build. Deux autres Releases sont censées s’arrêter, et la page cite ce que chacune affiche.
Ce qu’il construit
| instance | Component du catalogue | rattachement | ce qui lance une exécution |
|---|---|---|---|
data-fix | core/compute/task | core/manual-trigger | quelqu’un, à la main, sur chaque cible |
report | core/compute/task | aucune | sa planification ou, sur Docker Compose, le démarrage de la stack |
Le rattachement se trouve dans l’Aggregate, à côté de la tâche qu’il modifie : s’exécuter à la demande fait partie de ce qu’est data-fix, donc c’est le développeur qui l’écrit, et la Feature ne prend ni valeurs ni infra. La Release n’écrit rien pour elle.
La planification de report est un paramètre, report_schedule, que l’Aggregate déclare avec une valeur par défaut vide et lit dans la valeur schedule de la tâche :
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 }}"C’est un paramètre parce que les quatre cibles ne s’accordent pas sur une tâche sans rattachement. Kubernetes l’exécute selon une planification en tant que CronJob, ou une seule fois au déploiement s’il n’y en a pas. Docker Compose n’a pas de planificateur, donc il exécute la tâche une fois à chaque démarrage de la stack et refuse une planification. Sur AWS, rien n’exécute une tâche Amazon ECS lorsque Terraform ou CloudFormation applique la configuration, si bien qu’une tâche y a besoin d’une planification ou du rattachement, et est refusée sans l’un ni l’autre. Les Releases Kubernetes, Terraform et CloudFormation satisfont donc report_schedule, et la Release Docker Compose le laisse vide.
data-fix se construit de la même façon sur les quatre, sans planification ni paramètre.
Les six Releases
| Release | Manifest | report_schedule | le build |
|---|---|---|---|
release-helm.yaml | manifest-helm.yaml | 30 2 * * 1-5 | aboutit |
release-compose.yaml | manifest-compose.yaml | vide | aboutit |
release-terraform.yaml | manifest-terraform.yaml | 30 2 * * 1-5 | aboutit |
release-cloudformation.yaml | manifest-cloudformation.yaml | 30 2 * * 1-5 | aboutit |
release-compose-scheduled.yaml | manifest-compose.yaml | 30 2 * * 1-5 | s’arrête |
release-terraform-unscheduled.yaml | manifest-terraform.yaml | vide | s’arrête |
Chaque Manifest associe core/compute/task à la Recipe de sa cible et lie core/manual-trigger à la FeatureRecipe de sa cible : helm/task et helm/manual-trigger, compose/task et compose/manual-trigger, terraform/task-ecs et terraform/manual-trigger, et cloudformation/task-ecs et cloudformation/manual-trigger. Un Manifest qui ne lie aucune FeatureRecipe pour le rattachement arrête le build, en le nommant.
Chaque Release nomme sous infra.image l’image que chaque tâche exécute, puisque core/compute/task n’embarque aucun logiciel. Les Releases AWS nomment aussi, sous infra.overrides, le cluster, les sous-réseaux, les groupes de sécurité et le rôle d’exécution avec lesquels chaque tâche s’exécute et, là où report a une planification, le rôle sous lequel la planification lance chaque exécution. Chaque valeur propre au compte y est un espace réservé.
Générer l’exemple
Vous pouvez construire cet exemple avec les commandes ci-dessous, ou le faire construire pour vous par votre assistant IA.
Écrivez l’exemple dans un nouveau dossier qui porte son nom :
aggrega scaffold --example task-run-on-demandElle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier :
cd task-run-on-demandBuild
L’espace de travail lit le catalogue de la bibliothèque standard depuis le registre du hub que nomme .aggrega-config.yaml. Chaque Recipe ici se rend à partir du seul catalogue, si bien que chaque build s’exécute hors ligne une fois le fichier de verrouillage résolu.
aggrega build --release release-helm.yaml --auto-pull # one ReleaseDans un checkout du dépôt de la documentation, qui contient l’outil de build partagé qu’une copie écrite par aggrega scaffold --example n’apporte pas, ./check.sh construit les six Releases et vérifie chaque résultat. Il affiche une ligne par Release et ne se termine avec 0 que lorsque chacune a abouti comme le décrit cette page :
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.Avec un assistant IA
Un assistant IA configuré avec les outils d’Aggrega peut faire de même : collez-lui ce prompt.
Utilisez uniquement les outils Aggrega et ne créez vous-même aucun dossier. Si le dossier de l’espace de travail ne contient pas encore de dossier `task-run-on-demand`, appelez une fois l’outil `scaffold` avec `example` défini sur `task-run-on-demand` et sans `dir` : il écrit l’exemple dans un nouveau dossier `task-run-on-demand`. Appelez ensuite l’outil `build` avec `workspace_root` défini sur `task-run-on-demand`, `release` défini sur `release-helm.yaml`, `auto_pull` défini sur true et `write` défini sur true. Indiquez-moi quels fichiers le build a écrits ; ils se trouvent sous `task-run-on-demand/dist/`.Kubernetes
release-helm.yaml écrit deux fichiers, un CronJob par tâche, et rien d’autre. data-fix est un CronJob maintenu suspendu, selon une planification que le développeur n’a jamais écrite :
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: NeverUn CronJob a besoin d’une planification, et 0 0 30 2 * désigne le 30 février, une date qu’aucune année ne contient : suspendu, le CronJob ne lance aucune exécution, et une fois repris, il n’a toujours aucun moment auquel en lancer une. Sans le rattachement, une tâche sans planification serait un Job, qui s’exécute dès qu’il est déployé.
report est un CronJob selon la planification que la Release a satisfaite, et n’est pas suspendu :
[… 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]Une exécution de data-fix est un Job créé à partir de son CronJob, sous un nom de votre choix :
kubectl create job data-fix-run-1 --from=cronjob/data-fixLa même commande, avec --from=cronjob/report, lance une exécution supplémentaire de report entre ses exécutions planifiées.
Docker Compose
release-compose.yaml écrit un seul fichier Compose. Chaque tâche est un service que Compose ne redémarre pas lorsqu’il se termine ; data-fix porte aussi le profil manual, et report n’en porte aucun :
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 ne démarre un service qui porte un profil que lorsque ce profil est activé ou que le service est nommé sur la ligne de commande, si bien que docker compose up exécute report une fois et laisse data-fix arrêté. Une exécution de data-fix se lance en nommant son service, et --rm supprime son conteneur une fois l’exécution terminée :
docker compose -f dist/compose/docker-compose.yaml run --rm data-fixTerraform
release-terraform.yaml écrit une configuration racine avec un bloc de module par tâche, et le module de chaque tâche à côté. Les deux blocs diffèrent par la planification :
# 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"]}Le module ne déclare la planification EventBridge Scheduler que tant qu’il reçoit une expression, si bien que la définition de tâche de data-fix reste seule :
[… 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]La Recipe écrit la planification de report dans la forme propre à EventBridge Scheduler : 30 2 * * 1-5 devient cron(30 2 ? * 2,3,4,5,6 *), les jours de la semaine étant numérotés à partir du dimanche comme 1, en UTC parce que la Release ne nomme aucun fuseau horaire.
CloudFormation
release-cloudformation.yaml écrit un seul modèle de stack. Il contient une définition de tâche pour chaque tâche et une planification pour report seul :
{ "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] } }}Rien dans la stack ne fait référence à DataFixTaskDefinition, donc rien ne la lance.
Lancer une exécution sur Amazon ECS
Sur les deux cibles AWS, une exécution de data-fix se lance avec l’opération RunTask d’Amazon ECS, en lui donnant la famille de la définition de tâche telle qu’elle a été rendue ainsi que la configuration de cluster et de réseau que la Release nomme sous 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}'Nommée par sa seule famille, la définition de tâche se résout en sa dernière révision active.
Ce que le build ne fait pas
Le build écrit des fichiers et s’arrête. Il ne lance aucune exécution, sur aucune cible : il n’atteint aucun cluster, ne démarre aucune stack Compose et n’appelle aucune API AWS, et le rattachement ne change que ce que disent les fichiers. Il n’écrit pas non plus de script : chaque commande de cette page est celle de la cible, exécutée par qui l’exploite, et aucune ne se trouve dans dist/. Les réalisations du rattachement n’ajoutent aucun fichier propre sur aucune cible ; la modification que chacune apporte se trouve dans la sortie propre de la tâche, montrée plus haut.
Les deux Releases qui s’arrêtent
release-compose-scheduled.yaml satisfait report_schedule sur Docker Compose, et rattache aussi core/manual-trigger à report. Sur Kubernetes et AWS, une tâche avec une planification s’exécute selon celle-ci, que le rattachement soit présent ou non ; sur Docker Compose, sans planificateur, une tâche avec une planification n’a aucune réalisation, rattachée ou non. aggrega build --release release-compose-scheduled.yaml --auto-pull s’arrête :
[… 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 laisse report_schedule vide sur Terraform, si bien que report n’a ni planification ni rattachement, et rien sur AWS ne la lancerait jamais. C’est le cas pour lequel core/manual-trigger existe, et aggrega build --release release-terraform-unscheduled.yaml --auto-pull s’arrête en la nommant :
[… 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 KubernetesIci, la planification atteint la tâche par un paramètre que la Release satisfait, si bien que donner une planification au composant revient à satisfaire report_schedule, comme le fait release-terraform.yaml.