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. Below is a breakdown of each section, its keys, and their purposes.

Workload Resource Group

Purpose:
Holds primary Dev Box workload resources (Dev Center, Dev Box definitions, pools, and project resources).

YAML Representation:

workload:
  create: true
  name: devexp-workload
  description: prodExp
  tags:
    environment: dev
    division: Platforms
    team: DevExP
    project: Contoso-DevExp-DevBox
    costCenter: IT
    owner: Contoso
    landingZone: Workload
    resources: ResourceGroup

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:
Isolates security-related resources (Key Vaults, Defender for Cloud, NSGs, private endpoints).

YAML Representation:

security:
  create: true
  name: devexp-security
  description: prodExp
  tags:
    environment: dev
    division: Platforms
    team: DevExP
    project: Contoso-DevExp-DevBox
    costCenter: IT
    owner: Contoso
    landingZone: Workload
    resources: ResourceGroup

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

Monitoring Resource Group

Purpose:
Centralizes monitoring and observability resources (Log Analytics, Application Insights, Azure Monitor).

YAML Representation:

monitoring:
  create: true
  name: devexp-monitoring
  description: prodExp
  tags:
    environment: dev
    division: Platforms
    team: DevExP
    project: Contoso-DevExp-DevBox
    costCenter: IT
    owner: Contoso
    landingZone: Workload
    resources: ResourceGroup

Key Explanations:
Enables unified operational health monitoring and diagnostics.

Connectivity Resource Group

Purpose:
Contains networking and connectivity resources (VNets, NSGs, peerings, DNS zones, Azure Bastion).

YAML Representation:

connectivity:
  create: true
  name: devexp-connectivity
  description: prodExp
  tags:
    environment: dev
    division: Platforms
    team: DevExP
    project: Contoso-DevExp-DevBox
    costCenter: IT
    owner: Contoso
    landingZone: Workload
    resources: ResourceGroup

Key Explanations:
Segregates network infrastructure for specialized management and security.

Examples and Use Cases

Example: Deploying Dev Box Resources

Suppose you want to deploy a new Dev Box environment for the “Contoso-DevExp-DevBox” project in a development environment:

  • Workload group will host Dev Box definitions and pools.
  • Security group will contain Key Vaults for secrets used by Dev Box VMs.
  • Monitoring group will centralize logs and metrics for all Dev Box resources.
  • Connectivity group will manage VNets and NSGs for secure access.

Sample Usage in a Deployment Pipeline:

# Pseudocode for pipeline step
- task: AzureResourceManagerTemplateDeployment
  inputs:
    resourceGroupName: $(workload.name)
    templateLocation: 'Linked artifact'
    csmFile: 'devboxTemplate.json'
    deploymentMode: 'Incremental'

This ensures resources are deployed into the correct, pre-defined groups.

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, connectivity) to enable independent scaling, access control, and lifecycle management.

  • 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 Microsoft Dev Box Accelerator enables rapid, modular, and secure provisioning of development environments in Azure. The security.yaml file specifically 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.

3 - Network and Connectivity

How to configure the Azure Virtual Network, Subnets and Virtual Network type for Dev Center

Overview

This document provides a comprehensive analysis of the newtork.yaml configuration file, a core component of the Microsoft Dev Box Accelerator. This YAML file defines the virtual network (VNet) infrastructure for Dev Box environments, enabling secure, isolated, and scalable connectivity for development resources in Azure. The modular and decoupled design of this configuration allows organizations to tailor network settings to their specific needs, ensuring best practices for security, governance, and operational efficiency.

Table of Contents

Configurations

Below, each section and key of the YAML file is explained in detail, with the corresponding YAML representation.

Create Flag

create: true
  • Purpose: Determines whether to create a new VNet (true) or use an existing one (false).
  • Best Practice: Use true to ensure a dedicated, isolated network for each environment.

Virtual Network Type

virtualNetworkType: Managed
  • Options:
    • Managed: Azure manages the network configuration (recommended for dev/test).
    • Unmanaged: Customer manages the network (required for hybrid or production scenarios).
  • Best Practice: Use Managed for simplicity and security in dev/test; use Unmanaged for advanced scenarios.

Virtual Network Name

name: contoso-vnet
  • Purpose: Unique identifier for the VNet resource.
  • Naming Convention: [company]-[purpose]-[env]-vnet (e.g., contoso-dev-dev-vnet).

Address Prefixes

addressPrefixes:
  - 10.0.0.0/16
  • Purpose: Defines the IP address range for the VNet using CIDR notation.
  • Best Practices:
    • Use private ranges (e.g., 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16).
    • Avoid overlaps with on-premises or other Azure VNets.
    • Allocate enough space for current and future needs.

Subnets

