This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Accelerator Configration

Dev Box accelerator settings

1 - Resource Groups

How to either create new or connect to existent Azure Resource Groups to organize your Dev Box Landing Zone

Overview

This YAML configuration file azureResources.yaml defines the organizational structure for Azure resource groups as part of the Microsoft Dev Box Accelerator. It follows Azure Landing Zone best practices, enabling modular, decoupled, and scalable management of cloud resources. By segmenting resources into functional groups—workload, security, monitoring, and connectivity—the configuration supports clear governance, access control, and lifecycle management for enterprise-scale Dev Box deployments.

Role in Dev Box Accelerator:
This file is a foundational component, ensuring that all resources deployed for Microsoft Dev Box environments are organized, tagged, and governed according to enterprise standards. It enables teams to manage infrastructure and workloads independently, supporting both operational efficiency and compliance.

Table of Contents

Configurations

Each top-level section in the YAML file represents a distinct Azure resource group category, following Azure Landing Zone principles for segregation by function. Below is a breakdown of each section, its keys, and their purposes.

Workload Resource Group

Purpose: Hosts the main application resources for Dev Box environments, including Dev Center resources, Dev Box definitions, pools, and project assets.

Best Practices:

  • Separate application workloads from infrastructure and security components for independent scaling, access control, and lifecycle management.
  • Use clear, consistent naming and tagging for governance and automation.

YAML Example:

workload:
  create: true
  name: devexp-workload
  description: prodExp
  tags:
    environment: dev           # Deployment environment (dev, test, prod)
    division: Platforms        # Business division responsible for the resource
    team: DevExP              # Team owning the resource
    project: Contoso-DevExp-DevBox  # Project name
    costCenter: IT            # Financial allocation center
    owner: Contoso            # Resource owner
    landingZone: Workload     # Landing zone classification
    resources: ResourceGroup  # Resource type

Key Explanations:

  • create: Whether to create this resource group (true/false).
  • name: Resource group name, following a consistent naming convention.
  • description: Brief summary of the group’s purpose.
  • tags: Metadata for governance, cost allocation, and management.

Security Resource Group

Purpose: Contains security-related resources such as Azure Key Vaults, Network Security Groups (NSGs), Microsoft Defender for Cloud, and private endpoints.

Best Practices:

  • Isolate security resources to apply stricter access controls and enable separate monitoring/auditing of security components.
  • Use dedicated resource groups for security to support compliance and operational excellence.

YAML Example:

security:
  create: true
  name: devexp-security
  description: prodExp
  tags:
    environment: dev           # Deployment environment
    division: Platforms        # Business division
    team: DevExP              # Team
    project: Contoso-DevExp-DevBox  # Project name
    costCenter: IT            # Cost center
    owner: Contoso            # Owner
    landingZone: Workload     # Landing zone
    resources: ResourceGroup  # Resource type

Key Explanations:

  • Same structure as workload, but dedicated to security assets for stricter access and monitoring.

Monitoring Resource Group

Purpose: Contains monitoring and observability resources such as Log Analytics workspaces, Application Insights, Azure Monitor alerts, action groups, and dashboards.

Best Practices:

  • Centralize monitoring resources to provide a unified view of operational health and simplify diagnostics.
  • Use consistent tagging for cost management and reporting.

YAML Example:

monitoring:
  create: true
  name: devexp-monitoring
  description: prodExp
  tags:
    environment: dev           # Deployment environment
    division: Platforms        # Business division
    team: DevExP              # Team
    project: Contoso-DevExp-DevBox  # Project name
    costCenter: IT            # Cost center
    owner: Contoso            # Owner
    landingZone: Workload     # Landing zone
    resources: ResourceGroup  # Resource type

Key Explanations:

  • Enables unified operational health monitoring and diagnostics.

