Merge pull request #191794 from v-thepet/misc

DTL articles: Reference architecture, Create VM PowerShell, Manage storage account, Start VMs Automation runbook

Author: LJSpiller

articles/devtest-labs/TOC.yml

@@ -71,6 +71,8 @@
       href: devtest-lab-auto-shutdown.md
     - name: Set auto startup for lab VMs
       href: devtest-lab-auto-startup-vm.md
+    - name: Manage lab storage account
+      href: encrypt-storage.md
     - name: Scale your lab
       href: devtest-lab-scale-lab.md
     - name: Manage virtual machine bases
@@ -137,7 +139,7 @@
       href: devtest-lab-store-secrets-in-key-vault.md
     - name: Attach and detach data disks
       href: devtest-lab-attach-detach-data-disk.md
-    - name: Start VMs using Automation runbooks
+    - name: Define start order for lab VMs
       href: start-machines-use-automation-runbooks.md
     - name: Import virtual machines from another lab
       href: import-virtual-machines-from-another-lab.md
@@ -200,12 +202,8 @@
       href: devtest-lab-mandatory-artifacts.md
     - name: Troubleshoot issues with applying artifacts
       href: devtest-lab-troubleshoot-apply-artifacts.md
-  - name: Encrypt lab resources
-    items:
-    - name: Encrypt storage used by a lab
-      href: encrypt-storage.md
-    - name: Encrypt OS disks using customer-managed keys
-      href: encrypt-disks-customer-managed-keys.md
+  - name: Encrypt OS disks using customer-managed keys
+    href: encrypt-disks-customer-managed-keys.md
   - name: Integrate with CI/CD
     items:
     - name: Integrate labs into your Azure Pipelines CI/CD pipeline

articles/devtest-labs/devtest-lab-reference-architecture.md

@@ -1,71 +1,50 @@
 ---
-title: Encrypt an Azure storage account used by a lab
-description: Learn how to configure encryption of an Azure storage used by a lab in Azure DevTest Labs 
+title: Manage storage accounts for labs
+description: Learn about DevTest Labs storage accounts, encryption, customer-managed keys, and setting expiration dates for artifact results storage.
 ms.topic: how-to
-ms.date: 07/29/2020
+ms.date: 03/15/2022
 ---
 
-# Encrypt Azure storage used by a lab in Azure DevTest Labs
-Every lab created in Azure DevTest Labs is created with an associated Azure storage account. The storage account is used for the following purposes: 
+# Manage Azure DevTest Labs storage accounts
 
-- Storing [formula](devtest-lab-manage-formulas.md) documents that can be used to create virtual machines.
-- Storing artifact results that include deployment and extension logs generated from applying artifacts. 
-- [Uploading virtual hard disks (VHDs) to create custom images in the lab.](devtest-lab-create-template.md)
-- Caching frequently used [artifacts](add-artifact-vm.md) and [Azure Resource Manager templates](devtest-lab-create-environment-from-arm.md) for faster retrieval during virtual machine/environment creation.
+This article explains how to view and manage the Azure Storage accounts associated with Azure DevTest Labs.
 
-> [!NOTE]
-> The information above is critical for the lab to operate. It's stored for the life of the lab (and lab resources) unless explicitly deleted. Manually deleting these resources can lead to errors in creating lab VMs and/or formulas becoming corrupt for future use. 
+## View storage account contents
 
-## Locate the storage account and view its contents
+DevTest Labs automatically creates an Azure Storage account for every lab it creates. To see a lab's storage account and the information it holds:
 
-1. On the home page for the lab, select the **resource group** on the **Overview** page. You should see the **Resource group** page for the resource group that contains the lab. 
+1. On the lab's **Overview** page, select the **Resource group**.
 
-    :::image type="content" source="./media/encrypt-storage/overview-resource-group-link.png" alt-text="Select resource group on the Overview page":::
-1. Select the Azure storage account of the lab. The naming convention for the lab storage account is: `a<labNameWithoutInvalidCharacters><4-digit number>`. For example, if the lab name is `contosolab`, the storage account name could be `acontosolab7576`. 
+   :::image type="content" source="./media/encrypt-storage/overview-resource-group-link.png" alt-text="Screenshot that shows selecting the resource group on the lab Overview page.":::
 
-    :::image type="content" source="./media/encrypt-storage/select-storage-account.png" alt-text="Select storage account in the resource group of the lab":::
-3. On the **Storage account** page, select **Storage Explorer (preview)** on the left menu, and then select **BLOB CONTAINERS** to find relevant lab-related content. 
+1. On the resource group's **Overview** page, select the lab's storage account. The naming convention for the lab storage account is: `a<labName><4-digit number>`. For example, if the lab name is `contosolab`, the storage account name could be `acontosolab5237`. 
 
