🖥️ DevExp-DevBox

title

description

author

date

version

🖥️ DevExp-DevBox

Note

📖 Target Audience: Platform Engineers, DevOps Engineers, Cloud Architects, and IT Administrators ⏱️ Estimated Reading Time: 20-25 minutes

An enterprise-grade Infrastructure-as-Code (IaC) solution built with Azure Bicep for deploying and managing Microsoft Dev Box environments at scale. This accelerator implements Azure Landing Zone principles with a modular architecture that separates concerns across security, monitoring, connectivity, and workload layers—enabling platform engineering teams to provision consistent, secure developer workstations in minutes.

Whether you're setting up a development environment for a small team or deploying Dev Boxes across an enterprise, DevExp-DevBox provides the automation, governance, and flexibility you need. The solution integrates seamlessly with GitHub Actions for CI/CD, uses OIDC federation for passwordless Azure authentication, and supports PowerShell DSC for customizing Dev Box images with role-specific tooling.

🧭 Quick Navigation

⬅️ Previous	📚 Index	➡️ Next
—	Documentation	Architecture

📑 Table of Contents

Section	Description
✨ Features	Key capabilities and highlights
🏗️ Architecture	Landing zone design and service overview
📋 Prerequisites	Required tools and Azure permissions
🚀 Quick Start	Step-by-step deployment guide
📁 Project Structure	Repository directory layout
⚙️ Configuration	YAML settings and customization options
🔄 CI/CD Pipelines	GitHub Actions workflows
📦 Module Reference	Bicep module catalog
🧹 Cleanup	Resource removal options
🤝 Contributing	Development guidelines
📄 License	MIT License information
📚 Additional Resources	Documentation and external links

Tip

Use the links above to jump directly to any section. Each major section includes a "Back to Top" link for easy navigation.

✨ Features

Feature	Description
🏢 Landing Zone Architecture	Implements Azure best practices with segregated resource groups for Security, Monitoring, and Workload layers
📄 Configuration-as-Code	YAML-based configuration with JSON Schema validation for type safety and IDE IntelliSense
🧩 Modular Bicep Design	Reusable, composable modules with clear input/output contracts and typed parameters
🔐 OIDC Authentication	Passwordless GitHub Actions deployment using Azure AD federated credentials
📊 Multi-Project Support	Deploy multiple Dev Box projects with distinct pools, catalogs, and access controls
👥 Role-Based Access Control	Hierarchical RBAC with Managed Identities following least-privilege principles
⚙️ DSC Customization	PowerShell Desired State Configuration (DSC) for Dev Box image customization
🚀 Automated Provisioning	Azure Developer CLI (azd) integration for streamlined setup and deployment
📈 Centralized Monitoring	Log Analytics workspace integration for unified observability
🌐 Network Flexibility	Support for both Microsoft-managed and custom VNet configurations

⬆️ Back to Top

🏗️ Architecture

DevExp-DevBox implements a Landing Zone pattern that organizes Azure resources by function, ensuring proper separation of concerns and alignment with the Azure Well-Architected Framework.

Overview

The solution deploys a centralized Azure DevCenter that serves as the management hub for all developer workstations. Resources are organized into three distinct landing zones:

Security Landing Zone — Houses Azure Key Vault for secrets management and credential storage
Monitoring Landing Zone — Contains Log Analytics workspace for centralized logging and diagnostics
Workload Landing Zone — Deploys DevCenter, projects, pools, and network connectivity

This separation ensures that security-sensitive resources are isolated, monitoring is centralized, and workload components can scale independently. The modular Bicep architecture enables teams to customize configurations through YAML files while maintaining infrastructure consistency across environments.

Tip

📖 For detailed architecture documentation including TOGAF-aligned decision records, see the Architecture Documentation.

High-Level Architecture