Best Practices

  • Consistent Naming: Use a standard naming convention for resource groups (e.g., [project]-[purpose]-[environment]-rg) to simplify management and automation.
  • Tagging: Apply consistent tags across all resource groups for effective cost tracking, ownership, and compliance.
  • Separation of Concerns: Segregate resources by function (workload, security, monitoring) to enable independent scaling, access control, and lifecycle management.
  • Workload Group: Separate application workloads from infrastructure and security components for flexibility and easier management.
  • Security Group: Isolate security resources for stricter access controls and enable separate monitoring/auditing.
  • Monitoring Group: Centralize monitoring resources to provide a unified view of operational health and simplify diagnostics.
  • Adapt for Environments: Duplicate or adjust sections for different environments (dev, test, prod) by changing the environment tag and resource group names.
  • Documentation: Keep descriptions up to date to reflect the actual purpose of each group, aiding onboarding and audits.
  • Automation: Integrate this YAML into your Infrastructure as Code (IaC) pipelines to automate resource group creation and tagging.

References

2 - Security

How to configure Azure Key Vault and manage secrets for your Dev Box environment

Overview

This document provides a comprehensive analysis of the security.yaml configuration file, a core component of the Microsoft Dev Box Accelerator. The Accelerator enables rapid, modular, and secure provisioning of development environments in Azure. The security.yaml file governs the setup and management of an Azure Key Vault resource, which is critical for securely storing sensitive credentials and secrets required by development teams. By decoupling security configuration, the Accelerator ensures best practices, compliance, and flexibility across environments.

Table of Contents

Configurations

Below is a detailed breakdown of each section and key in the security.yaml file, including their YAML representation and purpose.

Resource Creation

create: true
  • Purpose: Indicates whether the Azure Key Vault resource should be created as part of the deployment.
  • Type: Boolean (true or false)
  • Typical Use: Set to true for initial deployments; set to false if the Key Vault already exists and should not be recreated.

Key Vault Configuration

keyVault:
  name: contoso
  description: Development Environment Key Vault
  secretName: gha-token
  • name: Globally unique name for the Key Vault.
  • description: Human-readable description of the Key Vault’s purpose.
  • secretName: Name of the secret (e.g., a GitHub Actions token) to be stored in the Key Vault.

Security Settings

  enablePurgeProtection: true
  enableSoftDelete: true
  softDeleteRetentionInDays: 7
  enableRbacAuthorization: true
  • enablePurgeProtection: Prevents permanent deletion of secrets, even by authorized users. Enhances data protection.
  • enableSoftDelete: Allows recovery of deleted secrets within a retention period.
  • softDeleteRetentionInDays: Number of days (7–90) that deleted secrets remain recoverable.
  • enableRbacAuthorization: Uses Azure Role-Based Access Control (RBAC) for access management instead of legacy access policies.

Resource Organization (Tags)

  tags:
    environment: dev
    division: Platforms
    team: DevExP
    project: Contoso-DevExp-DevBox
    costCenter: IT
    owner: Contoso
    landingZone: security
    resources: ResourceGroup
  • Purpose: Tags provide metadata for resource organization, cost management, and governance.
  • Common Tags:
    • environment: Deployment environment (e.g., dev, test, prod)
    • division, team, project: Organizational context
    • costCenter: For billing and chargeback
    • owner: Resource owner
    • landingZone: Azure landing zone classification
    • resources: Resource grouping identifier

Examples and Use Cases

Example 1: Provisioning a Key Vault for a New Dev Environment

A new development team needs a secure place to store secrets for CI/CD pipelines. By setting create: true and specifying the secretName, the Accelerator will provision a Key Vault and store the required GitHub Actions token.

create: true
keyVault:
  name: devbox-kv-001
  description: Dev Box Key Vault for Team Alpha
  secretName: gha-token
  enablePurgeProtection: true
  enableSoftDelete: true
  softDeleteRetentionInDays: 14
  enableRbacAuthorization: true
  tags:
    environment: dev
    team: Alpha
    project: DevBox
    costCenter: IT
    owner: TeamAlphaLead
    landingZone: security
    resources: ResourceGroup

Example 2: Reusing an Existing Key Vault

If the Key Vault already exists, set create: false to avoid redeployment:

create: false
keyVault:
  name: existing-kv
  # ...other settings...

