AWS Fargate Launch ExecModule

Overview

FargateLaunchModule version 2.0 submits one real AWS ECS RunTask request for the Fargate launch type. It replaces the legacy placeholder that returned a fake task ARN without contacting AWS.

The module validates a bounded task definition, VPC network override, optional container command and non-secret environment values. A real launch requires an explicit confirmation, a Security Fabric deployment approval, a verified READY AWS IntegrationAccount, sufficient prepaid credits for the authenticated workflow principal, and a stable ECS client token.

AWS credentials never come from workflow input, module configuration JSON, environment overrides, logs, errors, or outputs.

Usage

1. Register an ECS task definition whose execution role, task role, image, secret references, logging, health checks, and limits have already been reviewed.
2. Bind a least-privilege verified AWS IntegrationAccount to the ExecModule.
3. Run with dryRun: true to validate the bounded request and inspect its content-free plan.
4. Obtain the exact-action deployment approval required by Security Fabric.
5. Replay the same request with confirmLaunch: true, dryRun: false, and the same idempotencyKey.
6. Preserve idempotencyKey and taskArn for provider and billing reconciliation.

The module does not create clusters, task definitions, IAM roles, VPCs, subnets, security groups, load balancers, services, or autoscaling policies.

Inputs

Input	Type	Required	Default	Description
region	string	Yes	—	AWS region such as us-west-2.
cluster	string	Yes	—	ECS cluster name or ARN.
taskDefinition	string	Yes	—	Registered task-definition family, revision, or ARN. The image remains governed by that definition.
subnetIds	array	Yes	—	One to sixteen subnet IDs used by awsvpc networking.
securityGroupIds	array	No	[]	Up to five security-group IDs.
assignPublicIp	boolean	No	false	Requests a public IP for the task ENI when true.
containerName	string	Conditional	—	Task-definition container to override. Required when command or environment is present.
command	array	No	[]	Up to twenty non-empty, single-line command elements, each at most 1,024 characters.
environment	object	No	{}	Up to fifty sorted, non-secret environment entries. Values are single-line strings up to 4,096 characters.
cpu	integer	No	512	Task CPU override and billing input, from 256 through 16,384 units.
memory	integer	No	1024	Task memory override and billing input, from 512 through 122,880 MiB.
idempotencyKey	string	Yes	—	Stable 8–64 character ECS client token using letters, digits, ., _, or -.
confirmLaunch	boolean	No	false	Explicit acknowledgement required for provider execution.
dryRun	boolean	No	false	Validates and emits a plan without reading credentials, contacting AWS, or billing.

Raw credential fields such as apiKey, password, accessKeyId, secretAccessKey, sessionToken, or credentials are rejected. Secret-like environment names are also rejected; configure sensitive values through ECS task-definition secret references instead.

Outputs

Output	Type	Condition	Description
status	string	Always	planned, launched, or failed.
idempotencyKey	string	Valid request	ECS client token used for reconciliation.
plan	object	Dry run	Region, identifiers, resource counts, CPU/memory, command count, and environment key names only.
taskArn	string	AWS acceptance or post-acceptance billing failure	Accepted ECS task ARN.
clusterArn	string	AWS acceptance or post-acceptance billing failure	Cluster ARN returned by ECS.
chargedCredits	number	Successful launch and ledger commit	Credits recorded for the authenticated workflow principal.
providerRequestId	string	Successful launch and ledger commit	Bounded AWS request identifier for operational reconciliation.
compensation	string	Billing failure after AWS acceptance	stop_requested or manual_reconciliation_required.
error	object	Failure	Safe code, message, retryability, and recovery guidance.

Outputs never contain AWS credentials, environment values, command content, provider exception text, or a full balance response.

IntegrationAccount Requirements

Bind exactly one AWS IntegrationAccount through ExecModuleConfig.authConfig:

Field	Requirement
status	Must be READY.
verified	Must be true.
apiKey SecureField	AWS access key ID.
password SecureField	AWS secret access key.

Use a dedicated least-privilege IAM principal. Its policy should be bounded to the approved cluster, task-definition family, task roles, subnets, security groups, and operations:

• ecs:RunTask
• ecs:StopTask for billing compensation
• iam:PassRole only for the task and execution roles referenced by the approved task definition

The current implementation supports an access-key pair. Temporary session credentials and caller-supplied raw credentials are not accepted.

Configuration

The only configuration field is awsAccount, an integrationAccount selector. Launch shape belongs in workflow input so every approved action is explicit and auditable.

The module bills the trusted authenticated workflow principal established by Security Fabric. It does not accept a caller-provided billing account ID.

Operations

Dry run

dryRun: true performs deterministic validation and emits a content-free plan. It does not resolve the IntegrationAccount, query credits, call AWS, or mutate the ledger.

Confirmed launch

A real launch performs these steps once:

