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

2: Security

3: Dev Center

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.

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:
Contains the primary Dev Box workload resources including Dev Center resources, Dev Box definitions, Dev Box pools, and project resources.

Best Practice:
Separate application workloads from infrastructure components to enable independent scaling, access control, and lifecycle management.

YAML Representation:

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 including Key Vaults for secret management, Microsoft Defender for Cloud configurations, Network Security Groups, and private endpoints.

Best Practice:
Isolate security resources to apply stricter access controls and enable separate monitoring/auditing of security components.

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:
Contains monitoring and observability resources including Log Analytics workspaces, Application Insights components, Azure Monitor alerts and action groups, and dashboard/reporting resources.

Best Practice:
Centralize monitoring resources to provide a unified view of operational health and simplify diagnostic activities.

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.

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) to enable independent scaling, access control, and lifecycle management.
Workload Group:
Separate application workloads from infrastructure components for flexibility and easier management.
Security Group:
Isolate security resources to apply 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 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.

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 - 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: "devexp-devcenter"
location: "eastus2"

name: Globally unique identifier for the Dev Center resource (update to match your YAML).
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. The roleAssignments section includes both devCenter (for resource-level roles) and orgRoleTypes (for organization-level roles such as DevManager).

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 network, pools, catalogs, access controls, and tags.

Example Project Structures

projects:
  - name: "identityProvider"
    description: "Identity Provider project."

    network:
      name: identityProvider
      create: true
      resourceGroupName: "identityProvider-connectivity-RG"
      virtualNetworkType: Unmanaged  
      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: "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"

  - name: "eShop"
    description: "eShop project."

    network:
      name: eShop
      create: true
      resourceGroupName: "eShop-connectivity-RG"
      virtualNetworkType: Unmanaged  
      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: "19d12c65-509f-491d-bb38-49297e1c56a0"
          azureADGroupName: "eShop 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"
            - name: "Key Vault Secrets User"
              id: "4633458b-17de-408a-b874-0445c86b69e6"

    pools:
      - name: "backend-engineer"
        imageDefinitionName: "eShop-backend-engineer"
      - name: "frontend-engineer"
        imageDefinitionName: "eShop-frontend-engineer"

    environmentTypes:
      - name: "dev"
        deploymentTargetId: ""
      - name: "staging"
        deploymentTargetId: ""

    catalogs:
      environmentDefinition:
        name: "environments"
        type: "gitHub"
        uri: "https://github.com/Evilazaro/eShop.git"
        branch: "main"
        path: ".devcenter/environments"
      imageDefinition:
        name: "imageDefinitions"
        type: "gitHub"
        uri: "https://github.com/Evilazaro/eShop.git"
        branch: "main"
        path: ".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.
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. 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.

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.
Use the network section: Define project-level network configuration for each project to control connectivity and isolation.

References:

Accelerator Configration

1 - Resource Groups

Overview

Table of Contents

Configurations

Workload Resource Group

Security Resource Group

Monitoring Resource Group

Examples and Use Cases

Example: Deploying Dev Box Resources

Best Practices

2 - Security

Overview

Table of Contents

Configurations

Resource Creation

Key Vault Configuration

Security Settings

Resource Organization (Tags)

Examples and Use Cases

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

Example 2: Reusing an Existing Key Vault

Best Practices

3 - Dev Center

Overview

Configurations

Dev Center Metadata

Global Settings

Identity and Access Control

Catalogs

Environment Types

Projects

Example Project Structures

Top-Level Tags

Examples and Use Cases

Example 1: Adding a New Project

Example 2: Customizing Dev Box Pools

Example 3: Integrating with GitHub Catalogs

Best Practices