---
title: DevExp-DevBox High-Level Architecture
---
flowchart TB
    %% ===== EXTERNAL RESOURCES =====
    subgraph External["🌍 External Resources"]
        GH["📚 GitHub Catalog<br/>DSC Configurations"]
    end

    %% ===== AZURE SUBSCRIPTION =====
    subgraph SUB["☁️ Azure Subscription"]
        %% ===== SECURITY LANDING ZONE =====
        subgraph Security["🔐 Security Landing Zone"]
            KV[("🔑 Key Vault<br/>Secrets & Credentials")]
        end
        
        %% ===== MONITORING LANDING ZONE =====
        subgraph Monitoring["📊 Monitoring Landing Zone"]
            LA[("📈 Log Analytics<br/>Centralized Logging")]
        end
        
        %% ===== WORKLOAD LANDING ZONE =====
        subgraph Workload["📦 Workload Landing Zone"]
            DC["🖥️ DevCenter<br/>Management Hub"]
            
            subgraph Projects["📁 Projects"]
                P1["📋 Project 1"]
                P2["📋 Project 2"]
            end
            
            subgraph Pools["🏊 Dev Box Pools"]
                POOL1["💻 Frontend Pool"]
                POOL2["💻 Backend Pool"]
            end
        end
        
        %% ===== CONNECTIVITY =====
        subgraph Connectivity["🌐 Connectivity"]
            VNET["🔗 Virtual Network"]
            NC["🔌 Network Connection"]
        end
    end
    
    %% ===== CONNECTIONS =====
    DC -->|"manages"| P1 & P2
    P1 & P2 -->|"provisions"| POOL1 & POOL2
    POOL1 & POOL2 -->|"connects via"| NC
    NC -->|"uses"| VNET
    DC -.->|"syncs catalogs"| GH
    DC -.->|"reads secrets"| KV
    KV & DC & VNET -->|"sends diagnostics"| LA

    %% ===== NODE STYLES =====
    classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF
    classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF
    classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000
    classDef external fill:#6B7280,stroke:#4B5563,color:#FFFFFF,stroke-dasharray:5 5
    classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF

    %% ===== APPLY NODE CLASSES =====
    class DC,P1,P2 primary
    class POOL1,POOL2,VNET,NC secondary
    class KV,LA datastore
    class GH external

    %% ===== SUBGRAPH STYLES =====
    style SUB fill:#F3F4F6,stroke:#6B7280,stroke-width:2px
    style Security fill:#FEE2E2,stroke:#F44336,stroke-width:2px
    style Monitoring fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px
    style Workload fill:#ECFDF5,stroke:#10B981,stroke-width:2px
    style Projects fill:#D1FAE5,stroke:#059669,stroke-width:1px
    style Pools fill:#D1FAE5,stroke:#059669,stroke-width:1px
    style Connectivity fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px
    style External fill:#F3F4F6,stroke:#6B7280,stroke-width:2px

Azure Services Deployed

Service	Purpose
Azure DevCenter	Central hub for developer workstation management
Dev Box Projects	Project-level organization with team-specific configurations
Dev Box Pools	VM allocation with role-specific SKUs and images
Azure Key Vault	Secure storage for secrets (e.g., GitHub PAT for catalogs)
Log Analytics	Centralized logging and monitoring for all resources
Virtual Network	Network isolation with managed or custom VNet options

Module Dependency Flow

