View a markdown version of this page

AWS Batch examples using AWS CLI - AWS SDK Code Examples
Actions

There are more AWS SDK examples available in the AWS Doc SDK Examples GitHub repo.

AWS Batch examples using AWS CLI

The following code examples show you how to perform actions and implement common scenarios by using the AWS Command Line Interface with AWS Batch.

Actions are code excerpts from larger programs and must be run in context. While actions show you how to call individual service functions, you can see actions in context in their related scenarios.

Each example includes a link to the complete source code, where you can find instructions on how to set up and run the code in context.

Topics

Actions

The following code example shows how to use cancel-job.

AWS CLI

To cancel a job

The following cancel-job example cancels a job with the specified job ID.

aws batch cancel-job \
    --job-id a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 \
    --reason "Cancelling job."

This command produces no output.

For more information, see Job states in the AWS Batch User Guide.

  • For API details, see CancelJob in AWS CLI Command Reference.

The following code example shows how to use create-compute-environment.

AWS CLI

Example 1: To create a managed compute environment with On-Demand instances

The following create-compute-environment example creates a managed compute environment with specific C4 instance types that are launched on demand. The compute environment is called C4OnDemand.

aws batch create-compute-environment \
    --cli-input-json file://<path_to_json_file>/C4OnDemand.json

Contents of C4OnDemand.json:

{
    "computeEnvironmentName": "C4OnDemand",
    "type": "MANAGED",
    "state": "ENABLED",
    "computeResources": {
        "type": "EC2",
        "minvCpus": 0,
        "maxvCpus": 128,
        "desiredvCpus": 48,
        "instanceTypes": [
            "c4.large",
            "c4.xlarge",
            "c4.2xlarge",
            "c4.4xlarge",
            "c4.8xlarge"
        ],
        "subnets": [
            "subnet-220c0e0a",
            "subnet-1a95556d",
            "subnet-978f6dce"
        ],
        "securityGroupIds": [
            "sg-cf5093b2"
        ],
        "ec2KeyPair": "id_rsa",
        "instanceRole": "ecsInstanceRole",
        "tags": {
            "Name": "Batch Instance - C4OnDemand"
        }
    },
    "serviceRole": "arn:aws:iam::123456789012:role/AWSBatchServiceRole"
}

Output:

{
    "computeEnvironmentName": "C4OnDemand",
    "computeEnvironmentArn": "arn:aws:batch:us-west-2:123456789012:compute-environment/C4OnDemand"
}

For more information, see Create a compute environment in the AWS Batch User Guide.

Example 2: To create a managed compute environment with Spot Instances

The following create-compute-environment example creates a managed compute environment with the M4 instance type that is launched when the Spot bid price is at or below 20% of the On-Demand price for the instance type. The compute environment is called M4Spot.

aws batch create-compute-environment \
    --cli-input-json file://<path_to_json_file>/M4Spot.json

Contents of M4Spot.json:

{
    "computeEnvironmentName": "M4Spot",
    "type": "MANAGED",
    "state": "ENABLED",
    "computeResources": {
        "type": "SPOT",
        "spotIamFleetRole": "arn:aws:iam::123456789012:role/aws-ec2-spot-fleet-role",
        "minvCpus": 0,
        "maxvCpus": 128,
        "desiredvCpus": 4,
        "instanceTypes": [
            "m4"
        ],
        "bidPercentage": 20,
        "subnets": [
            "subnet-220c0e0a",
            "subnet-1a95556d",
            "subnet-978f6dce"
        ],
        "securityGroupIds": [
            "sg-cf5093b2"
        ],
        "ec2KeyPair": "id_rsa",
        "instanceRole": "ecsInstanceRole",
        "tags": {
            "Name": "Batch Instance - M4Spot"
        }
    },
    "serviceRole": "arn:aws:iam::123456789012:role/AWSBatchServiceRole"
}

Output:

{
    "computeEnvironmentName": "M4Spot",
    "computeEnvironmentArn": "arn:aws:batch:us-west-2:123456789012:compute-environment/M4Spot"
}

For more information, see Create a compute environment in the AWS Batch User Guide.

The following code example shows how to use create-job-queue.

AWS CLI

Example 1: To create a low priority job queue with a single compute environment

The following create-job-queue example creates a job queue called LowPriority that uses the M4Spot compute environment.

aws batch create-job-queue \
    --cli-input-json file://<path_to_json_file>/LowPriority.json

Contents of LowPriority.json:

{
    "jobQueueName": "LowPriority",
    "state": "ENABLED",
    "priority": 10,
    "computeEnvironmentOrder": [
        {
            "order": 1,
            "computeEnvironment": "M4Spot"
        }
    ]
}

Output:

{
    "jobQueueArn": "arn:aws:batch:us-west-2:123456789012:job-queue/LowPriority",
    "jobQueueName": "LowPriority"
}

