Skip to content

Commit 46e2873

Browse files
v-thepetv-thepet
committed
cli qs
1 parent 9efe0cd commit 46e2873

File tree

1 file changed

+71
-66
lines changed

1 file changed

+71
-66
lines changed

‎articles/batch/quick-create-cli.md

Lines changed: 71 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -1,200 +1,205 @@
11
---
2-
title: Quickstart - Run your first Batch job with the Azure CLI
3-
description: This quickstart shows how to create a Batch account and run a Batch job with the Azure CLI.
2+
title: 'Quickstart: Use the Azure CLI to create a Batch account and run a job
3+
description: Follow this quickstart to use the Azure CLI to create a Batch account and run a Batch job.
44
ms.topic: quickstart
5-
ms.date: 05/25/2021
5+
ms.date: 04/12/2023
66
ms.custom: mvc, devx-track-azurecli, mode-api
77
---
88
99
# Quickstart: Run your first Batch job with the Azure CLI
1010
11-
Get started with Azure Batch by using the Azure CLI to create a Batch account, a pool of compute nodes (virtual machines), and a job that runs tasks on the pool. Each sample task runs a basic command on one of the pool nodes.
11+
This quickstart shows you how to get started with Azure Batch by using Azure CLI commands. You create a Batch account that has a *pool* of virtual machines, or compute *nodes*. You then create and run a *job* with *tasks* that run commands on the pool nodes.
1212
13-
The Azure CLI is used to create and manage Azure resources from the command line or in scripts. After completing this quickstart, you will understand the key concepts of the Batch service and be ready to try Batch with more realistic workloads at larger scale.
13+
This quickstart uses the Azure CLI to create and manage Azure resources from the command line and in a script. After you complete this quickstart, you understand the key concepts of the Batch service and are ready to use Batch with more realistic, larger scale workloads.
1414
15-
[!INCLUDE [quickstarts-free-trial-note](../../includes/quickstarts-free-trial-note.md)]
15+
## Prerequisites
1616
17-
[!INCLUDE [azure-cli-prepare-your-environment.md](~/articles/reusable-content/azure-cli/azure-cli-prepare-your-environment.md)]
17+
- [!INCLUDE [quickstarts-free-trial-note](../../includes/quickstarts-free-trial-note.md)]
1818
19-
- This quickstart requires version 2.0.20 or later of the Azure CLI. If using Azure Cloud Shell, the latest version is already installed.
19+
- Azure Cloud Shell or Azure CLI.
2020
21-
## Create a resource group
21+
You can run the Azure CLI commands in this quickstart interactively in Azure Cloud Shell. To run the commands in the Cloud Shell, select **Open Cloudshell** at the upper-right corner of a code block. Select **Copy** to copy the code, and paste it into Cloud Shell to run it. You can also [run Cloud Shell from within the Azure portal](https://shell.azure.com). Cloud Shell always uses the latest version of the Azure CLI.
22+
23+
You can also [install Azure CLI locally](/cli/azure/install-azure-cli) to run the commands. The steps in this article require Azure CLI version 2.0.20 or later. Run [az version](/cli/azure/reference-index?#az-version) to see your installed version and dependent libraries, and run [az upgrade](/cli/azure/reference-index?#az-upgrade) to upgrade.
2224
23-
Create a resource group with the [az group create](/cli/azure/group#az-group-create) command. An Azure resource group is a logical container into which Azure resources are deployed and managed.
25+
If you use a local installation, sign in to Azure by using the [az login](/cli/azure/reference-index#az-login) command. If you're prompted on first use, install the Azure CLI extension.
2426

25-
The following example creates a resource group named *QuickstartBatch-rg* in the *eastus2* location.
27+
## Create a resource group
28+
29+
Run the following [az group create](/cli/azure/group#az-group-create) command to create an Azure resource group named `qsBatch` in the `eastus` Azure region. The resource group is a logical container that holds the Azure resources for this quickstart.
2630

2731
```azurecli-interactive
2832
az group create \
29-
--name QuickstartBatch-rg \
33+
--name qsBatch \
3034
--location eastus2
3135
```
3236

3337
## Create a storage account
3438

35-
You can link an Azure Storage account with your Batch account. Although not required for this quickstart, the storage account is useful to deploy applications and store input and output data for most real-world workloads. Create a storage account in your resource group with the [az storage account create](/cli/azure/storage/account#az-storage-account-create) command.
39+
Use the [az storage account create](/cli/azure/storage/account#az-storage-account-create) command to create an Azure Storage account to link to your Batch account. Although this quickstart doesn't use the storage account, most real-world Batch workloads use a linked storage account to deploy applications and store input and output data. Run the following command to create a `Stamdard_LRS` SKU storage account named `mybatchstorage` in your resource group:
3640

3741
```azurecli-interactive
3842
az storage account create \
39-
--resource-group QuickstartBatch-rg \
40-
--name mystorageaccount \
43+
--resource-group qsBatch \
44+
--name mybatchstorage \
4145
--location eastus2 \
4246
--sku Standard_LRS
4347
```
4448

4549
## Create a Batch account
4650

47-
Create a Batch account with the [az batch account create](/cli/azure/batch/account#az-batch-account-create) command. You need an account to create compute resources (pools of compute nodes) and Batch jobs.
48-
49-
The following example creates a Batch account named *mybatchaccount* in *QuickstartBatch-rg*, and links the storage account you created.
51+
Run the following [az batch account create](/cli/azure/batch/account#az-batch-account-create) command to create a Batch account named `mybatchaccount` in your resource group and link it with the `mybatchstorage` storage account.
5052

5153
```azurecli-interactive
5254
az batch account create \
5355
--name mybatchaccount \
54-
--storage-account mystorageaccount \
55-
--resource-group QuickstartBatch-rg \
56+
--storage-account mybatchstorage \
57+
--resource-group qsBatch \
5658
--location eastus2
5759
```
5860

59-
To create and manage compute pools and jobs, you need to authenticate with Batch. Log in to the account with the [az batch account login](/cli/azure/batch/account#az-batch-account-login) command. After you log in, your `az batch` commands use this account context.
61+
Sign in to the new Batch account by running the [az batch account login](/cli/azure/batch/account#az-batch-account-login) command. After you authenticate with Batch, the remaining `az batch` commands use this account context to create and manage compute pools and jobs.
6062

6163
```azurecli-interactive
6264
az batch account login \
6365
--name mybatchaccount \
64-
--resource-group QuickstartBatch-rg \
66+
--resource-group qsBatch \
6567
--shared-key-auth
6668
```
6769

6870
## Create a pool of compute nodes
6971

70-
Now that you have a Batch account, create a sample pool of Linux compute nodes using the [az batch pool create](/cli/azure/batch/pool#az-batch-pool-create) command. The following example creates a pool named *mypool* of two *Standard_A1_v2* nodes running Ubuntu 18.04 LTS. The suggested node size offers a good balance of performance versus cost for this quick example.
72+
Use the [az batch pool create](/cli/azure/batch/pool#az-batch-pool-create) command to create a pool of Linux compute nodes in your Batch account. The following example creates a pool named `myPool` that consists of two `Standard_A1_v2` size nodes running `Ubuntu 18.04 LTS` OS. The node size offers a good balance of performance versus cost for this quickstart example.
7173

7274
```azurecli-interactive
7375
az batch pool create \
74-
--id mypool --vm-size Standard_A1_v2 \
76+
--id myPool --vm-size Standard_A1_v2 \
7577
--target-dedicated-nodes 2 \
7678
--image canonical:ubuntuserver:18.04-LTS \
7779
--node-agent-sku-id "batch.node.ubuntu 18.04"
7880
```
7981

80-
Batch creates the pool immediately, but it takes a few minutes to allocate and start the compute nodes. During this time, the pool is in the `resizing` state. To see the status of the pool, run the [az batch pool show](/cli/azure/batch/pool#az-batch-pool-show) command. This command shows all the properties of the pool, and you can query for specific properties. The following command gets the allocation state of the pool:
82+
Batch creates the pool immediately, but takes a few minutes to allocate and start the compute nodes. During this time, the pool is in the `resizing` state.
83+
84+
To see the pool status, run the [az batch pool show](/cli/azure/batch/pool#az-batch-pool-show) command. This command shows all the properties of the pool, and you can query for specific properties. The following command shows the pool allocation state:
8185

8286
```azurecli-interactive
83-
az batch pool show --pool-id mypool \
87+
az batch pool show --pool-id myPool \
8488
--query "allocationState"
8589
```
8690

87-
Continue the following steps to create a job and tasks while the pool state is changing. The pool is ready to run tasks when the allocation state is `steady` and all the nodes are running.
91+
You can do the following steps to create a job and tasks while the pool state is changing. The pool is ready to run tasks when the allocation state is `steady` and all the nodes are running.
8892

8993
## Create a job
9094

91-
Now that you have a pool, create a job to run on it. A Batch job is a logical group for one or more tasks. A job includes settings common to the tasks, such as priority and the pool to run tasks on. Create a Batch job by using the [az batch job create](/cli/azure/batch/job#az-batch-job-create) command. The following example creates a job *myjob* on the pool *mypool*. Initially the job has no tasks.
95+
Use the [az batch job create](/cli/azure/batch/job#az-batch-job-create) command to create a Batch job to run on your pool. A Batch job is a logical group of one or more tasks. The job includes settings common to the tasks, such as the pool to run tasks on. The following example creates a job called `myJob` on `myPool` that initially has no tasks.
9296

9397
```azurecli-interactive
9498
az batch job create \
95-
--id myjob \
96-
--pool-id mypool
99+
--id myJob \
100+
--pool-id myPool
97101
```
98102

99-
## Create tasks
103+
## Create job tasks
104+
105+
Use the [az batch task create](/cli/azure/batch/task#az-batch-task-create) command to create some tasks to run in the job. Each task has a command line that specifies an app or script. Batch provides several ways to deploy apps and scripts to compute nodes.
100106

101-
Now use the [az batch task create](/cli/azure/batch/task#az-batch-task-create) command to create some tasks to run in the job. In this example, you create four identical tasks. Each task runs a `command-line` to display the Batch environment variables on a compute node, and then waits 90 seconds. When you use Batch, this command line is where you specify your app or script. Batch provides several ways to deploy apps and scripts to compute nodes.
107+
The following Bash script creates four identical, parallel tasks called `myTask1` through `myTask4`. The task command line displays the Batch environment variables on the compute node, and then waits 90 seconds.
102108

103-
The following Bash script creates four parallel tasks (*mytask1* to *mytask4*).
104109

105110
```azurecli-interactive
106111
for i in {1..4}
107112
do
108113
az batch task create \
109-
--task-id mytask$i \
110-
--job-id myjob \
114+
--task-id myTask$i \
115+
--job-id myJob \
111116
--command-line "/bin/bash -c 'printenv | grep AZ_BATCH; sleep 90s'"
112117
done
113118
```
114119

115-
The command output shows settings for each of the tasks. Batch distributes the tasks to the compute nodes.
120+
The command output shows the settings for each task. Batch distributes the tasks to the compute nodes.
116121

117122
## View task status
118123

119-
After you create a task, Batch queues it to run on the pool. Once a node is available to run it, the task runs.
124+
After you create the task, Batch queues the task to run on the pool. Once a node is available, the task runs.
120125

121-
Use the [az batch task show](/cli/azure/batch/task#az-batch-task-show) command to view the status of the Batch tasks. The following example shows details about *mytask1* running on one of the pool nodes.
126+
Use the [az batch task show](/cli/azure/batch/task#az-batch-task-show) command to view the status of Batch tasks. The following example shows details about the status of `myTask1`:
122127

123128
```azurecli-interactive
124129
az batch task show \
125-
--job-id myjob \
126-
--task-id mytask1
130+
--job-id myJob \
131+
--task-id myTask1
127132
```
128133

129-
The command output includes many details, but take note of the `exitCode` of the task command line and the `nodeId`. An `exitCode` of 0 indicates that the task command line completed successfully. The `nodeId` indicates the ID of the pool node on which the task ran.
134+
The command output includes many details, but note the `nodeId` and the task command line `exitCode`. The `nodeId` shows the name of the pool node that ran the task. An `exitCode` of `0` indicates that the task command line completed successfully.
130135

131136
## View task output
132137

133-
To list the files created by a task on a compute node, use the [az batch task file list](/cli/azure/batch/task) command. The following command lists the files created by *mytask1*:
138+
Use the [az batch task file list](/cli/azure/batch/task) command to list the files a task created on a node. The following command lists the files that `myTask1` created:
134139

135140
```azurecli-interactive
136141
az batch task file list \
137-
--job-id myjob \
138-
--task-id mytask1 \
142+
--job-id myJob \
143+
--task-id myTask1 \
139144
--output table
140145
```
141146

142-
Output is similar to the following:
147+
Results are similar to the following output:
143148

144-
```
149+
```output
145150
Name URL Is Directory Content Length
146151
---------- ------------------------------------------------------------------------------------------ -------------- ----------------
147-
stdout.txt https://mybatchaccount.eastus2.batch.azure.com/jobs/myjob/tasks/mytask1/files/stdout.txt False 695
148-
certs https://mybatchaccount.eastus2.batch.azure.com/jobs/myjob/tasks/mytask1/files/certs True
149-
wd https://mybatchaccount.eastus2.batch.azure.com/jobs/myjob/tasks/mytask1/files/wd True
150-
stderr.txt https://mybatchaccount.eastus2.batch.azure.com/jobs/myjob/tasks/mytask1/files/stderr.txt False 0
152+
stdout.txt https://mybatchaccount.eastus2.batch.azure.com/jobs/myJob/tasks/myTask1/files/stdout.txt False 695
153+
certs https://mybatchaccount.eastus2.batch.azure.com/jobs/myJob/tasks/myTask1/files/certs True
154+
wd https://mybatchaccount.eastus2.batch.azure.com/jobs/myJob/tasks/myTask1/files/wd True
155+
stderr.txt https://mybatchaccount.eastus2.batch.azure.com/jobs/myJob/tasks/myTask1/files/stderr.txt False 0
151156
152157
```
153158

154-
To download one of the output files to a local directory, use the [az batch task file download](/cli/azure/batch/task) command. In this example, task output is in `stdout.txt`.
159+
Use the [az batch task file download](/cli/azure/batch/task) command to download output files to a local directory. The following example downloads the *stdout.txt* file:
155160

156161
```azurecli-interactive
157162
az batch task file download \
158-
--job-id myjob \
159-
--task-id mytask1 \
163+
--job-id myJob \
164+
--task-id myTask1 \
160165
--file-path stdout.txt \
161166
--destination ./stdout.txt
162167
```
163168

164-
You can view the contents of `stdout.txt` in a text editor. The contents show the Azure Batch environment variables that are set on the node. When you create your own Batch jobs, you can reference these environment variables in task command lines, and in the apps and scripts run by the command lines. For example:
169+
You can view the contents of the *stdout.txt* output file in a text editor. The contents show the Azure Batch environment variables that are set on the node. You can reference these environment variables in your Batch job task command lines, and in the apps and scripts the command lines run. The following example shows a typical *stdout.txt* file:
165170

166-
```
167-
AZ_BATCH_TASK_DIR=/mnt/batch/tasks/workitems/myjob/job-1/mytask1
171+
```text
172+
AZ_BATCH_TASK_DIR=/mnt/batch/tasks/workitems/myJob/job-1/myTask1
168173
AZ_BATCH_NODE_STARTUP_DIR=/mnt/batch/tasks/startup
169-
AZ_BATCH_CERTIFICATES_DIR=/mnt/batch/tasks/workitems/myjob/job-1/mytask1/certs
174+
AZ_BATCH_CERTIFICATES_DIR=/mnt/batch/tasks/workitems/myJob/job-1/myTask1/certs
170175
AZ_BATCH_ACCOUNT_URL=https://mybatchaccount.eastus2.batch.azure.com/
171-
AZ_BATCH_TASK_WORKING_DIR=/mnt/batch/tasks/workitems/myjob/job-1/mytask1/wd
176+
AZ_BATCH_TASK_WORKING_DIR=/mnt/batch/tasks/workitems/myJob/job-1/myTask1/wd
172177
AZ_BATCH_NODE_SHARED_DIR=/mnt/batch/tasks/shared
173178
AZ_BATCH_TASK_USER=_azbatch
174179
AZ_BATCH_NODE_ROOT_DIR=/mnt/batch/tasks
175-
AZ_BATCH_JOB_ID=myjobl
180+
AZ_BATCH_JOB_ID=myJobl
176181
AZ_BATCH_NODE_IS_DEDICATED=true
177182
AZ_BATCH_NODE_ID=tvm-257509324_2-20180703t215033z
178-
AZ_BATCH_POOL_ID=mypool
179-
AZ_BATCH_TASK_ID=mytask1
183+
AZ_BATCH_POOL_ID=myPool
184+
AZ_BATCH_TASK_ID=myTask1
180185
AZ_BATCH_ACCOUNT_NAME=mybatchaccount
181186
AZ_BATCH_TASK_USER_IDENTITY=PoolNonAdmin
182187
```
183188

184189
## Clean up resources
185190

186-
If you want to continue with Batch tutorials and samples, use the Batch account and linked storage account created in this quickstart. There is no charge for the Batch account itself.
191+
If you want to continue with Batch tutorials and samples, you can use the Batch account and linked storage account you created in this quickstart. There's no charge for the Batch account itself.
187192

188-
You are charged for pools while the nodes are running, even if no jobs are scheduled. When you no longer need a pool, delete it with the [az batch pool delete](/cli/azure/batch/pool#az-batch-pool-delete) command. When you delete the pool, all task output on the nodes is deleted.
193+
Pools and nodes incur charges while the nodes are running, even if they aren't running jobs. When you no longer need a pool, use the [az batch pool delete](/cli/azure/batch/pool#az-batch-pool-delete) command to delete it. Deleting a pool deletes all task output on the nodes and the nodes themselves.
189194

190195
```azurecli-interactive
191-
az batch pool delete --pool-id mypool
196+
az batch pool delete --pool-id myPool
192197
```
193198

194-
When no longer needed, you can use the [az group delete](/cli/azure/group#az-group-delete) command to remove the resource group, Batch account, pools, and all related resources. Delete the resources as follows:
199+
When you no longer need the resources you created for this quickstart, you can use the [az group delete](/cli/azure/group#az-group-delete) command to delete the resource group and all its resources, including the storage account, Batch account, node pools, and all related resources. Run the following command:
195200

196201
```azurecli-interactive
197-
az group delete --name QuickstartBatch-rg
202+
az group delete --name qsBatch
198203
```
199204

200205
## Next steps

0 commit comments

Comments
 (0)