AWS Batch
User Guide

Creating a Job Definition

Before you can run jobs in AWS Batch, you must create a job definition.

To create a new job definition

  1. Open the AWS Batch console at https://console.aws.amazon.com/batch/.

  2. From the navigation bar, select the region to use.

  3. In the navigation pane, choose Job definitions, Create.

  4. For Job definition name, enter a unique name for your job definition. Up to 128 letters (uppercase and lowercase), numbers, hyphens, and underscores are allowed.

  5. (Optional) For Job role, you can specify an IAM role that provides the container in your job with permissions to use the AWS APIs. This feature uses Amazon ECS IAM roles for task functionality. For more information, including configuration prerequisites, see IAM Roles for Tasks in the Amazon Elastic Container Service Developer Guide.

    Note

    Only roles that have the Amazon Elastic Container Service Task Role trust relationship are shown here. For more information about creating an IAM role for your AWS Batch jobs, see Creating an IAM Role and Policy for your Tasks in the Amazon Elastic Container Service Developer Guide.

  6. For Container image, choose the Docker image to use for your job. Images in the Docker Hub registry are available by default. You can also specify other repositories with repository-url/image:tag. Up to 255 letters (uppercase and lowercase), numbers, hyphens, underscores, colons, periods, forward slashes, and number signs are allowed. This parameter maps to Image in the Create a container section of the Docker Remote API and the IMAGE parameter of docker run.

    • Images in Amazon ECR repositories use the full registry/repository:tag naming convention. For example, aws_account_id.dkr.ecr.region.amazonaws.com/my-web-app:latest

    • Images in official repositories on Docker Hub use a single name (for example, ubuntu or mongo).

    • Images in other repositories on Docker Hub are qualified with an organization name (for example, amazon/amazon-ecs-agent).

    • Images in other online repositories are qualified further by a domain name (for example, quay.io/assemblyline/ubuntu).

  7. For Command, specify the command to pass to the container. For simple commands, you can type the command as you would at a command prompt in the Space delimited tab. Then, verify that the JSON result (which is passed to the Docker daemon) is correct. For more complicated commands (for example, with special characters), you can switch to the JSON tab and enter the string array equivalent there.

    This parameter maps to Cmd in the Create a container section of the Docker Remote API and the COMMAND parameter to docker run. For more information about the Docker CMD parameter, go to https://docs.docker.com/engine/reference/builder/#cmd.

    Note

    You can use default values for parameter substitution as well as placeholders in your command. For more information, see Parameters.

  8. For vCPUs, specify the number of vCPUs to reserve for the container. This parameter maps to CpuShares in the Create a container section of the Docker Remote API and the --cpu-shares option to docker run. Each vCPU is equivalent to 1,024 CPU shares. You must specify at least 1 vCPU.

  9. For Memory, specify the hard limit (in MiB) of memory to present to the job's container. If your container attempts to exceed the memory specified here, the container is killed. This parameter maps to Memory in the Create a container section of the Docker Remote API and the --memory option to docker run. You must specify at least 4 MiB of memory for a job.

    Note

    If you are trying to maximize your resource utilization by providing your jobs as much memory as possible for a particular instance type, see Compute Resource Memory Management.

  10. For Job attempts, specify the maximum number of times to attempt your job (in case it fails). For more information, see Automated Job Retries.

  11. (Optional) For Execution timeout, specify the maximum number of seconds you would like to allow your job attempts to run. If an attempt exceeds the timeout duration, it is stopped and the status moves to FAILED. For more information, see Job Timeouts.

  12. For Ulimits, configure any ulimit values to use for your job's container.

    1. For Limit name, choose a ulimit to apply.

    2. For Soft limit, choose the soft limit to apply for the ulimit type.

    3. For Hard limit, choose the hard limit to apply for the ulimit type.

  13. (Optional) You can specify default values for parameter substitution as well as placeholders to use in the command that your job's container runs when it starts. For more information, see Parameters.

    1. For Key, specify the key for your parameter.

    2. For Value, specify the value for your parameter.

  14. (Optional) You can specify environment variables to pass to your job's container. This parameter maps to Env in the Create a container section of the Docker Remote API and the --env option to docker run.

    Important

    We do not recommend using plaintext environment variables for sensitive information, such as credential data.

    1. For Key, specify the key for your environment variable.

      Note

      Environment variables must not start with AWS_BATCH; this naming convention is reserved for variables that are set by the AWS Batch service.

    2. For Value, specify the value for your environment variable.

  15. (Optional) In the Security section, you can configure security options for your job's container.

    1. To give your job's container elevated privileges on the host instance (similar to the root user), select Privileged. This parameter maps to Privileged in the Create a container section of the Docker Remote API and the --privileged option to docker run.

    2. For User, enter the user name to use inside the container. This parameter maps to User in the Create a container section of the Docker Remote API and the --user option to docker run.

  16. (Optional) You can specify data volumes for your job to pass to your job's container.

    1. For Name, enter a name for your volume. Up to 255 letters (uppercase and lowercase), numbers, hyphens, and underscores are allowed.

    2. (Optional) For Source Path, enter the path on the host instance to present to the container. If you leave this field empty, then the Docker daemon assigns a host path for you. If you specify a source path, then the data volume persists at the specified location on the host container instance until you delete it manually. If the source path does not exist on the host container instance, the Docker daemon creates it. If the location does exist, the contents of the source path folder are exported to the container.

  17. (Optional) Specify mount points for your job's container to access.

    1. For Container path, enter the path on the container at which to mount the host volume.

    2. For Source volume, enter the name of the volume to mount.

    3. To make the volume read-only for the container, choose Read-only.

  18. Choose Create job definition.