Merge pull request #80544 from cynthn/iblinux-updates

Image Builder - Daniel edits

Author: v-dansch

articles/virtual-machines/linux/image-builder.md

@@ -16,6 +16,7 @@ This article shows you how you can create a customized Linux image using the Azu
 - Shell (inline) - runs specific commands. In this example, the inline commands include creating a directory and updating the OS.
 - File - copies a [file from GitHub](https://raw.githubusercontent.com/danielsollondon/azvmimagebuilder/master/quickquickstarts/exampleArtifacts/buildArtifacts/index.html) into a directory on the VM.
 
+
 We will be using a sample .json template to configure the image. The .json file we are using is here: [helloImageTemplateLinux.json](https://raw.githubusercontent.com/danielsollondon/azvmimagebuilder/master/quickquickstarts/0_Creating_a_Custom_Linux_Managed_Image/helloImageTemplateLinux.json). 
 
 > [!IMPORTANT]
@@ -52,7 +53,7 @@ az provider register -n Microsoft.VirtualMachineImages
 az provider register -n Microsoft.Storage
 ```
 
-## Create a resource group
+## Setup Example Variables
 
 We will be using some pieces of information repeatedly, so we will create some variables to store that information.
 
@@ -74,14 +75,17 @@ Create a variable for your subscription ID. You can get this using `az account s
 subscriptionID=<Your subscription ID>
 ```
 
-Create the resource group.
+## Create the resource group.
+This is used to store the image configuration template artifact and the image.
 
 ```azurecli-interactive
 az group create -n $imageResourceGroup -l $location
 ```
 
+## Set permissions on the resource group
+Give Image Builder 'contributor' permission to create the image in the resource group. Without the proper permissions, the image build will fail. 
 
-Give Image Builder permission to create resources in that resource group. The `--assignee` value is the app registration ID for the Image Builder service. 
+The `--assignee` value is the app registration ID for the Image Builder service. 
 
 ```azurecli-interactive
 az role assignment create \
@@ -90,9 +94,9 @@ az role assignment create \
     --scope /subscriptions/$subscriptionID/resourceGroups/$imageResourceGroup
 ```
 
-## Download the .json example
+## Download the template example
 
-Download the example .json file and configure it with the variables you created.
+A parameterized sample image configuration template has been created for you to use. Download the sample .json file and configure it with the variables you set earlier.
 
 ```azurecli-interactive
 curl https://raw.githubusercontent.com/danielsollondon/azvmimagebuilder/master/quickquickstarts/0_Creating_a_Custom_Linux_Managed_Image/helloImageTemplateLinux.json -o helloImageTemplateLinux.json
@@ -104,7 +108,19 @@ sed -i -e "s/<imageName>/$imageName/g" helloImageTemplateLinux.json
 sed -i -e "s/<runOutputName>/$runOutputName/g" helloImageTemplateLinux.json
 ```
 
-## Create the image
+You can modify this example .json as needed. For example, you can increase the value of `buildTimeoutInMinutes` to allow for longer running builds. You can edit the file in Cloud Shell using `vi`.
+
+```azurecli-interactive
+vi helloImageTemplateLinux.json
+```
+
+> [!NOTE]
+> For source image, you must always [specify a version](https://github.com/danielsollondon/azvmimagebuilder/blob/master/troubleshootingaib.md#image-version-failure), you cannot use `latest`.
+>
+> If you add or change the resource group where the image is being distributed, you need to make sure the [permissions are set for the resource group](#set-permissions-on-the-resource-group).
+
+
+## Submit the image configuration
 Submit the image configuration to the VM Image Builder service
 
 ```azurecli-interactive
@@ -116,8 +132,27 @@ az resource create \
     -n helloImageTemplateLinux01
 ```
 
+If it completes successfully, it will return a success message, and create an image builder configuration template artifact in the $imageResourceGroup. You can see the resource group in the portal if you enable 'Show hidden types'.
+
+Also, in the background, Image Builder creates a staging resource group in your subcription. Image Builder uses the staging resource group for the image build. The name of the resource group will be in this format: `IT_<DestinationResourceGroup>_<TemplateName>`.
+
+> [!IMPORTANT]
+> Do not delete the staging resource group directly. If you delete the image template artifact, it will automatically delete the staging resource group. For more information, see the [Clean up](#clean-up) section at the end of this article.
+
+If the service reports a failure during the image configuration template submission, see the [troubleshooting](https://github.com/danielsollondon/azvmimagebuilder/blob/master/troubleshootingaib.md#template-submission-errors--troubleshooting) steps. You will also need to delete the template before you retry submitting the build. To delete the template:
+
+```azurecli-interactive
+az resource delete \
+    --resource-group $imageResourceGroup \
+    --resource-type Microsoft.VirtualMachineImages/imageTemplates \
+    -n helloImageTemplateLinux01
+```
+
+## Start the image build
+
 Start the image build.
 
+
 ```azurecli-interactive
 az resource invoke-action \
      --resource-group $imageResourceGroup \
@@ -126,7 +161,9 @@ az resource invoke-action \
      --action Run 
 ```
 
-Wait until the build is complete. This can take about 15 minutes.
+Wait until the build is complete, for this example, it can take 10-15 minutes.
+
+If you encounter any errors, please review these [troubleshooting](https://github.com/danielsollondon/azvmimagebuilder/blob/master/troubleshootingaib.md#image-build-errors--troubleshooting) steps.
 
 
 ## Create the VM
@@ -174,14 +211,20 @@ For more detailed information about this .json file, see [Image builder template
 
 ## Clean up
 
-When you are done, delete the resources.
+When you are done, you can delete the resources.
+
+Delete the image builder template.
 
 ```azurecli-interactive
 az resource delete \
     --resource-group $imageResourceGroup \
     --resource-type Microsoft.VirtualMachineImages/imageTemplates \
     -n helloImageTemplateLinux01
+```
+
+Delete the image resource group.
 
+```bash
 az group delete -n $imageResourceGroup
 ```
 

articles/virtual-machines/linux/toc.yml

@@ -274,13 +274,13 @@
       items:
       - name: Overview
         href: image-builder-overview.md
-      - name: Use CLI
+      - name: Use Azure CLI
         href: image-builder.md
       - name: Template reference
         href: image-builder-json.md
-      - name: Use with galleries
+      - name: Build for image galleries
         href: image-builder-gallery.md
-      - name: Update an image version
+      - name: Update an existing image
         href: image-builder-gallery-update-image-version.md
       - name: Troubleshoot
         href: https://github.com/danielsollondon/azvmimagebuilder/blob/master/troubleshootingaib.md

articles/virtual-machines/windows/toc.yml

@@ -267,17 +267,17 @@
       items:
       - name: Overview
         href: ../linux/image-builder-overview.md?toc=%2fazure%2fvirtual-machines%2fwindows%2ftoc.json
-      - name: Use CLI
+      - name: Use Azure CLI 
         href: image-builder.md
-      - name: Use with galleries
+      - name: Build for image galleries
         href: image-builder-gallery.md
-      - name: Update an image version
+      - name: Update an existing image
         href: image-builder-gallery-update-image-version.md
-      - name: Use scripts in Azure Storage
+      - name: Storing scripts
         href: ../linux/image-builder-user-assigned-identity.md?toc=%2fazure%2fvirtual-machines%2fwindows%2ftoc.json
       - name: Template reference
         href: ../linux/image-builder-json.md?toc=%2fazure%2fvirtual-machines%2fwindows%2ftoc.json
-      - name: Troubleshoot
+      - name: Troubleshoot 
         href: https://github.com/danielsollondon/azvmimagebuilder/blob/master/troubleshootingaib.md
     - name: Find and use images
       href: cli-ps-findimage.md