Merge pull request #200656 from sheisanchez/first-arm-template

first arm tutorial review and new images

Author: v-ccolin

articles/azure-resource-manager/templates/media/template-tutorial-create-first-template/deployment-status.png

@@ -1,40 +1,40 @@
 ---
-title: Tutorial - Create & deploy template
+title: Tutorial - Create and deploy template
 description: Create your first Azure Resource Manager template (ARM template). In the tutorial, you learn about the template file syntax and how to deploy a storage account.
-author: mumian
-ms.date: 12/01/2021
+author: sheila
+ms.date: 06/07/2022
 ms.topic: tutorial
 ms.author: jgao
 ms.custom: devx-track-azurepowershell
 
-#Customer intent: As a developer new to Azure deployment, I want to learn how to use Visual Studio Code to create and edit Resource Manager templates, so I can use the templates to deploy Azure resources.
+#Customer intent: As a developer new to Azure deployment, I want to learn how to use Visual Studio Code to create and edit Azure Resource Manager templates, so I can use them to deploy Azure resources.
 
 ---
 
 # Tutorial: Create and deploy your first ARM template
 
-This tutorial introduces you to Azure Resource Manager templates (ARM templates). It shows you how to create a starter template and deploy it to Azure. You'll learn about the structure of the template and the tools you'll need for working with templates. It takes about **12 minutes** to complete this tutorial, but the actual time will vary based on how many tools you need to install.
+This tutorial introduces you to Azure Resource Manager templates (ARM templates). It shows you how to create a starter template and deploy it to Azure. It teaches you about the template structure and the tools you need to work with templates. It takes about **12 minutes** to complete this tutorial, but the actual time varies based on how many tools you need to install.
 
-This tutorial is the first of a series. As you progress through the series, you modify the starting template step by step until you've explored all of the core parts of an ARM template. These elements are the building blocks for much more complex templates. We hope by the end of the series you're confident creating your own templates and ready to automate your deployments with templates.
+This tutorial is the first of a series. As you progress through the series, you modify the starting template, step by step, until you've explored all of the core parts of an ARM template. These elements are the building blocks for more complex templates. We hope by the end of the series you're confident in creating your own templates and ready to automate your deployments with templates.
 
-If you want to learn about the benefits of using templates and why you should automate deployment with templates, see [ARM template overview](overview.md). To learn about ARM templates through a guided set of modules on Microsoft Learn, see [Deploy and manage resources in Azure by using ARM templates](/learn/paths/deploy-manage-resource-manager-templates/).
+If you want to learn about the benefits of using templates and why you should automate deployments with templates, see [ARM template overview](overview.md). To learn about ARM templates through a guided set of modules on [Microsoft Learn](/learn), see [Deploy and manage resources in Azure by using JSON ARM templates](/learn/paths/deploy-manage-resource-manager-templates.md).
 
-If you don't have an Azure subscription, [create a free account](https://azure.microsoft.com/free/) before you begin.
+If you don't have a Microsoft Azure subscription, [create a free account](https://azure.microsoft.com/free/) before you begin.
 
 > [!TIP]
-> If you're new to ARM templates, you might consider learning Bicep instead. Bicep is a new language that offers the same capabilities as ARM templates but with a syntax that's easier to use. To start learning Bicep, see [Quickstart: Create Bicep files with Visual Studio Code](../bicep/quickstart-create-bicep-use-visual-studio-code.md).
+> If you're new to ARM templates, you might consider learning Bicep instead. Bicep is a new language that offers the same capabilities as ARM templates but with an easier-to-use syntax. To start learning Bicep, see [Quickstart: Create Bicep files with Visual Studio Code](../bicep/quickstart-create-bicep-use-visual-studio-code.md).
 
 ## Get tools
 
 Let's start by making sure you have the tools you need to create and deploy templates. Install these tools on your local machine.
 
 ### Editor
 
-Templates are JSON files. To create templates, you need a good JSON editor. We recommend Visual Studio Code with the Resource Manager Tools extension. If you need to install these tools, see [Quickstart: Create ARM templates with Visual Studio Code](quickstart-create-templates-use-visual-studio-code.md).
+Templates are JavaScript Object Notation (JSON) files. To create templates, you need a good JSON editor. We recommend Visual Studio Code with the Azure Resource Manager Tools extension. If you need to install these tools, see [Quickstart: Create ARM templates with Visual Studio Code](quickstart-create-templates-use-visual-studio-code.md).
 
 ### Command-line deployment
 
-You also need either Azure PowerShell or Azure CLI to deploy the template. If you use Azure CLI, you must have the latest version. For the installation instructions, see:
+You also need either Azure PowerShell or Azure Command-Line Interface (CLI) to deploy the template. If you use Azure CLI, you need to have version 2.37.0 or later. For the installation instructions, see:
 
 - [Install Azure PowerShell](/powershell/azure/install-az-ps)
 - [Install Azure CLI on Windows](/cli/azure/install-azure-cli-windows)