subnets:
  - name: contoso-subnet
    properties:
      addressPrefix: 10.0.1.0/24
  • Purpose: Defines network segments within the VNet.
  • Best Practices:
    • Create separate subnets for different workloads or security zones.
    • Apply Network Security Groups (NSGs) at the subnet level.
    • Size subnets appropriately (e.g., /24 provides 251 usable IPs).

Tags

tags:
  environment: dev
  division: Platforms
  team: DevExP
  project: DevExP-DevBox
  costCenter: IT
  owner: Contoso
  resources: Network
  • Purpose: Metadata for resource organization, governance, and cost management.
  • Common Tags:
    • environment: Deployment environment (dev, test, staging, prod).
    • division: Organizational division responsible.
    • team: Team responsible for the resource.
    • project: Associated project.
    • costCenter: For charge-back/accounting.
    • owner: Individual or team owner.
    • resources: Resource type or purpose.
  • Best Practices:
    • Apply consistent tags across all resources.
    • Automate tagging where possible.

Examples and Use Cases

Example 1: Isolated Dev Environment

A development team needs a secure, isolated network for testing new features. They set create: true and use a dedicated address space and subnet:

create: true
virtualNetworkType: Managed
name: contoso-dev-dev-vnet
addressPrefixes:
  - 10.1.0.0/16
subnets:
  - name: dev-subnet
    properties:
      addressPrefix: 10.1.1.0/24
tags:
  environment: dev
  team: DevTeamA
  project: FeatureX
  costCenter: RnD
  owner: Alice
  resources: Network

Example 2: Hybrid Production Scenario

For production, the organization uses virtualNetworkType: Unmanaged to connect with on-premises resources and applies stricter subnetting and tagging.

Best Practices

  • Avoid IP Overlaps: Always check that your address space does not overlap with existing Azure or on-premises networks.
  • Subnet Sizing: Plan for future growth; resizing subnets later can be complex.
  • Tag Consistently: Use automation to enforce tagging policies for governance and cost tracking.
  • Security: Apply NSGs and consider Azure Firewall for enhanced security.
  • Documentation: Keep your YAML files under version control and document changes for auditing and troubleshooting.
  • Reference Azure Best Practices: Regularly review Azure VNet best practices for updates.

4 - Dev Center

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

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 file 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.

Configurations

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

Dev Center Metadata

name: "contoso-devcenter"
location: "eastus2"
  • name: Globally unique identifier for the Dev Center resource.
  • location: Azure region for deployment; select a region close to your team for performance.

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"
      - id: "18d7d88d-d35e-4fb5-a5c3-7773c20a72d9"
        name: "User Access Administrator"
    
    orgRoleTypes:
      - type: DevManager
        azureADGroupId: "8dae87fa-87b2-460b-b972-a4239fbd4a96"
        azureADGroupName: "Dev Manager"
        azureRBACRoles:
          - name: "DevCenter Project Admin"
            id: "331c37c6-af14-46d9-b9f4-e1909e1b95a0"
  • type: Managed identity type (SystemAssigned recommended for simplicity).
  • roleAssignments: Assigns Azure RBAC roles to the Dev Center and organizational groups for secure operations.

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.

Environment Types

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

Projects

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

Example Project Structure

projects:
  - name: "identityProvider"
    description: "Identity Provider project."
    
    identity:
      type: SystemAssigned
      roleAssignments:
        - azureADGroupId: "331f48d7-4a23-4ec4-b03a-4af29c9c6f34"
          azureADGroupName: "identityProvider Developers"
          azureRBACRoles:
            - name: "Contributor"
              id: "b24988ac-6180-42a0-ab88-20f7382dd24c"
            - name: "Dev Box User"
              id: "45d50f46-0b78-4001-a660-4198cbe8cd05"
            - name: "Deployment Environment User"
              id: "18e40d4e-8d2e-438d-97e1-9528336e149c"
    
    pools:
      - name: "backend-engineer"
        imageDefinitionName: "identityProvider-backend-engineer"
      - name: "frontend-engineer"
        imageDefinitionName: "identityProvider-frontend-engineer"
    
    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:

  • identity: Project-level identity and RBAC assignments.
  • pools: Role-specific Dev Box pools (e.g., backend, frontend).
  • environmentTypes: Environments available to the project.
  • catalogs: Project-specific catalogs for IaC and image definitions.
  • 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.

Examples and Use Cases

Example 1: Adding a New Project

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.

Example 2: Customizing Dev Box Pools

Define pools for different engineering roles (e.g., backend, frontend) with tailored image definitions.
Use Case: Ensures developers get the right tools and environments for their responsibilities.

Example 3: Integrating with GitHub Catalogs

Point catalogs to your organization’s GitHub repositories for configuration-as-code.
Use Case: Enables version-controlled, automated updates to Dev Box configurations and environments.

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 prod environments to match your release process.
  • Review RBAC Assignments: Grant only necessary permissions to minimize risk.
  • Document Custom Pools: Clearly describe the purpose and configuration of each Dev Box pool for maintainability.

References: