Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Using a customization file simplifies the creation of dev boxes for your team. With dev box customizations, you can create a shared team customization by creating a file called an image definition. Creating a reusable image from this image definition optimizes customizations and saves time during dev box creation. In this article, you learn how to configure a pool to use an image definition and build reusable images for your development teams.
To configure imaging for Microsoft Dev Box team customizations, first enable project-level catalogs and configure catalog sync settings. Next, attach a catalog with a definition file, set up a dev box pool to use an image definition, and verify that customizations apply; once confirmed, you can build a reusable image for faster dev box creation.
Prerequisites
To complete the steps in this article, you need:
- A dev center with an existing dev box definition and network connection. If you don't have a dev center, follow the steps in Quickstart: Configure Microsoft Dev Box to create it.
- A team customization file that you want to use to create a dev box. If you don't have a customization file, see Write a customization file for a dev box.
Permissions required to configure customizations
To perform the required actions for creating and applying customizations to a dev box, you need the following permissions:
| Action | Permission/Role |
|---|---|
| Enable project-level catalogs for a dev center. | Platform engineer with write access on the subscription. |
| Enable catalog sync settings for a project. | Platform engineer with write access on the subscription. |
| Attach a catalog to a project. | Project Admin or Contributor permissions on the project. |
| Create a customization file. | None specified. Anyone can create a customization file. |
| Use the developer portal to upload and apply a YAML file during dev box creation. | Dev Box User. |
| Add tasks to a catalog. | Permission to add to the repository that hosts the catalog. |
To manage a dev box pool, you need the following permissions:
| Action | Permission |
|---|---|
| Create, delete, or update a dev box pool. | - Owner or Contributor permissions on an Azure subscription or a specific resource group. - DevCenter Project Admin permissions for the project. |
Enable project-level catalogs
To attach a catalog to a project, you must enable project-level catalogs. For more information, see Configure project-level catalogs.
Configure catalog sync settings for the project
Configure your project to sync image definitions from the catalog. With this setting, you can use the image definitions in the catalog to create dev box pools.
Sign in to the Azure portal.
In the search box, enter projects. In the list of results, select Projects.
Open the Dev Box project for which you want to configure catalog sync settings.
Select Catalogs.
Select Sync settings.
On the Sync settings pane, select Image definitions, and then select Save.
Attach a catalog that contains the definition file
Before you can use a customization file as an image definition, you must attach a catalog that contains the definition file to your dev center or project. The catalog can be from GitHub or Azure Repos.
The Image definitions pane lists the image definitions that your project can access.
For more information about attaching catalogs, see Add and configure a catalog from GitHub or Azure Repos.
Configure a dev box pool to use an image definition
Make customizations available to your development teams by configuring a dev box pool to use a customization file (imagedefinition.yaml). Store the customization file in a repository linked to a catalog in your dev center or project. Specify this file as the image definition for the pool, and the customizations are applied to new dev boxes.
Create a dev box pool
In Microsoft Dev Box, a dev box pool is a collection of dev boxes that you manage together. You must have at least one dev box pool before users can create a dev box.
Pool properties
A dev box pool has the following properties:
| Property | Description |
|---|---|
| Definition | Determines the definition used for dev boxes in this pool. You can select an existing dev box definition or image definition when you create a dev box pool. - Dev Box Definitions define the base image and size for dev boxes. - Image definitions specify the software and configuration for the dev boxes. |
| Hibernation | Hibernation is supported when the source image and compute size are both compatible. |
| Region | The region where the dev boxes in the pool are deployed. Choose a region close to your expected dev box users for the optimal user experience. |
| Network connection | Determines the network that the dev boxes in the pool connect to. - Microsoft Hosted Network: You can choose to deploy dev boxes to a Microsoft-hosted network. - Azure joined network: You can choose to deploy dev boxes to an Azure joined network that you manage. If you choose to deploy dev boxes to a network that you manage, you must first configure a network connection. |
| Licensing | You can apply Azure Hybrid Benefit licenses to the dev boxes in the pool. Select the checkbox to confirm that your organization has Azure Hybrid Benefit licenses that you want to apply to the dev boxes in this pool. |
| Roles | You can assign users to be either Local Administrators or Standard Users on the dev boxes they create. |
| Access | Determines how users can access their dev boxes. - Single Sign-On (SSO): Enable single sign-on (SSO) to allow users to sign in to their dev boxes by using their organizational credentials. - Headless connections: Enable headless connections to allow developers to open a dev box in Visual Studio Code without a full desktop experience. |
| Cost controls | You can configure cost controls to help manage the costs of running dev boxes in the pool. - Auto-stop schedule: Set an autostop schedule to automatically stop or hibernate dev boxes at a specified time. - Hibernate: Configure dev boxes to hibernate after a specified grace period when no one is connected or when they have never been connected. |
The following steps show you how to create a dev box pool in a project.
If you don't have an available dev center and project, follow the steps in Quickstart: Configure Microsoft Dev Box to create them.
Sign in to the Azure portal.
In the search box, enter projects. In the list of results, select Projects.
Open the project where you want to create the dev box pool.
Select Dev box pools, then select Create.
On the Create a dev box pool pane, on the Basics tab, enter the following values:
Setting Value Name Enter a name for the pool. The pool name is visible to developers to select when they're creating dev boxes. The name must be unique within a project. Definition Select an existing dev box definition or image definition.
A dev box definition determines the base image and size for the dev boxes that are created.
An image definition allows you to specify your required Compute and SKU.Compute Image definitions only. Select the virtual machine size for the dev boxes in this pool. Storage Image definition only. Select the storage size for the dev boxes in this pool. Hibernation Shows whether hibernation is supported or not. Region Network connection 1. Select Deploy to a Microsoft hosted network.
2. Select your desired deployment region for the dev boxes. Choose a region close to your expected dev box users for the optimal user experience.Licensing Select this checkbox to confirm that your organization has Azure Hybrid Benefit licenses that you want to apply to the dev boxes in this pool. 
on the Management tab, enter the following values:
Setting Value Roles Dev box Creator Privileges Select Local Administrator or Standard User. Access Enable single sign-on (SSO) Select to enable users to sign in to their dev boxes by using their organizational credentials. Headless connections Select to enable developers to open a dev box in Visual Studio Code without a full desktop experience. Cost controls Auto-stop on schedule Select the checkbox to enable an autostop schedule. You can also configure an autostop schedule after the pool is created. Stop time Select a time to shut down all the dev boxes in the pool. Dev boxes that support hibernation hibernate at the specified time. Dev boxes that don't support hibernation shut down. Time zone Select the time zone for the stop time. Hibernate on disconnect Hibernates dev boxes that no one is connected to after a specified grace period. Grace period Hibernates dev boxes that have never been connected to after a specified grace period. 
Select Create.
Hibernation support for dev boxes
Dev Box supports hibernation when both these conditions are met:
- The source image supports hibernation.
- The compute resources of the dev box pool support hibernation.
If either the image or the pool doesn't support hibernation, the feature isn't available for dev boxes in that pool. If hibernation isn't supported, verify that the image was created with hibernation support and that the pool is using that image.
For more information about Dev Box support for hibernation, see Configure hibernation in Microsoft Dev Box.
Create a dev box by using the developer portal
To verify that customizations from the image definition file are applied, create a dev box in the Microsoft Dev Box developer portal. Follow the steps in Quickstart: Create and connect to a dev box by using the Microsoft Dev Box developer portal. Then connect to the newly created dev box and verify that the customizations work as you expected.
You can make adjustments to the customization file and create a new dev box to test the changes. When you're happy that the customizations are correct, you can build a reusable image.
Build a reusable image
To optimize customizations and create a reusable image for your team, you can use the following steps to build an image from the customization file. This image applies to all dev boxes created from the pool. The DevCenter service creates a Dev Box behind the scenes to create an image, and exports the image to an Azure Compute Gallery in a resource group managed by the DevCenter service.
Assign roles to the DevCenter service
In order to generate an image, you need to assign the DevCenter service the requisite roles to publish an image.
Sign in to the Azure portal.
Select Resource Groups.
Search for the managed by resource group with the name DevCenter(yourProjectName)(a random ID).
Under that resource group, navigate to Access Control, and give the Windows 365 and Project Fidalgo applications the roles Storage Account Contributor, Storage Blob Data Contributor, and Reader.
During the process of building an image, Dev Box creates a temporary storage account in your subscription to store a snapshot, from which Dev Box generates an image. This storage account doesn't allow anonymous blob access and can only be accessed by identities with the Storage Blob Reader access. This storage account must be accessible from public networks, so that the Dev Box service can export your snapshot to it. If you have Azure policies that block the creation of storage accounts with public network access, create an exception for the subscription your DevCenter project is in.
Build the image
On the Image definitions pane, select the image that you want to build.
Select Build.
Track the build progress in the Status column.
Important
When you're optimizing your image definition into an image, a dev box is created to run your customization file and generate an image. During this process, this dev box is connected to a virtual network that Microsoft manages. Tasks that require access to on-premises resources might fail.
When the build finishes successfully, the dev box pool automatically uses the image for new dev boxes. You don't need to do any extra configuration to assign the image to the pool. You can now create dev boxes from the pool, and the customizations are applied to each dev box.