-   :::image type="content" source="./media/encrypt-storage/storage-explorer.png" alt-text="Storage Explorer (Preview)" lightbox="./media/encrypt-storage/storage-explorer.png":::
+   :::image type="content" source="./media/encrypt-storage/select-storage-account.png" alt-text="Screenshot that shows selecting the storage account in the lab's resource group.":::
 
-## Encrypt the lab storage account
-Azure Storage automatically encrypts your data when it's persisted to the cloud. Azure Storage encryption protects your data and helps you to meet your organizational security and compliance commitments. For more information, see [Azure Storage encryption for data at rest](../storage/common/storage-service-encryption.md).
+3. On the **Storage account** page, select **Storage browser (preview)** on the left menu, and then select **Blob containers** to see relevant lab-related content.
 
-Data in the lab storage account is encrypted with a **Microsoft-managed key**. You can rely on Microsoft-managed keys for the encryption of your data, or you can manage encryption with your own keys. If you choose to manage encryption with your own keys for the lab’s storage account, you can specify a **customer-managed key** with Azure Key Vault to use for encrypting/decrypting data in Blob storage and in Azure Files. For more information about customer-managed keys, see [Use customer-managed keys with Azure Key Vault to manage Azure Storage encryption](../storage/common/customer-managed-keys-overview.md).
+   :::image type="content" source="./media/encrypt-storage/storage-explorer.png" alt-text="Screenshot that shows the Storage browser (preview).":::
 
-To learn how to configure customer-managed keys for Azure Storage encryption, see the following articles: 
+## Manage Azure Storage lifecycle
 
-- [Azure portal](../storage/common/customer-managed-keys-configure-key-vault.md)
-- [Azure PowerShell](../storage/common/customer-managed-keys-configure-key-vault.md)
-- [Azure CLI](../storage/common/customer-managed-keys-configure-key-vault.md)
+The lab storage account stores:
 
+- [Formula documents](devtest-lab-manage-formulas.md) to use for creating lab virtual machines (VMs).
+- [Uploaded virtual hard disks (VHDs)](devtest-lab-create-template.md) to use for creating custom VM images.
+- [Artifact](add-artifact-vm.md) and [Azure Resource Manager (ARM) template](devtest-lab-create-environment-from-arm.md) caches, for faster retrieval during VM and environment creation.
+- Artifact results, which are deployment and extension logs generated from applying artifacts.
 
-## Manage the Azure Blob storage life cycle
-As mentioned, the information stored in the Lab’s storage account is critical for the lab to operate without any errors. Unless explicitly deleted, this data will continue to remain in the lab’s storage account for the life of the lab or the life of specific lab virtual machines, depending on the type of data.
+The information in the lab storage account persists for the life of the lab and its resources, unless explicitly deleted. Most of this information is critical for the lab to operate. Manually deleting storage account information can cause data corruption or VM creation errors.
 
-### Uploaded VHDs
-These VHDs are used to create custom images. Removing them will make it no longer possible to create custom images from these VHDs.
+- Removing uploaded VHDs makes it no longer possible to create custom images from these VHDs.
+- Deleting formula documents can lead to errors when creating VMs from formulas, updating formulas, or creating new formulas.
+- DevTest Labs refreshes the artifact and ARM template caches whenever the lab connects to the artifact or template repositories. If you remove the caches manually, DevTest Labs recreates the caches the next time the lab connects to the repositories.
 
-### Artifacts Cache
-These caches will be re-created any time artifacts are applied. They'll be refreshed with the latest content from the respective referenced repositories. So, if you delete this information to save Storage-related expenses, the relief will be temporary.
+### Set expiration for artifact results
 
-### Azure Resource Manager template Cache
-These caches will be re-created any time Azure Resource Manager-based template repositories are connected and spun up in the lab. They'll be refreshed with the latest content from the respective referenced repositories. So, if you delete this information to save Storage-related expenses, the relief will be temporary.
+The artifact results size can increase over time as artifacts are applied. You can set an expiration rule for artifact results to regularly delete older results from the storage account. This practice reduces storage account size and helps control costs.
 
