Batch pools - az batch pool

Manage your Batch pools.

Commands

az batch pool all-statistics View statistics of all pools under your Batch account.
az batch pool all-statistics show Get lifetime summary statistics for all of the pools in the specified account. Statistics are aggregated across all pools that have ever existed in the account, from account creation to the last update time of the statistics.
az batch pool autoscale Manage automatic scaling of your Batch pools.
az batch pool autoscale disable Disables automatic scaling for a pool.
az batch pool autoscale enable Enables automatic scaling for a pool.
az batch pool autoscale evaluate Gets the result of evaluating an automatic scaling formula on the pool.
az batch pool create Create a pool in the specified account. When creating a pool, choose arguments from either Cloud Services Configuration or Virtual Machine Configuration.
az batch pool delete Deletes a pool from the specified account.
az batch pool list Lists all of the pools in the specified account.
az batch pool node-agent-skus Retrieve node agent SKUs of pools using a Virtual Machine Configuration.
az batch pool node-agent-skus list Lists all node agent SKUs supported by the Azure Batch service.
az batch pool os Manage the operating system of your Batch pools.
az batch pool os upgrade Upgrades the operating system of the specified pool.
az batch pool reset Update the properties of the specified pool. All updatable properties are replaced with the values specified or reset to default values if unspecified.
az batch pool resize Resize (or stop resizing) the Batch pool.
az batch pool set Update the properties of the specified pool. Properties can be updated independently, but when a property is updated in a sub-group, for example 'start task', all properties of that group are reset.
az batch pool show Gets information about the specified pool.
az batch pool usage-metrics View usage metrics of your Batch pools.
az batch pool usage-metrics list Lists the usage metrics, aggregated by pool across individual time intervals, for the specified account.

az batch pool create

Create a pool in the specified account. When creating a pool, choose arguments from either Cloud Services Configuration or Virtual Machine Configuration.

az batch pool create [--account-endpoint]
[--account-key]
[--account-name]
[--application-licenses]
[--application-package-references]
[--auto-scale-formula]
[--certificate-references]
[--enable-inter-node-communication]
[--id]
[--image]
[--json-file]
[--metadata]
[--node-agent-sku-id]
[--os-family {2, 3, 4, 5}]
[--resize-timeout]
[--start-task-command-line]
[--start-task-resource-files]
[--start-task-wait-for-success]
[--target-dedicated-nodes]
[--target-low-priority-nodes]
[--vm-size]

Optional Parameters

--account-endpoint

Batch service endpoint. Alternatively, set by environment variable: AZURE_BATCH_ENDPOINT.

--account-key

Batch account key. Alternatively, set by environment variable: AZURE_BATCH_ACCESS_KEY.

--account-name

Batch account name. Alternatively, set by environment variable: AZURE_BATCH_ACCOUNT.

--application-licenses

The list of application licenses the Batch service will make available on each compute node in the pool. The list of application licenses must be a subset of available Batch service application licenses. If a license is requested which is not supported, pool creation will fail. Space separated values.

--application-package-references

The list of application packages to be installed on each compute node in the pool. Space separated application IDs with optional version in 'id[#version]' format.

--auto-scale-formula

A formula for the desired number of compute nodes in the pool. The formula is checked for validity before the pool is created. If the formula is not valid, the Batch service rejects the request with detailed error information. For more information about specifying this formula, see https://azure.microsoft.com/documentation/articles/batch-automatic-scaling/.

--certificate-references

The list of certificates to be installed on each compute node in the pool. For Windows compute nodes, the Batch service installs the certificates to the specified certificate store and location. For Linux compute nodes, the certificates are stored in a directory inside the task working directory and an environment variable AZ_BATCH_CERTIFICATES_DIR is supplied to the task to query for this location. For certificates with visibility of 'remoteUser', a 'certs' directory is created in the user's home directory (e.g., /home/{user-name}/certs) and certificates are placed in that directory. Space separated certificate thumbprints.

--enable-inter-node-communication

Whether the pool permits direct communication between nodes. Enabling inter-node communication limits the maximum size of the pool due to deployment restrictions on the nodes of the pool. This may result in the pool not reaching its desired size. The default value is false. True if flag present.

--id

A string that uniquely identifies the pool within the account. The ID can contain any combination of alphanumeric characters including hyphens and underscores, and cannot contain more than 64 characters. The ID is case-preserving and case-insensitive (that is, you may not have two pool IDs within an account that differ only by case).