---
title: Module Dependency Flow
---
flowchart LR
    %% ===== ORCHESTRATION LAYER =====
    subgraph Orchestration["🎯 Orchestration"]
        MAIN["main.bicep<br/>(Subscription Scope)"]
    end
    
    %% ===== LANDING ZONE MODULES =====
    subgraph LandingZones["🏗️ Landing Zone Modules"]
        SEC["security.bicep"]
        MON["logAnalytics.bicep"]
        WL["workload.bicep"]
    end
    
    %% ===== CORE RESOURCES =====
    subgraph CoreResources["⚙️ Core Resources"]
        KV[("keyVault.bicep")]
        LA[("logAnalytics.bicep")]
        DC["devCenter.bicep"]
        VNET["vnet.bicep"]
    end
    
    %% ===== PROJECT RESOURCES =====
    subgraph ProjectResources["📁 Project Resources"]
        PROJ["project.bicep"]
        POOL["projectPool.bicep"]
        PCAT["projectCatalog.bicep"]
    end
    
    %% ===== PRIMARY FLOW CONNECTIONS =====
    MAIN ==>|"deploys"| SEC & MON & WL
    SEC -->|"creates"| KV
    MON -->|"creates"| LA
    WL -->|"creates"| DC & VNET
    DC -->|"creates"| PROJ
    PROJ -->|"creates"| POOL & PCAT
    
    %% ===== DEPENDENCY CONNECTIONS =====
    KV -.->|"provides secrets"| DC
    LA -.->|"receives diagnostics"| DC
    VNET -.->|"provides network"| POOL

    %% ===== NODE STYLES =====
    classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF
    classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF
    classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF
    classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000

    %% ===== APPLY NODE CLASSES =====
    class MAIN trigger
    class SEC,MON,WL primary
    class KV,LA,DC,VNET secondary
    class PROJ,POOL,PCAT datastore

    %% ===== SUBGRAPH STYLES =====
    style Orchestration fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px
    style LandingZones fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px
    style CoreResources fill:#ECFDF5,stroke:#10B981,stroke-width:2px
    style ProjectResources fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px

⬆️ Back to Top

📋 Prerequisites

Important

Ensure you have the following tools installed and properly configured before proceeding with deployment.

Ensure you have the following tools installed before proceeding:

Tool	Version	Purpose	Installation
Azure CLI	2.50+	Azure resource management	Install Azure CLI
Azure Developer CLI (azd)	Latest	Deployment orchestration	Install azd
GitHub CLI	2.0+	Repository and secret management	Install gh
Bicep CLI	0.20+	Template compilation	Included with Azure CLI
PowerShell	7.0+	Script execution	Install PowerShell

Azure Requirements

Important

The following Azure permissions and configurations are required for successful deployment.

✅ An active Azure subscription with Owner or Contributor + User Access Administrator permissions
✅ Azure AD permissions to create App Registrations (for OIDC setup)
✅ Registered resource providers:

# Register required resource providers
az provider register --namespace Microsoft.DevCenter
az provider register --namespace Microsoft.KeyVault
az provider register --namespace Microsoft.Network
az provider register --namespace Microsoft.OperationalInsights

Verify Prerequisites

# Check Azure CLI
az --version

# Check azd
azd version

# Check GitHub CLI
gh --version

# Check PowerShell
pwsh --version

⬆️ Back to Top

🚀 Quick Start

Deploy your Dev Box environment in 4 steps:

1️⃣ Clone the Repository

git clone https://github.com/Evilazaro/DevExp-DevBox.git
cd DevExp-DevBox

2️⃣ Authenticate with Azure and GitHub

# Login to Azure (interactive)
az login

# Set your target subscription
az account set --subscription "<subscription-id>"

# Login to GitHub (required for OIDC credential setup)
gh auth login

3️⃣ Run the Setup Script

The setup script performs the following:

✅ Initializes Azure Developer CLI environment
✅ Creates Azure AD App Registration for OIDC
✅ Configures federated credentials for GitHub Actions
✅ Sets up GitHub repository secrets and variables

Linux/macOS:

chmod +x setUp.sh
./setUp.sh -e <environment-name> -s github

Windows (PowerShell):

.\setUp.ps1 -EnvName <environment-name> -SourceControl github

Note

Parameters:

-e / -EnvName: Environment identifier (e.g., dev, staging, prod)
-s / -SourceControl: Source control platform (github or adogit)

4️⃣ Provision Infrastructure

# Deploy all resources to Azure
azd provision

The deployment takes approximately 15-30 minutes depending on the number of projects and pools configured.

Tip

For automated CI/CD deployments, use the GitHub Actions workflow. See CI/CD Pipelines.

🔧 Troubleshooting Common Issues

