Merge pull request #290389 from MicrosoftDocs/release-ignite-dev-box-customizations

Ignite 2024 ship room - Team customizations - Microsoft Dev Box - #330058

Author: MikeRayMSFT

articles/dev-box/.openpublishing.redirection.dev-box.json

@@ -69,6 +69,16 @@
       "source_path_from_root": "/articles/dev-box/tutorial-configure-multiple-monitors.md",
       "redirect_url": "/azure/dev-box/how-to-configure-multiple-monitors",
       "redirect_document_id": false
+    },
+    {
+      "source_path_from_root": "/articles/dev-box/how-to-customize-dev-box-setup-tasks.md",
+      "redirect_url": "/azure/dev-box/concept-what-are-team-customizations",
+      "redirect_document_id": false
+    },
+    {
+      "source_path_from_root": "/articles/dev-box/how-to-use-dev-home-customize-dev-box.md",
+      "redirect_url": "/azure/dev-box/how-to-use-dev-home-create-dev-box",
+      "redirect_document_id": false
     }
   ]
 }

articles/dev-box/concept-dev-box-role-based-access-control.md

@@ -238,7 +238,7 @@ access to the resources of their team.
 
 Microsoft Dev Box uses catalogs to enable developers to deploy
 customizations for dev boxes by using a catalog of tasks and a
