# Resource-aware scheduling
<a name="resource-aware-scheduling"></a>

AWS Batch schedules jobs based on the vCPU, GPU and the memory availability in the Compute Environment (CE) associated with the Job Queue (JQ). But sometimes, just the availability of these CE resources doesn't guarantee that the job will run successfully since it might be dependent on other required resources, so these jobs are cancelled or terminated. This results in inefficient use of compute resources. To solve this issue, resource-aware scheduling can check the availability of dependent, non-CE resources before it schedules the job to run on a CE.

AWS Batch resource-aware scheduling lets you schedule jobs based on consumable resources that are needed to run your jobs– 3rd party license tokens, database access bandwidth, the need to throttle calls to a third-party API, and so on. You specify the consumable resources which are needed for a job to run, and Batch takes these resource dependencies into account when it schedules a job. You can avoid making manual interventions to eliminate job failures and long waits caused by a shortage of consumable resources. You can reduce the under-utilization of compute resources by allocating only the jobs that have all the required resources available.

Resource-aware scheduling is available for both FIFO and Fair-share scheduling policies and can be used with all compute platforms supported by Batch including EKS, ECS, and Fargate. It can be used with Array jobs, Multi-node parallel (MNP) jobs, and with regular Batch jobs.

To configure resource-aware scheduling, you first specify all the consumable resources needed to run your jobs, along with the total count available of each resource. Then, for each job that requires a consumable resource, you specify the name and required quantities of each resource needed. Batch keeps track of how many consumable resources are available for the jobs in your job queues and makes sure that a job is scheduled to run only when all the required consumable resources are available for the job to run successfully. 

**Topics**
+ [Create consumable resources](resource-aware-scheduling-how-to-create.md)
+ [Specify the resources needed to run a job](resource-aware-scheduling-how-to-for-jobs.md)
+ [Check how many resources are in-use and available](resource-aware-scheduling-how-to-check-resources-check-resources.md)
+ [Update the quantity of a resource while it is in use by jobs](resource-aware-scheduling-how-to-update-quantity.md)
+ [Find the jobs that require a specific consumable resource](resource-aware-scheduling-how-to-find-jobs.md)
+ [Delete a consumable resource](resource-aware-scheduling-how-to-delete.md)

# Create consumable resources
<a name="resource-aware-scheduling-how-to-create"></a>

You must first create the consumable resources that represent the non-CE resources that are consumed when a job is running and are only available in limited quantities. Each consumable resource has a: 
+ resource name (`consumableResourceName`) that must be unique at the account level.
+ (optional) resource type (`resourceType`) that indicates whether the resource is available to be re-used after a job completes. This can be one of:
  + `REPLENISHABLE` (default)
  + `NON_REPLENISHABLE`
+ total quantity (`totalQuantity`) that specifies the total amount of the consumable resource available.

The maximum number of consumable resources per account is 50k.

**Console:**