Best Practices

  • Unique Naming: Ensure the name is globally unique within Azure to avoid deployment failures.
  • Retention Period: Adjust softDeleteRetentionInDays based on your organization’s compliance and recovery requirements.
  • RBAC vs. Access Policies: Prefer enableRbacAuthorization: true for modern, scalable access control.
  • Tagging: Use descriptive and consistent tags to simplify resource management, cost tracking, and automation.
  • Security: Always enable enablePurgeProtection and enableSoftDelete for production environments to prevent accidental or malicious loss of secrets.
  • Schema Validation: Use the provided $schema directive for IDE validation and to prevent misconfiguration.

References

3 - Dev Center

How to configure the Core, Identity and Access Management, Catalogs, Environments and Projects settings for the Dev Center

Dev Center Configuration Guide

Overview

The devcenter.yaml file is the central configuration for the Microsoft Dev Box Accelerator. It defines the structure, governance, and operational parameters for a Dev Center resource in Azure, enabling organizations to provide secure, scalable, and role-specific developer workstations (Dev Boxes). This YAML orchestrates Dev Box pools, access controls, environment types, project boundaries, and integration with version-controlled catalogs, ensuring a modular and decoupled approach to developer environment management.

Key Roles of this YAML:

  • Centralizes Dev Center resource setup and policy.
  • Defines projects, environments, and access controls.
  • Integrates with Git-based catalogs for configuration-as-code.
  • Enables automated, role-specific Dev Box provisioning.

Configuration Sections

Below is a breakdown of each major section, its YAML representation, and an explanation of its purpose.

Dev Center Metadata

name: "devexp-devcenter"
  • name: Globally unique identifier for the Dev Center resource.

Global Settings

catalogItemSyncEnableStatus: "Enabled"
microsoftHostedNetworkEnableStatus: "Enabled"
installAzureMonitorAgentEnableStatus: "Enabled"
  • catalogItemSyncEnableStatus: Enables automatic sync of catalog items from source repositories.
  • microsoftHostedNetworkEnableStatus: Uses Microsoft-managed networking for Dev Boxes (simplifies setup).
  • installAzureMonitorAgentEnableStatus: Installs Azure Monitor agent for monitoring and compliance.

Identity and Access Control

identity:
  type: "SystemAssigned"
  roleAssignments:
    devCenter:
      - id: "b24988ac-6180-42a0-ab88-20f7382dd24c"
        name: "Contributor"
        scope: "Subscription"
      - id: "18d7d88d-d35e-4fb5-a5c3-7773c20a72d9"
        name: "User Access Administrator"
        scope: "Subscription"
      - id: "4633458b-17de-408a-b874-0445c86b69e6"
        name: "Key Vault Secrets User"
        scope: "ResourceGroup"
      - id: "b86a8fe4-44ce-4948-aee5-eccb2c155cd7"
        name: "Key Vault Secrets Officer"
        scope: "ResourceGroup"
    orgRoleTypes:
      - type: DevManager
        azureADGroupId: "5a1d1455-e771-4c19-aa03-fb4a08418f22"
        azureADGroupName: "Platform Engineering Team"
        azureRBACRoles:
          - name: "DevCenter Project Admin"
            id: "331c37c6-af14-46d9-b9f4-e1909e1b95a0"
            scope: ResourceGroup
  • type: Managed identity type (SystemAssigned recommended for simplicity).
  • roleAssignments: Assigns Azure RBAC roles to the Dev Center and organizational groups for secure operations. Includes both resource-level (devCenter) and organization-level (orgRoleTypes) assignments, with explicit scopes for each role.

Catalogs

catalogs:
  - name: "customTasks"
    type: gitHub
    uri: "https://github.com/Evilazaro/DevExp-DevBox.git"
    branch: "main"
    path: "/.configuration/devcenter/tasks"
  • catalogs: List of Git-based repositories containing configuration scripts and templates for Dev Box customization. Use version-controlled repositories for configuration-as-code.

Environment Types

environmentTypes:
  - name: "dev"
    deploymentTargetId: ""
  - name: "staging"
    deploymentTargetId: ""
  - name: "UAT"
    deploymentTargetId: ""
  • environmentTypes: Defines deployment environments (e.g., dev, staging, UAT) for SDLC alignment.

Projects

Each project is a distinct logical unit with its own network, pools, catalogs, access controls, and tags.

Example Project Structure