For more information, see Create a job queue in the AWS Batch User Guide.

Example 2: To create a high priority job queue with two compute environments

The following create-job-queue example creates a job queue called HighPriority that uses the C4OnDemand compute environment with an order of 1 and the M4Spot compute environment with an order of 2. The scheduler will attempt to place jobs on the C4OnDemand compute environment first.

aws batch create-job-queue \
    --cli-input-json file://<path_to_json_file>/HighPriority.json

Contents of HighPriority.json:

{
    "jobQueueName": "HighPriority",
    "state": "ENABLED",
    "priority": 1,
    "computeEnvironmentOrder": [
        {
            "order": 1,
            "computeEnvironment": "C4OnDemand"
        },
        {
            "order": 2,
            "computeEnvironment": "M4Spot"
        }
    ]
}

Output:

{
    "jobQueueArn": "arn:aws:batch:us-west-2:123456789012:job-queue/HighPriority",
    "jobQueueName": "HighPriority"
}

For more information, see Create a job queue in the AWS Batch User Guide.

The following code example shows how to use delete-compute-environment.

AWS CLI

To delete a compute environment

The following delete-compute-environment example deletes the P2OnDemand compute environment.

aws batch delete-compute-environment \
    --compute-environment P2OnDemand

This command produces no output.

For more information, see Compute environments for AWS Batch in the AWS Batch User Guide.

The following code example shows how to use delete-job-queue.

AWS CLI

To delete a job queue

The following delete-job-queue example deletes the GPGPU job queue.

aws batch delete-job-queue \
    --job-queue GPGPU

This command produces no output.

For more information, see Delete a job queue in AWS Batch in the AWS Batch User Guide.

The following code example shows how to use deregister-job-definition.

AWS CLI

To deregister a job definition

The following deregister-job-definition example deregisters a job definition called sleep10.

aws batch deregister-job-definition \
    --job-definition sleep10

This command produces no output.

For more information, see Job definitions in the AWS Batch User Guide.

The following code example shows how to use describe-compute-environments.

AWS CLI

To describe a compute environment

The following describe-compute-environments example describes the P2OnDemand compute environment.

aws batch describe-compute-environments \
    --compute-environments P2OnDemand

Output:

{
    "computeEnvironments": [
        {
            "status": "VALID",
            "serviceRole": "arn:aws:iam::123456789012:role/AWSBatchServiceRole",
            "computeEnvironmentArn": "arn:aws:batch:us-west-2:123456789012:compute-environment/P2OnDemand",
            "computeResources": {
                "subnets": [
                    "subnet-220c0e0a",
                    "subnet-1a95556d",
                    "subnet-978f6dce"
                ],
                "tags": {
                    "Name": "Batch Instance - P2OnDemand"
                },
                "desiredvCpus": 48,
                "minvCpus": 0,
                "instanceTypes": [
                    "p2"
                ],
                "securityGroupIds": [
                    "sg-cf5093b2"
                ],
                "instanceRole": "ecsInstanceRole",
                "maxvCpus": 128,
                "type": "EC2",
                "ec2KeyPair": "id_rsa"
            },
            "statusReason": "ComputeEnvironment Healthy",
            "ecsClusterArn": "arn:aws:ecs:us-west-2:123456789012:cluster/P2OnDemand_Batch_2c06f29d-d1fe-3a49-879d-42394c86effc",
            "state": "ENABLED",
            "computeEnvironmentName": "P2OnDemand",
            "type": "MANAGED"
        }
    ]
}

For more information, see Compute environments for AWS Batch in the AWS Batch User Guide.

The following code example shows how to use describe-job-definitions.

AWS CLI

To describe active job definitions

The following describe-job-definitions example describes all of your active job definitions.

aws batch describe-job-definitions \
    --status ACTIVE

Output:

{
    "jobDefinitions": [
        {
            "status": "ACTIVE",
            "jobDefinitionArn": "arn:aws:batch:us-west-2:123456789012:job-definition/sleep60:1",
            "containerProperties": {
                "mountPoints": [],
                "image": "busybox",
                "environment": [],
                "vcpus": 1,
                "command": [
                    "sleep",
                    "60"
                ],
                "volumes": [],
                "memory": 128,
                "ulimits": []
            },
            "parameters": {},
            "type": "container",
            "jobDefinitionName": "sleep60",
            "revision": 1
        }
    ]
}

For more information, see Job definitions in the AWS Batch User Guide.

The following code example shows how to use describe-job-queues.

AWS CLI

To describe a job queue

The following describe-job-queues example describes the HighPriority job queue.

aws batch describe-job-queues \
    --job-queues HighPriority

Output:

{
    "jobQueues": [
        {
            "status": "VALID",
            "jobQueueArn": "arn:aws:batch:us-west-2:123456789012:job-queue/HighPriority",
            "computeEnvironmentOrder": [
                {
                    "computeEnvironment": "arn:aws:batch:us-west-2:123456789012:compute-environment/C4OnDemand",
                    "order": 1
                }
            ],
            "statusReason": "JobQueue Healthy",
            "priority": 1,
            "state": "ENABLED",
            "jobQueueName": "HighPriority"
        }
    ]
}

For more information, see Job queues in the AWS Batch User Guide.

The following code example shows how to use describe-jobs.

AWS CLI

To describe a job

The following describe-jobs example describes a job with the specified job ID.

aws batch describe-jobs \
    --jobs a1b2c3d4-5678-90ab-cdef-EXAMPLE11111

Output:

{
    "jobs": [
        {
            "status": "SUBMITTED",
            "container": {
                "mountPoints": [],
                "image": "busybox",
                "environment": [],
                "vcpus": 1,
                "command": [
                    "sleep",
                    "60"
                ],
                "volumes": [],
                "memory": 128,
                "ulimits": []
            },
            "parameters": {},
            "jobDefinition": "arn:aws:batch:us-west-2:123456789012:job-definition/sleep60:1",
            "jobQueue": "arn:aws:batch:us-west-2:123456789012:job-queue/HighPriority",
            "jobId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
            "dependsOn": [],
            "jobName": "example",
            "createdAt": 1480483387803
        }
    ]
}

For more information, see Jobs in the AWS Batch User Guide.

  • For API details, see DescribeJobs in AWS CLI Command Reference.

The following code example shows how to use list-jobs.

AWS CLI

Example 1: To list running jobs

The following list-jobs example lists the running jobs in the HighPriority job queue.

aws batch list-jobs \
    --job-queue HighPriority

Output:

{
    "jobSummaryList": [
        {
            "jobName": "example",
            "jobId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
        }
    ]
}

For more information, see Job states in the AWS Batch User Guide.

Example 2: To list submitted jobs

The following list-jobs example lists jobs in the HighPriority job queue that are in the SUBMITTED job status.

aws batch list-jobs \
    --job-queue HighPriority \
    --job-status SUBMITTED

Output:

{
    "jobSummaryList": [
        {
            "jobName": "example",
            "jobId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE22222"
        }
    ]
}

For more information, see Job states in the AWS Batch User Guide.

  • For API details, see ListJobs in AWS CLI Command Reference.

The following code example shows how to use register-job-definition.

AWS CLI

To register a job definition

The following register-job-definition example registers a job definition for a simple container job.

aws batch register-job-definition \
    --job-definition-name sleep30 \
    --type container \
    --container-properties '{ "image": "busybox", "vcpus": 1, "memory": 128, "command": [ "sleep", "30"]}'

Output:

{
    "jobDefinitionArn": "arn:aws:batch:us-west-2:123456789012:job-definition/sleep30:1",
    "jobDefinitionName": "sleep30",
    "revision": 1
}

For more information, see Create a single-node job definition in the AWS Batch User Guide.

The following code example shows how to use submit-job.

AWS CLI

To submit a job

The following submit-job example submits a simple container job called example to the HighPriority job queue.

aws batch submit-job \
    --job-name example \
    --job-queue HighPriority \
    --job-definition sleep60

Output:

{
    "jobName": "example",
    "jobId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
}

For more information, see Tutorial: submit a job in the AWS Batch User Guide.

  • For API details, see SubmitJob in AWS CLI Command Reference.

The following code example shows how to use terminate-job.

AWS CLI

To terminate a job

The following terminate-job example terminates a job with the specified job ID.

aws batch terminate-job \
    --job-id a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 \
    --reason "Terminating job."

This command produces no output.

For more information, see Job states in the AWS Batch User Guide.

  • For API details, see TerminateJob in AWS CLI Command Reference.

The following code example shows how to use update-compute-environment.

AWS CLI

To update a compute environment

The following update-compute-environment example disables the P2OnDemand compute environment so it can be deleted.

aws batch update-compute-environment \
    --compute-environment P2OnDemand \
    --state DISABLED

Output:

{
    "computeEnvironmentName": "P2OnDemand",
    "computeEnvironmentArn": "arn:aws:batch:us-west-2:123456789012:compute-environment/P2OnDemand"
}

For more information, see Update a compute environment in AWS Batch in the AWS Batch User Guide.

The following code example shows how to use update-job-queue.

AWS CLI

To update a job queue

The following update-job-queue example disables a job queue so that it can be deleted.

aws batch update-job-queue \
    --job-queue GPGPU \
    --state DISABLED

Output:

{
    "jobQueueArn": "arn:aws:batch:us-west-2:123456789012:job-queue/GPGPU",
    "jobQueueName": "GPGPU"
}

For more information, see Delete a job queue in AWS Batch in the AWS Batch User Guide.