1. Validate the complete request and require confirmLaunch: true.
2. Require Security Fabric production-deployment authorization and exact-action approval.
3. Resolve a verified READY AWS IntegrationAccount and read only its SecureFields.
4. Resolve the trusted workflow principal as the billing account.
5. Calculate the repository-standard Fargate launch credit cost and require sufficient funds.
6. Call ECS RunTask once with launchType: FARGATE, count: 1, and the supplied idempotencyKey as clientToken.
7. Require one returned task ARN and no ECS failure records.
8. Record the usage transaction for the authenticated principal.

The module does not automatically retry RunTask. AWS client-token idempotency protects deliberate reconciliation, but callers must check ECS before replaying an ambiguous request.

Billing compensation

If AWS accepts a task but ledger recording fails, the module calls StopTask for the returned task ARN. It reports whether the stop was requested. A failed compensation requires manual ECS and credit-ledger reconciliation; the module never claims a successful launch in that state.

Errors and Failure Modes

Error code	Meaning	Retryable	Recovery
VALIDATION_ERROR	A required value, identifier, bound, command, environment field, or credential-like input is invalid.	No	Correct the named input.
CONFIRMATION_REQUIRED	A real launch omitted confirmLaunch: true.	No	Review a dry run and obtain deployment approval.
INSUFFICIENT_CREDITS	The authenticated principal cannot cover the calculated launch cost.	No	Add credits or reduce task CPU/memory.
AWS_RUN_TASK_FAILED	The AWS SDK failed before a confirmed task response.	No automatic retry	Reconcile the client token in ECS, then decide whether to replay it.
AWS_RUN_TASK_UNCONFIRMED	AWS returned no accepted task ARN.	No automatic retry	Reconcile the client token before replay.
BILLING_FAILED_COMPENSATED	Ledger recording failed and StopTask was requested.	No	Verify that ECS stopped the task and reconcile billing.
BILLING_FAILED_RECONCILIATION_REQUIRED	Ledger recording and automatic stop both failed.	No	Stop the returned task ARN manually and reconcile the ledger.
FARGATE_EXECUTION_ERROR	An unexpected bounded execution failure occurred.	No automatic retry	Reconcile the client token before replay.

Security Fabric authorization or approval failures halt the protected launch instead of being converted into a normal module success/failure payload.

Example

Validate a private-subnet worker launch:

{
  "region": "us-west-2",
  "cluster": "production",
  "taskDefinition": "worker:42",
  "subnetIds": ["subnet-0123456789abcdef0"],
  "securityGroupIds": ["sg-0123456789abcdef0"],
  "assignPublicIp": false,
  "containerName": "worker",
  "command": ["java", "-jar", "worker.jar"],
  "environment": {
    "LOG_LEVEL": "info",
    "RELEASE_CHANNEL": "stable"
  },
  "cpu": 512,
  "memory": 1024,
  "idempotencyKey": "release-2026-08-14-001",
  "confirmLaunch": false,
  "dryRun": true
}

Expected result:

{
  "status": "planned",
  "idempotencyKey": "release-2026-08-14-001",
  "plan": {
    "region": "us-west-2",
    "cluster": "production",
    "taskDefinition": "worker:42",
    "subnetCount": 1,
    "securityGroupCount": 1,
    "assignPublicIp": false,
    "containerOverride": true,
    "commandEntries": 3,
    "environmentKeys": ["LOG_LEVEL", "RELEASE_CHANNEL"],
    "cpu": 512,
    "memory": 1024
  }
}

After approval, replay the same bounded input with confirmLaunch: true and dryRun: false.

Notes

• Pagination: not applicable; one execution submits exactly one task.
• Limits: subnet, security-group, command, environment, CPU, memory, identifier, and token bounds are validated before any side effect.
• Idempotency: the caller supplies the stable ECS clientToken. Reuse it only for the same logical request.
• Rate limits: the module performs one RunTask call and, only after a billing failure, one compensation StopTask call. It does not retry provider writes.
• API constraints: Fargate requires awsvpc networking and a compatible registered task definition. Container images cannot be overridden by RunTask; update and register a new task-definition revision instead.
• Destructive behavior: launching compute mutates cloud infrastructure and incurs external/provider cost. Compensation stops a task but cannot undo work that ran before the stop.
• Secret handling: use ECS task-definition secrets for application secrets. Workflow environment input is deliberately non-secret.
• Billing: the repository-standard BillingRateProvider calculates credits from requested CPU and memory. A successful output means both AWS acceptance and ledger recording completed.
• Provider verification boundary: deterministic tests cover validation, request mapping, credential isolation, safe errors, billing order, and compensation. A live AWS launch still requires an authorized account and reviewed cloud resources.
• Runtime boundary: merged source and published documentation do not update the deployed Workflow Studio catalog until the ValkyrAI backend release exposes version 2 through /v1/modules/metadata.

Related Documentation

• ExecModule catalog
• Integration Account Console
• Workflow Studio production guide
• Module authoring and testing