Una tarea ejecutada bajo demanda: un Aggregate, cuatro destinos
Una tarea que lleva core/manual-trigger, desplegada sin arrancar en Kubernetes, Docker Compose, Terraform y CloudFormation, junto a una tarea que no lleva nada, con el comando que inicia una ejecución en cada destino.
Algunos trabajos se ejecutan hasta completarse solo cuando alguien lo pide: una corrección de datos puntual, una copia de seguridad a petición. core/manual-trigger es la Feature para eso. Vinculada a un core/compute/task sin programación, despliega la tarea sin arrancarla, y cada ejecución la inicia alguien a mano, con el comando propio del destino.
Este espacio de trabajo compila un único Aggregate para cuatro destinos — Kubernetes mediante Helm, Docker Compose, Terraform y CloudFormation — y muestra, en cada uno, lo que la vinculación cambia en la salida renderizada y el comando que inicia una ejecución. La segunda tarea no lleva ninguna vinculación, así que la diferencia es visible en la misma compilación. Se espera que otras dos Releases se detengan, y la página cita lo que imprime cada una.
Lo que construye
| instancia | Component del catálogo | vinculación | qué inicia una ejecución |
|---|---|---|---|
data-fix | core/compute/task | core/manual-trigger | alguien, a mano, en cada destino |
report | core/compute/task | ninguno | su programación o, en Docker Compose, el arranque del stack |
La vinculación está en el Aggregate, junto a la tarea que cambia: ejecutarse bajo demanda forma parte de lo que es data-fix, así que la escribe el desarrollador, y la Feature no admite valores ni infra. La Release no escribe nada para ella.
La programación de report es un parámetro, report_schedule, que el Aggregate declara con un valor predeterminado vacío y lee en el valor schedule de la tarea:
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 un parámetro porque los cuatro destinos no coinciden respecto a una tarea sin vinculación. Kubernetes la ejecuta según una programación como CronJob, o una vez al desplegar si no tiene una. Docker Compose no tiene planificador, así que ejecuta la tarea una vez cada vez que arranca el stack y rechaza una programación. En AWS nada ejecuta una tarea de Amazon ECS cuando Terraform o CloudFormation aplican la configuración, así que allí una tarea necesita una programación o la vinculación, y se rechaza sin ninguna de las dos. Por eso las Releases de Kubernetes, Terraform y CloudFormation satisfacen report_schedule, y la Release de Docker Compose lo deja vacío.
data-fix se compila de la misma manera en los cuatro, sin programación ni parámetro.
Las seis Releases
| Release | Manifest | report_schedule | la compilación |
|---|---|---|---|
release-helm.yaml | manifest-helm.yaml | 30 2 * * 1-5 | se completa |
release-compose.yaml | manifest-compose.yaml | vacío | se completa |
release-terraform.yaml | manifest-terraform.yaml | 30 2 * * 1-5 | se completa |
release-cloudformation.yaml | manifest-cloudformation.yaml | 30 2 * * 1-5 | se completa |
release-compose-scheduled.yaml | manifest-compose.yaml | 30 2 * * 1-5 | se detiene |
release-terraform-unscheduled.yaml | manifest-terraform.yaml | vacío | se detiene |
Cada Manifest asigna core/compute/task a la Recipe de su destino y enlaza core/manual-trigger con la FeatureRecipe de su destino: helm/task y helm/manual-trigger, compose/task y compose/manual-trigger, terraform/task-ecs y terraform/manual-trigger, y cloudformation/task-ecs y cloudformation/manual-trigger. Un Manifest que no enlaza ninguna FeatureRecipe para la vinculación detiene la compilación, nombrándola.
Cada Release nombra bajo infra.image la imagen que ejecuta cada tarea, ya que core/compute/task no incluye ningún software. Las Releases de AWS nombran también, bajo infra.overrides, el clúster, las subredes, los grupos de seguridad y el rol de ejecución con los que se ejecuta cada tarea y, donde report tiene una programación, el rol con el que la programación inicia cada ejecución. Cada valor específico de la cuenta allí es un marcador de posición.
Generar el ejemplo
Puedes compilar este ejemplo con los comandos de abajo, o hacer que tu asistente de IA lo compile por ti.
Escribe el ejemplo en una carpeta nueva con su nombre:
aggrega scaffold --example task-run-on-demandDespués imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:
cd task-run-on-demandCompilación
El espacio de trabajo lee el catálogo de la biblioteca estándar del registro del hub que nombra .aggrega-config.yaml. Cada Recipe de aquí se renderiza solo a partir del catálogo, así que cada compilación se ejecuta sin conexión una vez resuelto el archivo de bloqueo.
aggrega build --release release-helm.yaml --auto-pull # one ReleaseEn un checkout del repositorio de la documentación, que contiene el script auxiliar de compilación compartido que una copia escrita por aggrega scaffold --example no incluye, ./check.sh compila las seis Releases y comprueba cada resultado. Imprime una línea por Release y termina con 0 solo cuando cada una ha acabado como describe esta página:
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.Con un asistente de IA
Un asistente de IA configurado con las herramientas de Aggrega puede hacer lo mismo: pégale este prompt.
Usa solo las herramientas de Aggrega y no crees ninguna carpeta por tu cuenta. Si la carpeta del espacio de trabajo aún no contiene una carpeta `task-run-on-demand`, llama una vez a la herramienta `scaffold` con `example` establecido en `task-run-on-demand` y sin `dir`: escribe el ejemplo en una nueva carpeta `task-run-on-demand`. Luego llama a la herramienta `build` con `workspace_root` establecido en `task-run-on-demand`, `release` establecido en `release-helm.yaml`, `auto_pull` establecido en true y `write` establecido en true. Dime qué archivos escribió la compilación; están en `task-run-on-demand/dist/`.Kubernetes
release-helm.yaml escribe dos archivos, un CronJob por tarea, y nada más. data-fix es un CronJob mantenido en suspensión, con una programación que el desarrollador nunca escribió:
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 necesita una programación, y 0 0 30 2 * designa el 30 de febrero, una fecha que ningún año contiene: suspendido, el CronJob no inicia ninguna ejecución y, reanudado, sigue sin tener un momento en el que iniciar una. Sin la vinculación, una tarea sin programación sería un Job, que se ejecuta en cuanto se despliega.
report es un CronJob con la programación que la Release satisfizo, y no está suspendido:
[… 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]Una ejecución de data-fix es un Job creado a partir de su CronJob, con un nombre que tú eliges:
kubectl create job data-fix-run-1 --from=cronjob/data-fixEl mismo comando, con --from=cronjob/report, inicia una ejecución adicional de report entre las programadas.
Docker Compose
release-compose.yaml escribe un único archivo de Compose. Cada tarea es un servicio que Compose no vuelve a arrancar cuando termina; data-fix lleva además el perfil manual, y report no lleva ninguno:
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 arranca un servicio que lleva un perfil solo cuando ese perfil está habilitado o el servicio se nombra en la línea de comandos, así que docker compose up ejecuta report una vez y deja data-fix detenido. Una ejecución de data-fix se inicia nombrando su servicio, y --rm elimina su contenedor cuando termina la ejecución:
docker compose -f dist/compose/docker-compose.yaml run --rm data-fixTerraform
release-terraform.yaml escribe una configuración raíz con un bloque de módulo por tarea, y el módulo de cada tarea a su lado. Los dos bloques difieren en la programación:
# 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"]}El módulo declara la programación de EventBridge Scheduler solo mientras recibe una expresión, así que la definición de tarea de data-fix queda sola:
[… 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 escribe la programación de report en la forma propia de EventBridge Scheduler: 30 2 * * 1-5 se convierte en cron(30 2 ? * 2,3,4,5,6 *), con los días de la semana numerados desde el domingo como 1, en UTC porque la Release no nombra ninguna zona horaria.
CloudFormation
release-cloudformation.yaml escribe una única plantilla de stack. Contiene una definición de tarea para cada tarea y una programación solo para report:
{ "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] } }}Nada en el stack hace referencia a DataFixTaskDefinition, así que nada la inicia.
Iniciar una ejecución en Amazon ECS
En ambos destinos de AWS, una ejecución de data-fix se inicia con la operación RunTask de Amazon ECS, a la que se pasa la familia de la definición de tarea tal como se renderizó y la configuración de clúster y de red que la Release nombra bajo 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}'Nombrada solo por su familia, la definición de tarea se resuelve en su revisión activa más reciente.
Lo que no hace la compilación
La compilación escribe archivos y se detiene. No inicia ninguna ejecución, en ningún destino: no alcanza ningún clúster, no arranca ningún stack de Compose y no llama a ninguna API de AWS, y la vinculación solo cambia lo que dicen los archivos. Tampoco escribe ningún script: cada comando de esta página es el propio del destino, ejecutado por quien lo opera, y ninguno está en dist/. Las realizaciones de la vinculación no añaden ningún archivo propio en ningún destino; el cambio que hace cada una está en la salida propia de la tarea, mostrada arriba.
Las dos Releases que se detienen
release-compose-scheduled.yaml satisface report_schedule en Docker Compose, y además vincula core/manual-trigger a report. En Kubernetes y AWS una tarea con programación se ejecuta según ella, esté o no la vinculación; en Docker Compose, sin planificador, una tarea con programación no tiene ninguna realización, vinculada o no. aggrega build --release release-compose-scheduled.yaml --auto-pull se detiene:
[… 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 deja vacío report_schedule en Terraform, así que report no tiene ni programación ni la vinculación, y nada en AWS la iniciaría nunca. Este es el caso para el que existe core/manual-trigger, y aggrega build --release release-terraform-unscheduled.yaml --auto-pull se detiene nombrándola:
[… 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 KubernetesAquí la programación llega a la tarea mediante un parámetro que la Release satisface, así que dar una programación al componente significa satisfacer report_schedule, como hace release-terraform.yaml.