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

Uma tarefa executada a pedido: um Aggregate, quatro destinos

Uma tarefa que transporta core/manual-trigger, implementada sem arrancar no Kubernetes, no Docker Compose, no Terraform e no CloudFormation, ao lado de uma tarefa que não transporta nada, com o comando que inicia uma execução em cada destino.

Algum trabalho só é executado até ao fim quando alguém o pede: uma correção de dados pontual, uma cópia de segurança a pedido. core/manual-trigger é a Feature para isso. Anexada a um core/compute/task sem agendamento, implementa a tarefa sem a arrancar, e cada execução é iniciada manualmente por alguém, com o comando próprio do destino.

Este espaço de trabalho compila um único Aggregate para quatro destinos — Kubernetes através do Helm, Docker Compose, Terraform e CloudFormation — e mostra, em cada um, o que o anexo altera na saída renderizada e o comando que inicia uma execução. A segunda tarefa não transporta nenhum anexo, pelo que a diferença é visível na mesma compilação. Espera-se que outras duas Releases sejam interrompidas, e a página cita o que cada uma imprime.

O que constrói

instânciaComponent do catálogoanexoo 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, o arranque da stack

O anexo está no Aggregate, ao lado da tarefa que altera: ser executada a pedido faz parte do que data-fix é, pelo que é o programador que o escreve, e a Feature não aceita 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 valor predefinido 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 anexo. O Kubernetes executa-a segundo um agendamento como CronJob, ou uma única vez na implementação se não tiver um. O Docker Compose não tem agendador, pelo que executa a tarefa uma vez sempre que a stack arranca e recusa um agendamento. Na AWS nada executa uma tarefa do Amazon ECS quando o Terraform ou o CloudFormation aplica a configuração, pelo que aí uma tarefa precisa de um agendamento ou do anexo, 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 deixa-o vazio.

data-fix compila-se da mesma forma nos quatro, sem agendamento e sem parâmetro.

As seis Releases

ReleaseManifestreport_schedulea compilação
release-helm.yamlmanifest-helm.yaml30 2 * * 1-5é concluída
release-compose.yamlmanifest-compose.yamlvazioé concluída
release-terraform.yamlmanifest-terraform.yaml30 2 * * 1-5é concluída
release-cloudformation.yamlmanifest-cloudformation.yaml30 2 * * 1-5é concluída
release-compose-scheduled.yamlmanifest-compose.yaml30 2 * * 1-5é interrompida
release-terraform-unscheduled.yamlmanifest-terraform.yamlvazioé interrompida

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 ao anexo interrompe a compilação, nomeando-o.

Cada Release nomeia sob infra.image a imagem que cada tarefa executa, uma vez que core/compute/task não inclui nenhum software. As Releases da AWS nomeiam também, 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. Cada valor específico da conta aí é um marcador de posição.

Gerar o exemplo

É possível compilar este exemplo com os comandos abaixo, ou pedir ao assistente de IA que o compile.

Escreva o exemplo numa nova pasta com o nome dele:

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

Depois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:

Terminal window
cd task-run-on-demand

Compilação

O espaço de trabalho lê o catálogo da biblioteca standard a partir do registo do hub que .aggrega-config.yaml nomeia. Cada Recipe aqui é renderizada apenas a partir do catálogo, pelo que cada compilação é executada offline assim que o ficheiro de bloqueio estiver resolvido.

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

Num checkout do repositório da documentação, que contém o script auxiliar de compilação partilhado que uma cópia escrita por aggrega scaffold --example não traz, ./check.sh compila as seis Releases e verifica cada resultado. Imprime uma linha por Release e termina com 0 apenas 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-lhe este prompt.

Utilize apenas as ferramentas do Aggrega e não crie nenhuma pasta por iniciativa própria. Se a pasta da área 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`: esta escreve o exemplo numa 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. Indique-me que ficheiros a compilação escreveu; encontram-se em `task-run-on-demand/dist/`.

Kubernetes

release-helm.yaml escreve dois ficheiros, um CronJob por tarefa, e nada mais. data-fix é um CronJob mantido suspenso, com um agendamento que o programador 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 * designa 30 de fevereiro, uma data que nenhum ano tem: suspenso, o CronJob não inicia nenhuma execução e, retomado, continua sem um momento em que iniciar uma. Sem o anexo, uma tarefa sem agendamento seria um Job, que é executado assim que é implementado.

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 à 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 adicional de report entre as agendadas.

Docker Compose

release-compose.yaml escreve um único ficheiro do Compose. Cada tarefa é um serviço que o Compose não volta a arrancar quando termina; data-fix transporta também o perfil manual, e report não transporta 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 só arranca um serviço que transporta um perfil quando esse perfil está ativado ou o serviço é nomeado na linha de comandos, pelo que docker compose up executa report uma vez e deixa data-fix parado. Uma execução de data-fix inicia-se nomeando o seu serviço, e --rm remove o seu contentor quando a execução termina:

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

Terraform

release-terraform.yaml escreve 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 só declara o agendamento do EventBridge Scheduler enquanto recebe uma expressão, pelo que a definição de tarefa de data-fix fica isolada:

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 passa a 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 escreve um único template de stack. 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 na stack faz referência a DataFixTaskDefinition, pelo que nada a inicia.

Iniciar uma execução no Amazon ECS

Em ambos os destinos da AWS, uma execução de data-fix é iniciada com a operação RunTask do Amazon ECS, à qual se passa a família da definição de tarefa tal 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 resolve-se na sua revisão ativa mais recente.

O que a compilação não faz

A compilação escreve ficheiros e para. Não inicia nenhuma execução, em nenhum destino: não alcança nenhum cluster, não arranca nenhuma stack do Compose e não chama nenhuma API da AWS, e o anexo altera apenas o que os ficheiros dizem. Também não escreve nenhum script: cada comando desta página é o próprio do destino, executado por quem o opera, e nenhum está em dist/. As realizações do anexo não acrescentam nenhum ficheiro próprio em nenhum destino; a alteração 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 anexa também core/manual-trigger a report. No Kubernetes e na AWS uma tarefa com agendamento é executada segundo ele, quer o anexo exista quer não; no Docker Compose, sem agendador, uma tarefa com agendamento não tem nenhuma realização, anexada 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, pelo que report não tem nem um agendamento nem o anexo, e nada na AWS alguma vez 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 através de um parâmetro que a Release satisfaz, pelo que dar um agendamento ao componente significa satisfazer report_schedule, como faz release-terraform.yaml.