Một tác vụ chạy theo yêu cầu: một Aggregate, bốn đích
Một tác vụ mang core/manual-trigger, được triển khai mà không khởi động trên Kubernetes, Docker Compose, Terraform và CloudFormation, bên cạnh một tác vụ không mang gì, cùng với lệnh khởi động một lần chạy trên mỗi đích.
Một số công việc chỉ chạy đến khi hoàn tất khi có người yêu cầu: một lần sửa dữ liệu đơn lẻ, một bản sao lưu theo yêu cầu. core/manual-trigger là Feature dành cho việc đó. Khi được gắn vào một core/compute/task không có lịch, nó triển khai tác vụ mà không khởi động tác vụ, và mỗi lần chạy là một lần có người khởi động thủ công, bằng lệnh riêng của đích.
Workspace này build một Aggregate cho bốn đích — Kubernetes thông qua Helm, Docker Compose, Terraform và CloudFormation — và cho thấy, trên mỗi đích, attachment thay đổi gì trong đầu ra được render và lệnh khởi động một lần chạy. Tác vụ thứ hai không mang attachment, nên sự khác biệt hiện rõ trong cùng một bản build. Hai Releases nữa được dự kiến sẽ dừng, và trang này trích dẫn những gì mỗi cái in ra.
Những gì ví dụ này xây dựng
| instance | Component trong catalog | attachment | thứ khởi động một lần chạy |
|---|---|---|---|
data-fix | core/compute/task | core/manual-trigger | một người, thủ công, trên mọi đích |
report | core/compute/task | không có | lịch của nó, hoặc, trên Docker Compose, việc stack khởi động |
Attachment nằm trong Aggregate, bên cạnh tác vụ mà nó thay đổi: việc chạy theo yêu cầu là một phần bản chất của data-fix, nên developer viết nó, và Feature không nhận giá trị nào cũng như không nhận infra. Release không viết gì cho nó.
Lịch của report là một tham số, report_schedule, được Aggregate khai báo với giá trị mặc định rỗng và đọc vào giá trị schedule của tác vụ:
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 }}"Nó là một tham số vì bốn đích xử lý khác nhau đối với một tác vụ không có attachment. Kubernetes chạy nó theo lịch dưới dạng CronJob, hoặc chạy một lần khi triển khai nếu không có lịch. Docker Compose không có bộ lập lịch, nên chạy tác vụ một lần mỗi khi stack khởi động và từ chối lịch. Trên AWS, không có gì chạy một tác vụ Amazon ECS khi Terraform hoặc CloudFormation áp dụng, nên một tác vụ ở đó cần một lịch hoặc attachment, và bị từ chối nếu không có cả hai. Vì vậy các Releases cho Kubernetes, Terraform và CloudFormation đáp ứng report_schedule, còn Release cho Docker Compose để trống nó.
data-fix được build theo cùng một cách trên cả bốn đích, không có lịch và không có tham số.
Sáu Releases
| Release | Manifest | report_schedule | bản build |
|---|---|---|---|
release-helm.yaml | manifest-helm.yaml | 30 2 * * 1-5 | hoàn tất |
release-compose.yaml | manifest-compose.yaml | rỗng | hoàn tất |
release-terraform.yaml | manifest-terraform.yaml | 30 2 * * 1-5 | hoàn tất |
release-cloudformation.yaml | manifest-cloudformation.yaml | 30 2 * * 1-5 | hoàn tất |
release-compose-scheduled.yaml | manifest-compose.yaml | 30 2 * * 1-5 | dừng lại |
release-terraform-unscheduled.yaml | manifest-terraform.yaml | rỗng | dừng lại |
Mỗi Manifest ánh xạ core/compute/task tới Recipe của đích tương ứng và liên kết core/manual-trigger với FeatureRecipe của đích đó: helm/task và helm/manual-trigger, compose/task và compose/manual-trigger, terraform/task-ecs và terraform/manual-trigger, cùng cloudformation/task-ecs và cloudformation/manual-trigger. Một Manifest không liên kết FeatureRecipe nào cho attachment sẽ dừng bản build và nêu tên nó.
Mỗi Release nêu image mà mỗi tác vụ chạy dưới infra.image, vì core/compute/task không đóng gói phần mềm nào. Các Releases cho AWS cũng nêu, dưới infra.overrides, cluster, subnet, security group và execution role mà mỗi tác vụ chạy cùng, và, nơi report có lịch, role mà lịch dùng để khởi động mỗi lần chạy. Mọi giá trị riêng cho tài khoản ở đó đều là placeholder.
Tạo ví dụ
Bạn có thể build ví dụ này bằng các lệnh bên dưới, hoặc để trợ lý AI của bạn build giúp bạn.
Ghi ví dụ vào một thư mục mới đặt theo tên của nó:
aggrega scaffold --example task-run-on-demandSau đó nó in ra các lệnh cần chạy tiếp theo. Lệnh đầu tiên chuyển vào thư mục mới:
cd task-run-on-demandBuild
Workspace đọc catalog thư viện chuẩn từ registry hub mà .aggrega-config.yaml nêu tên. Mọi Recipe ở đây chỉ render từ catalog, nên mọi bản build đều chạy offline sau khi lockfile được phân giải.
aggrega build --release release-helm.yaml --auto-pull # one ReleaseTrong một bản checkout của kho tài liệu, nơi chứa script trợ giúp build dùng chung mà một bản sao do aggrega scaffold --example ghi ra không có, ./check.sh build cả sáu Releases và kiểm tra từng kết quả. Nó in một dòng cho mỗi Release và chỉ thoát với mã 0 khi mỗi Release kết thúc như trang này mô tả:
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.Với trợ lý AI
Một trợ lý AI được thiết lập với các công cụ của Aggrega cũng có thể làm như vậy: hãy dán prompt này vào trợ lý.
Chỉ dùng các công cụ của Aggrega và không tự tạo thư mục nào. Nếu thư mục không gian làm việc chưa có thư mục `task-run-on-demand`, hãy gọi công cụ `scaffold` một lần với `example` đặt thành `task-run-on-demand` và không có `dir`: công cụ này ghi ví dụ vào một thư mục `task-run-on-demand` mới. Sau đó gọi công cụ `build` với `workspace_root` đặt thành `task-run-on-demand`, `release` đặt thành `release-helm.yaml`, `auto_pull` đặt thành true và `write` đặt thành true. Hãy cho tôi biết lần build đã ghi những tệp nào; chúng nằm dưới `task-run-on-demand/dist/`.Kubernetes
release-helm.yaml ghi hai tệp, một CronJob cho mỗi tác vụ, và không gì khác. data-fix là một CronJob được giữ ở trạng thái tạm ngưng, với một lịch mà developer chưa từng viết:
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: NeverMột CronJob cần một lịch, và 0 0 30 2 * chỉ ngày 30 tháng 2, một ngày không năm nào có: khi tạm ngưng, CronJob không khởi động lần chạy nào, và khi tiếp tục, nó vẫn không có thời điểm nào để khởi động một lần chạy. Nếu không có attachment, một tác vụ không có lịch sẽ là một Job, chạy ngay khi được triển khai.
report là một CronJob theo lịch mà Release đã đáp ứng, và không bị tạm ngưng:
[… 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]Một lần chạy của data-fix là một Job được tạo từ CronJob của nó, với tên do bạn chọn:
kubectl create job data-fix-run-1 --from=cronjob/data-fixCùng lệnh đó, khi được truyền --from=cronjob/report, sẽ khởi động một lần chạy bổ sung của report giữa các lần chạy theo lịch.
Docker Compose
release-compose.yaml ghi một tệp Compose. Mỗi tác vụ là một service mà Compose không khởi động lại khi nó thoát; data-fix còn mang profile manual, còn report không mang profile nào:
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 chỉ khởi động một service mang profile khi profile đó được bật hoặc service được nêu tên trên dòng lệnh, nên docker compose up chạy report một lần và để data-fix ở trạng thái dừng. Một lần chạy của data-fix được khởi động bằng cách nêu tên service của nó, và --rm xóa container của nó khi lần chạy kết thúc:
docker compose -f dist/compose/docker-compose.yaml run --rm data-fixTerraform
release-terraform.yaml ghi một cấu hình gốc với một khối module cho mỗi tác vụ, và module của mỗi tác vụ bên cạnh. Hai khối khác nhau ở lịch:
# 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"]}Module chỉ khai báo lịch EventBridge Scheduler khi được cung cấp một biểu thức, nên định nghĩa tác vụ của data-fix đứng riêng:
[… 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]Recipe viết lịch của report theo dạng riêng của EventBridge Scheduler: 30 2 * * 1-5 trở thành cron(30 2 ? * 2,3,4,5,6 *), các ngày trong tuần được đánh số từ Chủ nhật là 1, theo UTC vì Release không nêu múi giờ nào.
CloudFormation
release-cloudformation.yaml ghi một template stack. Template chứa một định nghĩa tác vụ cho mỗi tác vụ và một lịch chỉ cho 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] } }}Không có gì trong stack tham chiếu tới DataFixTaskDefinition, nên không có gì khởi động nó.
Khởi động một lần chạy trên Amazon ECS
Trên cả hai đích AWS, một lần chạy của data-fix được khởi động bằng thao tác Amazon ECS RunTask, với family của định nghĩa tác vụ như đã render cùng cấu hình cluster và mạng mà Release nêu dưới 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}'Khi chỉ được nêu bằng family, định nghĩa tác vụ được phân giải thành revision đang hoạt động mới nhất của nó.
Những gì bản build không làm
Bản build ghi tệp rồi dừng. Nó không khởi động lần chạy nào, trên bất kỳ đích nào: nó không kết nối tới cluster nào, không khởi động stack Compose nào và không gọi API AWS nào, và attachment chỉ thay đổi nội dung của các tệp. Nó cũng không ghi script nào: mọi lệnh trên trang này là lệnh riêng của đích, do người vận hành đích chạy, và không lệnh nào nằm trong dist/. Các hiện thực của attachment không thêm tệp riêng nào trên bất kỳ đích nào; thay đổi mà mỗi hiện thực tạo ra nằm trong chính đầu ra của tác vụ, như đã trình bày ở trên.
Hai Releases bị dừng
release-compose-scheduled.yaml đáp ứng report_schedule trên Docker Compose, và đồng thời gắn core/manual-trigger vào report. Trên Kubernetes và AWS, một tác vụ có lịch chạy theo lịch đó dù có attachment hay không; trên Docker Compose, vốn không có bộ lập lịch, một tác vụ có lịch không có hiện thực nào, dù được gắn hay không. aggrega build --release release-compose-scheduled.yaml --auto-pull dừng lại:
[… 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 để trống report_schedule trên Terraform, nên report không có lịch cũng không có attachment, và không có gì trên AWS sẽ khởi động nó. Đây chính là trường hợp mà core/manual-trigger tồn tại để xử lý, và aggrega build --release release-terraform-unscheduled.yaml --auto-pull dừng lại và nêu tên nó:
[… 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Ở đây lịch đến với tác vụ thông qua một tham số mà Release đáp ứng, nên việc cung cấp lịch cho component có nghĩa là đáp ứng report_schedule, như release-terraform.yaml làm.