Uma tarefa executada sob demanda: um Aggregate, quatro destinos
Uma tarefa que carrega core/manual-trigger, implantada sem iniciar no Kubernetes, no Docker Compose, no Terraform e no CloudFormation, ao lado de uma tarefa que não carrega nada, com o comando que inicia uma execução em cada destino.
Alguns trabalhos são executados até a conclusão apenas quando alguém os solicita: uma correção de dados pontual, um backup sob demanda. core/manual-trigger é a Feature para isso. Vinculada a um core/compute/task sem agendamento, ela implanta a tarefa sem iniciá-la, e cada execução é iniciada manualmente por alguém, com o comando próprio do destino.
Este espaço de trabalho faz o build de um único Aggregate para quatro destinos — Kubernetes por meio do Helm, Docker Compose, Terraform e CloudFormation — e mostra, em cada um, o que a vinculação muda na saída renderizada e o comando que inicia uma execução. A segunda tarefa não carrega nenhuma vinculação, então a diferença fica visível no mesmo build. Espera-se que outras duas Releases sejam interrompidas, e a página cita o que cada uma imprime.
O que ele constrói
| instância | Component do catálogo | vinculação | o que inicia uma execução |
|---|---|---|---|
data-fix | core/compute/task | core/manual-trigger | alguém, manualmente, em cada destino |
report | core/compute/task | nenhum | o seu agendamento ou, no Docker Compose, a inicialização do stack |
A vinculação fica no Aggregate, ao lado da tarefa que ela altera: ser executada sob demanda faz parte do que data-fix é, então quem a escreve é o desenvolvedor, e a Feature não recebe valores nem infra. A Release não escreve nada para ela.
O agendamento de report é um parâmetro, report_schedule, que o Aggregate declara com um padrão vazio e lê no valor schedule da tarefa:
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 }}"É um parâmetro porque os quatro destinos divergem quanto a uma tarefa sem vinculação. O Kubernetes a executa com um agendamento como CronJob, ou uma única vez na implantação se não houver um. O Docker Compose não tem agendador, então executa a tarefa uma vez a cada inicialização do stack e recusa um agendamento. Na AWS nada executa uma tarefa do Amazon ECS quando o Terraform ou o CloudFormation aplica a configuração, então ali uma tarefa precisa de um agendamento ou da vinculação, e é recusada sem nenhum dos dois. Por isso as Releases do Kubernetes, do Terraform e do CloudFormation satisfazem report_schedule, e a Release do Docker Compose o deixa vazio.
data-fix passa pelo build da mesma forma nos quatro, sem agendamento e sem parâmetro.
As seis Releases
| Release | Manifest | report_schedule | o build |
|---|---|---|---|
release-helm.yaml | manifest-helm.yaml | 30 2 * * 1-5 | é concluído |
release-compose.yaml | manifest-compose.yaml | vazio | é concluído |
release-terraform.yaml | manifest-terraform.yaml | 30 2 * * 1-5 | é concluído |
release-cloudformation.yaml | manifest-cloudformation.yaml | 30 2 * * 1-5 | é concluído |
release-compose-scheduled.yaml | manifest-compose.yaml | 30 2 * * 1-5 | é interrompido |
release-terraform-unscheduled.yaml | manifest-terraform.yaml | vazio | é interrompido |
Cada Manifest mapeia core/compute/task para a Recipe do seu destino e associa core/manual-trigger à FeatureRecipe do seu destino: helm/task e helm/manual-trigger, compose/task e compose/manual-trigger, terraform/task-ecs e terraform/manual-trigger, e cloudformation/task-ecs e cloudformation/manual-trigger. Um Manifest que não associa nenhuma FeatureRecipe à vinculação interrompe o build, nomeando-a.
Cada Release nomeia sob infra.image a imagem que cada tarefa executa, já que core/compute/task não empacota nenhum software. As Releases da AWS também nomeiam, sob infra.overrides, o cluster, as sub-redes, os grupos de segurança e a função de execução com que cada tarefa é executada e, onde report tem um agendamento, a função sob a qual o agendamento inicia cada execução. Todo valor específico da conta ali é um espaço reservado.
Gerar o exemplo
Você pode fazer o build deste exemplo com os comandos abaixo, ou pedir ao seu assistente de IA que faça o build por você.
Escreva o exemplo em uma nova pasta com o nome dele:
aggrega scaffold --example task-run-on-demandEm seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:
cd task-run-on-demandBuild
O espaço de trabalho lê o catálogo da biblioteca padrão a partir do registry do hub que .aggrega-config.yaml nomeia. Toda Recipe aqui é renderizada apenas a partir do catálogo, então todo build roda offline depois que o arquivo de bloqueio é resolvido.
aggrega build --release release-helm.yaml --auto-pull # one ReleaseEm um checkout do repositório da documentação, que contém o script auxiliar de build compartilhado que uma cópia escrita por aggrega scaffold --example não traz, ./check.sh compila as seis Releases e verifica cada resultado. Ele imprime uma linha por Release e sai com 0 somente quando cada uma terminou como esta página descreve:
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.Com um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole este prompt nele.
Use somente as ferramentas do Aggrega e não crie nenhuma pasta por conta própria. Se a pasta do espaço de trabalho ainda não contiver uma pasta `task-run-on-demand`, chame uma vez a ferramenta `scaffold` com `example` definido como `task-run-on-demand` e sem `dir`: ela grava o exemplo em uma nova pasta `task-run-on-demand`. Em seguida, chame a ferramenta `build` com `workspace_root` definido como `task-run-on-demand`, `release` definido como `release-helm.yaml`, `auto_pull` definido como true e `write` definido como true. Diga-me quais arquivos o build gravou; eles ficam em `task-run-on-demand/dist/`.Kubernetes
release-helm.yaml grava dois arquivos, um CronJob por tarefa, e nada mais. data-fix é um CronJob mantido suspenso, com um agendamento que o desenvolvedor nunca escreveu:
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: NeverUm CronJob precisa de um agendamento, e 0 0 30 2 * indica 30 de fevereiro, uma data que nenhum ano tem: suspenso, o CronJob não inicia nenhuma execução e, retomado, continua sem um horário em que iniciar uma. Sem a vinculação, uma tarefa sem agendamento seria um Job, que é executado assim que é implantado.
report é um CronJob com o agendamento que a Release satisfez, e não está suspenso:
[… 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]Uma execução de data-fix é um Job criado a partir do seu CronJob, com um nome à sua escolha:
kubectl create job data-fix-run-1 --from=cronjob/data-fixO mesmo comando, com --from=cronjob/report, inicia uma execução extra de report entre as agendadas.
Docker Compose
release-compose.yaml grava um único arquivo do Compose. Cada tarefa é um serviço que o Compose não reinicia quando ele termina; data-fix também carrega o perfil manual, e report não carrega nenhum:
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]O Compose inicia um serviço que carrega um perfil apenas quando esse perfil está habilitado ou o serviço é nomeado na linha de comando, então docker compose up executa report uma vez e deixa data-fix parado. Uma execução de data-fix é iniciada nomeando o seu serviço, e --rm remove o seu contêiner quando a execução termina:
docker compose -f dist/compose/docker-compose.yaml run --rm data-fixTerraform
release-terraform.yaml grava uma configuração raiz com um bloco de módulo por tarefa, e o módulo de cada tarefa ao lado. Os dois blocos diferem no agendamento:
# 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"]}O módulo declara o agendamento do EventBridge Scheduler apenas enquanto recebe uma expressão, então a definição de tarefa de data-fix fica sozinha:
[… 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]A Recipe escreve o agendamento de report na forma própria do EventBridge Scheduler: 30 2 * * 1-5 se torna cron(30 2 ? * 2,3,4,5,6 *), com os dias da semana numerados a partir do domingo como 1, em UTC porque a Release não nomeia nenhum fuso horário.
CloudFormation
release-cloudformation.yaml grava um único template de stack. Ele contém uma definição de tarefa para cada tarefa e um agendamento apenas 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 no stack faz referência a DataFixTaskDefinition, então nada a inicia.
Iniciar uma execução no Amazon ECS
Nos dois destinos da AWS, uma execução de data-fix é iniciada com a operação RunTask do Amazon ECS, que recebe a família da definição de tarefa como renderizada e a configuração de cluster e de rede que a Release nomeia sob 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}'Nomeada apenas pela sua família, a definição de tarefa é resolvida para a sua revisão ativa mais recente.
O que o build não faz
O build grava arquivos e para. Ele não inicia nenhuma execução, em nenhum destino: não alcança nenhum cluster, não inicia nenhum stack do Compose e não chama nenhuma API da AWS, e a vinculação muda apenas o que os arquivos dizem. Também não grava nenhum script: todo comando desta página é o próprio do destino, executado por quem o opera, e nenhum está em dist/. As realizações da vinculação não adicionam nenhum arquivo próprio em nenhum destino; a mudança que cada uma faz está na saída própria da tarefa, mostrada acima.
As duas Releases que são interrompidas
release-compose-scheduled.yaml satisfaz report_schedule no Docker Compose, e também vincula core/manual-trigger a report. No Kubernetes e na AWS uma tarefa com agendamento é executada conforme ele, haja ou não a vinculação; no Docker Compose, sem agendador, uma tarefa com agendamento não tem nenhuma realização, vinculada ou não. aggrega build --release release-compose-scheduled.yaml --auto-pull é interrompido:
[… 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 deixa report_schedule vazio no Terraform, então report não tem nem um agendamento nem a vinculação, e nada na AWS jamais a iniciaria. Este é o caso para o qual core/manual-trigger existe, e aggrega build --release release-terraform-unscheduled.yaml --auto-pull é interrompido, nomeando-a:
[… 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 KubernetesAqui o agendamento chega à tarefa por meio de um parâmetro que a Release satisfaz, então dar um agendamento ao componente significa satisfazer report_schedule, como faz release-terraform.yaml.