/dev-box-images

Primary LanguagePythonMIT LicenseMIT

Dev Box Images

This repo contains custom images to be used with Microsoft Dev Box. It demonstrates how to create custom images with pre-installed software using Packer and shared them via Azure Compute Gallery.

See the workflow file to see how images are built and deployed.

Images

Build Images

Name OS Additional Software
VS2022Box Windows 11 Enterprise Visual Studio 2022
VSCodeBox Windows 11 Enterprise

Use this form to request a new image.

Preinstalled Software

The following software is installed on all images. Use this form to request additional software.

Usage

To get started, fork this repository.

NOTE: The workflow that builds and publishes the images is only triggered if files the /images or /scripts folders change. After completing the steps below, modify any file within those two folders (like changing the version in the image.yml files) to initiate a build.

Azure Compute Gallery

Open the gallery.yml file in the root of the repository and update following properties to match your Azure Compute Gallery:

  • name - the name of your Azure Compute Gallery
  • resourceGroup - The resource group that contains your Azure Compute Gallery

Example:

name: MyGallery
resourceGroup: MyGallery-RG

Service Principal

The solution requires a Service Principal to provision resources associated with create a new image (VMs, etc.). See the Azure Login action docs for instructions on how to create.

IMPORTANT: Once you create a new Service Principal you must assign it the following roles in RBAC::

  • Contributor on the subscription used to provision resources, OR
  • Owner on a specific (existing) resource group (see Resource Group Usage below) and Contributor on the Azure Compute Gallery (and its resource group)

AZURE_CREDENTIALS

In your fork create a new repository secret named AZURE_CREDENTIALS with a value that contains credentials for the service principal created above. For details on how to create these credentials, see the Azure Login action docs.

Example:

az ad sp create-for-rbac --sdk-auth --role contributor --scopes /subscriptions/<GUID> -n MyUniqueName

output:

{
  "clientId": "<GUID>",
  "clientSecret": "<STRING>",
  "subscriptionId": "<GUID>",
  "tenantId": "<GUID>"
  (...)
}

IMPORTANT: when pasting in the value for AZURE_CREDENTIALS, remove all line breaks so that the JSON is on a single line. Otherwise GitHub will assume subscriptionId and tenantId are secrets and prevent them from being share across workflow jobs.

Example:

{ "clientId": "<GUID>", "clientSecret": "<GUID>", "subscriptionId": "<GUID>", "tenantId": "<GUID>", (...) }

Resource Group Usage

This solution uses Packer's Azure builder which can either provision resources into a new resource group that it controls (default) or an existing one. The advantage of using a packer defined resource group is that failed resource cleanup is easier because you can simply remove the entire resource group, however this means that the provided credentials must have permission to create and remove resource groups. By using an existing resource group you can scope the provided credentials to just this group, however failed builds are more likely to leave unused artifacts.

To use an existing resource group you must provide a value for buildResourceGroup in the images image.yml file.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.