Skip to content

ECS (Elastic Container Service)

Protocol: JSON 1.1 Endpoint: POST / + X-Amz-Target: AmazonEC2ContainerServiceV20141113.<Action>

ECS emulates clusters, task definitions, tasks, and services. In the default configuration tasks run as real Docker containers. Set mock: true (enabled automatically in tests) to run tasks as in-process stubs without Docker.

A value an enum-typed member does not have is rejected with InvalidParameterException rather than treated as absent. That matters more than it sounds: a launchType of EC22 silently ignored would fall through to Floci's default and place the task on Fargate, which is neither what the caller asked for nor what AWS answers.

Supported Operations

Clusters

Operation Description
CreateCluster Create a cluster (idempotent)
DescribeClusters Describe one or more clusters
ListClusters List cluster ARNs
UpdateCluster Update cluster settings
UpdateClusterSettings Update containerInsights and other settings
PutClusterCapacityProviders Associate capacity providers with a cluster
DeleteCluster Delete an empty cluster

A cluster round-trips what it was created with: settings, tags, configuration, serviceConnectDefaults, capacityProviders and defaultCapacityProviderStrategy are all accepted on CreateCluster and returned as sent. UpdateCluster replaces only the members the request named, leaving the ones it omits alone; UpdateClusterSettings replaces settings outright.

DescribeClusters returns settings, tags, statistics, attachments and configuration only when include asks for them, one of SETTINGS, TAGS, STATISTICS, ATTACHMENTS and CONFIGURATIONS; any other value is rejected. A member that was asked for is returned even when it is empty, so a client can tell an empty answer from a withheld one. STATISTICS reports the eight documented counts split by launch type (runningEC2TasksCount, runningFargateTasksCount, pendingEC2TasksCount, pendingFargateTasksCount, activeEC2ServiceCount, activeFargateServiceCount, drainingEC2ServiceCount, drainingFargateServiceCount) as name/value strings. The API reference spells one of those names RunningFargateTasksCount; Floci follows the wire, which is lower camel case like the other seven. The reference also describes pendingTasksCount as tasks in the PENDING state, but ECS counts a task as pending from RunTask until it runs, so Floci's count and the two pending statistics include a PROVISIONING task too. ATTACHMENTS is always an empty list, because Floci creates no managed scaling policies to attach.

DescribeClusters reports a cluster it cannot resolve as a MISSING entry in failures rather than dropping it, as DescribeServices and DescribeTasks do. ListClusters pages with maxResults (1 to 100) and nextToken, returning up to 100 ARNs when the request names neither.

DeleteCluster only deletes an empty cluster, and says which way it is not empty: ClusterContainsServicesException while a service is still ACTIVE, ClusterContainsContainerInstancesException while a container instance is still registered, and ClusterContainsTasksException while a task is still running. Delete the services, deregister the instances and stop the tasks first, as on AWS.

Task Definitions

Operation Description
RegisterTaskDefinition Register a new revision of a task definition
DescribeTaskDefinition Describe a task definition by family:revision or ARN
ListTaskDefinitions List task definition ARNs
ListTaskDefinitionFamilies List task definition family names
DeregisterTaskDefinition Mark a revision INACTIVE
DeleteTaskDefinitions Delete one or more task definitions

A task definition round-trips whole. Members Floci acts on are modelled (ephemeralStorage, pidMode, ipcMode, runtimePlatform, and at container level dependsOn, startTimeout, stopTimeout, user, workingDirectory, readonlyRootFilesystem, environmentFiles, dockerLabels, repositoryCredentials and the rest); everything else, such as proxyConfiguration, ulimits, resourceRequirements, systemControls and placement constraints, is kept verbatim and returned as registered. A client that reads back what it wrote (Terraform, or a deploy tool verifying its own RegisterTaskDefinition) sees no drift. A task runs its images for the architecture its runtimePlatform.cpuArchitecture names (X86_64 as linux/amd64, ARM64 as linux/arm64): a local image built for that platform is used as is, a pull asks the registry for that platform, and the container is created for it, so an X86_64 task runs under emulation on an arm64 Docker host. Without a cpuArchitecture a task runs on the Docker host's own architecture. An AWS::ECS::TaskDefinition in a CloudFormation template carries its containers' LinuxParameters into the same place, read as the ECS handler reads them (see CloudFormation), so they are returned in the API's shape and checked against the Fargate rules below exactly as if the task definition had been registered through the API. As CloudFormation's handler does, it sends the devices and tmpfs lists empty when the template has none.

The round trip reaches inside the members Floci does parse. A port mapping keeps its name, appProtocol and containerPortRange, which is what a service's serviceConnectConfiguration and vpcLatticeConfigurations reference by name, and a volume keeps the configurations Floci backs with nothing: dockerVolumeConfiguration, fsxWindowsFileServerVolumeConfiguration, s3filesVolumeConfiguration and configuredAtLaunch.

compatibilities is derived from the definition rather than echoed from requiresCompatibilities: ECS reports the launch types a definition actually works on, so an awsvpc definition with a valid Fargate size pair and no Fargate-unsupported parameters comes back as ["EC2", "FARGATE"] even when it never asked for FARGATE. EXTERNAL is added for any network mode other than awsvpc, which ECS Anywhere instances do not support. The derivation runs Fargate's own registration rules, so it can never disagree with what requiresCompatibilities: ["FARGATE"] would have accepted.

requiresAttributes names the container instance capabilities the definition needs for EC2 placement. ECS derives these from the container agent's capability model, which AWS does not publish in full, so Floci derives the subset whose names appear verbatim in the AWS documentation: the base com.amazonaws.ecs.capability.docker-remote-api.1.18, ecs.capability.task-eni for awsvpc, com.amazonaws.ecs.capability.task-iam-role (or ...task-iam-role-network-host under host networking) for a taskRoleArn, com.amazonaws.ecs.capability.logging-driver.<driver> per container log driver, com.amazonaws.ecs.capability.ecr-auth for an ECR image, and com.amazonaws.ecs.capability.privileged-container. Capabilities outside that set are not reported.

A revision goes ACTIVE, then INACTIVE on DeregisterTaskDefinition (which stamps deregisteredAt), then DELETE_IN_PROGRESS on DeleteTaskDefinitions (which stamps deleteRequestedAt). Deleting a revision that has not been deregistered is refused, as is a reference that names only the family: DeleteTaskDefinitions takes a revision, at most 10 per call. A deleted revision is not dropped, because AWS keeps describing it and the tasks already on it keep running; it just cannot start anything new, so RunTask, CreateService and UpdateService refuse it.

ListTaskDefinitions lists only ACTIVE revisions unless another status is asked for, orders them lexicographically by family and then numerically by revision (sort: DESC reverses it, so revision 11 sorts after revision 2 rather than before it), and pages with maxResults and nextToken.

ListTaskDefinitionFamilies filters on familyPrefix and on status, where ACTIVE keeps the families with at least one ACTIVE revision, INACTIVE the families with none, and ALL (the default) keeps both. It pages with maxResults and nextToken the same way.

At launch, a container's dependsOn decides the start order, and a COMPLETE, SUCCESS or HEALTHY condition holds the dependent container until the dependency gets there. The wait is bounded by the dependent container's startTimeout, defaulting to 60 seconds rather than AWS's longer agent default, because the service scheduler starts a service's tasks on its own thread, which a long wait holds up. A container's cpu becomes its CPU shares, its memory its hard limit, and a container without a memory of its own is capped at the task's; the task's cpu becomes a CPU quota. stopTimeout is the grace period the container gets on teardown; a container that does not ask for one gets 5 seconds rather than AWS's 30, because StopTask here answers synchronously and most containers ignore SIGTERM as PID 1. A container still running when its grace period is up is killed, so its exit code is always reported.

A container's linuxParameters reach Docker as ECS documents them. initProcessEnabled runs an init process as PID 1 (docker run --init) that forwards signals and reaps orphaned processes; capabilities are added and dropped (--cap-add, --cap-drop); each of devices is exposed (--device), with read, write and mknod when it names no permissions and at its hostPath when it names no containerPath; sharedMemorySize sizes /dev/shm in MiB (--shm-size); each of tmpfs is mounted at its containerPath with its mountOptions and size in MiB (--tmpfs); maxSwap caps memory plus swap at the container's hard limit plus that many MiB (--memory-swap, so 0 means no swap), and swappiness (--memory-swappiness) goes with it: as on ECS, RegisterTaskDefinition refuses a maxSwap without a swappiness, and drops a swappiness without maxSwap from the definition it stores. A container with no hard limit, neither its own memory nor the task's, gets no swap limit, because Docker cannot limit swap without one, but still its swappiness. A daemon on cgroup v2 discards swappiness, as Amazon Linux 2023 does. Inside a task behind a security group, NET_ADMIN and NET_RAW stay dropped whatever capabilities adds, because the group is enforced in the network namespace the task's containers share.

A device hands the container the host's hardware, so Floci refuses one as it refuses a host volume: by default, unless its hostPath is under floci.services.ecs.host-volume-roots (FLOCI_SERVICES_ECS_HOST_VOLUME_ROOTS) or floci.services.ecs.allow-unsafe-host-volumes is set, at RegisterTaskDefinition after AWS's own checks and again at launch. RegisterTaskDefinition reads the members as AWS does: a member of the wrong JSON type is refused with the deserializer's message (STRING_VALUE cannot be converted to Integer, Unexpected value type in payload, ...) before any other check, walking the shapes vendored in src/main/resources/aws/ecs-request-shapes.json (generated by tools/aws/regen_ecs_shapes.py from the botocore release pinned in tools/aws/requirements.txt), a number is stored as an integer with its fraction dropped and its range capped to 32 bits, a boolean may come as text in any case, and a null member is left out.

