コンテンツにスキップ
AggregaAggrega
言語の選択: 日本語
このページは機械翻訳されています。英語の原文を読む。

オンデマンドで実行するタスク:1 つの Aggregate、4 つのターゲット

core/manual-trigger を持つタスクを Kubernetes、Docker Compose、Terraform、CloudFormation 上に起動せずにデプロイし、何も持たないタスクと並べて、各ターゲットで実行を開始するコマンドとともに示します。

一部の作業は、誰かが求めたときにだけ完了まで実行されます。一度きりのデータ修正や、要求に応じたバックアップなどです。core/manual-trigger はそのための Feature です。スケジュールのない core/compute/task にアタッチすると、タスクを起動せずにデプロイし、各実行は誰かがターゲット自身のコマンドで手動で開始するものになります。

このワークスペースは 4 つのターゲット(Helm 経由の Kubernetes、Docker Compose、Terraform、CloudFormation)向けに 1 つの Aggregate をビルドし、それぞれについて、アタッチメントがレンダリング出力の何を変えるかと、実行を開始するコマンドを示します。2 つ目のタスクはアタッチメントを持たないため、違いは同じビルドの中で確認できます。さらに 2 つの Releases は停止することが想定されており、このページではそれぞれが出力する内容を引用しています。

構築されるもの

インスタンスカタログの Componentアタッチメント実行を開始するもの
data-fixcore/compute/taskcore/manual-trigger誰かが手動で、すべてのターゲットで
reportcore/compute/taskなしそのスケジュール、または Docker Compose ではスタックの起動

アタッチメントは Aggregate の中、変更対象のタスクの隣に置かれます。オンデマンドでの実行は data-fix が何であるかの一部なので開発者が記述し、その Feature は値も infra も受け取りません。Release はこれについて何も記述しません。

report のスケジュールはパラメータ report_schedule であり、Aggregate はこれを空のデフォルト値で宣言し、タスクの schedule 値に読み込みます:

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

これがパラメータなのは、アタッチメントのないタスクについて 4 つのターゲットの扱いが異なるためです。Kubernetes はスケジュールがあれば CronJob としてスケジュールどおりに実行し、なければデプロイ時に一度実行します。Docker Compose にはスケジューラがないため、スタックが起動するたびにタスクを一度実行し、スケジュールは拒否します。AWS では Terraform や CloudFormation の適用時に Amazon ECS タスクを実行するものが何もないため、そこでのタスクにはスケジュールかアタッチメントが必要で、どちらもなければ拒否されます。そのため Kubernetes、Terraform、CloudFormation の Releases は report_schedule を満たし、Docker Compose の Release はそれを空のままにします。

data-fix は 4 つすべてで同じようにビルドされ、スケジュールもパラメータもありません。

6 つの Releases

ReleaseManifestreport_scheduleビルド
release-helm.yamlmanifest-helm.yaml30 2 * * 1-5完了する
release-compose.yamlmanifest-compose.yaml空完了する
release-terraform.yamlmanifest-terraform.yaml30 2 * * 1-5完了する
release-cloudformation.yamlmanifest-cloudformation.yaml30 2 * * 1-5完了する
release-compose-scheduled.yamlmanifest-compose.yaml30 2 * * 1-5停止する
release-terraform-unscheduled.yamlmanifest-terraform.yaml空停止する

各 Manifest は core/compute/task をそのターゲットの Recipe にマッピングし、core/manual-trigger をそのターゲットの FeatureRecipe にバインドします。helm/task と helm/manual-trigger、compose/task と compose/manual-trigger、terraform/task-ecs と terraform/manual-trigger、そして cloudformation/task-ecs と cloudformation/manual-trigger です。アタッチメントに対して FeatureRecipe をバインドしない Manifest は、それを名指ししてビルドを停止します。

core/compute/task はソフトウェアをパッケージしないため、各 Release は各タスクが実行するイメージを infra.image の下で指定します。AWS の Releases はさらに infra.overrides の下で、各タスクが実行に使うクラスター、サブネット、セキュリティグループ、実行ロールを指定し、report にスケジュールがある場合は、スケジュールが各実行を開始する際のロールも指定します。そこにあるアカウント固有の値はすべてプレースホルダーです。

サンプルを生成する

このサンプルは以下のコマンドでビルドできます。または、AI アシスタントにビルドを任せることもできます。

例の名前を付けた新しいフォルダーに例を書き出します。

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

その後、次に実行するコマンドを表示します。最初のコマンドは新しいフォルダーに移動します。

Terminal window
cd task-run-on-demand

ビルド

ワークスペースは、.aggrega-config.yaml が指定する hub レジストリから標準ライブラリカタログを読み込みます。ここにあるすべての Recipe はカタログだけからレンダリングされるため、ロックファイルが解決されれば、すべてのビルドはオフラインで実行できます。

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

ドキュメントリポジトリのチェックアウト(aggrega scaffold --example が書き出したコピーにはない共有ビルドヘルパーを含みます)では、./check.sh が 6 つの Releases をすべてビルドし、それぞれの結果を確認します。Release ごとに 1 行を出力し、それぞれがこのページの説明どおりに終了した場合にのみ 0 で終了します。

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.

