openapi: 3.1.0
info:
title: AWS Fargate Amazon ECS API (Fargate) Clusters Task Definitions API
description: The Amazon ECS API provides programmatic access to manage Fargate tasks and services through Amazon Elastic Container Service. AWS Fargate is a serverless compute engine for containers that removes the need to provision and manage servers. This specification covers the core ECS API operations relevant to Fargate workloads, including registering task definitions with Fargate compatibility, running tasks on Fargate infrastructure, and managing services with the Fargate launch type. All operations use the JSON-RPC style with POST requests and an X-Amz-Target header specifying the action.
version: '2014-11-13'
contact:
name: Amazon Web Services
url: https://aws.amazon.com/fargate/
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
termsOfService: https://aws.amazon.com/service-terms/
servers:
- url: https://ecs.{region}.amazonaws.com
description: Amazon ECS regional endpoint
variables:
region:
default: us-east-1
description: AWS region
enum:
- us-east-1
- us-east-2
- us-west-1
- us-west-2
- eu-west-1
- eu-west-2
- eu-west-3
- eu-central-1
- eu-north-1
- ap-southeast-1
- ap-southeast-2
- ap-northeast-1
- ap-northeast-2
- ap-south-1
- sa-east-1
- ca-central-1
security:
- aws_sig_v4: []
tags:
- name: Task Definitions
description: Operations for registering and managing ECS task definitions with Fargate compatibility, including CPU, memory, network mode, and container configuration.
externalDocs:
url: https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RegisterTaskDefinition.html
paths:
/#X-Amz-Target=AmazonEC2ContainerServiceV20141113.RegisterTaskDefinition:
post:
operationId: registerTaskDefinition
summary: AWS Fargate Register a Fargate task definition
description: Registers a new task definition from the supplied family and container definitions. For Fargate tasks, the networkMode must be awsvpc, and task-level cpu and memory values are required. Use the requiresCompatibilities parameter with FARGATE to validate that all parameters meet Fargate requirements. The task definition is used to run tasks directly or as part of a service.
tags:
- Task Definitions
externalDocs:
url: https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RegisterTaskDefinition.html
parameters:
- $ref: '#/components/parameters/X-Amz-Target'
requestBody:
required: true
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/RegisterTaskDefinitionRequest'
responses:
'200':
description: Task definition registered successfully
content:
application/json:
schema:
$ref: '#/components/schemas/RegisterTaskDefinitionResponse'
'400':
$ref: '#/components/responses/ClientError'
'500':
$ref: '#/components/responses/ServerError'
/#X-Amz-Target=AmazonEC2ContainerServiceV20141113.DescribeTaskDefinition:
post:
operationId: describeTaskDefinition
summary: AWS Fargate Describe a task definition
description: Describes a task definition. You can specify a family and revision to find a specific task definition, or you can provide the family name alone to get the latest ACTIVE revision in that family. This is useful for inspecting the Fargate CPU, memory, and networking configuration of a registered task definition.
tags:
- Task Definitions
externalDocs:
url: https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DescribeTaskDefinition.html
parameters:
- $ref: '#/components/parameters/X-Amz-Target'
requestBody:
required: true
content:
application/x-amz-json-1.1:
schema:
type: object
required:
- taskDefinition
properties:
taskDefinition:
type: string
description: The family and revision (family:revision) or full ARN of the task definition to describe. If you specify only the family name, the latest ACTIVE revision is described.
include:
type: array
description: Specifies whether to see the resource tags for the task definition.
items:
type: string
enum:
- TAGS
responses:
'200':
description: Task definition described successfully
content:
application/json:
schema:
type: object
properties:
taskDefinition:
$ref: '#/components/schemas/TaskDefinition'
tags:
type: array
items:
$ref: '#/components/schemas/Tag'
'400':
$ref: '#/components/responses/ClientError'
'500':
$ref: '#/components/responses/ServerError'
/#X-Amz-Target=AmazonEC2ContainerServiceV20141113.ListTaskDefinitions:
post:
operationId: listTaskDefinitions
summary: AWS Fargate List task definitions
description: Returns a list of task definitions that are registered to your account. You can filter the results by family name to retrieve all revisions of a particular task definition family. Use the status filter to list only ACTIVE or INACTIVE task definitions.
tags:
- Task Definitions
externalDocs:
url: https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ListTaskDefinitions.html
parameters:
- $ref: '#/components/parameters/X-Amz-Target'
requestBody:
required: true
content:
application/x-amz-json-1.1:
schema:
type: object
properties:
familyPrefix:
type: string
description: The family name prefix to filter the task definitions with.
status:
type: string
description: The task definition status to filter on.
enum:
- ACTIVE
- INACTIVE
sort:
type: string
description: The order to sort the results in.
enum:
- ASC
- DESC
nextToken:
type: string
description: Token for the next set of results from a previous call.
maxResults:
type: integer
description: Maximum number of task definition results.
minimum: 1
maximum: 100
responses:
'200':
description: List of task definition ARNs
content:
application/json:
schema:
type: object
properties:
taskDefinitionArns:
type: array
items:
type: string
nextToken:
type: string
'400':
$ref: '#/components/responses/ClientError'
'500':
$ref: '#/components/responses/ServerError'
/#X-Amz-Target=AmazonEC2ContainerServiceV20141113.DeregisterTaskDefinition:
post:
operationId: deregisterTaskDefinition
summary: AWS Fargate Deregister a task definition
description: Deregisters the specified task definition by family and revision. Upon deregistration, the task definition is marked as INACTIVE. Existing tasks and services that reference an INACTIVE task definition continue to run without disruption. You cannot use an INACTIVE task definition to run new tasks or create new services.
tags:
- Task Definitions
externalDocs:
url: https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DeregisterTaskDefinition.html
parameters:
- $ref: '#/components/parameters/X-Amz-Target'
requestBody:
required: true
content:
application/x-amz-json-1.1:
schema:
type: object
required:
- taskDefinition
properties:
taskDefinition:
type: string
description: The family and revision (family:revision) or full ARN of the task definition to deregister.
responses:
'200':
description: Task definition deregistered successfully
content:
application/json:
schema:
type: object
properties:
taskDefinition:
$ref: '#/components/schemas/TaskDefinition'
'400':
$ref: '#/components/responses/ClientError'
'500':
$ref: '#/components/responses/ServerError'
components:
schemas:
LogConfiguration:
type: object
description: Log configuration for the container. Fargate tasks support the awslogs, splunk, and awsfirelens log drivers.
required:
- logDriver
properties:
logDriver:
type: string
description: The log driver to use for the container. Fargate supports awslogs, splunk, and awsfirelens.
enum:
- awslogs
- splunk
- awsfirelens
options:
type: object
description: Configuration options for the log driver. For awslogs, includes awslogs-group, awslogs-region, and awslogs-stream-prefix.
additionalProperties:
type: string
secretOptions:
type: array
description: Secret log configuration options passed to the log driver.
items:
type: object
properties:
name:
type: string
valueFrom:
type: string
EphemeralStorage:
type: object
description: The amount of ephemeral storage to allocate for the Fargate task. Available on platform version 1.4.0 or later for Linux and 1.0.0 or later for Windows.
required:
- sizeInGiB
properties:
sizeInGiB:
type: integer
description: The total amount of ephemeral storage in GiB.
minimum: 21
maximum: 200
RegisterTaskDefinitionResponse:
type: object
properties:
taskDefinition:
$ref: '#/components/schemas/TaskDefinition'
tags:
type: array
items:
$ref: '#/components/schemas/Tag'
Volume:
type: object
description: A data volume used by containers in a task. Fargate tasks support bind mounts and EFS volumes.
properties:
name:
type: string
description: The name of the volume, referenced by containers in mountPoints.
efsVolumeConfiguration:
type: object
description: Amazon EFS volume configuration for the task.
required:
- fileSystemId
properties:
fileSystemId:
type: string
description: The Amazon EFS file system ID.
rootDirectory:
type: string
description: The directory within the EFS file system to mount.
transitEncryption:
type: string
description: Whether to enable EFS transit encryption.
enum:
- ENABLED
- DISABLED
transitEncryptionPort:
type: integer
description: The port to use for encrypted transit.
authorizationConfig:
type: object
properties:
accessPointId:
type: string
description: The EFS access point ID.
iam:
type: string
description: Whether to use the task IAM role for authorization.
enum:
- ENABLED
- DISABLED
TaskDefinition:
type: object
description: A Fargate task definition describes the containers and parameters required to run a Fargate task.
properties:
taskDefinitionArn:
type: string
description: The full ARN of the task definition.
family:
type: string
description: The family name for the task definition.
revision:
type: integer
description: The revision of the task definition.
status:
type: string
description: The status of the task definition.
enum:
- ACTIVE
- INACTIVE
- DELETE_IN_PROGRESS
containerDefinitions:
type: array
description: The container definitions for the task.
items:
$ref: '#/components/schemas/ContainerDefinition'
cpu:
type: string
description: The task-level CPU value in CPU units. Required for Fargate.
memory:
type: string
description: The task-level memory value in MiB. Required for Fargate.
networkMode:
type: string
description: The Docker networking mode. Must be awsvpc for Fargate tasks.
enum:
- awsvpc
requiresCompatibilities:
type: array
description: The launch type compatibility requirements.
items:
type: string
enum:
- FARGATE
- EC2
executionRoleArn:
type: string
description: The ARN of the task execution role for pulling images and sending logs.
taskRoleArn:
type: string
description: The IAM role that containers in the task can assume.
runtimePlatform:
$ref: '#/components/schemas/RuntimePlatform'
ephemeralStorage:
$ref: '#/components/schemas/EphemeralStorage'
volumes:
type: array
description: The volumes defined for the task.
items:
$ref: '#/components/schemas/Volume'
registeredAt:
type: string
format: date-time
description: The Unix timestamp when the task definition was registered.
registeredBy:
type: string
description: The principal that registered the task definition.
compatibilities:
type: array
description: The launch type compatibilities for the task definition.
items:
type: string
PortMapping:
type: object
description: A port mapping for a container. For Fargate tasks, the containerPort is the only required field. The hostPort is automatically set to match the containerPort.
properties:
containerPort:
type: integer
description: The port number on the container bound to the host port.
minimum: 0
maximum: 65535
hostPort:
type: integer
description: The port number on the host. For Fargate tasks, this is always the same as the containerPort.
minimum: 0
maximum: 65535
protocol:
type: string
description: The protocol used for the port mapping.
enum:
- tcp
- udp
default: tcp
name:
type: string
description: The name for the port mapping, used for Service Connect.
appProtocol:
type: string
description: The application protocol for the port mapping, used for Service Connect.
enum:
- http
- http2
- grpc
ErrorResponse:
type: object
properties:
__type:
type: string
description: The error type identifier.
message:
type: string
description: A human-readable error message.
HealthCheck:
type: object
description: Container health check configuration. The health check command is run inside the container.
required:
- command
properties:
command:
type: array
description: The command to run to determine container health. Prefix with CMD for shell execution or CMD-SHELL for direct execution.
items:
type: string
interval:
type: integer
description: The period in seconds between health checks. Default is 30.
default: 30
minimum: 5
maximum: 300
timeout:
type: integer
description: The time in seconds to wait for a health check to succeed. Default is 5.
default: 5
minimum: 2
maximum: 120
retries:
type: integer
description: The number of times to retry a failed health check before the container is considered unhealthy. Default is 3.
default: 3
minimum: 1
maximum: 10
startPeriod:
type: integer
description: The grace period in seconds to allow the container to bootstrap before failed health checks count.
default: 0
minimum: 0
maximum: 300
RegisterTaskDefinitionRequest:
type: object
description: Request to register a Fargate task definition.
required:
- family
- containerDefinitions
properties:
family:
type: string
description: The family name for the task definition. Up to 255 characters consisting of letters, numbers, underscores, and hyphens.
maxLength: 255
pattern: ^[a-zA-Z0-9_-]+$
containerDefinitions:
type: array
description: The container definitions for the task.
items:
$ref: '#/components/schemas/ContainerDefinition'
cpu:
type: string
description: The task-level CPU value in CPU units. Required for Fargate. Valid values are 256, 512, 1024, 2048, 4096, 8192, and 16384.
enum:
- '256'
- '512'
- '1024'
- '2048'
- '4096'
- '8192'
- '16384'
memory:
type: string
description: The task-level memory value in MiB. Required for Fargate. The valid values depend on the CPU value specified.
networkMode:
type: string
description: The Docker networking mode. Must be awsvpc for Fargate tasks.
enum:
- awsvpc
requiresCompatibilities:
type: array
description: The launch type compatibility to validate against. Use FARGATE to ensure the task definition is Fargate-compatible.
items:
type: string
enum:
- FARGATE
- EC2
executionRoleArn:
type: string
description: The ARN of the task execution role that grants the ECS agent permission to pull images and publish logs.
taskRoleArn:
type: string
description: The IAM role that containers in the task can assume for AWS API access.
runtimePlatform:
$ref: '#/components/schemas/RuntimePlatform'
ephemeralStorage:
$ref: '#/components/schemas/EphemeralStorage'
volumes:
type: array
description: The volumes to make available for containers in the task.
items:
$ref: '#/components/schemas/Volume'
tags:
type: array
description: Tags to apply to the task definition.
items:
$ref: '#/components/schemas/Tag'
ContainerDefinition:
type: object
description: A container definition describes a container that is part of a task.
required:
- name
- image
properties:
name:
type: string
description: The name of the container. Up to 255 letters, numbers, underscores, and hyphens.
maxLength: 255
image:
type: string
description: The image used to start the container. Can be an image in a Docker Hub, Amazon ECR, or another repository.
cpu:
type: integer
description: The number of cpu units reserved for the container. For Fargate tasks, the task-level CPU value is used, and this is optional.
memory:
type: integer
description: The amount of memory (in MiB) to allocate to the container. For Fargate tasks, the task-level memory value is used, and this is optional.
memoryReservation:
type: integer
description: The soft limit (in MiB) of memory to reserve for the container.
essential:
type: boolean
description: If true, and the container fails or stops, all other containers in the task are stopped. At least one container must be marked essential in a task definition.
portMappings:
type: array
description: Port mappings for the container. For Fargate tasks with awsvpc network mode, only containerPort is used. The hostPort value is the same as containerPort.
items:
$ref: '#/components/schemas/PortMapping'
environment:
type: array
description: Environment variables to pass to the container.
items:
$ref: '#/components/schemas/KeyValuePair'
secrets:
type: array
description: Secrets to pass to the container from AWS Secrets Manager or AWS Systems Manager Parameter Store.
items:
type: object
properties:
name:
type: string
description: The name of the environment variable to set in the container.
valueFrom:
type: string
description: The secret ARN or SSM parameter ARN to expose as an environment variable.
logConfiguration:
$ref: '#/components/schemas/LogConfiguration'
healthCheck:
$ref: '#/components/schemas/HealthCheck'
command:
type: array
description: The command passed to the container. Overrides the CMD in the Dockerfile.
items:
type: string
entryPoint:
type: array
description: The entry point passed to the container. Overrides the ENTRYPOINT in the Dockerfile.
items:
type: string
workingDirectory:
type: string
description: The working directory to run commands inside the container.
user:
type: string
description: The user to use inside the container (UID or username).
readonlyRootFilesystem:
type: boolean
description: When true, the container is given read-only access to its root filesystem.
dependsOn:
type: array
description: Dependencies defined for container startup and shutdown ordering.
items:
type: object
properties:
containerName:
type: string
condition:
type: string
enum:
- START
- COMPLETE
- SUCCESS
- HEALTHY
mountPoints:
type: array
description: Mount points for data volumes in the container.
items:
type: object
properties:
sourceVolume:
type: string
containerPath:
type: string
readOnly:
type: boolean
KeyValuePair:
type: object
description: A key-value pair representing an environment variable.
properties:
name:
type: string
description: The name of the environment variable.
value:
type: string
description: The value of the environment variable.
Tag:
type: object
description: A key-value pair used to tag an Amazon ECS resource.
properties:
key:
type: string
description: The tag key. Tag keys are case-sensitive and must be unique.
maxLength: 128
value:
type: string
description: The tag value.
maxLength: 256
RuntimePlatform:
type: object
description: The operating system and CPU architecture for the Fargate task.
properties:
cpuArchitecture:
type: string
description: The CPU architecture. ARM64 is supported for Linux tasks.
enum:
- X86_64
- ARM64
default: X86_64
operatingSystemFamily:
type: string
description: The operating system family for the Fargate task.
enum:
- LINUX
- WINDOWS_SERVER_2019_FULL
- WINDOWS_SERVER_2019_CORE
- WINDOWS_SERVER_2022_FULL
- WINDOWS_SERVER_2022_CORE
- WINDOWS_SERVER_2025_FULL
- WINDOWS_SERVER_2025_CORE
default: LINUX
parameters:
X-Amz-Target:
name: X-Amz-Target
in: header
required: true
schema:
type: string
description: The ECS API action target header used for JSON-RPC style routing.
responses:
ServerError:
description: Server error. An internal service error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
ClientError:
description: Client error. The request was invalid, contained incorrect parameters, or the caller does not have required permissions.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
securitySchemes:
aws_sig_v4:
type: apiKey
name: Authorization
in: header
description: AWS Signature Version 4 authentication. Requests must be signed using AWS access credentials.
externalDocs:
description: AWS Fargate Developer Guide
url: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/AWS_Fargate.html