Amazon ECS Ecs Express Gateway Service API

openapi: 3.2.0
info:
  title: Amazon EC2 Container Service Express Gateway Service API
  version: '2014-11-13'
  description: Generated from AWS's published Smithy model for Amazon EC2 Container Service. 4 operation(s).
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/contact-us/
  license:
    name: Apache 2.0
    identifier: Apache-2.0
    url: https://github.com/aws/api-models-aws/blob/main/LICENSE
servers:
- url: https://ecs.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
tags:
- name: Express Gateway Service
paths:
  /#CreateExpressGatewayService:
    post:
      operationId: CreateExpressGatewayService
      summary: Create Express Gateway Service
      description: Creates an Express service that simplifies deploying containerized web applications on Amazon ECS with managed Amazon Web Services infrastructure. This operation provisions and configures Application Load Balancers, target groups, security groups, and auto-scaling policies automatically. Specify a primary container configuration with your application image and basic settings. Amazon ECS creates the necessary Amazon Web Services resources for traffic distribution, health monitoring, network access control, and capacity management. Provide an execution role for task operations and an infrastructure role for managing Amazon Web Services resources on your behalf.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/CreateExpressGatewayServiceResponse'
        '403':
          description: AccessDeniedException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '400':
          description: ClientException; ClusterNotFoundException; InvalidParameterException; PlatformTaskDefinitionIncompatibilityException; PlatformUnknownException; UnsupportedFeatureException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ClientException'
        '500':
          description: ServerException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ServerException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - AmazonEC2ContainerServiceV20141113.CreateExpressGatewayService
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/CreateExpressGatewayServiceRequest'
      tags:
      - Express Gateway Service
  /#DeleteExpressGatewayService:
    post:
      operationId: DeleteExpressGatewayService
      summary: Delete Express Gateway Service
      description: Deletes an Express service and removes all associated Amazon Web Services resources. This operation stops service tasks, removes the Application Load Balancer, target groups, security groups, auto-scaling policies, and other managed infrastructure components. The service enters a DRAINING state where existing tasks complete current requests without starting new tasks. After all tasks stop, the service and infrastructure are permanently removed. This operation cannot be reversed. Back up important data and verify the service is no longer needed before deletion.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/DeleteExpressGatewayServiceResponse'
        '403':
          description: AccessDeniedException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '400':
          description: ClientException; ClusterNotFoundException; InvalidParameterException; ServiceNotActiveException; ServiceNotFoundException; UnsupportedFeatureException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ClientException'
        '500':
          description: ServerException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ServerException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - AmazonEC2ContainerServiceV20141113.DeleteExpressGatewayService
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/DeleteExpressGatewayServiceRequest'
      tags:
      - Express Gateway Service
  /#DescribeExpressGatewayService:
    post:
      operationId: DescribeExpressGatewayService
      summary: Describe Express Gateway Service
      description: Retrieves detailed information about an Express service, including current status, configuration, managed infrastructure, and service revisions. Returns comprehensive service details, active service revisions, ingress paths with endpoints, and managed Amazon Web Services resource status including load balancers and auto-scaling policies. Use the include parameter to retrieve additional information such as resource tags.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/DescribeExpressGatewayServiceResponse'
        '403':
          description: AccessDeniedException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '400':
          description: ClientException; ClusterNotFoundException; InvalidParameterException; ResourceNotFoundException; UnsupportedFeatureException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ClientException'
        '500':
          description: ServerException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ServerException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - AmazonEC2ContainerServiceV20141113.DescribeExpressGatewayService
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/DescribeExpressGatewayServiceRequest'
      tags:
      - Express Gateway Service
  /#UpdateExpressGatewayService:
    post:
      operationId: UpdateExpressGatewayService
      summary: Update Express Gateway Service
      description: Updates an existing Express service configuration. Modifies container settings, resource allocation, auto-scaling configuration, and other service parameters without recreating the service. Amazon ECS creates a new service revision with updated configuration and performs a rolling deployment to replace existing tasks. The service remains available during updates, ensuring zero-downtime deployments. Some parameters like the infrastructure role cannot be modified after service creation and require creating a new service.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/UpdateExpressGatewayServiceResponse'
        '403':
          description: AccessDeniedException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '400':
          description: ClientException; ClusterNotFoundException; InvalidParameterException; ServiceNotActiveException; ServiceNotFoundException; UnsupportedFeatureException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ClientException'
        '500':
          description: ServerException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ServerException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - AmazonEC2ContainerServiceV20141113.UpdateExpressGatewayService
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/UpdateExpressGatewayServiceRequest'
      tags:
      - Express Gateway Service