firelensConfiguration is stored and returned the same way. RegisterTaskDefinition rejects a missing or unsupported type (fluentd and fluentbit only), and a task using awsfirelens must name exactly one router: a task definition with two FireLens routers, or a router publishing port 24224, is rejected at launch. A fluentbit or fluentd FireLens container is acted on at launch: Floci generates the router config (unix socket input, TCP forward on bridge/awsvpc, ECS metadata, optional include of a config-file-type=file or s3 extra config, and one output per awsfirelens container), starts that router first, and points application containers with logDriver: awsfirelens at the generated unix socket. A container with logDriver: awslogs streams to CloudWatch Logs through Floci, in the awslogs-group log group and the awslogs-region region (the task's region when it is not set). The log stream is <awslogs-stream-prefix>/<container-name>/<task-id>, or the Docker container ID when no prefix is set, as on AWS. Floci creates the log group when it does not exist, even without awslogs-create-group. A container with no logConfiguration, or with another log driver, sends nothing to CloudWatch Logs; its output still appears in Floci's own log. An [OUTPUT] for an AWS destination whose plugin reads a URL from endpoint (s3, cloudwatch, firehose) also gets Endpoint set to Floci's container-reachable base URL. The Fluent Bit AWS plugins take a custom endpoint only from their own configuration and ignore the AWS_ENDPOINT_URL injected into the container, so without it the router would ship logs to the real service. An endpoint set in the task definition's log options is never overwritten, so aiming one output at real AWS still works, and outputs declared in an @INCLUDEd or config-file-type=s3 config are not visible to Floci and keep whatever endpoint they were written with. The upstream C plugins (cloudwatch_logs, kinesis_firehose, kinesis_streams) are left alone instead. They hand endpoint to getaddrinfo as a bare host name rather than parsing it as a URL, and they always dial TLS, so Floci's http://host:port base URL fails there as Misformatted domain name and a bare host fails certificate verification; no output-level switch disables either. On the aws-for-fluent-bit 3.x line these plugins also honour a separate port (undocumented for kinesis_firehose and cloudwatch_logs, but it works), so an output can be aimed at Floci's port, but it still cannot complete the TLS handshake. Those outputs go wherever the task definition points them. An injected http:// endpoint also gets tls Off. Fluent Bit 1.9 (the aws-for-fluent-bit 2.x and :latest line) still calls flb_tls_session_create on HTTP S3 and SIGSEGVs on a NULL TLS context; the scheme alone is not enough. A tls the task definition already set is left alone. The TCP forward listens on 0.0.0.0 rather than AWS's awsvpc 127.0.0.1 because Floci shares a network namespace only when security-group enforcement or a shared task network gives an awsvpc task one. Such a task gets FLUENT_HOST=127.0.0.1, the value the ECS agent sets for awsvpc. In every other case, the injected FLUENT_HOST (the router's container IP) must be reachable. Fluent Bit config is written to /fluent-bit/etc/fluent-bit.conf. Fluentd config is written to /fluentd/etc/fluent.conf and uses @type (not Name) for output plugins; Floci does not inject an endpoint into Fluentd outputs. FireLens uses a bounded socket-volume name derived from the complete deployment and task identity, while its Docker labels retain the full configured resource namespace. The inspected host socket path must fit Linux's 107-byte Unix socket pathname limit. An unusually long Docker data root can still exceed that limit; launch then fails before creating containers and retains any failed volume cleanup for retry. Operator-named volumes are unaffected.

FireLens configuration archive uploads retry transient Docker connection failures up to six attempts, with exponential backoff starting at 500 ms. Each attempt sends the complete prebuilt archive through a fresh byte-backed stream, without a streaming pipe or writer thread. The router and application containers start only after the upload succeeds; permanent errors or exhausted retries follow the existing task-launch cleanup path. config-file-type=s3 follows where ECS itself draws the line. RegisterTaskDefinition rejects it for a Fargate-compatible task definition, with Fargate launch type does not support FirelensConfiguration config file from 's3', and rejects a config-file-value that is not an S3 object ARN with Invalid arn syntax. A Fargate task can still take its config from S3 the way AWS documents, by giving the aws-for-fluent-bit init process its aws_fluent_bit_init_s3_* environment variables. ECS never inspects those and Floci passes them through, so that registration is accepted here too; the init process reads the task metadata endpoint before downloading, and Floci serves one (see Task metadata endpoint). Floci does not validate a task definition's compatibilities / requiresCompatibilities against RunTask launchType; a Fargate-compatible definition can still be run with launchType=EC2 (and the reverse). On an EC2-compatible task definition Floci reads the object from its own S3, writes it to the fixed external.conf path next to the generated config (/fluent-bit/etc/external.conf or /fluentd/etc/external.conf), and includes it from there, matching the paths the ECS agent uses. The object is read before any container is created, so a missing bucket or key stops the task with the agent's reason, Unable to download firelens s3 config file: unable to download s3 config <key> from bucket <bucket>: <detail>, instead of leaking a started router. Shared network namespaces (AppConfig agent on 127.0.0.1:2772) are not implemented.

Container volumesFrom entries are also stored and returned. In Docker mode, source containers are launched before their consumers and their declared volumes are inherited with the requested read-only or read-write access mode. Startup ordering also respects FireLens router dependencies; cycles involving both volume inheritance and log routing are rejected before containers start.

Tasks

Operation Description
RunTask Launch one or more task instances
StartTask Start a task on specific container instances
StopTask Stop a running task
DescribeTasks Describe one or more tasks
ListTasks List task ARNs (filterable by cluster, family, service, status)
UpdateTaskProtection Set scale-in protection for tasks
GetTaskProtection Get current task protection state
ExecuteCommand Open an ECS Exec session into a container (see ECS Exec)

Fargate

A task definition that declares FARGATE in requiresCompatibilities is held to Fargate's rules at registration:

  • awsvpc network mode.
  • A task-level cpu and memory forming one of the documented pairs, from 256 CPU units through 32768 (the 32 vCPU tier offers only 60 GB, 120 GB and 244 GB), in CPU units or the 1 vCPU and 1 GB string forms. Windows rules out the sub-vCPU sizes.
  • An ephemeralStorage.sizeInGiB between 21 and 200.
  • None of the parameters that are not valid in a Fargate task: disableNetworking, dnsSearchDomains, dnsServers, dockerSecurityOptions, extraHosts, a GPU resourceRequirements entry, ipcMode, links, placementConstraints, privileged, linuxParameters.devices (an empty list passes), linuxParameters.sharedMemorySize, linuxParameters.maxSwap, linuxParameters.swappiness, a linuxParameters.capabilities.add entry other than SYS_PTRACE as written (sys_ptrace is refused by name), a pidMode other than task, or a host volume with a sourcePath. All of them are accepted on an EC2-compatible definition. The linuxParameters among them are checked in that order, with AWS's messages.
  • Whatever the launch type, in this order and with AWS's messages: every capabilities entry one of the names the KernelCapabilities reference lists, in any case and without a CAP_ prefix (Unrecognized Linux capabilities in add: [CAP_NET_ADMIN]); every device with a hostPath, and only read, write and mknod as permissions, as written; every tmpfs mount with a containerPath, a size above zero and mountOptions the Tmpfs reference lists, as written and with any =value; a sharedMemorySize above zero; and a maxSwap only with a swappiness, of zero or more, with a swappiness from 0 to 100. These come before the Fargate rules. The stored capabilities always carry both an add and a drop list, as on AWS.
  • A dependsOn graph that names only containers of the same task definition and has no cycle.

A launched Fargate task reports what AWS reports: platformVersion (with LATEST resolved to a concrete version, as AWS resolves it) and platformFamily (Linux, or the Windows Server family from the task definition's runtimePlatform.operatingSystemFamily), connectivity and connectivityAt, healthStatus, stopCode, version, availabilityZone, attributes with ecs.cpu-architecture, pullStartedAt / pullStoppedAt / stoppingAt / executionStoppedAt, ephemeralStorage and fargateEphemeralStorage, and enableExecuteCommand. overrides is always present with one containerOverrides entry per container, carrying whatever the request overrode, which is how AWS answers a task nobody overrode. group defaults to family:<family> for a RunTask and is service:<name> for a service's tasks. A container that asked for no CPU units reports "cpu": "0", as on AWS.

A task's attachments entry is an ElasticNetworkInterface carrying subnetId, networkInterfaceId, macAddress, privateDnsName and privateIPv4Address. DescribeTasks and DescribeServices report tags only when the request asks for them with include: ["TAGS"], as DescribeTaskDefinition already did. A task DescribeTasks cannot resolve comes back as a MISSING entry in failures, which is what the TasksRunning and TasksStopped waiters treat as terminal.

A created service reports the documented defaults: propagateTags is NONE and healthCheckGracePeriodSeconds is 0 when the request sets neither. A role is accepted only on a load-balanced service whose task definition does not use awsvpc, which is the only case AWS permits it in.

A Fargate service retains its requested platformVersion, defaulting to LATEST when omitted. CreateService, UpdateService and DescribeServices return that setting, while its tasks, deployments and service revisions report the resolved version (1.4.0 for LATEST). Updating between LATEST and that concrete version changes the service setting without rolling the deployment. Rollback restores the requested version from the successful revision. Older persisted revisions without that setting restore their stored platform version. EC2 services omit the platform members.

A described service always carries events and taskSets, empty list and all, so a client can tell an empty answer from a member Floci never wrote. taskSets holds the service's task sets, the same ones DescribeTaskSets returns, which is where a blue/green deploy tool reads them from. events is derived from the service's current state rather than replayed from a rollout, the same way deployments is: a service that has converged reports the one event tools poll for, (service <name>) has reached a steady state., with an id stable across calls; one still converging reports none. Each deployments entry carries the placement it runs under, its launchType or capacityProviderStrategy, platformVersion, platformFamily and networkConfiguration, not only its id and counts.

RunTask places at most 10 tasks per call and rejects propagateTags: SERVICE, which is a service-only option; TASK_DEFINITION copies the task definition's tags onto each task. StartTask requires the containerInstances it places onto, at most 10 of them.

RunTask and StartTask answer before the task's images are pulled, as AWS does. An awsvpc task comes back PROVISIONING with its ENI attachment PRECREATED, and any other task PENDING, each with its containers PENDING. The task then moves to RUNNING in the background. A launch that fails, on an image that cannot be pulled for example, shows in DescribeTasks as STOPPED with stopCode TaskFailedToStart. A StopTask on a task still launching answers with the task's status unchanged and desiredStatus STOPPED; the task then stops without its containers ever starting, or as soon as they have.

ListTasks filters by cluster, family, desiredStatus, launchType, containerInstance, serviceName and startedBy, and pages with maxResults and nextToken (100 per page by default). The default filter is a desired status of RUNNING, so a listing that has not asked for stopped tasks does not get them, PENDING matches nothing (ECS never sets that desired status), and startedBy has to be the only filter in the request.

On UpdateService, the changes that start new tasks roll the deployment: the task definition, the network configuration, the load balancers, the service registries, the Service Connect configuration, platformVersion and forceNewDeployment. The ones AWS documents as not triggering a deployment (desiredCount, deploymentConfiguration, enableExecuteCommand, enableECSManagedTags, propagateTags, healthCheckGracePeriodSeconds, availabilityZoneRebalancing, the capacity provider strategy and the placement members) are applied without rolling anything. An update replaces only the members it names: one that sends placementStrategy alone leaves a placementConstraints stored earlier in place, and an empty array clears a member the way AWS clears it.

When a service replaces or stops a task in Docker mode, the task remains STOPPING until its containers are removed. The service scheduler runs these Docker stops in the background, up to eight at a time, so a container waiting out its stopTimeout does not hold up the reconciliation of other tasks and services; a DAEMON replacement still starts only once the task it replaces is STOPPED. A failed Docker removal is retried on later reconciliation ticks, so the task is not reported as STOPPED while its container may still be serving. StopTask answers once its stop has landed, and on a task the scheduler is already stopping it waits for that stop rather than starting a second one.

In Docker mode, an essential container exiting stops the other containers in its task, including when it exits successfully. An omitted essential flag defaults to true. Floci reports EssentialContainerExited and Essential container in task exited, retaining each container's exit code. A nonessential container's exit updates that container to STOPPED without stopping its still-running siblings. Remaining containers are stopped through the same background stop and retry path described above. When an essential exit initiates the stop, Floci deregisters its load-balancer targets but stops the siblings without waiting for the service-replacement drain period. Graceful service replacements retain their configured drain delay.

Every awsvpc task gets a real ENI in the subnet it asked for, in Docker and in mock mode alike, and reports it as an attachments entry with its networkInterfaceId, privateIPv4Address and subnetId; the task's containers report the same interface in networkInterfaces. A subnet that does not exist fails the request rather than being ignored. While the task runs, ec2 DescribeNetworkInterfaces reports that ENI as in-use and refuses to delete it, so it never answers a search for a free interface; it carries no EC2 attachment, every member of one naming an instance that a task does not have. The ECS attachment is reported as DELETED once the task stops, and the ENI is released. Security-group enforcement (FLOCI_NETWORK_SECURITY_GROUP_ENFORCEMENT_ENABLED) adds packet filtering on top of the ENI; it is not needed for the ENI itself.

With Docker-backed VPC networks (FLOCI_SERVICES_EC2_VPC_NETWORKS_ENABLED=true and FLOCI_SERVICES_EC2_MOCK=false), a Docker-mode task also joins its VPC's Docker network at the ENI address, so an EC2 instance, a VpcConfig Lambda function or any other container on that network reaches the task at the privateIPv4Address that DescribeTasks reports. AWS gives the whole task that one address; Floci gives it to one container, the first in the task definition that maps a port, else the first, and the task's other containers do not answer at it. A task with a shared task network gives it to the helper holding its namespace instead, so every container answers at it. A task in a security-group protected namespace keeps that namespace and does not join the VPC network.

Capacity providers

capacityProviderStrategy is honoured on RunTask and CreateService, including the built-in FARGATE and FARGATE_SPOT providers. Tasks are spread the way ECS spreads them: the single entry that declares a base is filled first, then the rest are split by weight, with the remainder of the integer split going to the heaviest entries. A strategy and a launchType in the same request are rejected, as is an unknown provider or a second base, and a cluster's defaultCapacityProviderStrategy applies when a request carries neither. The documented bounds are enforced: at most 20 providers in a strategy, a weight of 0 to 1,000 and a base of 0 to 100,000. A provider of weight 0 places nothing beyond its base, so a strategy naming several providers that all weigh 0 is rejected; a lone provider of weight 0 still places the tasks, since the request named no alternative.

A task placed through a provider reports capacityProviderName and the launchType that provider resolves to. A service reports one or the other: DescribeServices omits launchType for a service created with a strategy, and omits capacityProviderStrategy for one created with a launch type, which is what AWS documents for the Service shape.

Service reconciliation calculates the provider split for the desired task count and fills deficits using the current deployment's running tasks. Scale-out and stopped-task replacement account for existing provider counts; tasks from a previous deployment do not cover the new deployment's targets.

With no launch type, no strategy and no cluster default, a task keeps Floci's FARGATE default: a local cluster has no container instances, so an EC2 default would have nowhere to place it.

A REPLICA service task placed on the EC2 launch type, or on a capacity provider other than FARGATE and FARGATE_SPOT, runs on an ACTIVE container instance of the cluster: the one running the fewest tasks, among the instances registered for that capacity provider when any are, otherwise among those registered for none. DescribeTasks then reports its containerInstanceArn. A cluster with no container instance to offer still runs the task, without one, where AWS would leave it unplaced. Placement constraints and strategies are not evaluated.

Task metadata endpoint

Floci serves the task metadata endpoint version 4 and injects ECS_CONTAINER_METADATA_URI_V4 into every container it launches. AWS serves it on the link-local address 169.254.170.2, which a local container cannot be given, so Floci serves the same paths on its own port; applications and the AWS SDKs read the environment variable rather than the address, so they work unchanged.

Path Returns
/v4/{id} The container's metadata
/v4/{id}/task The task's metadata, including every container
/v4/{id}/taskWithTags The task's metadata with its tags and its container instance's (EC2 only)
/v4/{id}/stats The container's Docker stats
/v4/{id}/task/stats The Docker stats of every container in the task, keyed by Docker id

The {id} is minted per container at launch, as the ECS agent mints it. The task document carries Cluster, TaskARN, Family, Revision, the statuses, Limits (CPU in vCPUs), the pull timestamps, AvailabilityZone, LaunchType, ServiceName for a service's task, VPCID for an EC2 task, and, for Fargate, ClockDrift and EphemeralStorageMetrics. Floci has no clock drift to report and does not meter the disk, so those two report a synchronized clock and zero usage.

An awsvpc container's Networks object describes the task ENI and the subnet it sits in: NetworkMode, IPv4Addresses, AttachmentIndex, MACAddress, PrivateDNSName, IPv4SubnetCIDRBlock, SubnetGatewayIpv4Address, DomainNameServers and DomainNameSearchList. A local ENI has no DHCP option set behind it, so the gateway is derived as the first address of the subnet's CIDR, the resolver as the third address of the VPC's, and the search domain from the region, the way a real VPC assigns them.

The stats paths read the Docker daemon when the request arrives, so they return the same ContainerStats document AWS returns, plus the network_rate_stats the ECS agent adds. Docker reports cumulative counters only, so the rates are taken across two consecutive samples: as on Fargate, that means a container has to have run for about a second before its stats are there. A container Floci has no running Docker container for reports an empty document instead, and one sampled only once reports its stats without network_rate_stats: the path exists for every container in the task, whether or not the daemon can measure it.

/v4/{id}/task/stats samples the task's containers in one pass, with every stream open at once, rather than one after another. A sidecar polls that path for network metrics, so the response costs about the single collection tick one container costs however many containers the task has.

taskWithTags is the container agent's path, so it answers for an EC2 task and 404s for a Fargate one, as on AWS. A container's CreatedAt, StartedAt and FinishedAt are Docker's own for that container, read when it starts and again when it stops; a task that never reached a daemon, which means mock: true or one restored from storage, reports the task's timestamps instead.

ECS Exec

ExecuteCommand opens a real shell in a task's container. The session must be interactive, which is the only mode ECS supports. The task must belong to the cluster the request names, must be RUNNING, must have been run with enableExecuteCommand, and must have a container behind it, which means Docker mode: a mock-mode task reports the ExecuteCommandAgent as running but has no runtime to exec into, and ExecuteCommand answers TargetNotConnectedException.

The response carries a session with a streamUrl pointing at Floci's own data channel and a single-use tokenValue, so the AWS CLI works as documented. The channel URL uses the incoming HTTP request's hostname, port and application base path instead of Floci's configured internal hostname. HTTP endpoints produce ws:// URLs and HTTPS endpoints produce wss:// URLs. Calls made inside Floci without an HTTP request retain the configured base URL. Reverse proxies must expose the data channel under the same endpoint and configure trusted forwarding on the server if they terminate TLS or rewrite the application base path:

aws ecs execute-command --cluster my-cluster --task <task-arn> \
  --container app --interactive --command "/bin/sh" \
  --endpoint-url $AWS_ENDPOINT_URL

Floci plays the SSM agent's half of the Session Manager protocol on that channel (the binary AgentMessage framing, the handshake, sequenced acknowledgements and terminal resizes) and bridges it to a docker exec in the container. Output is forwarded as bytes, including leading control bytes and invalid UTF-8, without interpreting the process's PTY output as Docker multiplexed headers. Deliberate limits:

  • The session runs as root (uid 0) whatever the container definition's user, as the real ECS Exec agent does.
  • The command runs through /bin/sh -c, so an image without a shell cannot be exec'd into.
  • Sessions are in memory, single use, and expire after five minutes if nobody connects.
  • ExecuteCommand logging (the executeCommandConfiguration on a cluster, which sends session transcripts to S3 or CloudWatch) is not implemented.

Services

Operation Description
CreateService Create a long-running service
UpdateService Update desired count, task definition, or deployment config
DeleteService Delete a service (supports force)
DescribeServices Describe one or more services (includes deployments, see below)
ListServices List service ARNs in a cluster
ListServicesByNamespace List the Region's services whose Service Connect configuration joined a Cloud Map namespace, given by name or ARN (a service with no namespace of its own joins its cluster's default); pages with maxResults and nextToken

ListServices filters on launchType and schedulingStrategy as well as cluster, and pages with maxResults and nextToken. Like ListServicesByNamespace, and unlike every other ECS listing, which pages a hundred at a time, a request that names no maxResults gets ten ARNs and a nextToken. A service joins the namespace its Service Connect configuration names, or its cluster's default when it names none, at the time the configuration is set: a later change to the cluster default does not move it.

With persistent storage, services survive a restart but their tasks do not: task state is held in memory. The service scheduler starts at boot, so within a few seconds of startup every persisted service is brought back to its desiredCount, re-registering load balancer targets and Cloud Map instances as its tasks start, without waiting for an ECS request.

Before shared container teardown, Floci pauses ECS reconciliation and waits for its current pass to finish. It also interrupts and waits for background task launches before other services retire their credentials or networking. A state reset starts fresh executors after the old tasks have been drained.

Service deployments

An ACTIVE service reports exactly one PRIMARY entry in services[].deployments, synthesized from the service's current state rather than tracked as a rollout. This is what AWS's ServicesStable waiter accepts on, so aws ecs wait services-stable, the SDK waiters, and Terraform's aws_ecs_service all converge normally. A deleted (INACTIVE) service reports an empty list.

rolloutState is COMPLETED once runningCount reaches desiredCount, and IN_PROGRESS before that. The deployment id is derived from the service ARN and its task definition, so it is stable across calls and across restarts, and rolls over when the task definition changes. createdAt tracks the deployment rather than the service: it is the service's creation time until a task-definition change starts a new deployment, and moves with it thereafter.

Known differences from AWS:

  • There is never a second ACTIVE deployment draining alongside the PRIMARY one. The running tasks are rolled onto a changed task definition (replacements on the new revision normally start first, then the stale tasks are drained, one reconciler tick apart), but the deployments list reports only the single PRIMARY throughout. A Docker-backed REPLICA service with an explicit minimumHealthyPercent: 0 stops stale tasks first when their fixed published ports conflict with the replacement's ports. See stable-port replacement below.
  • deployments is reported for every service. AWS omits it for services that use the CODE_DEPLOY or EXTERNAL deployment controller; Floci records and echoes deploymentController (along with schedulingStrategy and availabilityZoneRebalancing; AWS defaults ECS / REPLICA / ENABLED on create) but still synthesises the deployments list regardless of the controller type.
  • DAEMON scheduling runs exactly one task per ACTIVE container instance and derives desiredCount from that count; it is rejected for the Fargate launch type and for the CODE_DEPLOY / EXTERNAL controllers, as on AWS. Placement constraints are not evaluated.
  • pendingCount is always 0, matching the top-level service field.
  • forceNewDeployment (with an unchanged task definition) mints a new deployment id and rolls the running tasks: a replacement on the new deployment normally starts first, then the task from the previous deployment is drained one reconciler tick later. The deployments list still reports a single PRIMARY throughout.
  • A task of a service with loadBalancers that runs on a container instance is registered in a target group of target type instance as ECS registers it on AWS: the container instance's ec2InstanceId on the container's host port. The load balancer and its health checks reach that instance port at the task's container. When another task on the same instance already holds the host port, as when Floci runs in Docker and publishes no host ports so the tasks share a container port, the target gets a port from the ECS agent's dynamic range (32768 to 60999) instead, and networkBindings keeps reporting the published port. The container's other published host ports are taken on the instance too where free, so a target group health check on one of them reaches the container. The task holds these ports until it is STOPPED, through its deregistration delay, so a replacement on the same instance gets other ones. An ip target group, or a task with no container instance, gets the container's own address.
  • A rolling deployment of a service with loadBalancers stops a stale task only once every replacement's targets report healthy. A replacement that never turns healthy holds the deployment.
  • A stale or scaled-in task of a service with loadBalancers stays DEACTIVATING, its containers still running, for the longest deregistration_delay.timeout_seconds of its target groups (300 seconds by default), then turns STOPPING on the next reconciler tick. A StopTask call does not wait. The target leaves its target group at once rather than reporting draining.
  • updatedAt starts at createdAt and advances when the deployment status changes.
  • deploymentConfiguration is stored and reported as given. The deployment circuit breaker counts tasks that fail to start and moves a deployment through STOP_REQUESTED to STOPPED, or, with rollback enabled, through ROLLBACK_IN_PROGRESS to ROLLBACK_SUCCESSFUL or ROLLBACK_FAILED. A rollback restores the most recent successful service revision while retaining the service's current desiredCount. DescribeServiceDeployments reports the rollback target and reason under rollback, and configured and triggered alarm names under alarms. Enabled CloudWatch deployment alarms are also checked during reconciliation and fail the deployment when any configured alarm is in ALARM. Floci stops monitoring alarms when tasks converge; AWS continues monitoring through the deployment bake time. healthCheckGracePeriodSeconds, serviceRegistries and placement constraints and strategies are stored and reported but are not enforced; task placement does not evaluate constraints.
  • StopServiceDeployment is not implemented.

ECS EventBridge events

Floci publishes AWS-shaped lifecycle events to the default EventBridge bus (source: aws.ecs). Rules matching aws.ecs fire from ECS activity, in both docker and mock mode.

detail-type When Key detail fields
ECS Task State Change a task starts or stops lastStatus, desiredStatus, taskDefinitionArn, group, startedBy, stoppedReason, containers[].exitCode
ECS Deployment State Change a service deployment starts, fails, rolls back, or reaches steady state eventType (ERROR on failure, otherwise INFO), eventName, deploymentId

eventName is one of SERVICE_DEPLOYMENT_STARTED, SERVICE_DEPLOYMENT_IN_PROGRESS, SERVICE_DEPLOYMENT_COMPLETED, SERVICE_DEPLOYMENT_FAILED.

Known differences from AWS:

  • The task phase ladder is synthesized. Floci's task model only occupies PENDING, RUNNING and STOPPED, but a start emits PROVISIONING -> PENDING -> ACTIVATING -> RUNNING and a stop emits DEACTIVATING -> STOPPING -> DEPROVISIONING -> STOPPED, one ECS Task State Change per phase, so rules that filter on detail.lastStatus behave as on AWS.
  • SERVICE_DEPLOYMENT_FAILED is not emitted.
  • SubmitTaskStateChange / SubmitContainerStateChange remain ACK-only; Floci drives the task lifecycle itself rather than via agent submissions.

Container Insights metrics

A service on a cluster whose own containerInsights setting is enabled or enhanced, set through CreateCluster, UpdateCluster, UpdateClusterSettings or CloudFormation ClusterSettings, publishes its task counts to CloudWatch, one sample a minute, in both docker and mock mode.

Namespace Metrics Dimensions Unit
ECS/ContainerInsights RunningTaskCount, PendingTaskCount, DesiredTaskCount ClusterName, ServiceName Count

As on AWS, nothing is published while the service has no RUNNING task, so an alarm on RunningTaskCount sees missing data rather than a zero: set TreatMissingData to breaching to alarm on a stopped service.

Known differences from AWS:

  • Only these three service task counts are published. CPU, memory, network and storage metrics, the cluster and task dimension sets, and the performance log events are not.
  • The account default set with PutAccountSettingDefault does not turn metrics on for a cluster; only the cluster's own setting does.
  • A stack update that removes ClusterSettings leaves the cluster's settings in place: declare containerInsights as disabled to stop the metrics.

Service discovery

A service that declares serviceRegistries has each of its running tasks registered as a Cloud Map instance of the named service, and deregistered when the task stops. The instance carries AWS_INSTANCE_IPV4 and AWS_INSTANCE_PORT, chosen by network mode:

Network mode AWS_INSTANCE_IPV4 AWS_INSTANCE_PORT
awsvpc the address the task's container holds on the Docker network it was created on, or the namespace helper's for a task whose containers share one the entry's containerPort
bridge or host the address Floci reaches the container at: 127.0.0.1 when Floci runs natively, the container's Docker network address when Floci runs in Docker the host port the entry's containerPort was published on, or the containerPort when it has no binding

An explicit port on the registry entry is registered as-is in every mode, as on AWS. The instance also carries the metadata attributes AWS records: AVAILABILITY_ZONE, REGION, ECS_SERVICE_NAME, ECS_CLUSTER_NAME and ECS_TASK_DEFINITION_FAMILY. The task id is the instance id, as on AWS, so a replacement task supersedes its predecessor.

Combined with Cloud Map answering DNS for its namespaces, that is what makes <cloud-map-service>.<namespace> resolve to a running task from another container. Registration is best effort: a registry entry Floci cannot place is logged and skipped rather than failing the task. UpdateService moves running task registrations to replacement registries; stopping a task removes the registrations it actually created.

Known differences from AWS:

  • AWS supports only SRV records for a bridge or host network mode task, since the reachable port is the published host port rather than the container port. Floci serves only A records, so such a task registers its address and its published host port and resolves by address; the port is readable through DiscoverInstances rather than DNS.
  • An awsvpc task registers its container's Docker network address, not its ENI address. On AWS the two are the same interface. In Floci the ENI address is held only on the VPC's Docker network, when VPC networks are enabled, so it is not one a peer outside that network can connect to. The registrar falls back to the ENI address only when it cannot read an address from a running container. Because the address is the container's own, the port is its containerPort, not any host port Floci also published it on.
  • EC2_INSTANCE_ID is not recorded. Every Floci task runs as a container rather than on a registered EC2 host, which is the Fargate case on AWS, where the attribute is also absent.
  • An instance's health status never moves. AWS registers a task UNHEALTHY and promotes it to HEALTHY once the container health check passes, for a service discovery service that declares HealthCheckCustomConfig. Floci feeds no container health into Cloud Map, so a task registers HEALTHY, which is Cloud Map's own default for a RegisterInstance that names no AWS_INIT_HEALTH_STATUS, and stays there until it is deregistered.

Restarts

Task state is memory-only, so a restarted Floci knows no task and the service scheduler starts new ones to reach each service's desired count. Floci therefore clears what the previous run's tasks left behind before it starts their replacements, so a service is never served by a task nothing manages:

  • In Docker mode, every ECS container a previous run of this Floci left on the daemon is removed. A graceful shutdown already stops them; this covers a run that ended without one (SIGKILL, OOM, a stop timeout that expired mid-drain). Containers are recognised by the io.floci.owner label (the resource namespace and API port), so the containers of another Floci sharing the daemon stay, and are told apart from the current run's by a per-process io.floci.ecs.run label rather than by creation time. Both are also written under their legacy names, floci_owner_port and floci.ecs-run, which are still read for containers an earlier version created (see Internal Labels). Containers created by a Floci version without that label are not recognised and must be removed by hand once. If Docker cannot list or remove one, the ECS starts no task until it is gone, retrying the removal before each launch: a service's replacement on a reconciliation tick, or a RunTask or StartTask call, whose task then stops with a TaskFailedToStart reason naming the leftovers. Each distinct failure is logged as a warning once. Two Floci instances that share a daemon with the same API port and no FLOCI_DOCKER_RESOURCE_NAMESPACE carry the same owner label and would remove each other's task containers: give each its own namespace, or set FLOCI_SERVICES_ECS_RECONCILE_CONTAINERS_ON_STARTUP=false to skip this sweep, as EC2's FLOCI_SERVICES_EC2_RECONCILE_CONTAINERS_ON_STARTUP does for instance containers. It also skips the startup removal of task-role credentials proxies, which carry the same label. Registrations are still released either way, since each Floci releases only what its own persisted state recorded.
  • Every load balancer target and Cloud Map instance a previous run's tasks registered is deregistered. Floci registers task containers by address, and Docker hands a dead container's address to the next container it starts, so a stale target would route to an unrelated container. ECS records each registration it makes in its persisted state and releases exactly those, so a target or instance registered through the ELBv2 or Cloud Map API, even into the same target group or Cloud Map service, stays. A registration is recorded before it is made, so one cut short by the process dying is still released. A target already in its group when a task starts is recorded as the task's own, since its address and port reach only that task, so it is deregistered when the task stops, as ECS does on AWS.
  • Registrations no ECS task recorded, as those a Floci version without the record made, are removed once they would misroute: when a task starts, each registration that points at it and that no running task recorded is deregistered from the target groups and Cloud Map services an ECS service names, and a warning names it. Such an entry was left by a task that is gone, and would otherwise send another service's traffic to the new task. A target points at the task when it is at its container's address on the Docker network and on a port the container publishes. A Cloud Map instance points at it when it is at that container address, on any port since a DNS answer carries none, or at the task's ENI address in a namespace of the task's own VPC, as ENI addresses are unique only within a VPC. A loopback address, which every task published on the host shares, matches only on the task's host ports. Target groups and Cloud Map services no ECS service names are never touched.

Unknown services

A service reference that does not resolve is returned in failures with reason: MISSING and the ARN the service would have had, rather than being dropped from the response. DescribeServices therefore returns partial results instead of erroring, as AWS does, and aws ecs wait services-stable on a nonexistent service fails immediately instead of polling for its full timeout. A reference supplied as an ARN is echoed back unchanged.

Task Sets

Operation Description
CreateTaskSet Create a task set inside a service
UpdateTaskSet Update a task set's scale
DeleteTaskSet Delete a task set
DescribeTaskSets Describe task sets for a service
UpdateServicePrimaryTaskSet Promote a task set to primary

A task set can only be created in a service whose deployment controller is EXTERNAL or CODE_DEPLOY; a rolling service runs its own deployments, and AWS refuses the call rather than creating a task set nothing will place. launchType and capacityProviderStrategy are mutually exclusive, and a request naming neither takes the cluster's defaultCapacityProviderStrategy, falling back to EC2. scale accepts only the PERCENT unit.

The task set round-trips networkConfiguration (defaulting to the service's), loadBalancers, serviceRegistries, platformVersion and tags, and reports platformFamily, startedBy (CODE_DEPLOY for a task set Floci's CodeDeploy created, unset for an external one) and stabilityStatusAt. computedDesiredCount is the service's desiredCount times the task set's scale percentage, always rounded up: 3 desired at 50 percent is 2 tasks, not 1. UpdateTaskSet recomputes it.

Creating a service with the CODE_DEPLOY controller creates an initial PRIMARY task set at 100 percent scale. Its running and pending counts track the tasks launched by the service scheduler. The set reaches STEADY_STATE when the running count matches its computed desired count and no tasks are pending. CreateService and DescribeServices return the task set and an empty deployments list for this controller.

Sets added through CreateTaskSet have simulated scheduling. Their running and pending counts stay at zero, and they report STEADY_STATE so deployment tools can continue.

DeleteTaskSet refuses a task set that has not been scaled down to zero unless force is set. DescribeTaskSets returns tags only for include: ["TAGS"] and reports a reference naming no task set of that service as a MISSING failure. A task set reference that resolves to nothing is a TaskSetNotFoundException, and task sets are scoped to one cluster and service: another service's task set is not visible through this one.

Container Instances

Operation Description
RegisterContainerInstance Register a container instance with a cluster
DeregisterContainerInstance Deregister a container instance
DescribeContainerInstances Describe container instances
ListContainerInstances List container instance ARNs
UpdateContainerAgent Trigger agent update (stub)
UpdateContainerInstancesState Drain or activate container instances

RegisterContainerInstance keeps what the agent sent: totalResources comes back as both registeredResources and remainingResources, and versionInfo, attributes, tags and a re-registered containerInstanceArn all round-trip. The agent version is reported inside versionInfo, which is where the ContainerInstance shape puts it, not as a top-level agentVersion. An instance also reports registeredAt and a version counter that each state change increments.

The container instance's ec2InstanceId is the instanceId of the instanceIdentityDocument the agent registers with, so it names the EC2 instance the agent runs on, as on AWS. A registration without a document gets a generated i-floci-... id; one whose document is not JSON or names no instanceId fails with InvalidParameterException. Floci does not check instanceIdentityDocumentSignature.

DeregisterContainerInstance leaves the instance in the cluster as INACTIVE rather than dropping it, so a later DescribeContainerInstances still answers for it, as on AWS. A cluster's registeredContainerInstancesCount counts only the ACTIVE and DRAINING instances.

ListContainerInstances defaults to every instance other than the INACTIVE ones, validates status against the five documented values, and pages with maxResults (1 to 100) and nextToken. Its filter supports a single runningTasksCount numeric comparison with ==, !=, >, >=, <, <= or their named equivalents. Other cluster query subjects and compound expressions are not implemented and return InvalidParameterException. The running count in list filtering and DescribeContainerInstances includes tasks whose desired status is RUNNING, even while their last status is PENDING.

UpdateContainerInstancesState sets only ACTIVE or DRAINING, takes at most 10 instances per call, and refuses to drain an instance that is not ACTIVE first. It and DescribeContainerInstances report an instance the cluster does not have as a MISSING failure rather than dropping it.

DescribeContainerInstances withholds two members until the request asks for them, and rejects an include value that is neither: TAGS for the instance's tags, and CONTAINER_INSTANCE_HEALTH for its healthStatus. Floci runs no agent health checks of its own, so the one check it reports is AGENT_CONNECTIVITY, taken from the registration state the instance already tracks, and overallStatus follows it.

Capacity Providers

Operation Description
CreateCapacityProvider Create a custom capacity provider
UpdateCapacityProvider Update a capacity provider
DeleteCapacityProvider Delete a capacity provider
DescribeCapacityProviders Describe capacity providers (includes FARGATE built-ins)

A capacity provider name is validated the way AWS documents it: up to 255 letters, numbers, underscores and hyphens, and never prefixed with aws, ecs or fargate. A created provider reports its capacityProviderArn, a type of EC2_AUTOSCALING, and the autoScalingGroupProvider it was created with, so a client that wrote one reads back what it registered instead of seeing drift.

DescribeCapacityProviders returns tags only for include: ["TAGS"], and reports a name that resolves to nothing as a MISSING entry in failures rather than dropping it. The built-in FARGATE and FARGATE_SPOT providers are described with their own ARNs and a type matching their name.

DeleteCapacityProvider refuses the reserved FARGATE and FARGATE_SPOT providers, one that is still attached to a cluster (detach it with PutClusterCapacityProviders, or delete the cluster, first), and one still named in an active service's capacity provider strategy, which AWS requires to be removed with UpdateService before the provider goes. A deleted provider is reported with updateStatus: DELETE_IN_PROGRESS and an unchanged status, because DELETE_IN_PROGRESS is not one of the four values CapacityProviderStatus takes.

Service Deployments & Revisions

Operation Description
DescribeServiceDeployments Describe service deployments
ListServiceDeployments List service deployment ARNs
DescribeServiceRevisions Describe service revisions

A deployment is recorded on CreateService and on every UpdateService that rolls one, together with the service revision it targets. The two are linked the way AWS links them: a deployment reports targetServiceRevision (its ARN and the task counts) and sourceServiceRevisions, and the service itself reports currentServiceDeployment and currentServiceRevisions, so a caller gets from DescribeServices to the deployment without listing first. A service deployment carries no taskDefinition member, because AWS's ServiceDeployment shape has none: the revision names it.

A service revision is the snapshot of the service's configuration at that moment, copied rather than referenced, so it keeps reporting what the service looked like then: taskDefinition, the launchType or capacityProviderStrategy, platformVersion, platformFamily, networkConfiguration, loadBalancers, serviceRegistries, serviceConnectConfiguration and one containerImages entry per container definition. guardDutyEnabled is always false: Floci runs no runtime monitoring. Floci applies a change in place rather than rolling it, so a deployment is SUCCESSFUL with the same startedAt and finishedAt from the moment it is recorded. Both describes report an ARN that resolves to nothing as a MISSING failure.

Tags

Operation Description
TagResource Add tags to a cluster, service, task, or task definition
UntagResource Remove tags from a resource
ListTagsForResource List tags on a resource

Every operation that takes tags holds it to the limits ECS documents: at most 50 tags, a key of 1 to 128 characters and a value of up to 256. The count is taken from the request rather than the parsed map, so 51 entries that collapse to fewer distinct keys are still rejected.

Account Settings & Attributes

Operation Description
PutAccountSetting Set an account-level setting for the calling user
PutAccountSettingDefault Set the default account-level setting
DeleteAccountSetting Delete an account setting
ListAccountSettings List account settings
PutAttributes Set custom key-value attributes on resources
DeleteAttributes Remove attributes from resources
ListAttributes List resources with a given attribute

An account setting name must be one of the eleven ECS accepts, and its value is checked against what that name allows: 0, 7 or 14 for fargateTaskRetirementWaitPeriod, blocking or non-blocking for defaultLogDriverMode, enhanced on top of the usual flags for containerInsights, and enabled/disabled/on/off for the rest. A Setting reports its principalArn and its type, which is user except for guardDutyActivate, the setting GuardDuty owns on the account's behalf.

A request that names no principalArn acts for the account root, since Floci does not authenticate a separate user, and PutAccountSettingDefault writes that same root row: AWS describes the effective value as "the account settings for the root user or the default setting". ListAccountSettings returns only the settings the principal explicitly set, which is why an untouched account lists nothing; with effectiveSettings: true it returns all eleven at the value that principal actually reads, falling back from its own setting to the root default to the setting's built-in default. It pages with maxResults (1 to 10) and nextToken, ten at a time.

A setting is persisted under <principalArn>::<name> rather than the name alone, so settings written by an earlier Floci version are ignored after upgrading: delete ecs-account-settings.json from the persistence directory, or write the settings again.

Attributes belong to a cluster, not to a target id alone, so the same container instance id in two clusters is two targets. An attribute must name a container instance the cluster has, or the call is a TargetNotFoundException, and a target holds at most 10 custom attributes (AttributeLimitExceededException past that, and for a single call carrying more than 10). ListAttributes requires targetType, whose only valid value is container-instance, and pages with maxResults (1 to 100) and nextToken.

Agent / State Change Stubs

Operation Description
SubmitTaskStateChange Agent callback stub
SubmitContainerStateChange Agent callback stub
SubmitAttachmentStateChanges Agent callback stub
DiscoverPollEndpoint Returns the agent polling endpoint

IAM Enforcement

With IAM enforcement on, each ECS request is checked on the resources it names, from the generated request resources: a cluster, service, task, container instance, task set or capacity provider by its name or its ARN; a service, task or container instance in the request's cluster, given by name or ARN, or in the default cluster when the request names none, as ECS does; an attribute on the container instance its targetId names; a service deployment or revision by its ARN, which Floci mints under its service as AWS does (service-deployment/<cluster>/<service>/<id>); and a task definition as the revision ECS resolves its reference to, a family alone being its latest revision, so web, web:3 and the revision's ARN are the same resource. A service or task given by its ARN is checked on that ARN and, when the request's cluster is another, on the one of its name in that cluster too, which UpdateService acts on. A task definition ECS does not have is checked on any revision, task-definition/*:*. An operation whose action has no resource type in the Service Authorization Reference (ListClusters, ListServices, DescribeTaskDefinition, DeregisterTaskDefinition, the account settings) is checked on *. The roles a request passes are checked as iam:PassRole and the tags it sets as ecs:TagResource.

Configuration

Every awsvpc task receives an ENI in its subnet. With FLOCI_NETWORK_SECURITY_GROUP_ENFORCEMENT_ENABLED=true, a Docker-backed task's containers additionally share one protected network namespace built around that ENI, and packets are filtered against its security groups. Without enforcement, FLOCI_SERVICES_ECS_SHARED_TASK_NETWORK=true gives them one namespace with no filtering; see Same-task localhost for awsvpc tasks. A task without explicit security groups uses its subnet VPC's default group. Containers in the same task can communicate over localhost. Bridge and host task networking do not attach task-level awsvpc security groups. Mock mode reports control-plane state, including the ENI, and does not enforce packet filtering.

Variable Default Description
FLOCI_SERVICES_ECS_ENABLED true Enable or disable the ECS service
FLOCI_SERVICES_ECS_MOCK false Skip Docker; tasks reach RUNNING with nothing running behind them (useful for CI)
FLOCI_SERVICES_ECS_DOCKER_NETWORK (unset) Docker network for task containers
FLOCI_SERVICES_ECS_SHARED_TASK_NETWORK false Put an awsvpc task's containers in one network namespace, so they reach each other on localhost, without security-group enforcement (see Same-task localhost for awsvpc tasks)
FLOCI_SERVICES_ECS_DEFAULT_MEMORY_MB 512 Default memory (MB) when the task definition omits it
FLOCI_SERVICES_ECS_DEFAULT_CPU_UNITS 256 Default CPU units when the task definition omits it
FLOCI_SERVICES_ECS_HOST_VOLUME_ROOTS (unset) Approved parent directories for host volume bind mounts (volumes[].host.sourcePath) and container devices (linuxParameters.devices[].hostPath)
FLOCI_SERVICES_ECS_ALLOW_UNSAFE_HOST_VOLUMES false Allow any host path, bypassing the HOST_VOLUME_ROOTS allowlist; traversal, the bare root, and the Docker socket are still always rejected
FLOCI_SERVICES_ECS_ALLOW_PRIVILEGED_CONTAINERS false Allow EC2 task containers requesting privileged: true to run with Docker privilege on the host
FLOCI_SERVICES_ECS_RECONCILE_CONTAINERS_ON_STARTUP true On startup, in Docker mode, remove the ECS containers a previous run of this Floci left on the daemon before the scheduler starts replacement tasks (see Restarts)
FLOCI_SERVICES_ECS_IMAGE_PULL_BEHAVIOR default How task images are pulled at launch, as the ECS agent's ECS_IMAGE_PULL_BEHAVIOR: default, always, once or prefer-cached (see Image pulls)
FLOCI_SERVICES_ECS_TASK_ROLE_CREDENTIALS_ENABLED false Vend real task IAM role credentials to task containers
FLOCI_SERVICES_ECS_TASK_ROLE_CREDENTIALS_TTL_SECONDS 21600 Lifetime of the vended credentials
FLOCI_SERVICES_ECS_TASK_ROLE_CREDENTIALS_PORT 51679 Floci-side port serving the credentials endpoint
FLOCI_SERVICES_ECS_TASK_ROLE_CREDENTIALS_PROXY_IMAGE floci/network-helper:local Image for the per-network credentials proxy

Image pulls

Floci pulls a task's container images when the task starts, before it creates any of its containers, the way the ECS agent does. FLOCI_SERVICES_ECS_IMAGE_PULL_BEHAVIOR takes the values of the agent's ECS_IMAGE_PULL_BEHAVIOR:

Value Behavior
default Pull on every launch. When the pull fails, run the cached image if there is one, otherwise the task fails.
always Pull on every launch. When the pull fails, the task fails.
once Pull when Floci has not pulled the image since it started, or the cached image is gone. Otherwise run the cached image.
prefer-cached Pull only when there is no cached image.

Under default and always, a tag moved in its registry (a rebuilt :latest) is what the next task runs, so UpdateService --force-new-deployment picks it up. default also keeps a locally built image that was never pushed anywhere working: its pull fails and the cached image runs, with a warning in the log. Whichever behavior applies, the cached image is the one the local tag names at launch, so a docker pull or docker build on the Docker host is also picked up.

Each container reports the digest of the manifest it runs as imageDigest in DescribeTasks (and ImageID in the task metadata endpoint): the digest the registry reported when the task's launch pulled the tag, or, for a launch that runs the cached image, the image's digest for that repository. An image that has never been pulled from or pushed to the repository its reference names, such as one built locally, has no manifest digest and reports none, as does a cached image holding several digests for the repository when nothing local says which one the tag names. A task definition image given as a bare image id (sha256:...) runs that local image without a pull. Floci does not pin a service's digests across the tasks of one deployment, so a tag moved while a service is scaling can put tasks of the same deployment on different images.

Task IAM role credentials

Off by default. With FLOCI_SERVICES_ECS_TASK_ROLE_CREDENTIALS_ENABLED=true, a task whose definition sets a resolvable taskRoleArn gets credentials for that role the way real ECS vends them: Floci writes AWS_CONTAINER_CREDENTIALS_RELATIVE_URI into every container in the task, pointing at one /v2/credentials/{id} path per task, and the AWS SDKs pick it up with no code change.

The published path stays the same when credentials renew, including when a task first reads it after the previous credentials expire. Reads near expiry return a fresh session. Credentials already cached by another client remain valid until their original expiry; stopping the task revokes every generation. A deleted or recreated task role invalidates the endpoint.

A user-defined Docker network is required. Set FLOCI_SERVICES_ECS_DOCKER_NETWORK to a network you created; the default bridge will not work. The SDKs hardcode 169.254.170.2 for this endpoint, so Floci runs a small proxy container that holds that address on the task's network and forwards to FLOCI_SERVICES_ECS_TASK_ROLE_CREDENTIALS_PORT. Each task container is also given its own address in 169.254.0.0/16, without which it would have no route to the endpoint at all. Docker only allows both of those on a user-defined network.

A task under security-group enforcement gets its credentials the same way. Its containers share the helper's protected namespace, so the helper takes the one link-local address for the whole task, and the helper's ruleset always lets TCP to 169.254.170.2:80 through. AWS security groups do not filter traffic to the ECS task metadata endpoints either. The exception covers that one listener and nothing else on the network.

docker network create floci-net

docker run -d --name floci \
  -p 4566:4566 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  --network floci-net \
  -e FLOCI_SERVICES_ECS_DOCKER_NETWORK=floci-net \
  -e FLOCI_SERVICES_ECS_TASK_ROLE_CREDENTIALS_ENABLED=true \
  floci/floci:latest

Credentials a task sets for itself always win. Floci drops only the baseline AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_SESSION_TOKEN it would otherwise inject, because the SDKs read environment credentials before the container endpoint and leaving them in place would silently shadow the role. Anything the task definition sets explicitly is left alone.

In two cases a task that asks for a role gets none. It starts without the relative URI and keeps whatever baseline credentials Floci would have injected anyway. Usually that is the emulator's default account, but if Floci itself was started with AWS credentials in its environment those are forwarded into the task instead, and Floci logs a warning once per process when it does that.

Either way the task is not running as the role it asked for, so a policy test against it says nothing about that role: the call is evaluated against a different identity and may succeed or fail for reasons that have nothing to do with the role's policy.

  • The role does not resolve. It does not exist in the account, the ARN is malformed, or it names a different account: Floci looks the role up in the account the request authenticated as and requires an exact ARN match, so a cross-account taskRoleArn never resolves.
  • No user-defined Docker network is configured. The endpoint has nowhere to listen.

Each of these logs a warning naming the task and the role it asked for.

Ephemeral task volumes

A volume declared with only a name, or with an empty host and no sourcePath, supplies ephemeral storage shared by the containers in that task. Each container's mountPoints selects the volume, mount path and read-only mode. Floci creates a Docker volume for each mounted task volume; different tasks get separate storage even when they use the same task definition.

Both RegisterTaskDefinition and CloudFormation task definitions reject a mount source that does not name a declared volume, a volume with multiple configuration kinds, and an EFS access point or IAM authorization without transit encryption enabled. EFS, S3 Files and configured-at-launch volumes require a name; generic volumes and mount members remain optional.

Task teardown removes this storage after the containers have been removed. Cleanup also runs when a task exits naturally or fails to launch. The task reconciler retries failed removals, including cleanup left pending by a failed launch or a state reset. With reconcile-containers-on-startup enabled, Floci also removes task volumes left by a previous run after their containers are gone. Failed volume cleanup retries on reconciler ticks without blocking new task launches. The sweep matches the emulator owner and run labels; it leaves current-run volumes and other emulator instances alone. Unlike AWS's configurable delayed EC2 agent cleanup, Floci attempts removal during teardown. EFS-backed volumes remain shared and persistent, and the unsupported external volume configurations listed above remain unimplemented.

Host volume safety

A task definition's volumes[].host.sourcePath is a caller-controlled filesystem path that Floci bind-mounts straight into the launched container, so both RegisterTaskDefinition and the actual bind mount at RunTask time validate it (the second check narrows the window between validation and mount, and also covers task definitions registered before this policy existed).

Always rejected, regardless of configuration:

  • Relative paths, and any path containing a .. segment.
  • The bare filesystem root (/).
  • The Docker daemon socket and any directory that contains it (e.g. /var/run, /run, /var), including via a symlink that resolves onto one of these paths. The protected socket is the one Floci's own Docker client connects to, resolved the same way the client resolves it: floci.docker.docker-host, then DOCKER_HOST, then the active Docker context (Colima, OrbStack, Rancher Desktop, Podman), then /var/run/docker.sock. The conventional locations /var/run/docker.sock and /run/docker.sock are always protected as well.

By default, with no configuration, every host sourcePath is rejected. You must explicitly opt in with one of:

  • FLOCI_SERVICES_ECS_HOST_VOLUME_ROOTS: a comma-separated allowlist of approved parent directories. A sourcePath must resolve (symlinks included) under one of them:
services:
  floci:
    image: floci/floci:latest
    environment:
      FLOCI_SERVICES_ECS_HOST_VOLUME_ROOTS: /srv/floci/volumes,/data
  • FLOCI_SERVICES_ECS_ALLOW_UNSAFE_HOST_VOLUMES=true: allow any host path (for local development where any host path should be mountable). The traversal, bare-root, and Docker socket blocks above are never bypassed by this flag.

A container device's hostPath (linuxParameters.devices) goes through the same checks and the same allowlist, since a device hands the container the host's hardware.

An EC2 task definition may contain privileged: true, but Docker-backed tasks using it stop before launch unless the Floci operator sets FLOCI_SERVICES_ECS_ALLOW_PRIVILEGED_CONTAINERS=true. A privileged container has access to all host devices and can bypass the host path restrictions above, so enable this only when task definition callers are trusted.

A rejected sourcePath or device hostPath fails RegisterTaskDefinition with InvalidParameterException; a rejection caught again at RunTask time (e.g. a task definition registered before this policy existed) stops the task with that message as its stoppedReason. Named Docker volumes, EFS volumes, and host volumes with no sourcePath (ephemeral storage shared within a task) are unaffected by these checks.

EFS volume ownership

A task's efsVolumeConfiguration volumes are backed by shared local Docker volumes (Floci cannot mount a real EFS file system). When authorizationConfig.accessPointId identifies an access point stored by the EFS service in the task's region, Floci initialises the volume root using that access point's RootDirectory.CreationInfo (OwnerUid, OwnerGid, and Permissions). Its PosixUser adds the access point's GID and secondary GIDs to the mounting container as supplementary groups, preserving the container's own user. Access points with different settings initialise their own isolated volumes without requiring environment variables.

The floci.storage.efs.* settings below provide the fallback: ownership and permissions when the access point has no CreationInfo, and user and supplementary group when it has no PosixUser. They also apply when no access point is specified or its metadata is unavailable; unavailable metadata produces a warning. Without access point settings or fallback configuration, a plain named volume retains Docker's root:root 0755 defaults.

Unlike real EFS user enforcement, which applies identity per file system request, this local emulation preserves the container process identity and grants volume access by attaching the POSIX user's group and secondary groups as container supplementary groups. Explicit user overrides remain available via floci.storage.efs.mount-user. Root ownership retains unsigned 32-bit IDs, but the Docker runtime can reject supplementary group IDs above 2147483647.

Key (floci.storage.efs.) Env AWS equivalent Description
owner-uid FLOCI_STORAGE_EFS_OWNER_UID CreationInfo.OwnerUid Owner uid of the volume root (set together with owner-gid)
owner-gid FLOCI_STORAGE_EFS_OWNER_GID CreationInfo.OwnerGid Owner gid of the volume root (set together with owner-uid)
root-permissions FLOCI_STORAGE_EFS_ROOT_PERMISSIONS CreationInfo.Permissions 3-4 octal digits, e.g. 0777, or 2775 for the setgid bit
mount-user FLOCI_STORAGE_EFS_MOUNT_USER PosixUser {Uid,Gid} Run mounting containers as uid[:gid]
mount-group-add FLOCI_STORAGE_EFS_MOUNT_GROUP_ADD PosixUser supplementary Supplementary gid added to mounting containers
init-image FLOCI_STORAGE_EFS_INIT_IMAGE N/A Image for the one-off chown/chmod of the volume root (default busybox:stable)

owner-uid and owner-gid must be set together (a partial CreationInfo is not valid on AWS). The volume root is initialised once per volume per Floci process; express the setgid bit through a 4-digit root-permissions (e.g. 2775) so subdirectories inherit the owner gid. Initialisation changes only the root's ownership and permissions and preserves existing files. A Floci restart reapplies these settings on the next mount, unlike real EFS, which preserves permissions on an existing root directory.

Mock mode

Set FLOCI_SERVICES_ECS_MOCK=true to run without Docker. In this mode tasks skip container launch and reach RUNNING right after RunTask answers, then STOPPED when stopped. The task still reports a container per container definition and, for awsvpc, a real ENI, so a client reading containers[] or waiting on the task's address behaves as it does against AWS; nothing is running behind those containers, so ECS Exec answers TargetNotConnectedException and no logs are streamed. This is the recommended mode for unit/integration tests and CI pipelines where Docker-in-Docker is unavailable.

# docker-compose.yml — CI / test environment
services:
  floci:
    image: floci/floci:latest
    environment:
      FLOCI_SERVICES_ECS_MOCK: "true"
# docker-compose.yml — local development (real containers)
services:
  floci:
    image: floci/floci:latest
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      FLOCI_SERVICES_ECS_MOCK: "false"
      FLOCI_SERVICES_ECS_DOCKER_NETWORK: my_network

Docker socket requirement

When mock: false (the default), ECS launches real Docker containers and requires the Docker socket. Mount it and set the network so containers can reach each other. For private registry authentication and other Docker settings see Docker Configuration.

services:
  floci:
    image: floci/floci:latest
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      FLOCI_SERVICES_ECS_DOCKER_NETWORK: aws-local_default

Same-task localhost for awsvpc tasks

On Fargate, the containers of an awsvpc task share one network namespace and reach each other on localhost: an nginx in front of php-fpm on 127.0.0.1:9000, or an Envoy or log-router sidecar. Floci gives each task container a namespace of its own by default, so 127.0.0.1:<port of a sibling> is refused. Security-group enforcement shares one, but it needs rootful Docker on Linux.

Set FLOCI_SERVICES_ECS_SHARED_TASK_NETWORK=true (floci.services.ecs.shared-task-network, default false) to share one namespace without enforcement. Each Docker-backed awsvpc task then gets a helper container that holds its namespace, as the ECS agent's pause container does, and every container in the task joins it. Nothing is filtered, and the helper needs no privileges, so this works on rootless Docker and Podman. With enforcement on, the setting changes nothing: the task gets its protected namespace.

The helper holds what the task has once rather than per container: its published ports (with the host-port settings below), the link-local address its containers reach the task-role credential endpoint from, and its ENI address on the VPC's Docker network. It is removed when the task stops, and a helper a previous run left behind is removed at startup with the task's other containers. It uses the security-group helper image, FLOCI_NETWORK_SECURITY_GROUP_ENFORCEMENT_HELPER_IMAGE, which Floci builds locally by default.

As on AWS, two containers in one task can no longer listen on the same port, and a container reaches its siblings only on localhost, not at an address of its own.

Host access to awsvpc task ports

Native runs publish awsvpc task ports on dynamically allocated Docker host ports. When Floci runs in Docker, task ports remain private to the configured Docker network unless FLOCI_SERVICES_ECS_PUBLISH_AWSVPC_PORTS_TO_HOST=true is set.

Enabling host publishing preserves stable ports by default: an explicit non-zero hostPort is used, otherwise the host port equals containerPort. Existing host-side clients can keep using localhost:<hostPort>. Only one task at a time can reserve each stable port on the shared Docker host.

To run tasks with matching container ports concurrently, including rolling-deployment revisions, also set FLOCI_SERVICES_ECS_DYNAMIC_AWSVPC_HOST_PORTS=true (floci.services.ecs.dynamic-awsvpc-host-ports, default false). Docker then allocates an available host port per task, including tasks declaring an explicit hostPort. Discover the actual published address and port in DescribeTasks:

aws ecs describe-tasks --cluster my-cluster --tasks "$TASK_ARN" \
  --query 'tasks[].containers[].networkBindings[]'

Published awsvpc ports bind to 127.0.0.1 by default. Set floci.services.ecs.host-port-bind-address (FLOCI_SERVICES_ECS_HOST_PORT_BIND_ADDRESS) to another Docker-host interface if clients need one. The same stable or dynamic allocation and interface settings apply to security-group network-namespace helpers. These are interfaces on the Docker daemon's host, which may differ from Floci's host.

services:
  floci:
    image: floci/floci:latest
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      FLOCI_SERVICES_ECS_PUBLISH_AWSVPC_PORTS_TO_HOST: "true"
      FLOCI_SERVICES_ECS_DYNAMIC_AWSVPC_HOST_PORTS: "true"
      FLOCI_SERVICES_ECS_HOST_PORT_BIND_ADDRESS: "127.0.0.1"

Host publishing is an emulator convenience and defaults to false in Docker mode. With dynamic allocation enabled, host-side clients must use each task's reported host port. Load balancers inside Docker use the container's Docker-network address and container port; native load balancers use the published host port. Bridge/host-mode explicit bindings retain their existing fixed-port behavior.

Stable-port replacement

A Docker-backed REPLICA service can reuse a stable published host port across deployments by explicitly setting deploymentConfiguration.minimumHealthyPercent to 0. When a stale task holds a fixed port needed by the replacement, the scheduler stops that task before placing the replacement. This applies both to forced deployments of the same task definition and to task-definition changes that reuse the port.

The task stays STOPPING until Docker confirms removal of every container and any security-group namespace helper that owns its published ports. Incomplete removal is retried on later ticks. Stops run in the background so a slow graceful stop does not hold up unrelated services. Task protection still applies: a protected stale task keeps its port and delays replacement until its protection expires or is disabled.

For awsvpc, stable ports require FLOCI_SERVICES_ECS_PUBLISH_AWSVPC_PORTS_TO_HOST=true and FLOCI_SERVICES_ECS_DYNAMIC_AWSVPC_HOST_PORTS=false. An explicit non-zero hostPort is stable, and an omitted or zero hostPort uses containerPort. Explicit fixed bindings in bridge/host modes can also be reused this way. Dynamic ports and nonconflicting port changes keep the replacement-first behavior, as do services with positive or omitted minima. DAEMON scheduling is unchanged. Collision detection follows the actual Docker publisher, which currently publishes every mapping as TCP: changing a declared protocol alone does not free the host port.

This permits an outage at the stable endpoint. Zero is a minimum healthy percentage, not a general requirement for AWS to stop tasks first. Floci does not implement the full percentage-based deployment scheduler.

Examples

export AWS_ENDPOINT_URL=http://localhost:4566
export AWS_DEFAULT_REGION=us-east-1
export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test

# Create a cluster
aws ecs create-cluster --cluster-name my-cluster \
  --endpoint-url $AWS_ENDPOINT_URL

# Register a task definition
aws ecs register-task-definition \
  --family my-task \
  --container-definitions '[
    {
      "name": "app",
      "image": "nginx:latest",
      "cpu": 256,
      "memory": 512,
      "essential": true,
      "portMappings": [{"containerPort": 80, "protocol": "tcp"}]
    }
  ]' \
  --requires-compatibilities FARGATE \
  --cpu 256 --memory 512 \
  --network-mode awsvpc \
  --endpoint-url $AWS_ENDPOINT_URL

