local run-task (run an ECS task definition locally)

cdkd local run-task <Stack/TaskDefinitionPath> is the ECS counterpart of cdkd local invoke. It takes an AWS::ECS::TaskDefinition defined in a CDK app and starts every container on the developer's Docker host — no AWS deploy needed.

Implementation Phase 1: synchronous run of one task, stream every container's stdout/stderr with a [<name>] prefix, propagate the essential container's exit code. Phase 2 (cdkd local start-service — ECS Service replicas + restart policy) and Phase 3 (Service Connect / Cloud Map cross-service discovery via --add-host DNS overlay) are implemented; ALB-emulated path/host-based routing remains deferred.

Requires Docker. The first run pulls the AWS-published amazon/amazon-ecs-local-container-endpoints:latest-amd64 sidecar (a small Go binary maintained by awslabs) plus each container's image.

local run-task target resolution

Same target-syntax rules as cdkd local invoke:

• CDK display path (MyStack/MyService/TaskDef) — preferred
• Stack-qualified logical id (MyStack:MyServiceTaskDefXYZ1234)
• Single-stack apps may omit the stack prefix (MyTaskDef)

Path matching is prefix-based: an L2 path like MyStack/MyService/TaskDef resolves to the synthesized L1 child (MyStack/MyService/TaskDef/Resource).

local run-task options

Plus the standard shared options: -a/--app, -c/--context, --profile, --role-arn, --region, --verbose, --output.

Networking model

For every task invocation cdkd:

1. Creates a fresh docker network cdkd-local-task-<random> (or --cluster <name>-task-<random>) with subnet 169.254.170.0/24.
2. Starts the AWS-published amazon/amazon-ecs-local-container-endpoints:latest-amd64 sidecar on the network at the well-known IP 169.254.170.2.
3. Starts every user container on the same network with --network-alias <container-name> so siblings resolve each other by their CFn ContainerDefinitions[].Name.
4. Injects per-container env vars: ECS_CONTAINER_METADATA_URI_V4=http://169.254.170.2/v4/<container-name> and (when --assume-task-role is set) AWS_CONTAINER_CREDENTIALS_RELATIVE_URI=/role/<task-role-arn>.

awsvpc network mode is mapped to bridge locally with a warn line — docker cannot emulate ENI-per-task. AWS SDK calls from inside the container still reach public AWS endpoints via the developer network.

ECR image resolution

ContainerDefinitions[].Image is parsed in three tiers:

1. Public images — public.ecr.aws/..., docker.io/..., nginx:latest, etc. → plain docker pull (subject to --no-pull).
2. Direct ECR URIs — <account>.dkr.ecr.<region>.<urlSuffix>/<repo>:<tag> and the other served registry-host forms listed below (flat string, no intrinsics) → pullEcrImage (STS check + ECR auth + docker pull). The host suffix is matched against the one the URI's region actually uses — one suffix per region prefix: commercial and us-gov-* → amazonaws.com, cn-* → amazonaws.com.cn, us-iso-* → c2s.ic.gov, us-isob-* → sc2s.sgov.gov, eu-isoe-* → cloud.adc-e.uk, us-isof-* → csp.hci.ic.gov, eusc-* → amazonaws.eu. A look-alike host whose suffix does not belong to that region is deliberately NOT treated as ECR. The FIPS (<account>.dkr.ecr-fips.<region>.<urlSuffix>) and dual-stack (<account>.dkr-ecr.<region>.on.aws, <account>.dkr-ecr-fips.<region>.on.aws) registry endpoints are RECOGNIZED as ECR (the grammar is unified with cdkd gc's — previously only the plain form matched here, so a genuine FIPS or dual-stack registry classified as a public image: anonymous pull, no docker login). The dual-stack forms carry the fixed on.aws suffix instead of the region's partition suffix, and a form spelled with the other's suffix is refused. Recognition is not yet a working pull for those three forms: ecrLogin authenticates against the PLAIN host (<account>.dkr.ecr.<region>.<urlSuffix>, which is what GetAuthorizationToken reports) while the pull targets the host the template names, and docker's credential store is keyed on the hostname verbatim — so the pull fails with no basic auth credentials. This is a known limitation; today only the plain form (in any casing) is end-to-end pull-capable. The case fold is unaffected, since an upper-cased plain host is reconciled to the same lower-case spelling on both sides. Every segment is matched case-INSENSITIVELY, since DNS is; docker accepts an upper-cased registry host but requires a lower-case repository path, and cdkd folds only the host. Cross-account / cross-region supported: cdkd builds the ECR client for the URI's region and (when --ecr-role-arn <arn> is passed) issues sts:AssumeRole to gain credentials in the target account. Without --ecr-role-arn, cdkd falls through to the caller's credentials (succeeds when an IAM resource policy grants the caller direct cross-account access).
3. CDK-asset images (ContainerImage.fromAsset / DockerImageAsset) → cdk.out/<stack>.assets.json lookup → docker build via the shared src/assets/docker-build.ts helper, tagged cdkd-local-run-task-<asset-hash>. An image URI is recognized as a CDK asset when it embeds a container-assets ECR repo — either the CDK-bootstrap repo cdk-<qualifier>-container-assets-<acct>-<region> (any qualifier, not only the hnb659fds default) or the cdkd-owned repo cdkd-container-assets-<acct>-<region> that cdkd deploy publishes into once a bootstrap marker exists; a migrated stack's rewritten template / --from-state state carries the latter, so both classify identically. Custom-named cdkd asset repos (cdkd bootstrap --container-repo <name>) are recognized too under --from-state: when a container's Image is an ECR-hosted URI whose repo component does not match the conventional shapes (recognized here by a THIRD, narrower host test than tier 2's — a literal .dkr.ecr. substring, so today it sees only the plain lower-case form and neither the FIPS / dual-stack endpoints nor a mixed-case host — a known limitation. A miss is a slow path, not a wrong pull: the image falls through to the tier-2 ECR-pull route), cdkd lazily reads the region's bootstrap marker from the state bucket and classifies the image as a CDK asset when its repo component equals the marker's containerRepo (best-effort — a missing/unreadable marker falls back to the prefix match, and without --from-state no marker read happens, so the image routes through the ECR-pull tier instead: correct, just slower).

For Fn::Sub / Fn::GetAtt shapes pointing at AWS pseudo parameters or a same-stack ECR repository (the typical ContainerImage.fromEcrRepository(repo) synthesis), two additional resolution tiers fire before the URI is fed to tier 2:

• Tier 1 — AWS pseudo-parameter substitution (no state needed): ${AWS::AccountId} → STS GetCallerIdentity (lazy, cached for the run); ${AWS::Region} → --region / AWS_REGION / AWS_DEFAULT_REGION; ${AWS::Partition} → derived from region (cn-* → aws-cn, us-gov-* → aws-us-gov, us-iso-* → aws-iso, us-isob-* → aws-iso-b, us-isof-* → aws-iso-f, eu-isoe-* → aws-iso-e, eusc-* → aws-eusc, else aws); ${AWS::URLSuffix} → matches partition. Substituted URI then routes through tier 2.
• Tier 2 — same-stack ECR Repository reference (state needed): when the Fn::Sub body contains ${<LogicalId>} against an AWS::ECR::Repository, or when the template uses Fn::GetAtt: [<Repo>, 'RepositoryUri'], cdkd needs the deployed physical repo name. Pass --from-state (the stack must have been deployed via cdkd deploy); cdkd loads state, substitutes the physical name, then routes through tier 2. Without --from-state the error message points back at this flag as the resolution path.

Env / Secrets substitution (--from-state)

ContainerDefinitions[].Environment[].Value and Secrets[].ValueFrom entries are commonly intrinsic-valued in real-world CDK ECS apps — table.tableName synthesizes as Ref, table.tableArn as Fn::GetAtt, ecs.Secret.fromSecretsManager(secret) as Ref against the secret (returns the deployed ARN), ecs.Secret.fromSsmParameter(p) as Fn::Join over pseudo parameters + a Ref to the parameter, etc. Without --from-state these intrinsics are silently dropped (matching cdkd local invoke v1 semantics) and the developer sees an empty env var or a missing secret.

cdkd local run-task --from-state substitutes every intrinsic-valued entry against cdkd's deployed S3 state plus AWS pseudo parameters:

Per-key best-effort: when a substitution can't be produced (state missing for a referenced logical ID, attribute not captured at deploy time, unsupported intrinsic), the env / secret entry is dropped and a per-key warning surfaces on the task's warnings line — the run-task invocation never aborts. State-load failures (no record, multi-region ambiguity without --stack-region, bucket resolution error) also degrade to warn-and-fall-back rather than hard-fail.

Resolved Secrets[].ValueFrom strings then flow into the standard SecretsManager / SSM resolver below.

Secrets / SSM parameter resolution

ContainerDefinitions[].Secrets[].ValueFrom entries are resolved once at startup via the AWS SDK (after any --from-state intrinsic substitution above). Three accepted shapes:

Resolution failures (NotFound / AccessDenied / network error / invalid ARN) hard-fail with the offending container + secret name. The user fixes their AWS creds / IAM policy and re-runs. (Mirrors the cdkd local invoke --from-state philosophy: explicit failure beats silently-empty.)

Secret names that are refused. When a secret's name is accepted, its VALUE reaches the container through the docker run spawn environment (a value-less -e KEY flag, so the plaintext never appears on the argv / /proc/<pid>/cmdline). The NAME decides whether the secret is forwarded at all: two name shapes are not passed to the container — no -e flag and no spawn-env entry, so the value reaches neither the argv nor the spawn environment:

• A name that collides with a variable the docker CLI itself reads — matched case-insensitively (Windows env lookups are). This is a fixed exact denylist (connection / TLS / behaviour, PATH / PATHEXT / HOME / USERPROFILE, the loader / trust / runtime vars, the ssh exec-helper set, and the AWS credential-helper vars docker-credential-ecr-login reads) plus the LD_ / DYLD_ / AWS_ENDPOINT_URL_ prefix families; the authoritative list is DOCKER_CLIENT_ENV_KEYS / DOCKER_CLIENT_ENV_PREFIXES in src/utils/docker-cmd.ts. Forwarding such a name would let a template-controlled secret NAME redirect the docker client itself (e.g. a secret named DOCKER_HOST pointing the client at a different daemon).
• A malformed name — empty, or containing = / NUL. A name containing = is the dangerous case: the OS parses the environ entry's name as everything before the first =, so a secret named PATH=/tmp/evil: would be parsed as PATH — a different variable than the collision check saw. An empty or NUL-bearing name simply cannot form a valid environment variable.

Each refusal is reported with a warn identifying the dropped secret(s) so the drop is never silent; rename the secret if the container needs the value.

Container start ordering — DependsOn

Cyclic dependencies → hard-error at discovery with the offending cycle named. Topological sort decides the start order; siblings with no dependsOn relation start in template order.

Volumes

Lifecycle + teardown

1. The first essential: true container (defaults to containers[0] when no container declares essential: false) drives the task.
2. When the essential container exits, cdkd docker stops every other container with a 10s grace then docker rm -f.
3. The metadata sidecar is docker rm -f'd and the docker network is removed.
4. cdkd exits with the essential container's exit code.

^C triggers the same teardown. Double-^C exits 130 immediately (skipping container cleanup — same pattern as cdkd local start-api).

--detach skips steps 1, 2, and 4. The sidecar and user containers stay running for the caller to manage. cdkd prints the network name on exit so you can docker ps --filter network=<name> to inspect.

--keep-running skips step 2 only. The network + sidecar are still torn down. Use to docker exec into a stopped container post-mortem.

local run-task exit codes

• 0 — essential container exited 0.
• N (non-zero) — essential container exited N (cdkd propagates the code).
• Various cdkd-side error codes (Docker missing, target not found, network creation failed, secret resolution failed, ...) follow the global handler's defaults (typically 1).

local run-task Phase 1 scope (out of scope, deferred)