Merge pull request #304505 from RoseHJM/dtl-image-factory-deprecation

Stacyrch140 · web-flow · commit a7959bf6e05b · 2025-08-28T12:13:28.000-04:00
DTL - Image Factory -&gt; Image Builder note
diff --git a/articles/devtest-labs/image-factory-create.md b/articles/devtest-labs/image-factory-create.md
@@ -11,6 +11,8 @@ ms.custom: UpdateFrequency2
 # Create a custom image factory in Azure DevTest Labs
 This article shows you how to set up a custom image factory by using sample scripts available in the [Git repository](https://github.com/Azure/azure-devtestlab/tree/master/samples/DevTestLabs/Scripts/ImageFactory).
 
+[!INCLUDE [direct-azure-image-builder](includes/direct-azure-image-builder.md)]
+
 ## What's an image factory?
 An image factory is a configuration-as-code solution that builds and distributes images automatically regularly with all the desired configurations. The images in the image factory are always up to date, and the ongoing maintenance is almost zero once the whole process is automated. And, because all the required configurations are already in the image, it saves the time from manually configuring the system after a VM has been created with the base OS.
 
@@ -38,7 +40,7 @@ Using the DevTest Labs extension is an easy way to get started with automaticall
 
 There's an alternate implementation using PowerShell script for a more complex scenario. Using PowerShell, you can fully automate an image factory based on DevTest Labs that can be used in your Continuous Integration and Continuous Delivery (CI/CD) toolchain. The principles followed in this alternate solution are:
 
-- Common updates should require no changes to the image factory. (for example, adding a new type of custom image, automatically retiring old images, adding a new ‘endpoint’ DevTest Labs to receive custom images, and so on.)
+- Common updates should require no changes to the image factory. (for example, adding a new type of custom image, automatically retiring old images, adding a new 'endpoint' DevTest Labs to receive custom images, and so on.)
 - Common changes are backed by source code control (infrastructure as code)
 - DevTest Labs receiving custom images may not be in the same Azure Subscription (labs span subscriptions)
 - PowerShell scripts must be reusable so you can spin up more factories as needed
diff --git a/articles/devtest-labs/image-factory-save-distribute-custom-images.md b/articles/devtest-labs/image-factory-save-distribute-custom-images.md
@@ -11,6 +11,8 @@ ms.custom: UpdateFrequency2
 # Save custom images and distribute to multiple labs
 This article gives you the steps to save custom images from the already created virtual machines (VMs). It also covers how to distribute these custom images to other DevTest Labs in the organization.
 
+[!INCLUDE [direct-azure-image-builder](includes/direct-azure-image-builder.md)]
+
 ## Prerequisites
 The following items should already be in place:
 
diff --git a/articles/devtest-labs/image-factory-set-retention-policy-cleanup.md b/articles/devtest-labs/image-factory-set-retention-policy-cleanup.md
@@ -12,7 +12,9 @@ ms.custom: UpdateFrequency2
 
 # Set up an image retention policy in Azure DevTest Labs
 
-This article covers setting an image retention policy, cleaning up an image factory, and retiring old images from all the DevTest labs in an organization. 
+This article covers setting an image retention policy, cleaning up an image factory, and retiring old images from all the DevTest Labs in an organization. 
+
+[!INCLUDE [direct-azure-image-builder](includes/direct-azure-image-builder.md)]
 
 ## Prerequisites 
 
@@ -53,14 +55,14 @@ The script parameters are:
 
 ## Queue the build
 
-After you complete the build definition, queue up a new build to make sure everything is working. After the build completes successfully, the new custom images show up in the destination lab. If you check the image factory lab, you see no provisioned VMs. If you queue up further builds, you see the cleanup tasks retiring old custom images from the DevTest labs. The retirement proceeds according to the retention value set in the build variables.
+After you complete the build definition, queue up a new build to make sure everything is working. After the build completes successfully, the new custom images show up in the destination lab. If you check the image factory lab, you see no provisioned VMs. If you queue up further builds, you see the cleanup tasks retiring old custom images from the DevTest Labs. The retirement proceeds according to the retention value set in the build variables.
 
 > [!NOTE]
 > If you ran the build pipeline at the end of the previous article in this series, manually delete the virtual machines that you created in the image factory lab before queuing a new build. You only need the manual cleanup step when you set everything up and verify that it works.
 
 ## Summary
 
-You now have a running image factory that can generate custom images and distribute them to your labs on demand. At this point, it's just a matter of getting your images set up properly and identifying the target labs. As mentioned in the previous article, the *Labs.json* file located in your *Configuration* folder specifies which images should be made available in each of the target labs. As you add other DevTest labs to your organization, you simply need to add an entry in *Labs.json* for the new lab.
+You now have a running image factory that can generate custom images and distribute them to your labs on demand. At this point, it's just a matter of getting your images set up properly and identifying the target labs. As mentioned in the previous article, the *Labs.json* file located in your *Configuration* folder specifies which images should be made available in each of the target labs. As you add other DevTest Labs to your organization, you simply need to add an entry in *Labs.json* for the new lab.
 
 Adding a new image to your factory is also easy. When you want to include a new image in your factory, go to your factory lab in the Azure portal. Select the button to add a VM, and then choose the marketplace image and artifacts that you want. Instead of selecting the **Create** button to create the new VM, select **View Azure Resource Manager template**. Save the template as a .json file somewhere in the *GoldenImages* folder in your repository. The next time you run your image factory, it will create your custom image.
 
diff --git a/articles/devtest-labs/image-factory-set-up-devops-lab.md b/articles/devtest-labs/image-factory-set-up-devops-lab.md
@@ -11,14 +11,16 @@ ms.custom: UpdateFrequency2
 # Run an image factory from Azure DevOps
 This article covers all the preparations needed to run the image factory from Azure DevOps (formerly Visual Studio Team Services).
 
-> [!NOTE]
+> [!TIP]
 > Any orchestration engine will work! Azure DevOps is not mandatory. The image factory is run using Azure PowerShell scripts, so it could be run manually, by using Windows Task Scheduler, other CI/CD systems, and so on.
 
+[!INCLUDE [direct-azure-image-builder](includes/direct-azure-image-builder.md)]
+
 ## Create a lab for the image factory
-The first step in setting up the image factory is to create a lab in Azure DevTest Labs. This lab is the image factory lab where we create the virtual machines and save custom images. This lab is considered as part of the overall image factory process. Once you create a lab, make sure to save the name since you’ll need it later.
+The first step in setting up the image factory is to create a lab in Azure DevTest Labs. This lab is the image factory lab where we create the virtual machines and save custom images. This lab is considered as part of the overall image factory process. Once you create a lab, make sure to save the name since you'll need it later.
 
 ## Scripts and templates
-The next step in adopting the image factory for your team is to understand what’s available. The image factory scripts and templates are available publicly in the [DevTest Labs GitHub Repo](https://github.com/Azure/azure-devtestlab/tree/master/samples/DevTestLabs/Scripts/ImageFactory). Here is an outline of the pieces:
+The next step in adopting the image factory for your team is to understand what's available. The image factory scripts and templates are available publicly in the [DevTest Labs GitHub Repo](https://github.com/Azure/azure-devtestlab/tree/master/samples/DevTestLabs/Scripts/ImageFactory). Here is an outline of the pieces:
 
 - Image Factory. It's the root folder.
     - Configuration. The inputs to the image factory
@@ -29,14 +31,14 @@ The next step in adopting the image factory for your team is to understand what
 The articles in this section provide more details about these scripts and templates.
 
 ## Create an Azure DevOps team project
-Azure DevOps let you store the source code, run the Azure PowerShell in one place. You can schedule recurring runs to keep images up to date. There are good facilities for logging the results to diagnose any issues.  Using Azure DevOps isn’t a requirement however, you can use any harness/engine that can connect to Azure and can run Azure PowerShell.
+Azure DevOps lets you store the source code, run the Azure PowerShell in one place. You can schedule recurring runs to keep images up to date. There are good facilities for logging the results to diagnose any issues.  Using Azure DevOps isn't a requirement however, you can use any harness/engine that can connect to Azure and can run Azure PowerShell.
 
 If you have an existing DevOps account or project you would like to use instead, skip this step.
 
-To get started, create a free account in Azure DevOps. Visit https://www.visualstudio.com/ and select **Get started for free** right under **Azure DevOps** (formerly VSTS). You’ll need to choose a unique account name and make sure to choose to manage code using Git. Once you create the account, save the URL to your team project. Here is a sample URL: `https://<accountname>.visualstudio.com/MyFirstProject`.
+To get started, create a free account in Azure DevOps. Visit https://www.visualstudio.com/ and select **Get started for free** right under **Azure DevOps** (formerly VSTS). You'll need to choose a unique account name and make sure to choose to manage code using Git. Once you create the account, save the URL to your team project. Here is a sample URL: `https://<accountname>.visualstudio.com/MyFirstProject`.
 
 ## Check in the image factory to Git
-All the PowerShell, templates and configuration for the image factory are located in the [public DevTest Labs GitHub repo](https://github.com/Azure/azure-devtestlab/tree/master/samples/DevTestLabs/Scripts/ImageFactory). The fastest way to get the code into your new team project is to import a repository. Importing pulls in the whole DevTest Labs repository (so you’ll get extra docs, and samples).
+All the PowerShell, templates and configuration for the image factory are located in the [public DevTest Labs GitHub repo](https://github.com/Azure/azure-devtestlab/tree/master/samples/DevTestLabs/Scripts/ImageFactory). The fastest way to get the code into your new team project is to import a repository. Importing pulls in the whole DevTest Labs repository (so you'll get extra docs, and samples).
 
 1. Visit the Azure DevOps project that you created in the previous step (URL looks like **https:\//\<accountname>.visualstudio.com/MyFirstProject**).
 2. Select **Import a Repository**.
@@ -45,13 +47,13 @@ All the PowerShell, templates and configuration for the image factory are locate
 
     ![Screenshot that shows Import Git repo.](./media/set-up-devops-lab/import-git-repo.png)
 
-If you decide to only check in exactly what’s needed (the image factory files), follow the steps [here](https://www.visualstudio.com/en-us/docs/git/share-your-code-in-git-vs) to clone the Git repo and push only the files located in the **scripts/ImageFactory** directory.
+If you decide to only check in exactly what's needed (the image factory files), follow the steps [here](https://www.visualstudio.com/docs/git/share-your-code-in-git-vs) to clone the Git repo and push only the files located in the **scripts/ImageFactory** directory.
 
 ## Create a build and connect to Azure
 At this point, you have the source files stored in a Git repo in Azure DevOps. Now, you need to set up a pipeline to run the Azure PowerShell. There are lots of options to do these steps. In this article, you use build definition for simplicity, but it works with DevOps Build, DevOps Release (single or multiple environments), other execution engines like Windows Task Scheduler or any other harness that can execute Azure PowerShell.
 
 > [!NOTE]
-> One important point to keep in mind that some of the PowerShell files take a long time to run when there are a lot (10+) custom images to create. Free hosted DevOps Build/Release agents have a timeout of 30 min, so you can’t use the free hosted agent once you start building many images. This timeout challenge applies to whatever harness you decide to use, it’s good to verify up front that you can extend the typical timeouts for long running Azure PowerShell scripts. In the case of Azure DevOps, you can either use paid hosted Agents or use your own build agent.
+> One important point to keep in mind that some of the PowerShell files take a long time to run when there are a lot (10+) custom images to create. Free hosted DevOps Build/Release agents have a timeout of 30 min, so you can't use the free hosted agent once you start building many images. This timeout challenge applies to whatever harness you decide to use, it's good to verify up front that you can extend the typical timeouts for long running Azure PowerShell scripts. In the case of Azure DevOps, you can either use paid hosted Agents or use your own build agent.
 
 1. To start, select **Set up Build** on the homepage of your DevOps Project:
 
@@ -64,24 +66,24 @@ At this point, you have the source files stored in a Git repo in Azure DevOps. N
     ![Screenshot that shows Build definition.](./media/set-up-devops-lab/build-definition.png)
 
 ## Configure the build variables
-To simplify the command-line parameters, encapsulate the key values that drive the image factory to a set of build variables. Select the **Variables** tab and you’ll see a list of several default variables. Here’s the list of variables to enter in to Azure DevOps:
+To simplify the command-line parameters, encapsulate the key values that drive the image factory to a set of build variables. Select the **Variables** tab and you'll see a list of several default variables. Here's the list of variables to enter in to Azure DevOps:
 
 
-| Variable Name	| Value	| Notes |
+| Variable Name    | Value    | Notes |
 | ------------- | ----- | ----- |
 | ConfigurationLocation | /Scripts/ImageFactory/Configuration | This location is the full path in the repository to the **Configuration** folder. If you imported the whole repo above, the value to the left is correct. Otherwise update to point to the Configuration location. |
-| DevTestLabName | MyImageFactory | The name of the lab in Azure DevTest Labs used as the factory to produce images. If you don’t have one, create one. Make sure that the Lab is in the same subscription that the service endpoint has access to. |
+| DevTestLabName | MyImageFactory | The name of the lab in Azure DevTest Labs used as the factory to produce images. If you don't have one, create one. Make sure that the Lab is in the same subscription that the service endpoint has access to. |
 | ImageRetention | 1 | The number of images you want to save of each type. Set default value to 1. |
-| MachinePassword | ******* | The built-in admin account password for the virtual machines. This account is transient, so make sure that it’s secure. Select the little lock icon on the right to ensure it’s a secure string. |
+| MachinePassword | ******* | The built-in admin account password for the virtual machines. This account is transient, so make sure that it's secure. Select the little lock icon on the right to ensure it's a secure string. |
 | MachineUserName | ImageFactoryUser | The built-in admin account username for the virtual machines. This account is transient. |
 | StandardTimeoutMinutes | 30 | The timeout we should wait for regular Azure operations. |
-| SubscriptionId |	0000000000-0000-0000-0000-0000000000000	| The ID of the subscription where the lab exists and that the service endpoint has access to. |
+| SubscriptionId |    0000000000-0000-0000-0000-0000000000000    | The ID of the subscription where the lab exists and that the service endpoint has access to. |
 | VMSize | Standard_A3 | The size of the virtual machine to use for the **Create** step. The VMs created are transient. The size must be the one that's [enabled for the lab](devtest-lab-set-lab-policy.md). Confirm that there's enough [subscription cores quota](../azure-resource-manager/management/azure-subscription-service-limits.md).
 
 ![Screenshot that shows Build variables.](./media/set-up-devops-lab/configure-build-variables.png)
 
 ## Connect to Azure
-The next step is to set up a service principal. A service principal is an identity in Microsoft Entra ID that enables the DevOps build agent to operate in Azure on the user’s behalf. To set it up, start with adding you first Azure PowerShell Build Step.
+The next step is to set up a service principal. A service principal is an identity in Microsoft Entra ID that enables the DevOps build agent to operate in Azure on the user's behalf. To set it up, start with adding you first Azure PowerShell Build Step.
 
 1. Select **Add Task**.
 2. Search for **Azure PowerShell**.
@@ -95,10 +97,10 @@ The fastest way to set up a service principal is to let Azure DevOps do it for y
 2. For **Azure Connection Type**, choose **Azure Resource Manager**.
 3. Select the **Manage** link to set up the service principal.
 
-For more information, see this [blog post](https://devblogs.microsoft.com/devops/automating-azure-resource-group-deployment-using-a-service-principal-in-visual-studio-online-buildrelease-management/). When you select the **Manage** link, you’ll land in the right place in DevOps (second screenshot in the blog post) to set up the connection to Azure. Make sure to choose **Azure Resource Manager Service Endpoint** when setting up the connection.
+For more information, see this [blog post](https://devblogs.microsoft.com/devops/automating-azure-resource-group-deployment-using-a-service-principal-in-visual-studio-online-buildrelease-management/). When you select the **Manage** link, you'll land in the right place in DevOps (second screenshot in the blog post) to set up the connection to Azure. Make sure to choose **Azure Resource Manager Service Endpoint** when setting up the connection.
 
 ## Complete the build task
-If you select the build task, you’ll see all the details on the right pane that should be filled in.
+If you select the build task, you'll see all the details on the right pane that should be filled in.
 
 1. First, name the build task: **Create Virtual Machines**.
 2. Choose the **service principal** you created by choosing **Azure Resource Manager**
@@ -111,9 +113,9 @@ If you select the build task, you’ll see all the details on the right pane tha
 
 
 ## Queue the build
-Let’s verify that you have everything set up correctly by queuing up a new build. While the build is running, switch to the [Azure portal](https://portal.azure.com) and select on **All Virtual Machines** in your image factory lab to confirm that everything is working correctly. You should see three virtual machines get created in the lab.
+Let's verify that you have everything set up correctly by queuing up a new build. While the build is running, switch to the [Azure portal](https://portal.azure.com) and select on **All Virtual Machines** in your image factory lab to confirm that everything is working correctly. You should see three virtual machines get created in the lab.
 
-![VMs in the lab](./media/set-up-devops-lab/vms-in-lab.png)
+![Screenshot showing VMs in the lab](./media/set-up-devops-lab/vms-in-lab.png)
 
 ## Next steps
 The first step in setting up the image factory based on Azure DevTest Labs is complete. In the next article in the series, you get those VMs generalized and saved to custom images. Then, you have them distributed to all your other labs. See the next article in the series: [Save custom images and distribute to multiple labs](image-factory-save-distribute-custom-images.md).
diff --git a/articles/devtest-labs/includes/direct-azure-image-builder.md b/articles/devtest-labs/includes/direct-azure-image-builder.md
@@ -0,0 +1,13 @@
+---
+author: RoseHJM
+ms.author: rosemalcolm
+ms.date: 08/27/2025
+ms.topic: include
+ms.service: devtest-labs
+---
+
+> [!NOTE]
+> Azure VM Image Builder is the recommended solution for building images. VM Image Builder is designed to streamline the process of creating standardized virtual machine images for use in Azure. It supersedes Image Factory.
+> 
+> To learn more about Azure VM Image Builder, see [Azure VM Image Builder](/azure/virtual-machines/image-builder-overview?tabs=azure-powershell).
+
