Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

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ânciaComponent do catálogovinculaçãoo que inicia uma execução
data-fixcore/compute/taskcore/manual-triggeralguém, manualmente, em cada destino
reportcore/compute/tasknenhumo 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:

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

É 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

ReleaseManifestreport_scheduleo build
release-helm.yamlmanifest-helm.yaml30 2 * * 1-5é concluído
release-compose.yamlmanifest-compose.yamlvazioé concluído
release-terraform.yamlmanifest-terraform.yaml30 2 * * 1-5é concluído
release-cloudformation.yamlmanifest-cloudformation.yaml30 2 * * 1-5é concluído
release-compose-scheduled.yamlmanifest-compose.yaml30 2 * * 1-5é interrompido
release-terraform-unscheduled.yamlmanifest-terraform.yamlvazioé 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:

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

Em seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:

Terminal window
cd task-run-on-demand

Build

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.

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

Em 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 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.

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:

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

Um 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:

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]

Uma execução de data-fix é um Job criado a partir do seu CronJob, com um nome à sua escolha:

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

O 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:

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]

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:

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

Terraform

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:

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

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:

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]

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:

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

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:

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

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 --rm

release-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 Kubernetes

Aqui 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.