Issue	Solution
OIDC Authentication Failed	Verify federated credentials are configured correctly in Azure AD
Resource Provider Not Registered	Run `az provider register --namespace <provider>` for missing providers
Insufficient Permissions	Ensure you have Owner or Contributor + User Access Administrator roles
azd Provision Timeout	Check network connectivity and retry with `azd provision --debug`

⬆️ Back to Top

📁 Project Structure

Click to expand full directory tree

DevExp-DevBox/
├── 📄 azure.yaml                    # azd configuration (Linux/macOS)
├── 📄 azure-pwh.yaml                # azd configuration (Windows PowerShell)
├── 📄 setUp.sh                      # Setup script (Bash)
├── 📄 setUp.ps1                     # Setup script (PowerShell)
├── 📄 cleanSetUp.ps1                # Cleanup script
├── 📄 package.json                  # Hugo documentation dependencies
│
├── 📁 .configuration/               # Runtime configurations
│   ├── 📁 devcenter/workloads/      # DSC configurations for Dev Box images
│   │   ├── common-config.dsc.yaml
│   │   ├── common-backend-config.dsc.yaml
│   │   └── ...
│   ├── 📁 powershell/               # PowerShell utility scripts
│   └── 📁 setup/                    # Setup helper scripts
│       ├── 📁 Azure/                # Azure credential management
│       └── 📁 GitHub/               # GitHub secret management
│
├── 📁 .github/                      # GitHub Actions configuration
│   ├── 📁 actions/ci/               # Reusable composite actions
│   │   ├── bicep-standard-ci/       # Bicep build action
│   │   └── generate-release/        # Semantic versioning action
│   └── 📁 workflows/
│       ├── ci.yml                   # Continuous Integration
│       ├── deploy.yml               # Azure deployment
│       └── release.yml              # Release management
│
├── 📁 docs/                         # TOGAF-aligned documentation
│   ├── 📁 architecture/             # Architecture decision records
│   ├── 📁 devops/                   # CI/CD documentation
│   └── 📁 scripts/                  # Script usage guides
│
├── 📁 infra/                        # Bicep orchestration layer
│   ├── 📄 main.bicep                # Entry point (subscription scope)
│   ├── 📄 main.parameters.json      # Parameter file
│   └── 📁 settings/                 # YAML configuration files
│       ├── 📁 resourceOrganization/ # Landing zone resource groups
│       ├── 📁 security/             # Key Vault settings
│       └── 📁 workload/             # DevCenter configuration
│
└── 📁 src/                          # Reusable Bicep modules
    ├── 📁 connectivity/             # Network resources
    │   ├── connectivity.bicep
    │   ├── vnet.bicep
    │   └── networkConnection.bicep
    ├── 📁 identity/                 # RBAC assignments
    │   ├── devCenterRoleAssignment.bicep
    │   └── projectIdentityRoleAssignment.bicep
    ├── 📁 management/               # Monitoring resources
    │   └── logAnalytics.bicep
    ├── 📁 security/                 # Security resources
    │   ├── keyVault.bicep
    │   ├── secret.bicep
    │   └── security.bicep
    └── 📁 workload/                 # DevCenter resources
        ├── workload.bicep
        ├── 📁 core/                 # DevCenter core modules
        │   ├── devCenter.bicep
        │   ├── catalog.bicep
        │   └── environmentType.bicep
        └── 📁 project/              # Project-level modules
            ├── project.bicep
            ├── projectPool.bicep
            ├── projectCatalog.bicep
            └── projectEnvironmentType.bicep

⬆️ Back to Top

⚙️ Configuration

Note

DevExp-DevBox uses YAML configuration files with JSON Schema validation for a type-safe, IDE-friendly experience. Each configuration file has a corresponding JSON Schema that provides IntelliSense and validation in VS Code.

Configuration Files

File	Purpose	Schema
azureResources.yaml	Resource group naming, tagging, and landing zone organization	azureResources.schema.json
security.yaml	Key Vault configuration and access policies	security.schema.json
devcenter.yaml	DevCenter, projects, pools, catalogs, and RBAC	devcenter.schema.json