@@ -44,17 +44,17 @@ You also need either Azure PowerShell or Azure CLI to deploy the template. If yo
 After installing either Azure PowerShell or Azure CLI, make sure you sign in for the first time. For help, see [Sign in - PowerShell](/powershell/azure/install-az-ps#sign-in) or [Sign in - Azure CLI](/cli/azure/get-started-with-azure-cli#sign-in).
 
 > [!IMPORTANT]
-> If you're using Azure CLI, make sure you have version 2.6 or later. The commands shown in this tutorial will not work if you're using earlier versions. To check your installed version, use: `az --version`.
+> If you're using Azure CLI, make sure you have version 2.37.0 or later. If you're using Azure PowerShell, make sure you have version 7.2.4 or later. The commands shown in this tutorial don't work if you're using earlier versions. To check your installed version, use: `az --version`.
 
 Okay, you're ready to start learning about templates.
 
 ## Create your first template
 
-1. Open Visual Studio Code with the Resource Manager Tools extension installed.
+1. Open Visual Studio Code with the installed ARM processor Tools extension.
 1. From the **File** menu, select **New File** to create a new file.
-1. From the **File** menu, select **Save as**.
+1. From the **File** menu, select **Save As**.
 1. Name the file _azuredeploy_ and select the _json_ file extension. The complete name of the file is _azuredeploy.json_.
-1. Save the file to your workstation. Select a path that is easy to remember because you'll provide that path later when deploying the template.
+1. Save the file to your workstation. Select a path that's easy to remember because you need to provide that path later when deploying the template.
 1. Copy and paste the following JSON into the file:
 
     ```json
@@ -67,25 +67,25 @@ Okay, you're ready to start learning about templates.
 
     Here's what your Visual Studio Code environment looks like:
 
-    ![ARM template Visual Studio Code first template](./media/template-tutorial-create-first-template/resource-manager-visual-studio-code-first-template.png)
+    :::image type="content" source="./media/template-tutorial-create-first-template/resource-manager-visual-studio-code-first-template.png" alt-text="ARM template Visual Studio Code first template.":::
 
     This template doesn't deploy any resources. We're starting with a blank template so you can get familiar with the steps to deploy a template while minimizing the chance of something going wrong.
 
     The JSON file has these elements:
 
-    - `$schema`: Specifies the location of the JSON schema file. The schema file describes the properties that are available within a template. For example, the schema defines `resources` as one of the valid properties for a template. Don't worry that the date for the schema is 2019-04-01. This schema version is up to date and includes all of the latest features. The schema date hasn't been changed because there have been no breaking changes since its introduction.
-    - `contentVersion`: Specifies the version of the template (such as 1.0.0.0). You can provide any value for this element. Use this value to document significant changes in your template. When deploying resources using the template, this value can be used to make sure that the right template is being used.
-    - `resources`: Contains the resources you want to deploy or update. Currently, it's empty, but you'll add resources later.
+    - `$schema`: Specifies the location of the JSON schema file. The schema file describes the properties that are available within a template. The schema, for example, defines `resources` as one of the valid properties for a template. Don't worry that the date for the schema is 2019-04-01. This schema version is up to date and includes all of the latest features. The schema date hasn't been changed because there have been no breaking changes since its introduction.
+    - `contentVersion`: Specifies the version of the template, such as 1.0.0.0. You can provide any value for this element. Use this value to document significant changes in your template. When you deploy resources using the template, you can use this value to make sure you're using the right template.
+    - `resources`: Contains the resources you want to deploy or update. Currently, it's empty, but you can add resources later.
 
 1. Save the file.
 
 Congratulations, you've created your first template.
 
 ## Sign in to Azure
 
-To start working with Azure PowerShell/Azure CLI, sign in with your Azure credentials.
+To start working with Azure PowerShell or Azure CLI, sign in with your Azure credentials.
 
-Select the tabs in the following code sections to choose between Azure PowerShell and Azure CLI. The CLI examples in this article are written for the Bash shell.
+Select the tabs in the following code sections to pick between Azure PowerShell and Azure CLI. The CLI examples in this article are written for the Bash shell.
 
 # [PowerShell](#tab/azure-powershell)
 
@@ -101,7 +101,7 @@ az login
 
 ---
 
-If you have multiple Azure subscriptions, select the subscription you want to use. Replace `SubscriptionName` with your subscription name. You can also use the subscription ID instead of the subscription name.
+If you have multiple Azure subscriptions, choose the subscription you want to use. Replace `SubscriptionName` with your subscription name. You can also use your subscription ID instead of your subscription name.
 
 # [PowerShell](#tab/azure-powershell)
 
@@ -119,7 +119,12 @@ az account set --subscription SubscriptionName
 
 ## Create resource group
 
-When you deploy a template, you specify a resource group that will contain the resources. Before running the deployment command, create the resource group with either Azure CLI or Azure PowerShell.
+When you deploy a template, you can specify a resource group to contain the resources. Before running the deployment command, create the resource group with either the Bash Azure CLI or Azure PowerShell. 
+
+> [!NOTE]
+> Samples for the Azure CLI are written for the bash shell. To run this sample in Windows PowerShell or the Command Prompt, you may need to remove the back slashes and write the command as one line such as:
+
+```az group create --name myResourceGroup --location "Central US"```
 
 # [PowerShell](#tab/azure-powershell)
 
@@ -155,7 +160,7 @@ New-AzResourceGroupDeployment `
 
 # [Azure CLI](#tab/azure-cli)
 
-To run this deployment command, you must have the [latest version](/cli/azure/install-azure-cli) of Azure CLI.
+To run this deployment command, you need to have the [latest version](/cli/azure/install-azure-cli) of Azure CLI.
 
 ```azurecli
 templateFile="{provide-the-path-to-the-template-file}"
@@ -171,11 +176,11 @@ The deployment command returns results. Look for `ProvisioningState` to see whet
 
 # [PowerShell](#tab/azure-powershell)
 
-![PowerShell deployment provisioning state](./media/template-tutorial-create-first-template/resource-manager-deployment-provisioningstate.png)
+  :::image type="content" source="./media/template-tutorial-create-first-template/resource-manager-deployment-provisioningstate.png" alt-text="PowerShell deployment provisioning state.":::
 
 # [Azure CLI](#tab/azure-cli)
 
-![Azure CLI deployment provisioning state](./media/template-tutorial-create-first-template/azure-cli-provisioning-state.png)
+  :::image type="content" source="./media/template-tutorial-create-first-template/azure-cli-provisioning-state.png" alt-text="Azure CLI deployment provisioning state.":::
 
 ---
 
@@ -190,34 +195,38 @@ You can verify the deployment by exploring the resource group from the Azure por
 
 1. From the left menu, select **Resource groups**.
 
-1. Select the resource group deploy in the last procedure. The default name is **myResourceGroup**. You shall see no resource deployed within the resource group.
+1. Check the box to the left of **myResourceGroup** and select **myResourceGroup**.
 
-1. Notice in the upper right of the overview, the status of the deployment is displayed. Select **1 Succeeded**.
+1. Select the resource group you created in the earlier procedure. The default name is **myResourceGroup**. The resource group doesn't have any resources yet because you deployed a blank template.
 
-   ![View deployment status](./media/template-tutorial-create-first-template/deployment-status.png)
+1. Notice in the middle of the overview, in the **Essentials** section, the page displays the deployment status next to **Deployments**. Select **1 Succeeded**.
 
-1. You see a history of deployment for the resource group. Select **blanktemplate**.
+    :::image type="content" source="./media/template-tutorial-create-first-template/deployment-status.png" alt-text="See deployment status.":::
 
-   ![Select deployment](./media/template-tutorial-create-first-template/select-from-deployment-history.png)
+1. You see a history of deployment for the resource group. Check the box to the left of **blanktemplate** and select **blanktemplate**.
 
-1. You see a summary of the deployment. In this case, there's not a lot to see because no resources were deployed. Later in this series you might find it helpful to review the summary in the deployment history. Notice on the left you can view inputs, outputs, and the template used during deployment.
+    :::image type="content" source="./media/template-tutorial-create-first-template/select-from-deployment-history.png" alt-text="Select deployment.":::
 
-   ![View deployment summary](./media/template-tutorial-create-first-template/view-deployment-summary.png)
+1. You see a summary of the deployment. In this case, there's not a lot to see because no resources are deployed. Later in this series you might find it helpful to review the summary in the deployment history. Notice on the left you can see inputs, outputs, and  the template that the deployment used.
+
+    :::image type="content" source="./media/template-tutorial-create-first-template/view-deployment-summary.png" alt-text="See deployment summary.":::
 
 ## Clean up resources
 
 If you're moving on to the next tutorial, you don't need to delete the resource group.
 
 If you're stopping now, you might want to delete the resource group.
 
-1. From the Azure portal, select **Resource group** from the left menu.
-2. Enter the resource group name in the **Filter by name** field.
-3. Select the resource group name.
+1. From the Azure portal, select **Resource groups** from the left menu.
+2. Type the resource group name in the **Filter for any field...**.
+3. Check the box next to **myResourceGroup** and select **myResourceGroup** or the resource group name you chose.
 4. Select **Delete resource group** from the top menu.
 
+    :::image type="content" source="./media/template-tutorial-create-first-template/resource-deletion.png" alt-text="See deletion.":::
+
 ## Next steps
 
-You created a simple template to deploy to Azure. In the next tutorial, you'll add a storage account to the template and deploy it to your resource group.
+You created a simple template to deploy to Azure. In the next tutorial, you can learn how to add a storage account to the template and deploy it to your resource group.
 
 > [!div class="nextstepaction"]
 > [Add resource](template-tutorial-add-resource.md)