-### Formulas
-These documents are used to support the option to both create formulas from existing VMs, and creating VMs from formulas. Deleting these formula documents may lead to errors while doing the following operations:
-
-- Creating a formula from an existing lab VM
-- Creating or updating formulas 
-- Creating a VM from a formula.
-
-### Artifact results
-As artifacts are applied, the size of the respective artifact results can increase over time depending on the number and type of artifacts being run on lab VMs. So, as a lab owner, you may want to control the lifecycle of such documents. For more information, see [Manage the Azure Blob storage lifecycle](../storage/blobs/lifecycle-management-overview.md).
-
-> [!IMPORTANT]
-> We recommend that you do this step to reduce expenses associated with the Azure Storage account. 
-
-For example, the following rule is used to set a 90-day expiration rule specifically for artifact results. It ensures that older artifact results are recycled from the storage account on a regular cadence.
+The following rule sets a 90-day expiration specifically for artifact results:
 
 ```json
 {
@@ -93,9 +72,18 @@ For example, the following rule is used to set a 90-day expiration rule specific
 }
 ```
 
+## Storage encryption and customer-managed keys
+
+Azure Storage automatically encrypts all data in the lab storage account. Azure Storage encryption protects your data and helps meet organizational security and compliance commitments. For more information, see [Azure Storage encryption for data at rest](../storage/common/storage-service-encryption.md).
+
+Azure Storage encrypts lab data with a Microsoft-managed key. Optionally, you can manage encryption with your own keys. If you choose to manage lab storage account encryption with your own key, you can use Azure Key Vault to  specify a customer-managed key for encrypting and decrypting data.
+
+For more information and instructions on configuring customer-managed keys for Azure Storage encryption, see:
+
+- [Use customer-managed keys with Azure Key Vault to manage Azure Storage encryption](/azure/storage/common/customer-managed-keys-overview.md)
+- [Configure encryption with customer-managed keys stored in Azure Key Vault](/azure/storage/common/customer-managed-keys-configure-key-vault)
+
 ## Next steps
-To learn how to configure customer-managed keys for Azure Storage encryption, see the following articles: 
 
-- [Azure portal](../storage/common/customer-managed-keys-configure-key-vault.md)
-- [Azure PowerShell](../storage/common/customer-managed-keys-configure-key-vault.md)
-- [Azure CLI](../storage/common/customer-managed-keys-configure-key-vault.md)
+For more information about managing Azure Storage, see [Optimize costs by automatically managing the data lifecycle](../storage/blobs/lifecycle-management-overview.md).
+

articles/devtest-labs/devtest-lab-vm-powershell.md

@@ -1,25 +1,34 @@
 ---
-title: Start machines using Automation runbooks
-description: Learn how to start virtual machines in a lab in Azure DevTest Labs by using Azure Automation runbooks. 
+title: Define VM start order with Azure Automation
+description: Learn how to start virtual machines in a specific order by using Azure Automation runbooks in Azure DevTest Labs.
 ms.topic: how-to
-ms.date: 06/26/2020 
+ms.date: 03/17/2022
 ms.custom: devx-track-azurepowershell
 ---
 