Landing Zone Configuration

Configure resource groups in infra/settings/resourceOrganization/azureResources.yaml:

# Workload Resource Group - Dev Center and projects
workload:
  create: true
  name: devexp-workload
  tags:
    environment: dev
    project: Contoso-DevExp-DevBox
    costCenter: IT

# Security Resource Group - Key Vault
security:
  create: true
  name: devexp-security
  tags:
    environment: dev
    landingZone: Security

# Monitoring Resource Group - Log Analytics
monitoring:
  create: true
  name: devexp-monitoring
  tags:
    environment: dev
    landingZone: Monitoring

Example: Adding a New Project

Tip

Edit infra/settings/workload/devcenter.yaml to add a new project. The JSON Schema provides IntelliSense for available options.

Edit infra/settings/workload/devcenter.yaml to add a project:

projects:
  - name: "my-new-project"
    description: "My team's development environment"
    
    # Network configuration
    network:
      name: my-project-vnet
      create: true
      virtualNetworkType: Managed  # Or "Unmanaged" for custom VNets
      addressPrefixes:
        - 10.1.0.0/16
      subnets:
        - name: devbox-subnet
          properties:
            addressPrefix: 10.1.1.0/24
    
    # Identity and access control
    identity:
      type: SystemAssigned
      roleAssignments:
        - azureADGroupId: "<your-aad-group-id>"
          azureADGroupName: "My Team Developers"
          azureRBACRoles:
            - name: "Dev Box User"
              id: "45d50f46-0b78-4001-a660-4198cbe8cd05"
              scope: Project
    
    # Dev Box pools
    pools:
      - name: "standard-pool"
        imageDefinitionName: "my-image-definition"
        vmSku: general_i_16c64gb256ssd_v2
    
    # Environment types available to this project
    environmentTypes:
      - name: "dev"
        deploymentTargetId: ""

VM SKU Options

SKU	vCPUs	RAM	Storage	Use Case
`general_i_8c32gb256ssd_v2`	8	32 GB	256 GB	Light development
`general_i_16c64gb256ssd_v2`	16	64 GB	256 GB	Standard development
`general_i_32c128gb512ssd_v2`	32	128 GB	512 GB	Heavy workloads, builds

DSC Customization

Dev Box images can be customized using PowerShell Desired State Configuration (DSC). Sample configurations are provided in .configuration/devcenter/workloads/:

Configuration	Purpose
`common-config.dsc.yaml`	Base configuration for all Dev Boxes
`common-backend-config.dsc.yaml`	Backend developer tools (Azure CLI, .NET SDK, Docker)
`common-frontend-usertasks-config.dsc.yaml`	Frontend developer tools (Node.js, npm)
`winget-upgrade-packages.dsc.yaml`	Automated package updates

Example: Backend Developer DSC

# .configuration/devcenter/workloads/common-backend-config.dsc.yaml
properties:
  configurationVersion: "0.2.0"
  resources:
    # Azure CLI
    - resource: Microsoft.WinGet.DSC/WinGetPackage
      id: Microsoft.AzureCLI
      settings:
        id: Microsoft.AzureCLI

    # Azure Developer CLI
    - resource: Microsoft.WinGet.DSC/WinGetPackage
      id: Microsoft.Azd
      settings:
        id: Microsoft.Azd

    # Visual Studio Code
    - resource: Microsoft.WinGet.DSC/WinGetPackage
      id: Microsoft.VisualStudioCode
      settings:
        id: Microsoft.VisualStudioCode

⬆️ Back to Top

🔄 CI/CD Pipelines

Note

DevExp-DevBox includes a complete CI/CD pipeline architecture using GitHub Actions with OIDC-based authentication for secure, passwordless Azure deployments. The pipeline follows DevOps best practices with semantic versioning, artifact management, and environment-specific deployment gates.

Pipeline Architecture

