openapi: 3.1.0
info:
  title: 'AWS Fargate Amazon ECS API (Fargate) Clusters #X Amz Target=AmazonEC2ContainerServiceV20141113.CreateService 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: '#X Amz Target=AmazonEC2ContainerServiceV20141113.CreateService'
paths:
  /#X-Amz-Target=AmazonEC2ContainerServiceV20141113.CreateService:
    post:
      operationId: createService
      summary: AWS Fargate Create a Fargate service
      description: Creates a new Amazon ECS service that runs and maintains a desired number of tasks. When using the Fargate launch type, tasks are launched on serverless infrastructure without managing servers. A network configuration with awsvpc mode is required for Fargate services. You can configure load balancers, deployment strategies, service discovery, and auto scaling for long-running Fargate workloads.
      tags:
      - '#X Amz Target=AmazonEC2ContainerServiceV20141113.CreateService'
      externalDocs:
        url: https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_CreateService.html
      parameters:
      - $ref: '#/components/parameters/X-Amz-Target'
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/CreateServiceRequest'
      responses:
        '200':
          description: Service created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  service:
                    $ref: '#/components/schemas/Service'
        '400':
          $ref: '#/components/responses/ClientError'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    AwsVpcConfiguration:
      type: object
      description: The VPC networking configuration for Fargate tasks, which always use the awsvpc network mode.
      required:
      - subnets
      properties:
        subnets:
          type: array
          description: The IDs of the subnets associated with the task or service. All specified subnets must be in the same VPC.
          items:
            type: string
        securityGroups:
          type: array
          description: The IDs of the security groups associated with the task or service. If no security group is specified, the default security group for the VPC is used.
          items:
            type: string
          maxItems: 5
        assignPublicIp:
          type: string
          description: Whether the task's elastic network interface receives a public IP address. A value of ENABLED is required when using public subnets so Fargate tasks can pull container images.
          enum:
          - ENABLED
          - DISABLED
    NetworkConfiguration:
      type: object
      description: The network configuration for a task or service. Required for Fargate tasks and services.
      properties:
        awsvpcConfiguration:
          $ref: '#/components/schemas/AwsVpcConfiguration'
    DeploymentConfiguration:
      type: object
      description: The deployment configuration for a service, controlling how updates are rolled out.
      properties:
        maximumPercent:
          type: integer
          description: The upper limit of the number of tasks allowed during a deployment as a percentage of the desired count. Default is 200%.
          default: 200
        minimumHealthyPercent:
          type: integer
          description: The lower limit of the number of running tasks during a deployment as a percentage of the desired count. Default is 100%.
          default: 100
        deploymentCircuitBreaker:
          type: object
          description: The deployment circuit breaker to automatically roll back unhealthy deployments.
          properties:
            enable:
              type: boolean
              description: Whether to enable the deployment circuit breaker.
            rollback:
              type: boolean
              description: Whether to enable automatic rollback on deployment failure.
    Service:
      type: object
      description: Details of an ECS service running Fargate tasks.
      properties:
        serviceArn:
          type: string
          description: The ARN of the service.
        serviceName:
          type: string
          description: The name of the service.
        clusterArn:
          type: string
          description: The ARN of the cluster that hosts the service.
        taskDefinition:
          type: string
          description: The task definition ARN used by the service.
        status:
          type: string
          description: The status of the service.
        desiredCount:
          type: integer
          description: The desired number of tasks for the service.
        runningCount:
          type: integer
          description: The number of tasks currently running.
        pendingCount:
          type: integer
          description: The number of tasks in a pending state.
        launchType:
          type: string
          description: The infrastructure the tasks run on.
          enum:
          - FARGATE
          - EC2
          - EXTERNAL
        platformVersion:
          type: string
          description: The Fargate platform version the tasks run on.
        platformFamily:
          type: string
          description: The operating system the tasks run on.
        schedulingStrategy:
          type: string
          description: The scheduling strategy for the service.
          enum:
          - REPLICA
          - DAEMON
        networkConfiguration:
          $ref: '#/components/schemas/NetworkConfiguration'
        deploymentConfiguration:
          $ref: '#/components/schemas/DeploymentConfiguration'
        deployments:
          type: array
          description: The current deployments for the service.
          items:
            $ref: '#/components/schemas/Deployment'
        loadBalancers:
          type: array
          description: The load balancers associated with the service. Fargate supports Application Load Balancers and Network Load Balancers only.
          items:
            $ref: '#/components/schemas/LoadBalancer'
        serviceRegistries:
          type: array
          description: The service discovery registries for the service.
          items:
            type: object
            properties:
              registryArn:
                type: string
              port:
                type: integer
              containerName:
                type: string
              containerPort:
                type: integer
        enableExecuteCommand:
          type: boolean
          description: Whether ECS Exec is enabled for the service.
        createdAt:
          type: string
          format: date-time
          description: The timestamp when the service was created.
        createdBy:
          type: string
          description: The principal that created the service.
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
    CapacityProviderStrategyItem:
      type: object
      description: A capacity provider strategy item specifying a capacity provider and its weight and base values. Use FARGATE or FARGATE_SPOT for serverless compute.
      required:
      - capacityProvider
      properties:
        capacityProvider:
          type: string
          description: The short name of the capacity provider. Valid Fargate values are FARGATE and FARGATE_SPOT.
        weight:
          type: integer
          description: The relative percentage of the total number of tasks that should use the specified capacity provider.
          minimum: 0
          maximum: 1000
        base:
          type: integer
          description: The number of tasks, at minimum, to run on the specified capacity provider. Only one capacity provider in a strategy can have a base defined.
          minimum: 0
          maximum: 100000
    LoadBalancer:
      type: object
      description: The load balancer configuration for a service. Fargate services support Application Load Balancers (ALB) and Network Load Balancers (NLB) with IP target type.
      properties:
        targetGroupArn:
          type: string
          description: The ARN of the Elastic Load Balancing target group.
        containerName:
          type: string
          description: The name of the container to route traffic to.
        containerPort:
          type: integer
          description: The port on the container to route traffic to.
    CreateServiceRequest:
      type: object
      description: Request to create a Fargate service.
      required:
      - serviceName
      properties:
        cluster:
          type: string
          description: The short name or full ARN of the cluster on which to create the service.
        serviceName:
          type: string
          description: The name of the service. Up to 255 characters.
          maxLength: 255
        taskDefinition:
          type: string
          description: The family and revision (family:revision) or full ARN of the task definition to run in the service.
        desiredCount:
          type: integer
          description: The number of task instances to place and keep running.
          minimum: 0
        launchType:
          type: string
          description: The infrastructure on which to run the service. Use FARGATE for serverless compute.
          enum:
          - FARGATE
          - EC2
          - EXTERNAL
        capacityProviderStrategy:
          type: array
          description: The capacity provider strategy for the service. Cannot be used with launchType.
          items:
            $ref: '#/components/schemas/CapacityProviderStrategyItem'
        platformVersion:
          type: string
          description: The Fargate platform version to run the service on.
          default: LATEST
        networkConfiguration:
          $ref: '#/components/schemas/NetworkConfiguration'
        loadBalancers:
          type: array
          description: The load balancer configuration for the service. Fargate supports ALB and NLB with IP target type only.
          items:
            $ref: '#/components/schemas/LoadBalancer'
        deploymentConfiguration:
          $ref: '#/components/schemas/DeploymentConfiguration'
        schedulingStrategy:
          type: string
          description: The scheduling strategy to use for the service.
          enum:
          - REPLICA
          - DAEMON
          default: REPLICA
        enableExecuteCommand:
          type: boolean
          description: Whether to enable ECS Exec for the tasks in the service.
        enableECSManagedTags:
          type: boolean
          description: Whether to enable Amazon ECS managed tags for the tasks.
        propagateTags:
          type: string
          description: Whether to propagate tags from the task definition or service to the tasks.
          enum:
          - TASK_DEFINITION
          - SERVICE
          - NONE
        serviceRegistries:
          type: array
          description: The service discovery configuration for the service.
          items:
            type: object
            properties:
              registryArn:
                type: string
              port:
                type: integer
              containerName:
                type: string
              containerPort:
                type: integer
        tags:
          type: array
          description: Tags to apply to the service.
          items:
            $ref: '#/components/schemas/Tag'
    ErrorResponse:
      type: object
      properties:
        __type:
          type: string
          description: The error type identifier.
        message:
          type: string
          description: A human-readable error message.
    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
    Deployment:
      type: object
      description: Details of a service deployment.
      properties:
        id:
          type: string
          description: The deployment ID.
        status:
          type: string
          description: The deployment status.
        taskDefinition:
          type: string
          description: The task definition ARN for the deployment.
        desiredCount:
          type: integer
          description: The desired number of tasks in the deployment.
        runningCount:
          type: integer
          description: The number of running tasks in the deployment.
        pendingCount:
          type: integer
          description: The number of pending tasks in the deployment.
        launchType:
          type: string
          description: The launch type used by the deployment.
        platformVersion:
          type: string
          description: The Fargate platform version used by the deployment.
        rolloutState:
          type: string
          description: The rollout state of the deployment.
          enum:
          - COMPLETED
          - FAILED
          - IN_PROGRESS
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        networkConfiguration:
          $ref: '#/components/schemas/NetworkConfiguration'
  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