1. In the left navigation panel of the [AWS Batch console](https://console.aws.amazon.com/batch), choose **Consumable resources**.

1. Choose **Create consumable resource**.

1. Enter a unique **Resource name**, the **Total resource quantity**, and select whether the **Type of resource** is **Replenishable** or **Non-replenishable**.

1. Choose **Create consumable resource**.

**API:**

Use the [`CreateConsumableResource` API](https://docs.aws.amazon.com/batch/latest/APIReference/API_CreateConsumableResource.html) to define the resources you want.

# Specify the resources needed to run a job
<a name="resource-aware-scheduling-how-to-for-jobs"></a>

When you register a job you can specify the name of one or more resources you created (`consumableResource`) and the quantity of that resource each instance of the job requires (`quantity`).

Batch keeps track of the available units of each resource at any given moment. For each job in the job queue, the Batch scheduler ensures that your job runs only when the specified resource dependencies are available.

If a consumable resource for the job is not available when the job reaches the head of the queue, the job will wait in `RUNNABLE` state until all the required resources become available or the job state time limit is reached (see [View a job queue in AWS Batch](job_queue_viewing_status.md)). Once Batch has validated that all the resources are available, the job transitions to the `STARTING` state and then to `RUNNING`. Resources are locked once the job moves to `STARTING` and are then unlocked when the job moves to `SUCCEEDED` or `FAILED`.

You can also update the quantity of a resource needed for a specific job when you submit the job.

**Console:**

**To specify resources and their needed quantities when you define a job:**

1. Define a job using the job definition wizard from the [AWS Batch console](https://console.aws.amazon.com/batch) (**Job definitions** -> **Create**).

1. In the wizard's Step 4: **Configure containers**, under **Consumable resource**, select the **Name** of a required resource from the list. In the **Requested value** field, enter the quantity of this resource needed by an instance of this job, then choose **Add consumable resource**.

1. Repeat the previous step for all the consumable resources required by the job. You can specify up to 5 resources for each job you define.

1. You'll see a list of the consumable resources you have created after you complete the job definition wizard but before you choose **Create job definition**.

**To update needed quantities of resources when you submit a job:**

1. In the left navigation pane of the [AWS Batch console](https://console.aws.amazon.com/batch), choose **Jobs**, then choose **Submit new job**.

1. In the wizard's Step 2: **Configure overrides**, under **Consumable resource overrides**, enter a new **Requested value** for any consumable resource whose needed quantity you want to override for the job.

1. After you have completed all the overrides you want to make for this job, choose **Next** to continue to **Review and submit**.

**API:**

When you register a job with the [`RegisterJobDefinition` API](https://docs.aws.amazon.com/batch/latest/APIReference/API_RegisterJobDefinition.html), use the `consumableResourceList` in the `consumableResourceProperties` portion of the request to specify the consumable resources required to run an instance of the job, and the quantity of each.

When you submit a job with the [`SubmitJob` API](https://docs.aws.amazon.com/batch/latest/APIReference/API_SubmitJob.html) you can override the list of consumable resources and the quantity of each using the `consumableResourcePropertiesOverride` portion of the request. Note that this only overrides the quantity of the resource needed by each instance of the job, not the total quantity available.

# Check how many resources are in-use and available
<a name="resource-aware-scheduling-how-to-check-resources-check-resources"></a>

Batch lets you query the number of available resources (`availableQuantity`), the number of resources in use (`inUseQuantity`), and the total resources (`totalQuantity`) at a given moment.

Once a job goes to the `STARTING` state, the consumed resources will be subtracted from the available quantity of that resource. If the resource is `REPLENISHABLE`, the number of consumed resources will be added back to the available quantity as soon as the job has moved to either the SUCCEEDED or FAILED state, and the total quantity will remain the same. If the resource is `NON_REPLENISHABLE`, the number of consumed resources is subtracted from both the total and available quantities and won't be added back whether the job moves to the `SUCCEEDED` or `FAILED` state.

**Note**  
This information may lag by up to 30 seconds.

**Console:**

1. In the left navigation panel of the [AWS Batch console](https://console.aws.amazon.com/batch), choose **Consumable resources**.

1. Select either the **Replenishable** or **Non-replenishable** tab to view the resources of that type that you have created.

1. For each **Replenishable** resource, the console displays the **Name**, the **Total** quantity of the resource, the number currently **In-use** and how many are still **Available**, along with a calculation of the **Utilization** (the number of resources in-use divided by the total quantity of that resource).

   For each **Non-replenishable** resource, the console displays the **Name**, the number currently **In-use** and how many are still **Available**.

You can also view current information about consumable resources from a job detail page in the console.

1. In the left navigation panel of the [AWS Batch console](https://console.aws.amazon.com/batch), choose **Jobs**, then select a job's name to open the details page for that job.

1. Information on both **Replenishable resources** and **Non-replenishable resources** are available to view if the job requires them. For both types, the console displays the resource's **Name**, the **Requested** quantity for the job, how many are still **Available**, the number currently **In-use**, the **Total** quantity of the resource, along with a calculation of the **Current utilization** (the number of resources in-use by the job divided by the total quantity of that resource).

**API:**

Use the [`DescribeConsumableResource` API](https://docs.aws.amazon.com/batch/latest/APIReference/API_DescribeConsumableResource.html) which returns the following information:

```
{
   "availableQuantity": number,
   "consumableResourceArn": "string",
   "consumableResourceName": "string",
   "createdAt": number,
   "inUseQuantity": number,
   "resourceType": "string",
   "tags": { 
      "string" : "string" 
   },
   "totalQuantity": number
}
```

The [`ListConsumableResources` API](https://docs.aws.amazon.com/batch/latest/APIReference/API_ListConsumableResources.html) also reports the number of resources in use (`inUseQuantity`) and the total number of resources currently available (`totalQuantity`) as part of its listing of all the consumable resources you have created in your account. This API also allows you filter the consumable resource list query based on the consumable resource name.

# Update the quantity of a resource while it is in use by jobs
<a name="resource-aware-scheduling-how-to-update-quantity"></a>

You can reset the total quantity of a resource to a new value, add to the total quantity or subtract from it.

If the new total quantity you specify is greater than before, Batch schedules more jobs accordingly. If the new total quantity is less than before and there are no units of this resource in use, Batch just reduces the total (or available) quantity. If there are units in use, Batch reduces the available quantity immediately and, as jobs finish, Batch reduces the total (available) quantity so that it eventually arrives at the new number. 

**Console:**

1. In the left navigation panel of the [AWS Batch console](https://console.aws.amazon.com/batch), choose **Consumable resources**.

1. Select either the **Replenishable** or **Non-replenishable** tab to view the resources of that type that you have created.

1. For **Replenishable** resources:

   1. Choose the resource you want to update, then select **Actions** and choose **Set resources**, **Add resources**, or **Remove resources**.

   1. A pop-up window appears in which you can **Set total value**, **Add resources**, or **Remove resources** depending on which action you chose in the previous step. Enter the quantity you want to set as the new total value, you want to add to the total quantity or that you want to subtract from the total quantity, then select **Ok**.

   For **Non-replenishable** resources:

   1. Choose the resource you want to update, then select **Actions** and choose **Set resources**, **Add resources**, or **Remove resources**.

   1. A pop-up window appears in which you can **Set available value**, **Add resources**, or **Remove resources** depending on which action you chose in the previous step. Enter the quantity you want to set as the new available value, you want to add to the available quantity or that you want to subtract from the available quantity, then select **Ok**.

**API:**

Use the [`UpdateConsumableResource` API](https://docs.aws.amazon.com/batch/latest/APIReference/API_UpdateConsumableResource.html) to set a new total quantity for the resource, or to increase or reduce the total quantity.

# Find the jobs that require a specific consumable resource
<a name="resource-aware-scheduling-how-to-find-jobs"></a>

Batch lets you retrieve a list of jobs that require a specific consumable resource.

**Console:**

1. In the left navigation panel of the [AWS Batch console](https://console.aws.amazon.com/batch), choose **Consumable resources**.

1. In the list, select the name of the consumable resource. The details page for that resource opens.

1. Under **Search jobs**, enter any filters you want to apply to the list of jobs. You can filter by the **Job name** ('equals', 'starts with'), the **Date range** (when the job was created), and by **Additional criteria** ('job queue', 'job definition', 'shared job identifier'). For each type of filter you want to apply, select from the available options in the drop-down list and enter any additional information requested.

   Choose **Search**.

1. A (filtered) list of jobs that require the consumable resource is displayed, including the job's name, status, number of requested units of the consumable resource, other needed consumable resources, and so on. Using this list, you can select one or more jobs to **Cancel** or **Terminate**. You can also select a job's name to open that job's detail page.

1. Under **Search jobs** you can now **Refresh results** or **Clear search** and start over.

**API:**

You can get a list of jobs that use a specific consumable resource with the [`ListJobsByConsumableResource` API](https://docs.aws.amazon.com/batch/latest/APIReference/API_ListJobsByConsumableResource.html). This API also lets you filter the job list query using the job status or the job name.

# Delete a consumable resource
<a name="resource-aware-scheduling-how-to-delete"></a>

You can delete a consumable resource at any time, even when the jobs that require the resource are still running. Once a consumable resource is deleted, there may be a gap between the time the delete command is received and the job scheduler honors the delete, so it's possible jobs that consume the resource may be scheduled right after the delete call. If the deleted consumable resource has resource type (`resourceType`) `REPLENISHABLE`, this will be ignored when the jobs complete. If you delete a consumable resource and re-create it with the same name, it is considered to be the same resource and it can be used by `RUNNABLE` jobs.

**Console:**

1. In the left navigation panel of the [AWS Batch console](https://console.aws.amazon.com/batch), choose **Consumable resources**.

1. Select either the **Replenishable** or **Non-replenishable** tab to view the resources of that type that you have created.

1. Select each resource you want to delete, then choose **Delete**. A pop-up window **Delete consumable resource** appears. To confirm the deletion, choose **Delete**.

You can also delete a consumable resource from its detail page in the console.

1. In the left navigation panel of the [AWS Batch console](https://console.aws.amazon.com/batch), choose **Consumable resources**.

1. Select either the **Replenishable** or **Non-replenishable** tab to view the resources of that type that you have created.

1. Choose the name of the resource you want to delete. The details page of the consumable resource appears. Choose **Delete**. A pop-up window **Delete consumable resource** appears. To confirm the deletion, choose **Delete**.

**API:**

Use the [`DeleteConsumableResource` API](https://docs.aws.amazon.com/batch/latest/APIReference/API_DeleteConsumableResource.html) to delete a consumable resource.