-# Start virtual machines in a lab in order by using Azure Automation runbooks
-The [autostart](devtest-lab-set-lab-policy.md#set-autostart) feature of DevTest Labs allows you to configure VMs to start automatically at a specified time. However, this feature doesn't support machines to start in a specific order. There are several scenarios where this type of automation would be useful.  One scenario is where a Jumpbox VM in a lab is the access point to the other VMs. The Jumpbox VM must start before the other VMs. This article shows you how to set up an Azure Automation account with a PowerShell runbook that executes a script. The script uses tags on VMs in the lab to allow you to control the startup order without having to change the script.
+# Define the startup order for DevTest Lab VMs with Azure Automation
 
-## Setup
-In this example, VMs in the lab need to have the tag **StartupOrder** added with the appropriate value, such as 0, 1, 2. Designate any machine that doesn't need starting as -1.
+This article explains how to start up DevTest Labs virtual machines (VMs) in a specific order by using a PowerShell runbook in Azure Automation. The PowerShell script uses tags on lab VMs, so you can change the startup order without having to change the script.
 
-## Create an Azure Automation account
-Create an Azure Automation account by following instructions in [this article](../automation/automation-create-standalone-account.md). Choose the **Run As Accounts** option when creating the account. Once the automation account is created, open the **Modules** page, and select **Update Azure Modules** on the menu bar. The default modules are several versions old and without the update the script may not function.
+The DevTest Labs [autostart](devtest-lab-set-lab-policy.md#set-autostart) feature can configure lab VMs to start automatically at a specified time. However, sometimes you might want lab VMs to start in a specific sequence. For example, if a jumpbox VM in a lab is the access point to the other VMs, the jumpbox VM must start before the other VMs.
 
-## Add a runbook
-Now, to add a runbook to the automation account, select **Runbooks** on the left menu. Select **Add a runbook** on the menu, and follow instructions to [create a PowerShell runbook](../automation/learn/powershell-runbook-managed-identity.md).
+## Prerequisites
 
-## PowerShell script
-The following script takes the subscription name, the lab name as parameters. The flow of the script is to get all the VMs in the lab, and then parse out the tag information to create a list of the VM names and their startup order. The script walks through the VMs in order and starts the VMs. If there are multiple VMs in a specific order number, they start asynchronously using PowerShell jobs. For those VMs that don’t have a tag, set startup value to be the last (10). Those machines start last, by default.  If you don't want the VM to be auto started, set the tag value to 11, and the script will ignore the VM.
+- [Create and apply a tag](devtest-lab-add-tag.md) called **StartupOrder** to all lab VMs with an appropriate startup value, 0 through 10. Designate any machines that don't need starting as -1.
+
+- Create an Azure Automation account by following instructions in [Create a standalone Azure Automation account](/azure/automation/automation-create-standalone-account). Choose the **Run As Accounts** option when you create the account.
+
+## Create the PowerShell runbook
+
+1. On the **Overview** page for the Automation Account, select **Runbooks** from the left menu.
+1. On the **Runbooks** page, select **Create a runbook**.
+1. Follow the instructions in [Create an Automation PowerShell runbook using managed identity](../automation/learn/powershell-runbook-managed-identity.md) to create a PowerShell runbook. Populate the runbook with the following PowerShell script.
+
+## Prepare the PowerShell script
+
+The following script takes the subscription name and the lab name as parameters. The script gets all the VMs in the lab and parses their tag information to create a list of VM names and their startup order. The script walks through the list in order and starts the VMs.
+
+If there are multiple VMs in a specific order number, those VMs start asynchronously using PowerShell jobs. VMs that don't have a tag have their startup value set to 10 and start last by default. The script ignores any VMs that have tag values other than 0 through 10.
 
 ```powershell
 #Requires -Version 3.0
@@ -46,7 +55,7 @@ $dtLab = Find-AzResource -ResourceType 'Microsoft.DevTestLab/labs' -ResourceName
 $dtlAllVms = New-Object System.Collections.ArrayList
 $AllVMs = Get-AzResource -ResourceId "$($dtLab.ResourceId)/virtualmachines" -ApiVersion 2016-05-15
 
-# Get the StartupOrder tag, if missing set to be run last (10)
+# Get the StartupOrder tag. If missing, set to start up last (10).
 ForEach ($vm in $AllVMs) {
     if ($vm.Tags) {
         if ($vm.Tags['StartupOrder']) {
@@ -119,10 +128,16 @@ While ($current -le 10) {
 }
 ```
 
-## Create a schedule
-To have this script execute daily, [create a schedule](../automation/shared-resources/schedules.md#create-a-schedule) in the automation account. Once the schedule is created, [link it to the runbook](../automation/shared-resources/schedules.md#link-a-schedule-to-a-runbook). 
+## Run the script
+
+- To run this script daily, [create a schedule](../automation/shared-resources/schedules.md#create-a-schedule) in the Automation Account, and [link the schedule to the runbook](../automation/shared-resources/schedules.md#link-a-schedule-to-a-runbook).
 
-In a large-scale situation that has multiple subscriptions with multiple labs, store the parameter information in a file for different labs. Pass the file to the script instead of passing the individual parameters. The script must be modified, but the core execution is the same. While this sample uses the Azure Automation to execute the PowerShell script, there are other options like using a task in a Build/Release pipeline.
+- In an enterprise scenario that has several subscriptions with multiple labs, you can store the parameter information for different labs and subscriptions in a file. Pass the file to the script instead of passing the individual parameters.
+
+- This example uses Azure Automation to run the PowerShell script, but you can also use other options, like a [build/release pipeline](use-devtest-labs-build-release-pipelines.md).
 
 ## Next steps
-See the following article to learn more about Azure Automation: [An introduction to Azure Automation](../automation/automation-intro.md).
+
+- [What is Azure Automation?](/azure/automation/automation-intro)
+- [Start up lab virtual machines automatically](devtest-lab-auto-startup-vm.md)
+- [Use command-line tools to start and stop Azure DevTest Labs virtual machines](use-command-line-start-stop-virtual-machines.md)