| title | description | services | documentationcenter | author | manager | editor | ms.assetid | ms.service | ms.devlang | ms.topic | ms.tgt_pltfrm | ms.workload | ms.date | ms.author |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Get started with Azure Batch PowerShell | Microsoft Docs |
Get a quick introduction to the Azure PowerShell cmdlets you can use to manage the Azure Batch service |
batch |
tamram |
timlt |
f9ad62c5-27bf-4e6b-a5bf-c5f5914e6199 |
batch |
NA |
get-started-article |
powershell |
big-compute |
10/20/2016 |
tamram |
With the Azure Batch PowerShell cmdlets, you can perform and script many of the same tasks you carry out with the Batch APIs, the Azure portal, and the Azure Command-Line Interface (CLI). This is a quick introduction to the cmdlets you can use to manage your Batch accounts and work with your Batch resources such as pools, jobs, and tasks.
For a complete list of Batch cmdlets and detailed cmdlet syntax, see the Azure Batch cmdlet reference.
This article is based on cmdlets in Azure PowerShell version 3.0.0. We recommend that you update your Azure PowerShell frequently to take advantage of service updates and enhancements.
Perform the following operations to use Azure PowerShell to manage your Batch resources.
-
Run the Login-AzureRmAccount cmdlet to connect to your subscription (the Azure Batch cmdlets ship in the Azure Resource Manager module):
Login-AzureRmAccount -
Register with the Batch provider namespace. This operation only needs to be performed once per subscription.
Register-AzureRMResourceProvider -ProviderNamespace Microsoft.Batch
New-AzureRmBatchAccount creates a Batch account in a specified resource group. If you don't already have a resource group, create one by running the New-AzureRmResourceGroup cmdlet. Specify one of the Azure regions in the Location parameter, such as "Central US". For example:
New-AzureRmResourceGroup –Name MyBatchResourceGroup –location "Central US"
Then, create a Batch account in the resource group, specifying a name for the account in <account_name> and the location and name of your resource group. Creating the Batch account can take some time to complete. For example:
New-AzureRmBatchAccount –AccountName <account_name> –Location "Central US" –ResourceGroupName <res_group_name>
Note
The Batch account name must be unique to the Azure region for the resource group, contain between 3 and 24 characters, and use lowercase letters and numbers only.
Get-AzureRmBatchAccountKeys shows the access keys associated with an Azure Batch account. For example, run the following to get the primary and secondary keys of the account you created.
$Account = Get-AzureRmBatchAccountKeys –AccountName <account_name>
$Account.PrimaryAccountKey
$Account.SecondaryAccountKey
New-AzureRmBatchAccountKey generates a new primary or secondary account key for an Azure Batch account. For example, to generate a new primary key for your Batch account, type:
New-AzureRmBatchAccountKey -AccountName <account_name> -KeyType Primary
Note
To generate a new secondary key, specify "Secondary" for the KeyType parameter. You have to regenerate the primary and secondary keys separately.
Remove-AzureRmBatchAccount deletes a Batch account. For example:
Remove-AzureRmBatchAccount -AccountName <account_name>
When prompted, confirm you want to remove the account. Account removal can take some time to complete.
To authenticate using the Batch PowerShell cmdlets when you create and manage Batch pools, jobs, tasks, and other resources, first create a BatchAccountContext object to store your account name and keys:
$context = Get-AzureRmBatchAccountKeys -AccountName <account_name>
You pass the BatchAccountContext object into cmdlets that use the BatchContext parameter.
Note
By default, the account's primary key is used for authentication, but you can explicitly select the key to use by changing your BatchAccountContext object’s KeyInUse property: $context.KeyInUse = "Secondary".
Use cmdlets such as New-AzureBatchPool, New-AzureBatchJob, and New-AzureBatchTask to create resources under a Batch account. There are corresponding Get- and Set- cmdlets to update the properties of existing resources, and Remove- cmdlets to remove resources under a Batch account.
When using many of these cmdlets, in addition to passing a BatchContext object, you need to create or pass objects that contain detailed resource settings, as shown in the following example. See the detailed help for each cmdlet for additional examples.
When creating or updating a Batch pool, you select a cloud service configuration or a virtual machine configuration for the operating system on the compute nodes (see Batch feature overview). Your choice determines whether your compute nodes are imaged with one of the Azure Guest OS releases or with one of the supported Linux or Windows VM images in the Azure Marketplace.
When you run New-AzureBatchPool, pass the operating system settings in a PSCloudServiceConfiguration or PSVirtualMachineConfiguration object. For example, the following cmdlet creates a new Batch pool with size Small compute nodes in the cloud service configuration, imaged with the latest operating system version of family 3 (Windows Server 2012). Here, the CloudServiceConfiguration parameter specifies the $configuration variable as the PSCloudServiceConfiguration object. The BatchContext parameter specifies a previously defined variable $context as the BatchAccountContext object.
$configuration = New-Object -TypeName "Microsoft.Azure.Commands.Batch.Models.PSCloudServiceConfiguration" -ArgumentList @(4,"*")
New-AzureBatchPool -Id "AutoScalePool" -VirtualMachineSize "Small" -CloudServiceConfiguration $configuration -AutoScaleFormula '$TargetDedicated=4;' -BatchContext $context
The target number of compute nodes in the new pool is determined by an autoscaling formula. In this case, the formula is simply $TargetDedicated=4, indicating the number of compute nodes in the pool is 4 at most.
Use cmdlets such as Get-AzureBatchPool, Get-AzureBatchJob, and Get-AzureBatchTask to query for entities created under a Batch account.
As an example, use Get-AzureBatchPools to find your pools. By default this queries for all pools under your account, assuming you already stored the BatchAccountContext object in $context:
Get-AzureBatchPool -BatchContext $context
You can supply an OData filter using the Filter parameter to find only the objects you’re interested in. For example, you can find all pools with ids starting with “myPool”:
$filter = "startswith(id,'myPool')"
Get-AzureBatchPool -Filter $filter -BatchContext $context
This method is not as flexible as using “Where-Object” in a local pipeline. However, the query gets sent to the Batch service directly so that all filtering happens on the server side, saving Internet bandwidth.
An alternative to an OData filter is to use the Id parameter. To query for a specific pool with id "myPool":
Get-AzureBatchPool -Id "myPool" -BatchContext $context
The Id parameter supports only full-id search, not wildcards or OData-style filters.
By default, each cmdlet returns a maximum of 1000 objects. If you reach this limit, either refine your filter to bring back fewer objects, or explicitly set a maximum using the MaxCount parameter. For example:
Get-AzureBatchTask -MaxCount 2500 -BatchContext $context
To remove the upper bound, set MaxCount to 0 or less.
Batch cmdlets can leverage the PowerShell pipeline to send data between cmdlets. This has the same effect as specifying a parameter, but makes working with multiple entities easier.
For example, find and display all tasks under your account:
Get-AzureBatchJob -BatchContext $context | Get-AzureBatchTask -BatchContext $context
Restart (reboot) every compute node in a pool:
Get-AzureBatchComputeNode -PoolId "myPool" -BatchContext $context | Restart-AzureBatchComputeNode -BatchContext $context
Application packages provide a simplified way to deploy applications to the compute nodes in your pools. With the Batch PowerShell cmdlets, you can upload and manage application packages in your Batch account, and deploy package versions to compute nodes.
Create an application:
New-AzureRmBatchApplication -AccountName <account_name> -ResourceGroupName <res_group_name> -ApplicationId "MyBatchApplication"
Add an application package:
New-AzureRmBatchApplicationPackage -AccountName <account_name> -ResourceGroupName <res_group_name> -ApplicationId "MyBatchApplication" -ApplicationVersion "1.0" -Format zip -FilePath package001.zip
Set the default version for the application:
Set-AzureRmBatchApplication -AccountName <account_name> -ResourceGroupName <res_group_name> -ApplicationId "MyBatchApplication" -DefaultVersion "1.0"
List an application's packages
$application = Get-AzureRmBatchApplication -AccountName <account_name> -ResourceGroupName <res_group_name> -ApplicationId "MyBatchApplication"
$application.ApplicationPackages
Delete an application package
Remove-AzureRmBatchApplicationPackage -AccountName <account_name> -ResourceGroupName <res_group_name> -ApplicationId "MyBatchApplication" -ApplicationVersion "1.0"
Delete an application
Remove-AzureRmBatchApplication -AccountName <account_name> -ResourceGroupName <res_group_name> -ApplicationId "MyBatchApplication"
Note
You must delete all of an application's application package versions before you delete the application. You will receive a 'Conflict' error if you try to delete an application that currently has application packages.
You can specify one or more application packages for deployment when you create a pool. When you specify a package at pool creation time, it is deployed to each node as the node joins pool. Packages are also deployed when a node is rebooted or reimaged.
Specify the -ApplicationPackageReference option when creating a pool to deploy an application package to the pool's nodes as they join the pool. First, create a PSApplicationPackageReference object, and configure it with the application Id and package version you want to deploy to the pool's compute nodes:
$appPackageReference = New-Object Microsoft.Azure.Commands.Batch.Models.PSApplicationPackageReference
$appPackageReference.ApplicationId = "MyBatchApplication"
$appPackageReference.Version = "1.0"
Now create the pool, and specify the package reference object as the argument to the ApplicationPackageReferences option:
New-AzureBatchPool -Id "PoolWithAppPackage" -VirtualMachineSize "Small" -CloudServiceConfiguration $configuration -BatchContext $context -ApplicationPackageReferences $appPackageReference
You can find more information on application packages in Application deployment with Azure Batch application packages.
Important
You must link an Azure Storage account to your Batch account to use application packages.
To update the applications assigned to an existing pool, first create a PSApplicationPackageReference object with the desired properties (application Id and package version):
$appPackageReference = New-Object Microsoft.Azure.Commands.Batch.Models.PSApplicationPackageReference
$appPackageReference.ApplicationId = "MyBatchApplication"
$appPackageReference.Version = "2.0"
Next, get the pool from Batch, clear out any existing packages, add our new package reference, and update the Batch service with the new pool settings:
$pool = Get-AzureBatchPool -BatchContext $context -Id "PoolWithAppPackage"
$pool.ApplicationPackageReferences.Clear()
$pool.ApplicationPackageReferences.Add($appPackageReference)
Set-AzureBatchPool -BatchContext $context -Pool $pool
You've now updated the pool's properties in the Batch service. To actually deploy the new application package to compute nodes in the pool, however, you must restart or reimage those nodes. You can restart every node in a pool with this command:
Get-AzureBatchComputeNode -PoolId "PoolWithAppPackage" -BatchContext $context | Restart-AzureBatchComputeNode -BatchContext $context
Tip
You can deploy multiple application packages to the compute nodes in a pool. If you'd like to add an application package instead of replacing the currently deployed packages, omit the $pool.ApplicationPackageReferences.Clear() line above.
- For detailed cmdlet syntax and examples, see Azure Batch cmdlet reference.
- For more information about applications and application packages in Batch, see Application deployment with Azure Batch application packages.