---
title: CI/CD Pipeline Architecture
---
flowchart TB
    %% ===== TRIGGERS =====
    subgraph Triggers["🎯 Triggers"]
        direction LR
        T1(["🌿 Push: feature/**"])
        T2(["🔧 Push: fix/**"])
        T3(["📝 PR to main"])
        T4(["🖱️ Manual: Deploy"])
        T5(["🖱️ Manual: Release"])
    end
    
    %% ===== CONTINUOUS INTEGRATION =====
    subgraph CI["🔄 Continuous Integration (ci.yml)"]
        direction TB
        CI1["📊 generate-tag-version<br/>Semantic Version Calculation"]
        CI2["🔨 build<br/>Bicep Compilation & Validation"]
        CI1 -->|"passes version"| CI2
    end
    
    %% ===== DEPLOYMENT =====
    subgraph Deploy["🚀 Deployment (deploy.yml)"]
        direction TB
        D1["✅ Validate Variables<br/>Check Required Secrets"]
        D2["🔨 Build Bicep<br/>Compile Templates"]
        D3["🔐 OIDC Auth<br/>Federated Credentials"]
        D4["☁️ azd provision<br/>Deploy to Azure"]
        D1 -->|"validates"| D2
        D2 -->|"authenticates"| D3
        D3 -->|"deploys"| D4
    end
    
    %% ===== RELEASE =====
    subgraph Release["🏷️ Release (release.yml)"]
        direction TB
        R1["📊 generate-release<br/>Tag & Changelog"]
        R2["🔨 build<br/>Final Artifacts"]
        R3[/"🎉 publish-release<br/>GitHub Release"/]
        R1 -->|"generates"| R2
        R2 -->|"publishes"| R3
    end
    
    %% ===== WORKFLOW CONNECTIONS =====
    T1 & T2 & T3 -->|"triggers"| CI
    T4 -->|"triggers"| Deploy
    T5 -->|"triggers"| Release

    %% ===== NODE STYLES =====
    classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF
    classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF
    classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF
    classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000

    %% ===== APPLY NODE CLASSES =====
    class T1,T2,T3,T4,T5 trigger
    class CI1,CI2 primary
    class D1,D2,D3,D4 secondary
    class R1,R2,R3 datastore

    %% ===== SUBGRAPH STYLES =====
    style Triggers fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px
    style CI fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px
    style Deploy fill:#ECFDF5,stroke:#10B981,stroke-width:2px
    style Release fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px

Workflows Overview

Workflow	File	Trigger	Purpose
Continuous Integration	`.github/workflows/ci.yml`	Push to `feature/`, `fix/`; PRs to `main`	Build and validate Bicep templates
Deploy to Azure	`.github/workflows/deploy.yml`	Manual dispatch	Provision infrastructure to Azure
Release	`.github/workflows/release.yml`	Manual dispatch	Generate semantic versions and GitHub releases

Required GitHub Configuration

Repository Variables

Variable	Description	Example
`AZURE_CLIENT_ID`	App Registration client ID	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
`AZURE_TENANT_ID`	Azure AD tenant ID	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
`AZURE_SUBSCRIPTION_ID`	Target subscription ID	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
`AZURE_LOCATION`	Default Azure region	`eastus2`

Repository Secrets

Secret	Description
`KEY_VAULT_SECRET`	GitHub Personal Access Token for private catalog access

Deploying via GitHub Actions

Important

Ensure all required repository variables and secrets are configured before triggering a deployment.

Navigate to Actions → Deploy to Azure
Click Run workflow
Configure deployment parameters:
- AZURE_ENV_NAME: Environment name (e.g., dev, staging, prod)
- AZURE_LOCATION: Azure region (e.g., eastus2, westus2)
Click Run workflow

Setting Up OIDC Authentication

The setup scripts automatically configure OIDC, but you can also set it up manually:

# Create App Registration and federated credentials
.\.configuration\setup\powershell\Azure\generateDeploymentCredentials.ps1

Tip

For comprehensive CI/CD pipeline documentation including reusable actions, versioning strategy, and best practices, see the DevOps Documentation.