projects:
  - name: "identityProvider"
    description: "Identity Provider project."
    network:
      name: identityProvider
      create: true
      resourceGroupName: "identityProvider-connectivity-RG"
      virtualNetworkType: Managed
      addressPrefixes:
        - 10.0.0.0/16
      subnets:
        - name: identityProvider-subnet
          properties:
            addressPrefix: 10.0.1.0/24
      tags:
        environment: dev
        division: Platforms
        team: DevExP
        project: DevExP-DevBox
        costCenter: IT
        owner: Contoso
        resources: Network
    identity:
      type: SystemAssigned
      roleAssignments:
        - azureADGroupId: "67a29bc3-f25c-4599-9cb1-4da19507e8ee"
          azureADGroupName: "Identity Provider Engineers"
          azureRBACRoles:
            - name: "Contributor"
              id: "b24988ac-6180-42a0-ab88-20f7382dd24c"
              scope: Project
            - name: "Dev Box User"
              id: "45d50f46-0b78-4001-a660-4198cbe8cd05"
              scope: Project
            - name: "Deployment Environment User"
              id: "18e40d4e-8d2e-438d-97e1-9528336e149c"
              scope: Project
            - name: "Key Vault Secrets User"
              id: "4633458b-17de-408a-b874-0445c86b69e6"
              scope: ResourceGroup
            - id: "b86a8fe4-44ce-4948-aee5-eccb2c155cd7"
              name: "Key Vault Secrets Officer"
              scope: ResourceGroup
    pools:
      - name: "backend-engineer"
        imageDefinitionName: "identityProvider-backend-engineer"
        vmSku: general_i_32c128gb512ssd_v2
      - name: "frontend-engineer"
        imageDefinitionName: "identityProvider-frontend-engineer"
        vmSku: general_i_16c64gb256ssd_v2
    environmentTypes:
      - name: "dev"
        deploymentTargetId: ""
      - name: "staging"
        deploymentTargetId: ""
    catalogs:
      environmentDefinition:
        name: "environments"
        type: gitHub
        uri: "https://github.com/Evilazaro/IdentityProvider.git"
        branch: "main"
        path: "/.configuration/devcenter/environments"
      imageDefinition:
        name: "imageDefinitions"
        type: gitHub
        uri: "https://github.com/Evilazaro/IdentityProvider.git"
        branch: "main"
        path: "/.configuration/devcenter/imageDefinitions"
    tags:
      environment: "dev"
      division: "Platforms"
      team: "DevExP"
      project: "DevExP-DevBox"
      costCenter: "IT"
      owner: "Contoso"
      resources: "Project"

Key Elements:

  • network: Project-level network configuration, including VNet, subnets, and network tags. Use Managed for Azure-managed networking.
  • identity: Project-level identity and RBAC assignments, with explicit scopes for each role.
  • pools: Role-specific Dev Box pools (e.g., backend, frontend) with VM SKU specified for each pool.
  • environmentTypes: Environments available to the project.
  • catalogs: Project-specific catalogs for IaC and image definitions. Note the path differences for each project.
  • tags: Resource tags for governance and cost tracking.

Top-Level Tags

tags:
  environment: "dev"
  division: "Platforms"
  team: "DevExP"
  project: "DevExP-DevBox"
  costCenter: "IT"
  owner: "Contoso"
  resources: "DevCenter"
  • tags: Applied to the Dev Center resource for consistent governance, cost allocation, and ownership tracking.

Best Practices

  • Use Azure AD Groups: Assign permissions via groups, not individuals, for easier management.
  • Leverage Tags: Apply consistent tags for cost tracking, ownership, and resource organization.
  • Keep Catalogs Modular: Separate environment and image definitions for flexibility and reuse.
  • Automate Sync: Enable catalog sync for up-to-date Dev Box provisioning.
  • Align Environments with SDLC: Define dev, staging, and UAT environments to match your release process.
  • Review RBAC Assignments: Grant only necessary permissions to minimize risk, and use explicit scopes.
  • Document Custom Pools: Clearly describe the purpose, configuration, and VM SKU of each Dev Box pool for maintainability.
  • Use the network section: Define project-level network configuration for each project to control connectivity and isolation.

References