# Run a task
aws ecs run-task \
  --cluster my-cluster \
  --task-definition my-task \
  --launch-type FARGATE \
  --endpoint-url $AWS_ENDPOINT_URL

# Create a service
aws ecs create-service \
  --cluster my-cluster \
  --service-name my-service \
  --task-definition my-task \
  --desired-count 1 \
  --launch-type FARGATE \
  --endpoint-url $AWS_ENDPOINT_URL

# List running tasks
aws ecs list-tasks --cluster my-cluster \
  --endpoint-url $AWS_ENDPOINT_URL

# Stop a task
aws ecs stop-task \
  --cluster my-cluster \
  --task <task-arn> \
  --endpoint-url $AWS_ENDPOINT_URL

# Delete a service
aws ecs delete-service \
  --cluster my-cluster \
  --service my-service \
  --force \
  --endpoint-url $AWS_ENDPOINT_URL

Java SDK Example

EcsClient ecs = EcsClient.builder()
    .endpointOverride(URI.create("http://localhost:4566"))
    .region(Region.US_EAST_1)
    .credentialsProvider(StaticCredentialsProvider.create(
        AwsBasicCredentials.create("test", "test")))
    .build();

// Create cluster
ecs.createCluster(r -> r.clusterName("my-cluster"));

// Register task definition
ecs.registerTaskDefinition(r -> r
    .family("my-task")
    .containerDefinitions(c -> c
        .name("app")
        .image("nginx:latest")
        .cpu(256)
        .memory(512)
        .essential(true))
    .requiresCompatibilities(Compatibility.FARGATE)
    .cpu("256")
    .memory("512")
    .networkMode(NetworkMode.AWSVPC));

// Run a task
RunTaskResponse response = ecs.runTask(r -> r
    .cluster("my-cluster")
    .taskDefinition("my-task")
    .launchType(LaunchType.FARGATE)
    .count(1));

String taskArn = response.tasks().get(0).taskArn();