⬆️ Back to Top

📦 Module Reference

Click to expand module catalog

Core Modules

Module	Path	Description
`main.bicep`	`infra/main.bicep`	Orchestration entry point (subscription scope)

Security Layer

Module	Path	Description
`security.bicep`	`src/security/security.bicep`	Security landing zone orchestrator
`keyVault.bicep`	`src/security/keyVault.bicep`	Azure Key Vault with RBAC
`secret.bicep`	`src/security/secret.bicep`	Key Vault secret management

Management Layer

Module	Path	Description
`logAnalytics.bicep`	`src/management/logAnalytics.bicep`	Log Analytics workspace

Connectivity Layer

Module	Path	Description
`connectivity.bicep`	`src/connectivity/connectivity.bicep`	Connectivity orchestrator
`vnet.bicep`	`src/connectivity/vnet.bicep`	Virtual network with subnets
`networkConnection.bicep`	`src/connectivity/networkConnection.bicep`	DevCenter network connection
`resourceGroup.bicep`	`src/connectivity/resourceGroup.bicep`	Connectivity resource group

Workload Layer

Module	Path	Description
`workload.bicep`	`src/workload/workload.bicep`	Workload orchestrator
`devCenter.bicep`	`src/workload/core/devCenter.bicep`	DevCenter resource
`catalog.bicep`	`src/workload/core/catalog.bicep`	DevCenter catalog
`environmentType.bicep`	`src/workload/core/environmentType.bicep`	Environment type definition
`project.bicep`	`src/workload/project/project.bicep`	DevCenter project
`projectPool.bicep`	`src/workload/project/projectPool.bicep`	Dev Box pool
`projectCatalog.bicep`	`src/workload/project/projectCatalog.bicep`	Project-level catalog
`projectEnvironmentType.bicep`	`src/workload/project/projectEnvironmentType.bicep`	Project environment type

Identity Layer

Module	Path	Description
`devCenterRoleAssignment.bicep`	`src/identity/devCenterRoleAssignment.bicep`	DevCenter RBAC
`projectIdentityRoleAssignment.bicep`	`src/identity/projectIdentityRoleAssignment.bicep`	Project RBAC
`keyVaultAccess.bicep`	`src/identity/keyVaultAccess.bicep`	Key Vault access policies
`orgRoleAssignment.bicep`	`src/identity/orgRoleAssignment.bicep`	Organization-level RBAC

⬆️ Back to Top

🧹 Cleanup

Warning

The cleanup operations below will permanently delete Azure resources and associated data. Ensure you have backed up any important configurations before proceeding.

Remove all deployed resources when no longer needed.

Option 1: Azure Developer CLI (Recommended)

# Remove all resources and purge Key Vault
azd down --purge --force

Option 2: Cleanup Script (Full Cleanup)

The cleanup script performs a comprehensive teardown:

.\cleanSetUp.ps1 -EnvName <environment-name> -Location <azure-region>

What the cleanup script removes:

Resource Type	Action
Subscription Deployments	Deletes all ARM deployments
Role Assignments	Removes user and managed identity RBAC
Service Principals	Deletes OIDC app registrations
GitHub Secrets	Removes Azure credential secrets
Resource Groups	Deletes Security, Monitoring, Workload, and Connectivity RGs

Option 3: Manual Cleanup

# List resource groups
az group list --query "[?starts_with(name, 'devexp-')].name" -o tsv

# Delete specific resource groups
az group delete --name devexp-workload-<env>-<region>-RG --yes --no-wait
az group delete --name devexp-security-<env>-<region>-RG --yes --no-wait
az group delete --name devexp-monitoring-<env>-<region>-RG --yes --no-wait

Caution

Key Vault soft-delete is enabled by default. Use --purge flag or manually purge deleted vaults to fully remove secrets. Soft-deleted Key Vaults consume quota and may block re-deployment with the same name.

⬆️ Back to Top

🤝 Contributing

Note

Contributions are welcome! We follow a standard GitHub workflow with conventional commits.

How to Contribute

Fork the repository
Create a feature branch:
```
git checkout -b feature/amazing-feature
```
Make your changes following the guidelines below
Test locally:
```
az bicep build --file infra/main.bicep
```

Commit your changes:

git commit -m 'feat: add amazing feature'

Push to the branch:
```
git push origin feature/amazing-feature
```
Open a Pull Request to main

Development Guidelines

Area	Guideline
Bicep	Follow Bicep best practices
Parameters	Include `@description()` decorators for all parameters
Resources	Add appropriate tags to all resources
Naming	Use consistent naming conventions (camelCase for variables, kebab-case for resources)
Documentation	Update README and architecture docs for configuration changes
Testing	Validate Bicep files compile before submitting PRs

Commit Message Convention

We use Conventional Commits:

feat: add new Dev Box pool configuration
fix: correct Key Vault access policy
docs: update README with DSC examples
refactor: simplify network module

⬆️ Back to Top

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

📚 Additional Resources

Documentation

Resource	Description
Architecture Documentation	TOGAF-aligned architecture decision records
DevOps Documentation	Comprehensive CI/CD pipeline documentation
Script Documentation	Setup and configuration script guides

External References

Resource	Link
Microsoft Dev Box	Documentation
Azure DevCenter	Documentation
Azure Bicep	Documentation
Azure Landing Zones	Cloud Adoption Framework
Azure Developer CLI	Documentation

Support

🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions

⬆️ Back to Top

📚 Related Documents

Document	Description
Business Architecture	Business context and drivers
Data Architecture	Data models and flows
Application Architecture	Application components and interactions
Technology Architecture	Technology stack and infrastructure
Security Architecture	Security controls and compliance
Deployment Architecture	Deployment patterns and strategies
DevOps Documentation	CI/CD and operational guides
Scripts Documentation	Setup and configuration scripts

🧭 Navigation

⬆️ Back to Top · 📚 Documentation · 🏗️ Architecture · 🔧 DevOps

Built with ❤️ by the Evilazaro Alves

Name		Name	Last commit message	Last commit date
Latest commit History 2,410 Commits
.configuration		.configuration
.github		.github
docs		docs
infra		infra
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
azure-pwh.yaml		azure-pwh.yaml
azure.yaml		azure.yaml
cleanSetUp.ps1		cleanSetUp.ps1
package.json		package.json
setUp.ps1		setUp.ps1
setUp.sh		setUp.sh

License

Evilazaro/DevExp-DevBox

Folders and files

Latest commit

History

Repository files navigation

🖥️ DevExp-DevBox

📑 Table of Contents

✨ Features

🏗️ Architecture

Overview

High-Level Architecture

Azure Services Deployed

Module Dependency Flow

📋 Prerequisites

Azure Requirements

Verify Prerequisites

🚀 Quick Start

1️⃣ Clone the Repository

2️⃣ Authenticate with Azure and GitHub

3️⃣ Run the Setup Script

4️⃣ Provision Infrastructure

📁 Project Structure

⚙️ Configuration

Configuration Files

Landing Zone Configuration

Example: Adding a New Project

VM SKU Options

DSC Customization

Example: Backend Developer DSC

🔄 CI/CD Pipelines

Pipeline Architecture

Workflows Overview

Required GitHub Configuration

Repository Variables

Repository Secrets

Deploying via GitHub Actions

Setting Up OIDC Authentication

📦 Module Reference

Core Modules

Security Layer

Management Layer

Connectivity Layer

Workload Layer

Identity Layer

🧹 Cleanup

Option 1: Azure Developer CLI (Recommended)

Option 2: Cleanup Script (Full Cleanup)

Option 3: Manual Cleanup

🤝 Contributing

How to Contribute

Development Guidelines

Commit Message Convention

📄 License

📚 Additional Resources

Documentation

External References

Support

📚 Related Documents

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 19

Packages 0

Uh oh!

Languages

Packages