¡Hi developer 👋🏻! This repo contains several script to help you understand how Microsoft DevBox and Azure Deployment Environments works.
In order to follow this tutorial, you need to have the following tools installed:
Or you can use Dev Containers with Visual Studio Code. Just open this repo in a container and you will have all the tools you need.
Also, you need a .env file with a personal access token to read GitHub repo contents. You can check .env-sample to see the expected format.
az extension add --name devcenteraz login --use-device-codeTo make it easier to follow this tutorial, let's set some variables.
source scripts/00-minimal-setup/00-variables-and-registrations.shAs every Azure resource, the first thing you need to do is to create a resource group. Also, in a enterprise environment, you will probably want to create a virtual network to connect your dev boxes to your corporate network.
source scripts/00-minimal-setup/01-create-rg.shDev Center is the place where you will manage your projects.
source scripts/00-minimal-setup/02-create-dev-center.shProjects in Dev Center should represent a team or a group of people that will use the same dev resources. For example, you can create a project for your backend team, another for your frontend team, and so on.
For this demo we need a Microsoft Entra ID Group for our developers. You can create a group with the following command:
source scripts/00-minimal-setup/03-create-entra-id-groups.shsource scripts/00-minimal-setup/03-create-projects.shDev Box definitions are created within a project and they carry information about the dev box and any requirements for using it to create VMs. This includes the image version, the size of the VM, and the virtual network to connect to.
source scripts/01-basic-devbox/01-create-dev-box-definition.shA dev box pool is a collection of dev boxes that are created from the same dev box definition. You can create a dev box pool for each team or group of people that will use the same dev boxes.
source scripts/01-basic-devbox/02-create-dev-box-pool.shCongrats 🎉, you have created a dev box pool. Now you can access the Developer Portal and create a new dev box.
The URL for the developer portal is https://devportal.microsoft.com
You can access with any user in the Devs group 👩🏼💻👨🏻💻
We have two options to create a custom image: using Azure Image Builder or using Packer.
Azure Image Builder is a service that allows you to create custom images in Azure. You can use it to create a custom image from a managed image, a shared image gallery image, or a generalized VM. You can also use it to create a custom image from a Packer template.
The first thing we need is a gallery.
source scripts/02-custom-devbox/image-builder/01-create-azure-compute-gallery.shImage definitions are created within a gallery and they carry information about the image and any requirements for using it to create VMs. This includes whether the image is Windows or Linux, release notes, and minimum and maximum memory requirements. It's a definition of a type of image.
source scripts/02-custom-devbox/image-builder/02-create-image-definition.shAn image version is what you use to create a VM when using a gallery. You can have multiple versions of an image as needed for your environment. Like a managed image, when you use an image version to create a VM, the image version is used to create new disks for the VM. Image versions can be used multiple times.
In order to create your custom image you can use Azure Image Builder and for that you need a identity. This identity needs some permissions but there is no built-in role. So let's create a custom role for the image builder too.
source scripts/02-custom-devbox/image-builder/03-create-azure-image-builder-identity-and-role.shLastly you need to define the ingredients for your new image: what is the image base, if some customization is needed and how much time it has the builder to build it.
We are going to use this template: custom-images/win11-with-vscode.json which install Visual Studio Code in a Windows 11.
source scripts/02-custom-devbox/image-builder/04-create-an-image-template.shAnd now just wait... a little bit ⌚
Congrats 🎉, you have created a custom image. Now you can use it to create a new dev box.
source scripts/02-custom-devbox/image-builder/05-create-dev-box-definition.shAfter that you can create a dev box pool
source scripts/02-custom-devbox/image-builder/06-create-dev-box-pool.shand access the Developer Portal to create a new dev box.
Developer Portal URL: https://devportal.microsoft.com
You should see a Windows 11 with VS Code installed.
The other option to create a custom image is to use Packer. Packer is a tool for creating identical machine images for multiple platforms from a single source configuration.
The first thing you need to do is to install Packer. Once you have Packer installed, you can create a Packer template. In this repo we have several examples of Packer templates. You can use the packer-for-image-generation folder to create a custom image with Packer.
But first we need to create a new gallery for these packages. In order to execute packer you need a service principal:
SUBSCRIPTION_ID=$(az account show --query id -o tsv)
RESULT=$(az ad sp create-for-rbac --name hcp-packer --role Contributor --scopes /subscriptions/$SUBSCRIPTION_ID)IMPORTANT: Please replace the
variables.pkr.hclfile with your own values.
export ARM_CLIENT_SECRET=$(echo $RESULT | jq -r .password)
export ARM_CLIENT_ID=$(echo $RESULT | jq -r .appId)
export ARM_TENANT_ID=$(az account show --query tenantId -o tsv)
export ARM_SUBSCRIPTION_ID=$(az account show --query id -o tsv)
export ARM_RESOURCE_GROUP_NAME=$PACKER_GALLERY_RESOURCE_GROUPWith that in place, you can create this resources using the terrafom script in the terraform folder.
source scripts/02-custom-devbox/packer/01-create-resources-using-tf.shOnce you have the custom images created, you need to attach the gallery to the Dev Center:
source scripts/02-custom-devbox/packer/02-assign-packer-gallery.shCreate the Dev Box definitions:
source scripts/02-custom-devbox/packer/03-create-dev-box-definitions-for-packer-images.shAnd create the Dev Box Pools:
source scripts/02-custom-devbox/packer/04-create-dev-box-pool-with-packer-images.shCheck the portal and create a new dev box with the new images.
You can use configuration-as-code to customize the dev box. Configuration-as-code allows you to define the configuration of a dev box in a YAML file. You can use configuration-as-code to customize the dev box by installing software, configuring settings, and running scripts.
But first platform admin teams must choose which tasks are available to their developers by defining a Catalog of tasks. A Catalog is a collection of tasks that developers can use to customize their dev boxes. Each task in the catalog is a YAML file that defines a task that can be run on a dev box plus a script that is executed when the task is run.
For this environment we are going to allow the tasks in the allowed-tasks folder. So we need to attach this folder to the Dev Center.
source scripts/02-custom-devbox/customizations/00-attach-catalog-with-allowed-tasks.shSo now you can create a new dev box with some customizations. Just go to the Developer Portal and upload the devbox-customizations/workload.yaml file.
After creation you should see all this installed:
- Visual Studio Code
### Integrate Dev Box with a virtual network
Create a network connections 📞If you need to connect to a virtual network, you can create a network connection. A network connection is a connection between a dev box and a virtual network. You can create a network connection for each virtual network that you want to connect to a dev box. After you create a network connection, you have to attach it to a dev center.
source scripts/03-network-integration/01-create-vnet-and-network-connections.shsource scripts/03-network-integration/02-create-vm-with-sql-server-in-that-vnet.shNo we can create a new dev box pool with the network connection using the dev box definition what we have with vscode.
source scripts/03-network-integration/03-create-dev-box-pool.shThe URL for the developer portal is https://devportal.microsoft.com
An environment definition is composed of least two files:
- An Azure Resource Manager template (ARM template) in JSON file format. For example, azuredeploy.json.
- A configuration file that provides metadata about the template. This file should be named environment.yaml.
You can see some examples in the catalog folder.
source scripts/04-environments/01-create-a-catalog.shYou can use BICEP and then convert it to ARM template.
az bicep build --file {bicep_file} --outfile {out_file}for example:
az bicep build --file catalog/ARMTemplates/tour-of-heroes-environment/main.bicep --outfile catalog/ARMTemplates/tour-of-heroes-environment/azuredeploy.jsonOr now you can use Azure Deployment Environments (ADE) extensibility model which allows you to provide a curated set of IaC templates that your developers can use to deploy environments. You can use any IaC tool that you want. For example, Bicep, Terraform, or Pulumi templates.
For this scenario you need a create a Docker image that contains the tools that you want to use.
source scripts/04-environments/02-ade-extensibility-model.sh![IMPORTANT] Don't try to create the resource group in your terraform files. Instead do this:
variable "resource_group_name" {}
data "azurerm_resource_group" "rg" {
name = var.resource_group_name
}Because the resource group is created by the Dev Center.
If you want to check if the deployment went well you can check the logs:
az devcenter dev environment list --project $PROJECT_FOR_ENVIRONMENTS --dev-center $DEV_CENTER_NAMEAnd you can check for environment name:
az devcenter dev environment show --environment-name $DEV_ENVIRONMENT_TYPE --project $PROJECT_FOR_ENVIRONMENTS --dev-center $DEV_CENTER_NAMEYOUR_ENVIRONMENT_NAME="direwolvescosmos"
# Get list of operations on the environment, choose the latest operation
OPERATION_ID=$(az devcenter dev environment list-operation \
--environment-name $YOUR_ENVIRONMENT_NAME \
--project $PROJECT_FOR_ENVIRONMENTS \
--dev-center $DEV_CENTER_NAME \
--query "[-1].operationId" -o tsv)
# Using the latest operation ID, view the operation logs
watch az devcenter dev environment show-logs-by-operation \
--environment-name $YOUR_ENVIRONMENT_NAME \
--project $PROJECT_FOR_ENVIRONMENTS \
--operation-id $OPERATION_ID \
--dev-center $DEV_CENTER_NAMEDelete an environment:
az devcenter dev environment delete \
--environment-name direwolvesweb \
--project $PROJECT_FOR_ENVIRONMENTS \
--dev-center $DEV_CENTER_NAMECongratulations 🎉 You did it! Now you can delete all and go to sleep 🛌💤
Please keep in mind that before you delete the resources, you need to delete the environments created by the users.
source scripts/clean-up.sh