components:
  schemas:
    Tag:
      type: object
      properties:
        key:
          type: string
          description: One part of a key-value pair that make up a tag. A key is a general label that acts like a category for more specific tag values.
        value:
          type: string
          description: The optional part of a key-value pair that make up a tag. A value acts as a descriptor within a tag category (key).
    DeleteExpressGatewayServiceResponse:
      type: object
      properties:
        service:
          $ref: '#/components/schemas/ECSExpressGatewayService'
    ServerException:
      type: object
      properties:
        message:
          type: string
          description: Message that describes the cause of the exception.
    ECSExpressGatewayService:
      type: object
      properties:
        cluster:
          type: string
          description: The short name or full ARN of the cluster that hosts the Express service.
        serviceName:
          type: string
          description: The name of the Express service.
        serviceArn:
          type: string
          description: The ARN that identifies the Express service.
        infrastructureRoleArn:
          type: string
          description: The ARN of the infrastructure role that manages Amazon Web Services resources for the Express service.
        status:
          $ref: '#/components/schemas/ExpressGatewayServiceStatus'
        currentDeployment:
          type: string
          description: The current deployment configuration for the Express service.
        activeConfigurations:
          type: array
          items:
            $ref: '#/components/schemas/ExpressGatewayServiceConfiguration'
          description: The list of active service configurations for the Express service.
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
          description: The metadata applied to the Express service.
        createdAt:
          type: string
          format: date-time
          description: The Unix timestamp for when the Express service was created.
        updatedAt:
          type: string
          format: date-time
          description: The Unix timestamp for when the Express service was last updated.
    UpdateExpressGatewayServiceResponse:
      type: object
      properties:
        service:
          $ref: '#/components/schemas/UpdatedExpressGatewayService'
    ClientException:
      type: object
      properties:
        message:
          type: string
          description: Message that describes the cause of the exception.
    Secret:
      type: object
      properties:
        name:
          type: string
          description: The name of the secret.
        valueFrom:
          type: string
          description: The secret to expose to the container. The supported values are either the full ARN of the Secrets Manager secret or the full ARN of the parameter in the SSM Parameter Store. For information about the require Identity and Access Management permissions, see Required IAM permissions for Amazon ECS secrets (for Secrets Manager) or Required IAM permissions for Amazon ECS secrets (for Systems Manager Parameter store) in the Amazon Elastic Container Service Developer Guide. If the SSM Parameter Store parameter exists in the same Region as the task you're launching, then you can use either the full A
      required:
      - name
      - valueFrom
    UpdatedExpressGatewayService:
      type: object
      properties:
        serviceArn:
          type: string
          description: The ARN of the Express service that is being updated.
        cluster:
          type: string
          description: The cluster associated with the Express service that is being updated.
        serviceName:
          type: string
          description: The name of the Express service that is being updated.
        status:
          $ref: '#/components/schemas/ExpressGatewayServiceStatus'
        targetConfiguration:
          $ref: '#/components/schemas/ExpressGatewayServiceConfiguration'
        createdAt:
          type: string
          format: date-time
          description: The Unix timestamp for when the Express service that is being updated was created.
        updatedAt:
          type: string
          format: date-time
          description: The Unix timestamp for when the Express service that is being updated was most recently updated.
    KeyValuePair:
      type: object
      properties:
        name:
          type: string
          description: The name of the key-value pair. For environment variables, this is the name of the environment variable.
        value:
          type: string
          description: The value of the key-value pair. For environment variables, this is the value of the environment variable.
    ExpressGatewayServiceNetworkConfiguration:
      type: object
      properties:
        securityGroups:
          type: array
          items:
            type: string
          description: The IDs of the security groups associated with the Express service.
        subnets:
          type: array
          items:
            type: string
          description: The IDs of the subnets associated with the Express service.
    ExpressGatewayRepositoryCredentials:
      type: object
      properties:
        credentialsParameter:
          type: string
          description: The Amazon Resource Name (ARN) of the secret containing the private repository credentials.
    ExpressGatewayServiceAwsLogsConfiguration:
      type: object
      properties:
        logGroup:
          type: string
          description: The name of the CloudWatch Logs log group to send container logs to.
        logStreamPrefix:
          type: string
          description: The prefix for the CloudWatch Logs log stream names. The default for an Express service is ecs.
      required:
      - logGroup
      - logStreamPrefix
    CreateExpressGatewayServiceResponse:
      type: object
      properties:
        service:
          $ref: '#/components/schemas/ECSExpressGatewayService'
    ExpressGatewayContainer:
      type: object
      properties:
        image:
          type: string
          description: The image used to start a container. This string is passed directly to the Docker daemon. Images in the Docker Hub registry are available by default. Other repositories are specified with either repository-url/image:tag or repository-url/image@digest. For Express services, the image typically contains a web application that listens on the specified container port. The image can be stored in Amazon ECR, Docker Hub, or any other container registry accessible to your execution role.
        containerPort:
          type: integer
          description: The port number on the container that receives traffic from the load balancer. Default is 80.
        awsLogsConfiguration:
          $ref: '#/components/schemas/ExpressGatewayServiceAwsLogsConfiguration'
        repositoryCredentials:
          $ref: '#/components/schemas/ExpressGatewayRepositoryCredentials'
        command:
          type: array
          items:
            type: string
          description: The command that is passed to the container.
        environment:
          type: array
          items:
            $ref: '#/components/schemas/KeyValuePair'
          description: The environment variables to pass to the container.
        secrets:
          type: array
          items:
            $ref: '#/components/schemas/Secret'
          description: The secrets to pass to the container.
      required:
      - image
    CreateExpressGatewayServiceRequest:
      type: object
      properties:
        executionRoleArn:
          type: string
          description: 'The Amazon Resource Name (ARN) of the task execution role that grants the Amazon ECS container agent permission to make Amazon Web Services API calls on your behalf. This role is required for Amazon ECS to pull container images from Amazon ECR, send container logs to Amazon CloudWatch Logs, and retrieve sensitive data from Amazon Web Services Systems Manager Parameter Store or Amazon Web Services Secrets Manager. The execution role must include the AmazonECSTaskExecutionRolePolicy managed policy or equivalent permissions. For Express services, this role is used during task startup and runtime '
        infrastructureRoleArn:
          type: string
          description: The Amazon Resource Name (ARN) of the infrastructure role that grants Amazon ECS permission to create and manage Amazon Web Services resources on your behalf for the Express service. This role is used to provision and manage Application Load Balancers, target groups, security groups, auto-scaling policies, and other Amazon Web Services infrastructure components. The infrastructure role must include permissions for Elastic Load Balancing, Application Auto Scaling, Amazon EC2 (for security groups), and other services required for managed infrastructure. This role is only used during Express serv
        serviceName:
          type: string
          description: The name of the Express service. This name must be unique within the specified cluster and can contain up to 255 letters (uppercase and lowercase), numbers, underscores, and hyphens. The name is used to identify the service in the Amazon ECS console and API operations. If you don't specify a service name, Amazon ECS generates a unique name for the service. The service name becomes part of the service ARN and cannot be changed after the service is created.
        cluster:
          type: string
          description: The short name or full Amazon Resource Name (ARN) of the cluster on which to create the Express service. If you do not specify a cluster, the default cluster is assumed.
        healthCheckPath:
          type: string
          description: 'The path on the container that the Application Load Balancer uses for health checks. This should be a valid HTTP endpoint that returns a successful response (HTTP 200) when the application is healthy. If not specified, the default health check path is /ping. The health check path must start with a forward slash and can include query parameters. Examples: /health, /api/status, /ping?format=json.'
        primaryContainer:
          $ref: '#/components/schemas/ExpressGatewayContainer'
        taskRoleArn:
          type: string
          description: The Amazon Resource Name (ARN) of the IAM role that containers in this task can assume. This role allows your application code to access other Amazon Web Services services securely. The task role is different from the execution role. While the execution role is used by the Amazon ECS agent to set up the task, the task role is used by your application code running inside the container to make Amazon Web Services API calls. If your application doesn't need to access Amazon Web Services services, you can omit this parameter.
        networkConfiguration:
          $ref: '#/components/schemas/ExpressGatewayServiceNetworkConfiguration'
        cpu:
          type: string
          description: The number of CPU units used by the task. This parameter determines the CPU allocation for each task in the Express service. The default value for an Express service is 256 (.25 vCPU).
        memory:
          type: string
          description: The amount of memory (in MiB) used by the task. This parameter determines the memory allocation for each task in the Express service. The default value for an express service is 512 MiB.
        cpuArchitecture:
          type: string
          enum:
          - X86_64
          - ARM64
          description: 'The CPU architecture that the task runs on. If you don''t specify a value, the default is X86_64. Valid values: X86_64 - The x86 64-bit architecture. ARM64 - The 64-bit ARM architecture. Ensure that the container image you specify supports the architecture you choose. The operating system family for an Express service is always LINUX. You can''t specify cpuArchitecture together with taskDefinitionArn.'
        scalingTarget:
          $ref: '#/components/schemas/ExpressGatewayScalingTarget'
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
          description: The metadata that you apply to the Express service to help categorize and organize it. Each tag consists of a key and an optional value. You can apply up to 50 tags to a service.
        taskDefinitionArn:
          type: string
          description: The Amazon Resource Name (ARN) of a task definition to use to create the Express Gateway service. This allows you to manage your own task definition, giving you more control over the service configuration such as adding sidecar containers. The task definition must have a container named Main with a single TCP port mapping that includes a container port and port name. The task definition must also have FARGATE compatibility. If you provide a task definition ARN, you cannot also specify primaryContainer, executionRoleArn, taskRoleArn, cpu, memory, or cpuArchitecture.
      required:
      - infrastructureRoleArn
    DescribeExpressGatewayServiceRequest:
      type: object
      properties:
        serviceArn:
          type: string
          description: The Amazon Resource Name (ARN) of the Express service to describe. The ARN uniquely identifies the service within your Amazon Web Services account and region.
        include:
          type: array
          items:
            type: string
            enum:
            - TAGS
          description: Specifies additional information to include in the response. Valid values are TAGS to include resource tags associated with the Express service.
      required:
      - serviceArn
    ExpressGatewayServiceStatus:
      type: object
      properties:
        statusCode:
          type: string
          enum:
          - ACTIVE
          - DRAINING
          - INACTIVE
          description: The status of the Express service.
        statusReason:
          type: string
          description: Information about why the Express service is in the current status.
    IngressPathSummary:
      type: object
      properties:
        accessType:
          type: string
          enum:
          - PUBLIC
          - PRIVATE
          description: The type of access to the endpoint for the Express service.
        endpoint:
          type: string
          description: The endpoint for access to the service.
      required:
      - accessType
      - endpoint
    ExpressGatewayScalingTarget:
      type: object
      properties:
        minTaskCount:
          type: integer
          description: The minimum number of tasks to run in the Express service.
        maxTaskCount:
          type: integer
          description: The maximum number of tasks to run in the Express service.
        autoScalingMetric:
          type: string
          enum:
          - AVERAGE_CPU
          - AVERAGE_MEMORY
          - REQUEST_COUNT_PER_TARGET
          description: The metric used for auto-scaling decisions. The default metric used for an Express service is CPUUtilization.
        autoScalingTargetValue:
          type: integer
          description: The target value for the auto-scaling metric. The default value for an Express service is 60.
    ExpressGatewayServiceConfiguration:
      type: object
      properties:
        serviceRevisionArn:
          type: string
          description: The ARN of the service revision.
        executionRoleArn:
          type: string
          description: The ARN of the task execution role for the service revision.
        taskRoleArn:
          type: string
          description: The ARN of the task role for the service revision.
        taskDefinitionArn:
          type: string
          description: The ARN of the task definition used by this service revision. This is present for all Express services and reflects the task definition in use, whether managed by Amazon ECS or provided by the customer.
        cpu:
          type: string
          description: The CPU allocation for tasks in this service revision.
        memory:
          type: string
          description: The memory allocation for tasks in this service revision.
        cpuArchitecture:
          type: string
          enum:
          - X86_64
          - ARM64
          description: 'The CPU architecture that the task runs on. Valid values: X86_64 - The x86 64-bit architecture. ARM64 - The 64-bit ARM architecture. Different service revisions can report different architectures. This value isn''t returned when the service uses a customer-provided task definition that doesn''t specify a CPU architecture.'
        networkConfiguration:
          $ref: '#/components/schemas/ExpressGatewayServiceNetworkConfiguration'
        healthCheckPath:
          type: string
          description: The health check path for this service revision.
        primaryContainer:
          $ref: '#/components/schemas/ExpressGatewayContainer'
        scalingTarget:
          $ref: '#/components/schemas/ExpressGatewayScalingTarget'
        ingressPaths:
          type: array
          items:
            $ref: '#/components/schemas/IngressPathSummary'
          description: The entry point into this service revision.
        createdAt:
          type: string
          format: date-time
          description: The Unix timestamp for when this service revision was created.
    UpdateExpressGatewayServiceRequest:
      type: object
      properties:
        serviceArn:
          type: string
          description: The Amazon Resource Name (ARN) of the Express service to update.
        executionRoleArn:
          type: string
          description: The Amazon Resource Name (ARN) of the task execution role for the Express service.
        healthCheckPath:
          type: string
          description: The path on the container for Application Load Balancer health checks.
        primaryContainer:
          $ref: '#/components/schemas/ExpressGatewayContainer'
        taskRoleArn:
          type: string
          description: The Amazon Resource Name (ARN) of the IAM role for containers in this task.
        networkConfiguration:
          $ref: '#/components/schemas/ExpressGatewayServiceNetworkConfiguration'
        cpu:
          type: string
          description: The number of CPU units used by the task.
        memory:
          type: string
          description: The amount of memory (in MiB) used by the task.
        cpuArchitecture:
          type: string
          enum:
          - X86_64
          - ARM64
          description: 'The CPU architecture that the task runs on. If you don''t specify a value, the service keeps its current architecture. Valid values: X86_64 - The x86 64-bit architecture. ARM64 - The 64-bit ARM architecture. Changing the architecture starts a new deployment that replaces the running tasks. Ensure that the container image you specify supports the architecture you choose. The operating system family for an Express service is always LINUX. You can''t specify cpuArchitecture together with taskDefinitionArn.'
        scalingTarget:
          $ref: '#/components/schemas/ExpressGatewayScalingTarget'
        taskDefinitionArn:
          type: string
          description: The Amazon Resource Name (ARN) of a task definition to use to update the Express Gateway service. This allows you to manage your own task definition, giving you more control over the service configuration such as adding sidecar containers. The task definition must have a container named Main with a single TCP port mapping that includes a container port and port name. The task definition must also have FARGATE compatibility. If you provide a task definition ARN, you cannot also specify primaryContainer, executionRoleArn, taskRoleArn, cpu, memory, or cpuArchitecture.
      required:
      - serviceArn
    AccessDeniedException:
      type: object
      properties:
        message:
          type: string
          description: Message that describes the cause of the exception.
    DeleteExpressGatewayServiceRequest:
      type: object
      properties:
        serviceArn:
          type: string
          description: The Amazon Resource Name (ARN) of the Express service to delete. The ARN uniquely identifies the service within your Amazon Web Services account and region.
      required:
      - serviceArn
    DescribeExpressGatewayServiceResponse:
      type: object
      properties:
        service:
          $ref: '#/components/schemas/ECSExpressGatewayService'
  securitySchemes:
    sigv4:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4. The Authorization header carries an AWS4-HMAC-SHA256 signature over the canonical request, with X-Amz-Date (and X-Amz-Security-Token for temporary credentials). Not a bearer token.
      x-aws-sigv4:
        signingName: ecs
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/582e55931c45b944739742a2c1620b6026dd2d13/models/ecs/service/2014-11-13/ecs-2014-11-13.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)