-configuration file to install software, add extensions, clone
+customization file to install software, add extensions, clone
 repositories, and more. 
 
 Microsoft Dev Box stores catalogs in either a [GitHub repository](https://docs.github.com/repositories/creating-and-managing-repositories/about-repositories) or an [Azure DevOps Services repository](/azure/devops/repos/get-started/what-is-repos). You can attach a catalog to a dev center or to a project.

articles/dev-box/concept-what-are-team-customizations.md

@@ -0,0 +1,75 @@
+---
+title: Streamline Your Workflow with Dev Box Team Customizations
+description: Understand how to use Dev Box Team Customizations to create ready-to-code configurations for your development teams.
+author: RoseHJM
+ms.author: rosemalcolm
+ms.service: dev-box
+ms.topic: concept-article
+ms.date: 11/06/2024
+
+#customer intent: As a Project Admin or Dev Center Admin, I want to understand how to use Dev Box Team Customizations so that I can create efficient, ready-to-code configurations for my development teams.
+---
+
+# Microsoft Dev Box Team Customizations
+Getting developers started on a new project or team can be complex and time-consuming. Microsoft Dev Box Team Customizations enables you to streamline developer environment setup. With Team Customizations, you can configure ready-to-code workstations with necessary applications, tools, repositories, code libraries, packages, and build scripts.
+Team Customizations allows you to define a shared Dev Box configuration for each of your development teams without having to invest in setting up an imaging solution like Packer or Azure virtual machine (VM) Image Templates. It provides a lightweight alternative that allows central platform engineering teams to delegate Dev Box configuration management to the teams that use them. Team Customizations also offers an in-built way of optimizing your team's Dev Box customizations by flattening them into a custom image using the same customization file, without the need to manage added infrastructure or maintain image templates.
+
+[!INCLUDE [customizations-preview-text](includes/customizations-preview-text.md)]
+
+## How does Dev Box Team Customizations work?
+When you configure Dev Box Team Customizations for your organization, careful planning and informed decision-making are essential. The following diagram provides an overview of the process and highlights key decision points.
+
+:::image type="content" source="media/concept-what-are-team-customizations/dev-box-customizations-workflow.svg" alt-text="Diagram showing the workflow for Dev Box Team Customizations, including steps for planning, configuring, and deploying customizations." lightbox="media/concept-what-are-team-customizations/dev-box-customizations-workflow.svg":::
+ 
+- **Configure your dev center:**
+  - Enable project-level catalogs.
+  - Assign permissions for Project Admins.
+- **Decide whether to use a catalog with custom reusable components:**
+  - Dev center
+    - PowerShell or WinGet statements.
+  - Your own catalog
+    - Host in Azure Repos or GitHub.
+    - Add tasks.
+    - Attach to dev center or project.
+- **Create a team customizations file:**
+  - Create a team customizations file called imagedefinition.yaml.
+- **Specify image in a dev box pool:**
+  - Create or modify a dev box pool and specify imagedefinition.yaml as the image definition.
+- **Choose how you'll use the image definition:**
+    - Optimize for team customization.
+    - Build each time you create a dev box.
+- **Create dev box:**
+  - Create your dev box from the configured pool using the developer portal.
+
+## What is a customization file?
+Dev Box customizations use a yaml formatted file to specify a list of tasks to apply from the catalog when creating a new dev box. These tasks identify the catalog task and provide parameters like the name of the software to install. The customization file is then made available to the developers creating new dev boxes. 
+
+You can use secrets from your Azure Key Vault in your customization file to clone private repositories, or with any custom task you author that requires an access token.
+
+## What are tasks?
+Dev Box customization tasks are wrappers for PowerShell scripts, allowing you as a platform team to define reusable components that your teams can use in their customizations. WinGet and PowerShell are available as primitive tasks out of the box.
+
+When creating tasks, determine which need to run in a SYSTEM context and which can run after sign-in, in a user context. Team customizations can be run in a SYSTEM context and in a user context (after sign-in). Individual customizations can only run in a user context. 
+
+## Differences Between Team and Individual Customizations
+Individual developers can attach a yaml-based customization file when creating their Dev Box to control the development environment on their Dev Box. Individual customizations should be used only for personal settings and apps. Tasks specified in the individual customization file run only in the user context, after sign-in. While teams of developers can share common yaml files, this approach can be inefficient and error-prone, and against compliance policies. Dev Box Team Customizations provides a workflow for developer team leaders, Project Admins, and dev center administrators to preconfigure customization files on Dev Box pools. This way, a developer creating a dev box doesn't need to find and upload a customization file for themselves.
+
+## Key terms
+When working with Dev Box Team Customizations, you should be familiar with the following key terms:
+
+- **Catalog**
+    - Can be stored in your code repository, or in a separate repository of customization files.
+    - Hosted on GitHub or Azure Repos.
+    - Attached to dev center or project to make tasks accessible to the developer team.
+- **Tasks**
+    - Perform specific actions, like installing software.
+    - Consist of one or more PowerShell scripts and a task.yaml file.
+- **Customization file**
+    - Yaml-based file defining tasks for dev boxes.
+    - When shared across a team, it's an *image definition* and specifies the base dev box image, along with its customization options.
+
+## Related content
+- [Quickstart: Create Dev Box Team Customizations](quickstart-team-customizations.md)
+- [Write a Team Customization file for Dev Box](how-to-write-customization-file.md)
+- [Configure imaging for Dev Box Team Customizations](how-to-configure-customization-imaging.md)
+- [Configure customization tasks](how-to-create-customization-tasks-catalog.md)

articles/dev-box/how-to-configure-customization-imaging.md

@@ -0,0 +1,131 @@
+---
+title: Imaging for Dev Box Team Customizations
+description: Configure dev box pools to use image definition files, optimizing customizations, and creating reusable images for your team.
+author: RoseHJM
+ms.author: rosemalcolm
+ms.service: dev-box
+ms.topic: how-to
+ms.date: 11/05/2024
+
+#customer intent: As a dev center administrator or Project Admin, I want to configure dev box pools to use image definition files so that my development teams can create customized dev boxes.
+---
+
+# Create a shared Customization
+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 customization 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 Dev Box Team Customizations, enable project-level catalogs and configure catalog sync settings for the project. Then, attach a catalog that contains a definition file to your project, configure a dev box pool to use an image definition, and verify that the customizations apply to a new dev box. When the customizations apply correctly, you can choose to build a reusable image, which makes the creation of new dev boxes quicker.
+
+[!INCLUDE [customizations-preview-text](includes/customizations-preview-text.md)]
+
+## 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](quickstart-configure-dev-box-service.md) to create them.
+- 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](./how-to-write-customization-file.md).
+
+## Permissions required to configure customizations
+  
+[!INCLUDE [permissions-for-customizations](includes/permissions-for-customizations.md)]
+
+To manage a dev box pool, you need the following permissions:
+
+| Action | Permissions required |
+|---|---|
+| _Create, delete, or update a dev box pool_ | - Owner or Contributor permissions on an Azure subscription or a specific resource group. </br>- DevCenter Project Admin permissions for the project. |
+
+## Enable project-level catalogs
+
+Enable project-level catalogs. This setting allows you to attach a catalog to a project.
+
+For more information about project-level catalogs, see [Enable project-level catalogs](https://aka.ms/deployment-environments/project-catalog).
+
+## Configure catalog sync settings for the project
+
+Configure your project to sync image definitions from the catalog. This setting allows you to use the image definitions in the catalog to create dev box pools.
+
+1. Sign in to the [Azure portal](https://portal.azure.com).
+1. In the search box, enter **projects**. In the list of results, select **Projects**.
+1. Open the Dev Box project for which you want to configure catalog sync settings.
+1. Select **Catalogs**.
+1. Select **Sync settings**.
+
+   :::image type="content" source="./media/how-to-configure-customization-imaging/customizations-project-sync-settings-small.png" alt-text="Screenshot of the Catalogs pane in the Azure portal, with Sync settings highlighted." lightbox="./media/how-to-configure-customization-imaging/customizations-project-sync-settings.png":::
+
+1. In the **Sync settings** pane, select **Image definitions**, and then select **Save**.
+ 
+   :::image type="content" source="./media/how-to-configure-customization-imaging/customizations-project-sync-image-definitions.png" alt-text="Screenshot of the Sync settings pane in the Azure portal, with Image definitions selected." lightbox="./media/how-to-configure-customization-imaging/customizations-project-sync-image-definitions.png":::
+
+## Attach 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. 
+
+On the Image definition page, you see the image definitions accessible to your project.
+
+:::image type="content" source="media/how-to-configure-customization-imaging/team-customizations-image-definitions-small.png" alt-text="Screenshot of the Image definition pane in the Azure portal, showing accessible image definitions for a project." lightbox="media/how-to-configure-customization-imaging/team-customizations-image-definitions.png":::
+
+For more information about attaching catalogs, see [Add and configure a catalog from GitHub or Azure Repos](../deployment-environments/how-to-configure-catalog.md).
+
+## 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.
+
+The following steps show you how to create a dev box pool and specify an image definition. 
+
+1. Sign in to the [Azure portal](https://portal.azure.com).
+1. In the search box, enter **projects**. In the list of results, select **Projects**.
+1. Open the Dev Box project with which you want to associate the new dev box pool.
+1. Select **Dev box pools**, and then select **Create**.
+1. On the **Create a dev box pool** pane, 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. It must be unique within a project. |
+   | **Definition** | Lists image definitions from accessible catalogs and dev box definitions. Select an image definition file. |
+   | **Network connection** | Select **Deploy to a Microsoft hosted network**, or use an existing network connection. |
+   |**Enable single sign-on** | Select **Yes** to enable single sign-on for the dev boxes in this pool. Single sign-on must be configured for the organization. See [Enable single sign-on for dev boxes](https://aka.ms/dev-box/single-sign-on). |
+   | **Dev box Creator Privileges** | Select **Local Administrator** or **Standard User**. |
+   | **Enable Auto-stop** | **Yes** is the default. Select **No** to disable an auto-stop schedule. You can configure an auto-stop schedule after the pool is created. |
+   | **Stop time** | Select a time to shut down all the dev boxes in the pool. |
+   | **Time zone** | Select the time zone that the stop time is in. |
+   | **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. |
+
+   :::image type="content" source="./media/how-to-configure-customization-imaging/pool-specify-image-definition.png" alt-text="Screenshot of the pane for creating a dev box pool." lightbox="./media/how-to-configure-customization-imaging/pool-specify-image-definition.png":::
+
+1. Select **Create**.
+1. Verify that the new dev box pool appears in the list. You might need to refresh the screen.
+ 
+### 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. 
+
+[Quickstart: Create and connect to a dev box by using the Microsoft Dev Box developer portal](quickstart-create-dev-box.md)
+
+Sign in to the [Microsoft Dev Box developer portal](https://aka.ms/devbox-portal).
+
+When the dev box is created, the customizations from the image definition file are applied to the dev box. You can now connect to the 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.
+
+### Choose to build a reusable image
+To optimize customizations and create a reusable image for your team, you build an image from the customization file. This image applies to all dev boxes created from the pool.
+
+To build an image from a customization file, follow these steps:
+1. On the Image definition page, select the image you want to build.
+ 
+   :::image type="content" source="./media/how-to-configure-customization-imaging/customizations-select-image-small.png" alt-text="Screenshot of the Image definition page, showing the list of image definition with one selected." lightbox="./media/how-to-configure-customization-imaging/customizations-select-image-small.png"::: 
+ 
+1. Select **Build**.
+ 
+   :::image type="content" source="./media/how-to-configure-customization-imaging/customizations-build-image-small.png" alt-text="Screenshot of the Image definition page, with Build highlighted." lightbox="./media/how-to-configure-customization-imaging/customizations-build-image-small.png"::: 
+ 
+1. Track progress 
+
+   :::image type="content" source="./media/how-to-configure-customization-imaging/customizations-image-build-progress-small.png" alt-text="Screenshot of the Image definition page, with the image status Progressing highlighted." lightbox="./media/how-to-configure-customization-imaging/customizations-image-build-progress.png":::  
+
+> [!IMPORTANT]
+> When 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 managed by Microsoft, and tasks that require access to on premise resources might fail.
+
+When the build completes 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.
+
+## Related content
+- [Microsoft Dev Box Team Customizations](concept-what-are-team-customizations.md)
+- [Write a customization file](./how-to-write-customization-file.md) 
+- [Add and configure a catalog from GitHub or Azure Repos](../deployment-environments/how-to-configure-catalog.md)