--image

OS image URN in 'publisher:offer:sku[:version]' format. Version is optional and if omitted latest will be used. Values from 'az batch pool node-agent-skus list'. Example: 'MicrosoftWindowsServer:WindowsServer:2012-R2-Datacenter:latest'.

--json-file

A file containing the pool specification in JSON format. If this parameter is specified, all 'Pool Arguments' are ignored.

--metadata

A list of name-value pairs associated with the pool as metadata. The Batch service does not assign any meaning to metadata; it is solely for the use of user code. Space separated values in 'key=value' format.

--node-agent-sku-id

The SKU of the Batch node agent to be provisioned on compute nodes in the pool. The Batch node agent is a program that runs on each node in the pool, and provides the command-and-control interface between the node and the Batch service. There are different implementations of the node agent, known as SKUs, for different operating systems. You must specify a node agent SKU which matches the selected image reference. To get the list of supported node agent SKUs along with their list of verified image references, see the 'List supported node agent SKUs' operation.

--os-family

The Azure Guest OS family to be installed on the virtual machines in the pool. Possible values are: 2 - OS Family 2, equivalent to Windows Server 2008 R2 SP1. 3 - OS Family 3, equivalent to Windows Server 2012. 4 - OS Family 4, equivalent to Windows Server 2012 R2. 5 - OS Family 5, equivalent to Windows Server 2016. For more information, see Azure Guest OS Releases (https://azure.microsoft.com/documentation/articles/cloud-services-guestos-update-matrix/#releases).

accepted values: 2, 3, 4, 5
--resize-timeout

The timeout for allocation of compute nodes to the pool. This timeout applies only to manual scaling; it has no effect when enableAutoScale is set to true. The default value is 15 minutes. The minimum value is 5 minutes. If you specify a value less than 5 minutes, the Batch service returns an error; if you are calling the REST API directly, the HTTP status code is 400 (Bad Request). Expected format is an ISO-8601 duration.

--start-task-command-line

The command line of the start task. The command line does not run under a shell, and therefore cannot take advantage of shell features such as environment variable expansion. If you want to take advantage of such features, you should invoke the shell in the command line, for example using "cmd /c MyCommand" in Windows or "/bin/sh -c MyCommand" in Linux.

--start-task-resource-files

A list of files that the Batch service will download to the compute node before running the command line. Space separated resource references in filename=blobsource format.

--start-task-wait-for-success

Whether the Batch service should wait for the start task to complete successfully (that is, to exit with exit code 0) before scheduling any tasks on the compute node. If true and the start task fails on a compute node, the Batch service retries the start task up to its maximum retry count (maxTaskRetryCount). If the task has still not completed successfully after all retries, then the Batch service marks the compute node unusable, and will not schedule tasks to it. This condition can be detected via the node state and scheduling error detail. If false, the Batch service will not wait for the start task to complete. In this case, other tasks can start executing on the compute node while the start task is still running; and even if the start task fails, new tasks will continue to be scheduled on the node. The default is false. True if flag present.

--target-dedicated-nodes

The desired number of dedicated compute nodes in the pool. This property must not be specified if enableAutoScale is set to true. If enableAutoScale is set to false, then you must set either targetDedicatedNodes, targetLowPriorityNodes, or both.

--target-low-priority-nodes

The desired number of low-priority compute nodes in the pool. This property must not be specified if enableAutoScale is set to true. If enableAutoScale is set to false, then you must set either targetDedicatedNodes, targetLowPriorityNodes, or both.

--vm-size

The size of virtual machines in the pool. All virtual machines in a pool are the same size. For information about available sizes of virtual machines for Cloud Services pools (pools created with cloudServiceConfiguration), see Sizes for Cloud Services (http://azure.microsoft.com/documentation/articles/cloud-services-sizes-specs/). Batch supports all Cloud Services VM sizes except ExtraSmall, A1V2 and A2V2. For information about available VM sizes for pools using images from the Virtual Machines Marketplace (pools created with virtualMachineConfiguration) see Sizes for Virtual Machines (Linux) (https://azure.microsoft.com/documentation/articles/virtual-machines-linux-sizes/) or Sizes for Virtual Machines (Windows) (https://azure.microsoft.com/documentation/articles/virtual-machines-windows-sizes/). Batch supports all Azure VM sizes except STANDARD_A0 and those with premium storage (STANDARD_GS, STANDARD_DS, and STANDARD_DSV2 series).

az batch pool delete

When you request that a pool be deleted, the following actions occur: the pool state is set to deleting; any ongoing resize operation on the pool are stopped; the Batch service starts resizing the pool to zero nodes; any tasks running on existing nodes are terminated and requeued (as if a resize pool operation had been requested with the default requeue option); finally, the pool is removed from the system. Because running tasks are requeued, the user can rerun these tasks by updating their job to target a different pool. The tasks can then run on the new pool. If you want to override the requeue behavior, then you should call resize pool explicitly to shrink the pool to zero size before deleting the pool. If you call an Update, Patch or Delete API on a pool in the deleting state, it will fail with HTTP status code 409 with error code PoolBeingDeleted.

az batch pool delete --pool-id
[--account-endpoint]
[--account-key]
[--account-name]
[--if-match]
[--if-modified-since]
[--if-none-match]
[--if-unmodified-since]
[--yes]

Required Parameters

--pool-id

The ID of the pool to delete.

Optional Parameters

--account-endpoint

Batch service endpoint. Alternatively, set by environment variable: AZURE_BATCH_ENDPOINT.

--account-key

Batch account key. Alternatively, set by environment variable: AZURE_BATCH_ACCESS_KEY.

--account-name

Batch account name. Alternatively, set by environment variable: AZURE_BATCH_ACCOUNT.

--if-match

An ETag value associated with the version of the resource known to the client. The operation will be performed only if the resource's current ETag on the service exactly matches the value specified by the client.

--if-modified-since

A timestamp indicating the last modified time of the resource known to the client. The operation will be performed only if the resource on the service has been modified since the specified time.

--if-none-match

An ETag value associated with the version of the resource known to the client. The operation will be performed only if the resource's current ETag on the service does not match the value specified by the client.

--if-unmodified-since

A timestamp indicating the last modified time of the resource known to the client. The operation will be performed only if the resource on the service has not been modified since the specified time.

--yes -y

Do not prompt for confirmation.

az batch pool list

Lists all of the pools in the specified account.

az batch pool list [--account-endpoint]
[--account-key]
[--account-name]
[--expand]
[--filter]
[--select]

Optional Parameters

--account-endpoint

Batch service endpoint. Alternatively, set by environment variable: AZURE_BATCH_ENDPOINT.

--account-key

Batch account key. Alternatively, set by environment variable: AZURE_BATCH_ACCESS_KEY.

--account-name

Batch account name. Alternatively, set by environment variable: AZURE_BATCH_ACCOUNT.

--expand

An OData $expand clause.

--filter

An OData $filter clause.

--select

An OData $select clause.

az batch pool reset

Update the properties of the specified pool. All updatable properties are replaced with the values specified or reset to default values if unspecified.

az batch pool reset --pool-id
[--account-endpoint]
[--account-key]
[--account-name]
[--application-package-references]
[--certificate-references]
[--json-file]
[--metadata]
[--start-task-command-line]
[--start-task-environment-settings]
[--start-task-max-task-retry-count]
[--start-task-wait-for-success]

Required Parameters

--pool-id

The ID of the pool to update.

Optional Parameters

--account-endpoint

Batch service endpoint. Alternatively, set by environment variable: AZURE_BATCH_ENDPOINT.

--account-key

The Batch account key. Alternatively, set by environment variable: AZURE_BATCH_ACCESS_KEY.

--account-name

The Batch account name. Alternatively, set by environment variable: AZURE_BATCH_ACCOUNT.

--application-package-references

A list of application packages to be installed on each compute node in the pool. Changes to application package references affect all new compute nodes joining the pool, but do not affect compute nodes that are already in the pool until they are rebooted or reimaged. The list replaces any existing application package references. If omitted, or if you specify an empty collection, any existing application packages references are removed from the pool.

--certificate-references

A list of certificates to be installed on each compute node in the pool. If you specify an empty collection, any existing certificate references are removed from the pool. For Windows compute nodes, the Batch service installs the certificates to the specified certificate store and location. For Linux compute nodes, the certificates are stored in a directory inside the task working directory and an environment variable AZ_BATCH_CERTIFICATES_DIR is supplied to the task to query for this location. For certificates with visibility of 'remoteUser', a 'certs' directory is created in the user's home directory (e.g., /home/{user-name}/certs) and certificates are placed in that directory.

--json-file

The file containing pool update properties parameter specification in JSON format. If this parameter is specified, all 'Pool Update Properties Parameter Arguments' are ignored.

--metadata

A list of name-value pairs associated with the pool as metadata. This list replaces any existing metadata configured on the pool. If omitted, or if you specify an empty collection, any existing metadata is removed from the pool.

--start-task-command-line

The command line of the start task. The command line does not run under a shell, and therefore cannot take advantage of shell features such as environment variable expansion. If you want to take advantage of such features, you should invoke the shell in the command line, for example using "cmd /c MyCommand" in Windows or "/bin/sh -c MyCommand" in Linux.

--start-task-environment-settings

A list of environment variable settings for the start task. Space separated values in 'key=value' format.

--start-task-max-task-retry-count

The maximum number of times the task may be retried.

--start-task-wait-for-success

Whether the Batch service should wait for the start task to complete successfully (that is, to exit with exit code 0) before scheduling any tasks on the compute node. True if flag present, otherwise defaults to False.

az batch pool resize

Resize (or stop resizing) the Batch pool.

az batch pool resize --pool-id
[--abort]
[--account-endpoint]
[--account-key]
[--account-name]
[--if-match]
[--if-modified-since]
[--if-none-match]
[--if-unmodified-since]
[--node-deallocation-option {requeue, retainedData, taskCompletion, terminate}]
[--resize-timeout]
[--target-dedicated-nodes]
[--target-low-priority-nodes]

Required Parameters

--pool-id

The ID of the pool.

Optional Parameters

--abort

Stop the pool resize operation.

--account-endpoint

Batch service endpoint. Alternatively, set by environment variable: AZURE_BATCH_ENDPOINT.

--account-key

The Batch account key. Alternatively, set by environment variable: AZURE_BATCH_ACCESS_KEY.

--account-name

The Batch account name. Alternatively, set by environment variable: AZURE_BATCH_ACCOUNT.

--if-match

The operation will be performed only if the resource's current ETag exactly matches the specified value.

--if-modified-since

The operation will be performed only if the resource has been modified since the specified timestamp.

--if-none-match

The operation will not be performed only if the resource's current ETag exactly matches the specified value.

--if-unmodified-since

The operation will not be performed only if the resource has been modified since the specified timestamp.

--node-deallocation-option

When nodes may be removed from the pool, if the pool size is decreasing.

accepted values: requeue, retainedData, taskCompletion, terminate
--resize-timeout

The timeout for allocation of compute nodes to the pool or removal of compute nodes from the pool. The default value is 15 minutes. The minimum value is 5 minutes. If you specify a value less than 5 minutes, the Batch service returns an error; if you are calling the REST API directly, the HTTP status code is 400 (Bad Request).

--target-dedicated-nodes

The desired number of dedicated compute nodes in the pool.

--target-low-priority-nodes

The desired number of low-priority compute nodes in the pool.

az batch pool set

Update the properties of the specified pool. Properties can be updated independently, but when a property is updated in a sub-group, for example 'start task', all properties of that group are reset.

az batch pool set --pool-id
[--account-endpoint]
[--account-key]
[--account-name]
[--application-package-references]
[--certificate-references]
[--if-match]
[--if-modified-since]
[--if-none-match]
[--if-unmodified-since]
[--json-file]
[--metadata]
[--start-task-command-line]
[--start-task-environment-settings]
[--start-task-max-task-retry-count]
[--start-task-resource-files]
[--start-task-wait-for-success]

Required Parameters

--pool-id

The ID of the pool to update.

Optional Parameters

--account-endpoint

Batch service endpoint. Alternatively, set by environment variable: AZURE_BATCH_ENDPOINT.

--account-key

Batch account key. Alternatively, set by environment variable: AZURE_BATCH_ACCESS_KEY.

--account-name

Batch account name. Alternatively, set by environment variable: AZURE_BATCH_ACCOUNT.

--application-package-references

A list of application packages to be installed on each compute node in the pool. Changes to application package references affect all new compute nodes joining the pool, but do not affect compute nodes that are already in the pool until they are rebooted or reimaged. If this element is present, it replaces any existing application package references. If you specify an empty collection, then all application package references are removed from the pool. If omitted, any existing application package references are left unchanged. Space separated application IDs with optional version in 'id[#version]' format.

--certificate-references

A list of certificates to be installed on each compute node in the pool. If omitted, any existing certificate references are left unchanged. For Windows compute nodes, the Batch service installs the certificates to the specified certificate store and location. For Linux compute nodes, the certificates are stored in a directory inside the task working directory and an environment variable AZ_BATCH_CERTIFICATES_DIR is supplied to the task to query for this location. For certificates with visibility of 'remoteUser', a 'certs' directory is created in the user's home directory (e.g., /home/{user-name}/certs) and certificates are placed in that directory. Space separated certificate thumbprints.

--if-match

An ETag value associated with the version of the resource known to the client. The operation will be performed only if the resource's current ETag on the service exactly matches the value specified by the client.

--if-modified-since

A timestamp indicating the last modified time of the resource known to the client. The operation will be performed only if the resource on the service has been modified since the specified time.

--if-none-match

An ETag value associated with the version of the resource known to the client. The operation will be performed only if the resource's current ETag on the service does not match the value specified by the client.

--if-unmodified-since

A timestamp indicating the last modified time of the resource known to the client. The operation will be performed only if the resource on the service has not been modified since the specified time.

--json-file

A file containing the pool patch parameter specification in JSON format. If this parameter is specified, all 'Pool Arguments' are ignored.

--metadata

A list of name-value pairs associated with the pool as metadata. If this element is present, it replaces any existing metadata configured on the pool. If you specify an empty collection, any metadata is removed from the pool. If omitted, any existing metadata is left unchanged. Space separated values in 'key=value' format.

--start-task-command-line

The command line of the start task. The command line does not run under a shell, and therefore cannot take advantage of shell features such as environment variable expansion. If you want to take advantage of such features, you should invoke the shell in the command line, for example using "cmd /c MyCommand" in Windows or "/bin/sh -c MyCommand" in Linux.

--start-task-environment-settings

A list of environment variable settings for the start task. Space separated values in 'key=value' format.

--start-task-max-task-retry-count

The maximum number of times the task may be retried. The Batch service retries a task if its exit code is nonzero. Note that this value specifically controls the number of retries. The Batch service will try the task once, and may then retry up to this limit. For example, if the maximum retry count is 3, Batch tries the task up to 4 times (one initial try and 3 retries). If the maximum retry count is 0, the Batch service does not retry the task. If the maximum retry count is -1, the Batch service retries the task without limit.

--start-task-resource-files

A list of files that the Batch service will download to the compute node before running the command line. Space separated resource references in filename=blobsource format.

--start-task-wait-for-success

Whether the Batch service should wait for the start task to complete successfully (that is, to exit with exit code 0) before scheduling any tasks on the compute node. If true and the start task fails on a compute node, the Batch service retries the start task up to its maximum retry count (maxTaskRetryCount). If the task has still not completed successfully after all retries, then the Batch service marks the compute node unusable, and will not schedule tasks to it. This condition can be detected via the node state and scheduling error detail. If false, the Batch service will not wait for the start task to complete. In this case, other tasks can start executing on the compute node while the start task is still running; and even if the start task fails, new tasks will continue to be scheduled on the node. The default is false. Specify either 'true' or 'false' to update the property.

az batch pool show

Gets information about the specified pool.

az batch pool show --pool-id
[--account-endpoint]
[--account-key]
[--account-name]
[--expand]
[--if-match]
[--if-modified-since]
[--if-none-match]
[--if-unmodified-since]
[--select]

Required Parameters

--pool-id

The ID of the pool to get.

Optional Parameters

--account-endpoint

Batch service endpoint. Alternatively, set by environment variable: AZURE_BATCH_ENDPOINT.

--account-key

Batch account key. Alternatively, set by environment variable: AZURE_BATCH_ACCESS_KEY.

--account-name

Batch account name. Alternatively, set by environment variable: AZURE_BATCH_ACCOUNT.

--expand

An OData $expand clause.

--if-match

An ETag value associated with the version of the resource known to the client. The operation will be performed only if the resource's current ETag on the service exactly matches the value specified by the client.

--if-modified-since

A timestamp indicating the last modified time of the resource known to the client. The operation will be performed only if the resource on the service has been modified since the specified time.

--if-none-match

An ETag value associated with the version of the resource known to the client. The operation will be performed only if the resource's current ETag on the service does not match the value specified by the client.

--if-unmodified-since

A timestamp indicating the last modified time of the resource known to the client. The operation will be performed only if the resource on the service has not been modified since the specified time.

--select

An OData $select clause.