Tip: To onboard a new team, add a new entry under projects with its own identity, pools, catalogs, and tags.
Use Case: Isolates access and configurations for different business units or applications.

4 - Azure Development CLI: azd

How to configure the azd deployment tools.

Azure Development CLI Configuration (azure.yaml)

This document describes the structure and configuration options for the azure.yaml file used with the Azure Development CLI (azd). The file enables you to define project metadata, lifecycle hooks, and automation for your Azure development environment.

Schema Reference

# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/refs/heads/main/schemas/v1.0/azure.yaml.json

This line specifies the JSON schema for validation and editor support. It ensures your configuration follows the expected structure for Azure Dev CLI projects.

Project Name

name: ContosoDevExp

Description:
Defines the name of your Azure Dev CLI project.
Example:

name: MyAwesomeProject

Hooks

Hooks allow you to run custom scripts at specific points in the deployment lifecycle. In this example, a preprovision hook is defined.

Preprovision Hook

hooks:
  preprovision:
    shell: sh
    continueOnError: false
    interactive: true
    run: |
      #!/bin/bash
      set -e 
      defaultPlatform="github"
      if [ -z "${SOURCE_CONTROL_PLATFORM}" ]; then
          echo "SOURCE_CONTROL_PLATFORM is not set. Setting it to '${defaultPlatform}' by default."
          export SOURCE_CONTROL_PLATFORM="${SOURCE_CONTROL_PLATFORM:-${defaultPlatform}}"
      else
          echo "Existing SOURCE_CONTROL_PLATFORM is set to '${SOURCE_CONTROL_PLATFORM}'."
      fi      
      ./setup.sh -e ${AZURE_ENV_NAME} -s ${SOURCE_CONTROL_PLATFORM}

Configuration Options

  • shell:
    Specifies the shell to use for running the script.
    Example: sh (for Bash scripts)

  • continueOnError:
    If set to true, the script will continue even if an error occurs.
    Example: false (script stops on error)

  • interactive:
    If true, the script can prompt the user for input.
    Example: true

  • run:
    The actual script to execute.
    Example:

    #!/bin/bash
set -e
# ... your commands ...

Example: Customizing the Preprovision Hook

Suppose you want to use Azure DevOps as your source control platform and run a different setup script:

hooks:
  preprovision:
    shell: sh
    continueOnError: false
    interactive: true
    run: |
      #!/bin/bash
      set -e
      defaultPlatform="adogit"
      if [ -z "${SOURCE_CONTROL_PLATFORM}" ]; then
          export SOURCE_CONTROL_PLATFORM="${SOURCE_CONTROL_PLATFORM:-${defaultPlatform}}"
      fi
      ./custom-setup.sh -e ${AZURE_ENV_NAME} -s ${SOURCE_CONTROL_PLATFORM}

How to Configure

  1. Set the Project Name:
    Change the name field to match your project.

  2. Customize Hooks:

    • Edit the preprovision hook to run any setup commands before provisioning resources.
    • Adjust the shell, error handling, and interactivity as needed.
    • Use environment variables to pass configuration to your scripts.

  3. Use Environment Variables:
    The script checks for SOURCE_CONTROL_PLATFORM and sets a default if not present.
    You can override this by setting the variable before running azd:

    export SOURCE_CONTROL_PLATFORM="adogit"
azd up

  4. Run Setup Scripts:
    The hook runs setup.sh with the environment name and source control platform.
    Ensure your script is executable and located in the project root.

Full Example

# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/refs/heads/main/schemas/v1.0/azure.yaml.json

name: MyAwesomeProject

hooks:
  preprovision:
    shell: sh
    continueOnError: false
    interactive: true
    run: |
      #!/bin/bash
      set -e
      defaultPlatform="github"
      if [ -z "${SOURCE_CONTROL_PLATFORM}" ]; then
          export SOURCE_CONTROL_PLATFORM="${SOURCE_CONTROL_PLATFORM:-${defaultPlatform}}"
      fi
      ./setup.sh -e ${AZURE_ENV_NAME} -s ${SOURCE_CONTROL_PLATFORM}

Additional Resources

This configuration enables automated, repeatable environment setup for Azure development projects using the Azure