Merge pull request #207860 from MicrosoftDocs/release-preview-dev-box

Release preview dev box--scheduled release at 7AM of 8/15

Author: JiayueHu

articles/dev-box/concept-dev-box-concepts.md

@@ -0,0 +1,46 @@
+---
+title: Microsoft Dev Box key concepts
+titleSuffix: Microsoft dev box
+description: Learn key concepts and terminology for Microsoft Dev Box.
+services: dev-box
+ms.service: dev-box
+author: RoseHJM
+ms.author: rosemalcolm
+ms.topic: conceptual
+ms.date: 08/10/2022
+ms.custom: template-concept 
+---
+
+<!-- 
+  Customer intent:
+	As a developer I want to understand Dev Box concepts and terminology so that I can set up Dev Box environment.
+ -->
+# Microsoft Dev Box key concepts
+
+This article describes the key concepts and components of Microsoft Dev Box. 
+
+## Dev center
+
+A dev center is a collection of projects that require similar settings. Dev centers enable dev infrastructure managers to manage the images and SKUs available to the projects using [dev box definitions](concept-dev-box-concepts.md#dev-box-definition), and configure the networks the development teams consume using [network connections](./concept-dev-box-concepts.md#network-connection).  
+
+## Projects
+
+A project is the point of access for the development team members. When you associate a project with a dev center, all the settings at the dev center level will be applied to the project automatically. Each project can be associated with only one dev center. Dev managers can configure the dev boxes available for the project by  specifying the [dev box definitions](./concept-dev-box-concepts.md#dev-box-definition) appropriate for their workloads.
+
+## Dev box definition
+
+A dev box definition specifies a source image and size, including compute size and storage size. You can use a source image from the marketplace, or a custom image from your own [Azure Compute Gallery](./how-to-configure-azure-compute-gallery.md). You can use dev box definitions across multiple projects in a dev center. 
+
+## Network connection 
+
+IT administrators and dev infrastructure managers configure the network used for dev box creation in accordance with their organizational policies. Network connections store configuration information like Active Directory join type and virtual network that dev boxes use to connect to network resources. 
+
+When creating a network connection, you must choose whether to use a native Azure Active Directory (Azure AD) join or a hybrid Azure AD join. If your dev boxes need to connect exclusively to cloud-based resources, use a native Azure AD join. Use a hybrid Azure AD join if your dev boxes need to connect to on-premises resources and cloud-based resources. To learn more about Azure AD and hybrid Azure AD joined  devices, [Plan your Azure Active Directory device deployment](/azure/active-directory/devices/plan-device-deployment).
+
+The virtual network specified in a network connection also determines the region for the dev box. You can create multiple network connections based on the regions where you support developers and use them when creating different dev box pools to ensure dev box users create a dev box in a region close to them. Using a region close to the dev box user provides the best experience. 
+
+## Dev box pool 
+A dev box pool is a collection of dev boxes that you manage together that you manage together and to which you apply similar settings. You can create multiple dev box pools to support the needs of hybrid teams working in different regions or on different workloads.
+
+## Dev box 
+A dev box is a preconfigured ready-to-code workstation that you create through the self-service developer portal. The new dev box has all the tools, binaries, and configuration required for a dev box user to be productive immediately. You can create and manage multiple dev boxes to work on multiple work streams. As a dev box user you have control over your own dev boxes - you can create more as you need them, and delete them when you have finished using them.

articles/dev-box/how-to-configure-azure-compute-gallery.md

@@ -0,0 +1,153 @@
+---
+title: Configure an Azure Compute Gallery
+titleSuffix: Microsoft Dev Box
+description: 'Learn how to create a repository for managing and sharing Dev Box images.'
+services: dev-box
+ms.service: dev-box
+author: RoseHJM
+ms.author: rosemalcolm
+ms.date: 07/28/2022
+ms.topic: how-to
+---
+
+# Configure an Azure Compute Gallery
+
+ An Azure Compute Gallery is a repository in Azure for managing and sharing images. It's stored in your Azure subscription and helps you build structure and organization around your image resources. You can use Azure Compute Gallery to provide custom images for your dev box users.
+
+Advantages of using a gallery include:
+- You maintain the images in a single location and use them across dev centers, projects, and pools.
+- Development teams can use the *latest* image version of an image definition to ensure they always receive the most recent image when creating dev boxes.
+- Development teams can use a specific image version to standardize on a supported image version until a newer version is validated.
+
+
+You can learn more about Azure Compute Galleries and how to create them here:
+- [Store and share images in an Azure Compute Gallery](../virtual-machines/shared-image-galleries.md) 
+- [Create a gallery for storing and sharing resources](../virtual-machines/create-gallery.md#create-a-gallery-for-storing-and-sharing-resources) 
+
+## Pre-requisites
+- A dev center. If don't have an available dev center, follow these steps: [Create a dev center](./quickstart-configure-dev-box-service.md#create-a-dev-center). 
+- An Azure Compute Gallery. In order to use this gallery to configure Dev Box definitions, it must have at least [one image definition and one image version](../virtual-machines/image-version.md). 
+    - The image definition must have [Trusted Launch enabled as the Security Type](../virtual-machines/trusted-launch.md). You configure the security type when creating the image definition. 
+    - The image version must meet the [Windows 365 image requirements](/windows-365/enterprise/device-images#image-requirements).
+        - Generation 2
+        - Hyper-V v2
+        - Windows OS
+        - Generalized image
+
+    :::image type="content" source="media/how-to-configure-azure-compute-gallery/image-definition.png" alt-text="Screenshot showing the Windows 365 image requirement settings.":::
+
+> [!IMPORTANT]
+> If you have existing images that do not meet the Windows 365 image requirements, those images will not be listed for image creation.
+
+## Provide permissions for services to access the gallery
+When using an Azure Compute Gallery image to create a dev box definition, the Windows 365 service validates the image to ensure that it  meets the requirements to be provisioned for a dev box. In addition, the Dev Box service replicates the image to the regions specified in the attached network connections so the images are present in the region required for dev box creation.
+
+To allow the services to perform these actions, you must provide permissions to your gallery as follows:
+
+### Add a user assigned identity to dev center
+1. Use these steps to [Create a user-assigned managed identity](/azure/active-directory/managed-identities-azure-resources/how-manage-user-assigned-managed-identities?pivots=identity-mi-methods-azp#create-a-user-assigned-managed-identity).  
+1. Sign in to the [Azure portal](https://portal.azure.com).
+1. In the search box, type *Dev box* and select **Dev centers** from the list.
+1. Open your DevCenter and select **Identity** from the left menu.
+1. On the **User assigned** tab, select **+ Add**.
+1. In Add user assigned managed identity, select the user-assigned managed identity that you created in step 1 and then select **Add**.
+
+   :::image type="content" source="media/how-to-configure-azure-compute-gallery/assign-managed-id.png" alt-text="Screenshot showing the Add user assigned managed identity pane, with the managed ID highlighted."::: 
+
+### How does the Dev Box service assign permissions?
+The Dev Box service behaves differently depending how you attach your gallery.
+- When you use the Azure portal to attach the gallery to your Dev center, the Dev Box service creates the necessary role assignments automatically when you attach the gallery.
+- When you use the CLI to attach the gallery to your Dev center, you must manually create the Windows 365 Service Principal and dev center Managed Identity role assignments before attempting to attach the gallery.
+
+Follow these steps to manually assign each role:
+
+#### Windows 365 Service Principal
+1. Sign in to the [Azure portal](https://portal.azure.com).
+
+1. In the search box, type *Azure Compute Gallery* and select the gallery you want to attach to the dev center.
+
+1. Select the **Access Control (IAM)** menu item.
+
+1. Select **+ Add** > **Add role assignment**.
+
+1. On the Role tab, select **Reader**, and then select **Next**.
+
+1. On the Members tab, select **+ Select Members**.
+
+1. In Select members, search for and select **Cloud PC**, and then select **Select**. 
+
+1. On the Members tab, select **Next**.
+
+1. On the Review + assign tab, select **Review + assign**.
+
+#### Dev center Managed Identity
+1. Open the gallery you want to attach to the dev center from the [Azure portal](https://ms.portal.azure.com/#blade/HubsExtension/BrowseResource/resourceType/Microsoft.Compute%2Fgalleries). You can also search for Azure Compute Galleries to find your gallery.
+
+1. Select **Access Control (IAM)** from the left menu.
+
+1. Select **+ Add** > **Add role assignment**.
+
+1. On the Role tab, select the **Owner** role, and then select **Next**.
+
+1. On the Members tab, under **Assign access to**, select **Managed Identity**, and then select **+ Select Members**.
+
+1. In Select managed identities, search for and select the user assigned managed identity you created in "Create a Dev center Managed Identity" and then select 
+**Select**.
+
+1. On the Members tab, select **Next**.
+
+1. On the Review + assign tab, select **Review + assign**.
+
+You can use the same managed identity in multiple DevCenters and Azure Compute Galleries. Any DevCenter with the managed identity added will have the necessary permissions to the images in the Azure Compute Gallery you've added the owner role assignment to.
+
+## Attach a gallery to a dev center
+In order to use the images from a gallery in dev box definitions, you must first associate it with the dev center.
+
+1. Sign in to the [Azure portal](https://portal.azure.com).
+
+2. In the search box, type *Dev box* and select **Dev centers** from the list.
+ 
+3.  Select the dev center you want to attach the gallery to.
+ 
+:::image type="content" source="media/how-to-configure-azure-compute-gallery/devcenter-grid.png" alt-text="Screenshot showing the list of existing dev centers.":::
+
+4. From the left menu, select **Azure compute galleries** to list the galleries attached to this dev center.
+ 
+:::image type="content" source="media/how-to-configure-azure-compute-gallery/gallery-grid-empty.png" alt-text="Screenshot showing the Azure compute galleries page. There are no existing Azure compute galleries.":::
+
+5. Select **+ Add** to select a gallery to attach.
+
+6. In Add Azure compute gallery, select your gallery. If you have access to more than one gallery with the same name, the subscription name is shown in parentheses.
+ 
+:::image type="content" source="media/how-to-configure-azure-compute-gallery/gallery-add.png" alt-text="Screenshot showing the Select a Gallery to add option.":::
+
+7. If there's a name conflict in the dev center, then you must provide a unique name to use for this gallery.
+
+8. Select **Add**.
+  
+:::image type="content" source="media/how-to-configure-azure-compute-gallery/gallery-grid.png" alt-text="Screenshot showing the Azure compute galleries page with example galleries listed.":::
+
+After successful addition, the images in the gallery will be available to select from when creating and updating dev box definitions.
+
+## Remove a gallery from a dev center
+You can detach galleries from dev centers so that their images can no longer be used to create dev box definitions in the dev center. Galleries that are being actively used in dev box definitions cannot be removed from the dev center. The associated dev box definition must be deleted or updated to use an image from a different gallery before you can remove the gallery.
+
+1. Sign in to the [Azure portal](https://portal.azure.com).
+
+2. In the search box, type *Dev box* and select **Dev centers** from the list.
+ 
+3. Select the dev center you want to remove the gallery from.
+
+4. From the left menu, select **Azure compute galleries** to list the galleries attached to this dev center.
+
+5. Select the gallery you want to remove, and then select **Remove**.
+
+   :::image type="content" source="media/how-to-configure-azure-compute-gallery/remove-gallery-from-devcenter.png" alt-text="Screenshot showing the Azure compute galleries page with a gallery selected and the Remove button highlighted.":::
+
+6. Select **Continue** from the confirmation dialog.
+
+The gallery will be detached from the dev center. The gallery and its images won't be deleted, and you can reattach it if necessary. 
+
+## Next steps
+Learn more about Microsoft Dev Box:
+- [Microsoft Dev Box key concepts](./concept-dev-box-concepts.md)

articles/dev-box/how-to-dev-box-user.md

@@ -0,0 +1,62 @@
+---
+title: Provide access to dev box users
+titleSuffix: Microsoft Dev Box
+description: Learn how to provide access to projects for dev box users so that they can create and manage dev boxes.
+services: dev-box
+ms.service: dev-box
+author: RoseHJM
+ms.author: rosemalcolm
+ms.date: 04/15/2022
+ms.topic: how-to
+---
+
+# Provide access to projects for dev box users
+
+Team members must have access to a specific Dev Box project before they can create dev boxes. By using the built-in DevCenter Dev Box User role, you can assign permissions to Active Directory Users or Groups at the project level. 
+
+A DevCenter Dev Box User can:
+
+- View pools within a project.
+- Create dev boxes.
+- Connect to a dev box.
+- Manage dev boxes that they created.
+- Delete dev boxes that they created.
+
+## Assign permissions to dev box users
+
+1. Sign in to the [Azure portal](https://portal.azure.com).
+ 
+1. In the search box, type *Dev box* and select **Projects**. 
+
+1. Select the project you want to provide your team members access to.
+ 
+   :::image type="content" source="./media/how-to-dev-box-user/projects-grid.png" alt-text="Screenshot showing the list of existing projects.":::
+
+1. Select **Access Control (IAM)** from the left menu.
+ 
+   :::image type="content" source="./media/how-to-dev-box-user/access-control-tab.png " alt-text="Screenshot showing the Project Access control page with the Access Control link highlighted.":::
+
+1. Select **Add** > **Add role assignment**.
+ 
+   :::image type="content" source="./media/how-to-dev-box-user/add-role-assignment.png" alt-text="Screenshot showing the Add menu with Add role assignment highlighted.":::
+
+1. On the Add role assignment page, on the Role tab, search for *devcenter dev box user*, select the **DevCenter Dev Box User** built-in role, and then select **Next**.
+ 
+   :::image type="content" source="./media/how-to-dev-box-user/dev-box-user-role.png" alt-text="Screenshot showing the search box.":::
+
+1. On the Members tab, select **+ Select Members**.
+ 
+   :::image type="content" source="./media/how-to-dev-box-user/dev-box-user-select-members.png" alt-text="Screenshot showing the Members tab with Select members highlighted.":::
+
+1. In **Select members**, select the Active Directory Users or Groups you want to add, and then select **Select**.
+ 
+   :::image type="content" source="./media/how-to-dev-box-user/select-members-search.png" alt-text="Screenshot showing the Select members pane with a user account highlighted.":::
+
+1. On the Members tab, select **Review + assign**.
+
+The user will now be able to view the project and all the pools within it. Dev box users can create dev boxes from any of the pools and manage those dev boxes from the [developer portal](https://aka.ms/devbox-portal).
+
+[!INCLUDE [dev box runs on creation note](./includes/note-dev-box-runs-on-creation.md)]
+## Next steps
+
+- [Quickstart: Create a dev box by using the developer portal](quickstart-create-dev-box.md)

articles/dev-box/how-to-project-admin.md

@@ -0,0 +1,62 @@
+---
+title: Manage Dev Box projects
+titleSuffix: Microsoft Dev Box
+description: Learn how to manage multiple projects by delegating permissions to project admins.
+services: dev-box
+ms.service: dev-box
+author: RoseHJM
+ms.author: rosemalcolm
+ms.date: 07/29/2022
+ms.topic: how-to
+---
+
+# Provide access to projects for project admins
+
+You can create multiple projects in the dev center to align with each team's specific requirements. By using the built-in DevCenter Project Admin role, you can delegate project administration to a member of a team. Project Admins can use the network connections and dev box definitions configured at the dev center level to create and manage dev box pools within their project.
+
+A Dev Center Project Admin can manage a project by:
+
+- Viewing the network connections attached to the dev center.
+- Viewing the dev box definitions attached to the dev center.
+- Creating, viewing, updating, deleting dev box pools in the project.
+
+## Assign permissions to project admins
+ 
+Follow the instructions below to add role assignments for this role.
+
+1. Sign in to the [Azure portal](https://portal.azure.com).
+ 
+1. In the search box, type *Dev box* and select **Projects**. 
+
+1. Select the project you want to provide your team members access to.
+ 
+   :::image type="content" source="./media/how-to-project-admin/projects-grid.png" alt-text="Screenshot showing the list of existing projects.":::
+
+1. Select **Access Control (IAM)** from the left menu.
+ 
+   :::image type="content" source="./media/how-to-project-admin/access-control-tab.png" alt-text="Screenshot showing the Project Access control page with the Access Control link highlighted.":::
+
+1. Select **Add** > **Add role assignment**.
+ 
+   :::image type="content" source="./media/how-to-project-admin/add-role-assignment.png" alt-text="Screenshot showing the Add menu with Add role assignment highlighted.":::
+
+1. On the Add role assignment page, on the Role tab, search for *devcenter project admin*, select the **DevCenter Project Admin** built-in role, and then select **Next**.
+ 
+   :::image type="content" source="./media/how-to-project-admin/project-admin-role.png" alt-text="Screenshot showing the search box highlighted.":::
+
+1. On the Members tab, select **+ Select Members**.
+ 
+   :::image type="content" source="./media/how-to-project-admin/project-admin-select-members.png" alt-text="Screenshot showing the Members tab with Select members highlighted.":::
+
+1. In **Select members**, select the Active Directory Users or Groups you want to add, and then select **Select**.
+ 
+   :::image type="content" source="./media/how-to-project-admin/select-members-search.png" alt-text="Screenshot showing the Select members pane with a user account highlighted.":::
+
+1. On the Members tab, select **Review + assign**.
+
+The user will now be able to manage the project and create dev box pools within it.
+
+[!INCLUDE [permissions note](./includes/note-permission-to-create-dev-box.md)]
+## Next steps
+
+- [Quickstart: Configure the Microsoft Dev Box service](quickstart-configure-dev-box-service.md)

articles/dev-box/includes/note-dev-box-runs-on-creation.md

@@ -0,0 +1,10 @@
+---
+author: RoseHJM
+ms.author: rosemalcolm
+ms.date: 08/11/2022
+ms.topic: include
+ms.service: dev-box
+---
+
+> [!IMPORTANT]
+> A dev box is automatically started and running when the creation process completes. Dev boxes incur costs whenever they are running.

articles/dev-box/includes/note-permission-to-create-dev-box.md

@@ -0,0 +1,10 @@
+---
+author: RoseHJM
+ms.author: rosemalcolm
+ms.date: 07/29/2022
+ms.topic: include
+ms.service: dev-box
+---
+
+> [!IMPORTANT]
+> Users assigned the Dev Box User role or Project Admin role can create dev boxes.