AI アシスタントを使う

Aggrega のツールでセットアップした AI アシスタントでも同じことができます。次のプロンプトを貼り付けてください。

Aggrega のツールのみを使用し、フォルダーは自分で作成しないでください。ワークスペースフォルダーにまだ `task-run-on-demand` フォルダーがない場合は、`example` を `task-run-on-demand` に設定し、`dir` を指定せずに `scaffold` ツールを 1 回呼び出してください。これにより、新しい `task-run-on-demand` フォルダーに例が書き込まれます。次に、`workspace_root` を `task-run-on-demand`、`release` を `release-helm.yaml`、`auto_pull` を true、`write` を true に設定して `build` ツールを呼び出してください。ビルドが書き込んだファイルを教えてください。ファイルは `task-run-on-demand/dist/` の下にあります。

Kubernetes

release-helm.yaml は 2 つのファイル、つまりタスクごとに 1 つの CronJob を書き出し、それ以外は何も書きません。data-fix は、開発者が一度も書いていないスケジュールで一時停止状態に保たれた CronJob です:

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

CronJob にはスケジュールが必要で、0 0 30 2 * はどの年にも存在しない日付である 2 月 30 日を指します。一時停止中の CronJob は実行を開始せず、再開しても実行を開始する時刻がありません。アタッチメントがなければ、スケジュールのないタスクは Job になり、デプロイされるとすぐに実行されます。

report は Release が満たしたスケジュールで動く CronJob で、一時停止されていません:

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]

data-fix の実行は、その CronJob から任意の名前で作成される Job です:

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

同じコマンドに --from=cronjob/report を指定すると、report のスケジュールされた実行の合間に追加の実行を開始します。

Docker Compose

release-compose.yaml は 1 つの Compose ファイルを書き出します。各タスクは、終了しても Compose が再び起動しないサービスです。data-fix はさらにプロファイル manual を持ち、report は何も持ちません:

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]

Compose は、プロファイルを持つサービスを、そのプロファイルが有効化されたときか、コマンドラインでそのサービスが指定されたときにのみ起動します。そのため docker compose up は report を一度実行し、data-fix は停止したままにします。data-fix の実行はそのサービスを指定して開始し、--rm は実行終了後にそのコンテナを削除します:

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

Terraform

release-terraform.yaml は、タスクごとに 1 つの module ブロックを持つルート構成と、その隣に各タスクのモジュールを書き出します。2 つのブロックはスケジュールが異なります:

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

モジュールは式が与えられている場合にのみ EventBridge Scheduler のスケジュールを宣言するため、data-fix のタスク定義は単独で存在します:

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]

Recipe は report のスケジュールを EventBridge Scheduler 独自の形式で書きます。30 2 * * 1-5 は cron(30 2 ? * 2,3,4,5,6 *) になり、曜日は日曜日を 1 として番号付けされ、Release がタイムゾーンを指定していないため UTC になります。

CloudFormation

release-cloudformation.yaml は 1 つのスタックテンプレートを書き出します。そこには各タスクのタスク定義と、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]
}
}
}

スタック内に DataFixTaskDefinition を参照するものはないため、それを起動するものはありません。

Amazon ECS で実行を開始する

どちらの AWS ターゲットでも、data-fix の実行は Amazon ECS の RunTask 操作で開始し、レンダリングされたとおりのタスク定義のファミリーと、Release が 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}'

ファミリーだけで指定すると、タスク定義は最新のアクティブなリビジョンに解決されます。

ビルドが行わないこと

ビルドはファイルを書き出して停止します。どのターゲットでも実行は開始しません。クラスターに接続せず、Compose スタックを起動せず、AWS API も呼び出さず、アタッチメントが変えるのはファイルの内容だけです。スクリプトも書きません。このページのコマンドはすべてターゲット自身のもので、それを運用する人が実行し、どれも dist/ にはありません。アタッチメントの実現は、どのターゲットでも独自のファイルを追加しません。それぞれが加える変更は、上に示したタスク自身の出力の中にあります。

停止する 2 つの Releases

release-compose-scheduled.yaml は Docker Compose で report_schedule を満たし、さらに core/manual-trigger を report にアタッチします。Kubernetes と AWS では、スケジュールのあるタスクはアタッチメントの有無にかかわらずそのスケジュールで実行されます。スケジューラのない Docker Compose では、スケジュールのあるタスクはアタッチの有無にかかわらず実現を持ちません。aggrega build --release release-compose-scheduled.yaml --auto-pull は停止します:

[… 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 は Terraform で report_schedule を空のままにするため、report にはスケジュールもアタッチメントもなく、AWS 上でそれを起動するものは何もありません。これこそ core/manual-trigger が存在する理由となるケースであり、aggrega build --release release-terraform-unscheduled.yaml --auto-pull はそれを名指しして停止します:

[… 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

ここではスケジュールが Release の満たすパラメータを通じてタスクに届くため、コンポーネントにスケジュールを与えるとは、release-terraform.yaml が行うように report_schedule を満たすことを意味します。