Create job definitions using EcsProperties - Amazon Batch
ContainerProperties versus EcsProperties job definitionsGeneral changes to the Amazon Batch APIsMulti-container job definitions for Amazon ECSMulti-container job definitions for Amazon EKS
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Create job definitions using EcsProperties

With Amazon Batch job definitions using EcsProperties, you can model hardware, sensors, 3D environments and other simulations in separate containers. You can use this feature to logically organize your workload components, and separate them from the main application. This feature can be used with Amazon Batch on Amazon Elastic Container Service (Amazon ECS), Amazon Elastic Kubernetes Service (Amazon EKS), and Amazon Fargate.

ContainerProperties versus EcsProperties job definitions

You can choose to use ContainerProperties or EcsProperties job definitions as your use case dictates. At a high-level, running Amazon Batch jobs with EcsProperties is similar to running jobs with a ContainerProperties.

The legacy job definition structure, using ContainerProperties, remains supported. If you currently have workflows using this structure, you can continue to run them.

The main difference is that there is a new object added to the job definition to accommodate EcsProperties-based definitions.

For example, a job definition that uses ContainerProperties on Amazon ECS and Fargate has the following structure:

{
   "containerProperties": {
     ...
     "image": "my_ecr_image1",
     ...
  },
...
}

A job definition that uses EcsProperties on Amazon ECS and Fargate has the following structure:

{
  "ecsProperties": {
    "taskProperties": [{
      "containers": [
        { 
          ...
          "image": "my_ecr_image1",
          ...
        },
        { 
          ...
          "image": "my_ecr_image2",
          ...
        },

General changes to the Amazon Batch APIs

The following further outlines some of the key differences when using the ContainerProperties and the EcsProperties API data types:

Multi-container job definitions for Amazon ECS

To accommodate the multi-container structure for Amazon ECS, some of the API data types are different. For example,

  • ecsProperties is the same level as containerProperties in the single-container definition. For more information, see EcsProperties in the Amazon Batch API Reference Guide.

  • taskProperties contains the properties defined for the Amazon ECS task. For more information, see EcsProperties in the Amazon Batch API Reference Guide.

  • containers includes similar information to containerProperties in the single-container definition. The main difference is that containers allows you to define up to ten containers. For more information, see ECSTaskProperties:containers in the Amazon Batch API Reference Guide.

  • essential parameter indicates how the container affects the job. All essential containers must complete successfully (exit as 0) in order for the job to progress. If a container that is marked as essential fails (exits as non-0), then the job fails.

    The default value is true and at least one container must be marked as essential. For more information, see essential in the Amazon Batch API Reference Guide.

  • With the dependsOn parameter, you can define a list of container dependencies. For more information, see dependsOn in the Amazon Batch API Reference Guide.

    Note

    The complexity of the dependsOn list and the associated container runtime can affect the start time for your job. If the dependencies take a long time to run, the job will remain in a STARTING state until they complete.

For more information about the ecsProperties and structure, see RegisterJobDefinition request syntax for ecsProperties.

Multi-container job definitions for Amazon EKS

To accommodate the multi-container structure for Amazon EKS, some of the API data types are different. For example,

  • name is a unique identifier for the container. This object isn't required for a single container, but is required when defining multiple containers in a pod. When name isn't defined for single containers, the default name, default, is applied.

  • initContainers are defined within the eksPodProperties data type. They run before application containers, always runs to completion, and must complete successfully before the next container starts.

    These containers are registered with the Amazon EKS Connector agent and persists the registration information in the Amazon Elastic Kubernetes Service backend data store. The initContainers object can accept up to ten (10) elements. For more information, see Init Containers in the Kubernetes documentation.

    Note

    The initContainers object can affect the start time for your job. If the initContainers take a long time to run, the job will remain in a STARTING state until they complete.

  • shareProcessNamespace indicates if the containers in the pod can share the same process namespace. The default values is false. Setting this to true to enable containers see and signal processes in other containers that located in the same pod.

  • Every container has importance. All containers must complete successfully (exit as 0) for the job to succeed. If one container fails (exits as other than 0), then the job fails.

For more information about the eksProperties and structure, see RegisterJobDefinition request syntax for eksProperties.