From 9de6ed6b07f328fa9ec6e95a1c36b07d0e79b61d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 14:08:41 -0500 Subject: [PATCH 01/49] Remove outdated documentation files: RELEASE_STRATEGY.md and SECURITY.md --- CODE_OF_CONDUCT.md | 128 --- CONTRIBUTING.md | 1 - README.md | 1822 ------------------------------------------- RELEASE_STRATEGY.md | 242 ------ SECURITY.md | 2 - 5 files changed, 2195 deletions(-) delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 README.md delete mode 100644 RELEASE_STRATEGY.md delete mode 100644 SECURITY.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index 637fa493..00000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,128 +0,0 @@ -# Contributor Covenant Code of Conduct - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in our -community a harassment-free experience for everyone, regardless of age, body -size, visible or invisible disability, ethnicity, sex characteristics, gender -identity and expression, level of experience, education, socio-economic status, -nationality, personal appearance, race, religion, or sexual identity -and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, -diverse, inclusive, and healthy community. - -## Our Standards - -Examples of behavior that contributes to a positive environment for our -community include: - -* Demonstrating empathy and kindness toward other people -* Being respectful of differing opinions, viewpoints, and experiences -* Giving and gracefully accepting constructive feedback -* Accepting responsibility and apologizing to those affected by our mistakes, - and learning from the experience -* Focusing on what is best not just for us as individuals, but for the - overall community - -Examples of unacceptable behavior include: - -* The use of sexualized language or imagery, and sexual attention or - advances of any kind -* Trolling, insulting or derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or email - address, without their explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Enforcement Responsibilities - -Community leaders are responsible for clarifying and enforcing our standards of -acceptable behavior and will take appropriate and fair corrective action in -response to any behavior that they deem inappropriate, threatening, offensive, -or harmful. - -Community leaders have the right and responsibility to remove, edit, or reject -comments, commits, code, wiki edits, issues, and other contributions that are -not aligned to this Code of Conduct, and will communicate reasons for moderation -decisions when appropriate. - -## Scope - -This Code of Conduct applies within all community spaces, and also applies when -an individual is officially representing the community in public spaces. -Examples of representing our community include using an official e-mail address, -posting via an official social media account, or acting as an appointed -representative at an online or offline event. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported to the community leaders responsible for enforcement at -evalvesd@microsoft.com. -All complaints will be reviewed and investigated promptly and fairly. - -All community leaders are obligated to respect the privacy and security of the -reporter of any incident. - -## Enforcement Guidelines - -Community leaders will follow these Community Impact Guidelines in determining -the consequences for any action they deem in violation of this Code of Conduct: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behavior deemed -unprofessional or unwelcome in the community. - -**Consequence**: A private, written warning from community leaders, providing -clarity around the nature of the violation and an explanation of why the -behavior was inappropriate. A public apology may be requested. - -### 2. Warning - -**Community Impact**: A violation through a single incident or series -of actions. - -**Consequence**: A warning with consequences for continued behavior. No -interaction with the people involved, including unsolicited interaction with -those enforcing the Code of Conduct, for a specified period of time. This -includes avoiding interactions in community spaces as well as external channels -like social media. Violating these terms may lead to a temporary or -permanent ban. - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including -sustained inappropriate behavior. - -**Consequence**: A temporary ban from any sort of interaction or public -communication with the community for a specified period of time. No public or -private interaction with the people involved, including unsolicited interaction -with those enforcing the Code of Conduct, is allowed during this period. -Violating these terms may lead to a permanent ban. - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community -standards, including sustained inappropriate behavior, harassment of an -individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within -the community. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], -version 2.0, available at -https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. - -Community Impact Guidelines were inspired by [Mozilla's code of conduct -enforcement ladder](https://github.com/mozilla/diversity). - -[homepage]: https://www.contributor-covenant.org - -For answers to common questions about this code of conduct, see the FAQ at -https://www.contributor-covenant.org/faq. Translations are available at -https://www.contributor-covenant.org/translations. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index eb1ae458..00000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1 +0,0 @@ -... diff --git a/README.md b/README.md deleted file mode 100644 index 5317b2ac..00000000 --- a/README.md +++ /dev/null @@ -1,1822 +0,0 @@ ---- -title: Dev Box Landing Zone Accelerator -description: - Enterprise-ready Infrastructure as Code (IaC) solution for deploying Microsoft - Dev Box environments following Azure Cloud Adoption Framework best practices. -author: DevExp Team -date: 2024-01-01 -version: 1.0.0 -tags: [azure, devbox, devcenter, bicep, infrastructure-as-code, landing-zone] ---- - -# πŸš€ Dev Box Landing Zone Accelerator - -[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) -[![Azure](https://img.shields.io/badge/Azure-DevCenter-0078D4?logo=microsoft-azure)](https://azure.microsoft.com/services/dev-box/) -[![Bicep](https://img.shields.io/badge/IaC-Bicep-blue)](https://learn.microsoft.com/azure/azure-resource-manager/bicep/) - -> [!NOTE] **Target Audience:** Platform Engineers, Cloud Architects, and DevOps -> Teams
**Reading Time:** ~25 minutes - -
-πŸ“ Navigation - -| Previous | Index | Next | -| :------- | :--------: | --------------------------------------: | -| β€” | **README** | [Release Strategy](RELEASE_STRATEGY.md) | - -
- ---- - -## πŸ“– Overview - -Organizations adopting Microsoft Dev Box face significant challenges in -establishing secure, scalable, and compliant cloud development environments. -Traditional approaches often result in fragmented deployments, inconsistent -security configurations, and lengthy setup times that hinder developer -productivity. Development teams need standardized, pre-configured environments -that align with enterprise governance policies while maintaining flexibility for -different project requirements. - -The Dev Box Landing Zone Accelerator addresses these challenges by providing an -enterprise-ready, Infrastructure as Code (IaC) solution that automates the -deployment of Microsoft Dev Box environments following Azure Cloud Adoption -Framework best practices. This accelerator eliminates the complexity of manual -configuration, ensures consistent security postures across all development -environments, and significantly reduces the time-to-productivity for development -teams. - -Built on Azure Bicep and integrated with Azure Developer CLI (azd), this -solution provides a repeatable, testable deployment pattern that scales from -individual projects to enterprise-wide implementations. It incorporates identity -management, network isolation, monitoring, and security controls out-of-the-box, -enabling organizations to focus on building applications rather than managing -infrastructure. - -> [!TIP] This accelerator is built on **Azure Bicep** and integrated with -> **Azure Developer CLI (azd)**, providing a repeatable, testable deployment -> pattern that scales from individual projects to enterprise-wide -> implementations. - ---- - -
-πŸ“‘ Table of Contents - -- [πŸ“– Overview](#-overview) -- [πŸ—οΈ Architecture Overview](#️-architecture-overview) - - [🏒 Business Architecture](#-business-architecture) - - [πŸ’Ύ Data Architecture](#-data-architecture) - - [πŸ“ Application Architecture](#-application-architecture) - - [☁️ Technology Architecture](#️-technology-architecture) -- [✨ Key Features and Benefits](#-key-features-and-benefits) -- [πŸ“‹ Prerequisites](#-prerequisites) -- [πŸ” Azure RBAC Roles](#-azure-rbac-roles) -- [πŸš€ Deployment Instructions](#-deployment-instructions) -- [βš™οΈ Configuration Reference](#️-configuration-reference) -- [πŸ“¦ Release Strategy](#-release-strategy) -- [πŸ”§ Troubleshooting](#-troubleshooting) -- [🧹 Cleanup](#-cleanup) -- [🀝 Contributing](#-contributing) -- [πŸ”’ Security](#-security) -- [πŸ“„ License](#-license) -- [πŸ’¬ Support](#-support) -- [πŸ“š Additional Resources](#-additional-resources) -- [πŸ“Ž Related Documents](#-related-documents) - -
- ---- - -## πŸ—οΈ Architecture Overview - -The Dev Box Landing Zone Accelerator implements a layered architecture aligned -with TOGAF principles, organizing resources into four distinct landing zones: -Security, Monitoring, Connectivity, and Workload. This design ensures separation -of concerns, independent scaling, and adherence to enterprise governance -requirements. - -### 🏒 Business Architecture - -#### Purpose - -The business architecture layer defines the organizational capabilities, value -streams, and business processes required to establish and operate -enterprise-scale cloud development environments. It aligns technical -implementation with business objectives including developer productivity, -security compliance, cost optimization, and operational efficiency. - -#### 🎯 Key Capabilities - -- **Developer Environment Provisioning**: Automated creation and lifecycle - management of standardized development environments -- **Security and Compliance Management**: Enforcement of enterprise security - policies, role-based access control, and regulatory compliance -- **Resource Governance**: Centralized control of resource allocation, cost - management, and policy enforcement -- **Identity and Access Management**: Integration with Azure Active Directory - for authentication and authorization -- **Monitoring and Observability**: Centralized logging, metrics collection, and - operational insights -- **Catalog Management**: Version-controlled environment definitions and image - repositories - -#### πŸ”„ High-Level Process - -1. **Environment Request**: Developers or administrators initiate environment - provisioning -2. **Authentication**: Identity verification through Azure AD integration -3. **Authorization**: RBAC policy evaluation and permission validation -4. **Resource Allocation**: DevCenter assigns resources based on project - configuration -5. **Network Configuration**: Connectivity establishment (managed or unmanaged - VNet) -6. **Security Policy Application**: Key Vault integration and secret management -7. **Monitoring Integration**: Log Analytics and diagnostic settings - configuration -8. **Environment Delivery**: Developer access to provisioned Dev Box - -#### πŸ—ΊοΈ Business Capability Map - -```mermaid ---- -title: Business Capability Map ---- -flowchart TB - %% ===== DEVELOPER ENVIRONMENT MANAGEMENT ===== - subgraph DevEnv["Developer Environment Management"] - DE1["Environment Provisioning"] - DE2["Catalog Management"] - DE3["Image Definition Management"] - DE4["Pool Management"] - end - - %% ===== SECURITY & COMPLIANCE ===== - subgraph SecComp["Security & Compliance"] - SC1["Identity Management"] - SC2["Secret Management"] - SC3["Network Isolation"] - SC4["RBAC Enforcement"] - end - - %% ===== RESOURCE GOVERNANCE ===== - subgraph ResGov["Resource Governance"] - RG1["Resource Group Management"] - RG2["Policy Enforcement"] - RG3["Cost Management"] - RG4["Tag Management"] - end - - %% ===== MONITORING & OBSERVABILITY ===== - subgraph MonObs["Monitoring & Observability"] - MO1["Centralized Logging"] - MO2["Metrics Collection"] - MO3["Diagnostic Settings"] - MO4["Activity Tracking"] - end - - %% ===== CROSS-CAPABILITY DEPENDENCIES ===== - DevEnv -->|requires| SecComp - DevEnv -->|governed by| ResGov - DevEnv -->|observed by| MonObs - SecComp -->|audited by| MonObs - ResGov -->|monitored by| MonObs - - %% ===== CLASS DEFINITIONS ===== - 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 - - %% ===== NODE STYLING ===== - class DE1,DE2,DE3,DE4 primary - class SC1,SC2,SC3,SC4 secondary - class RG1,RG2,RG3,RG4 datastore - class MO1,MO2,MO3,MO4 external - - %% ===== SUBGRAPH STYLING ===== - style DevEnv fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px - style SecComp fill:#ECFDF5,stroke:#10B981,stroke-width:2px - style ResGov fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px - style MonObs fill:#F3F4F6,stroke:#6B7280,stroke-width:2px -``` - -#### πŸ“Š Value Stream Map - -```mermaid ---- -title: Value Stream Map ---- -flowchart LR - %% ===== VALUE STREAM STAGES ===== - A["Developer Request"] -->|initiates| B["Identity Verification"] - B -->|validates| C["Authorization Check"] - C -->|approves| D["Resource Allocation"] - D -->|configures| E["Network Configuration"] - E -->|applies| F["Security Policy Application"] - F -->|integrates| G["Monitoring Integration"] - G -->|completes| H["Environment Ready"] - H -->|grants| I["Developer Access"] - - %% ===== CLASS DEFINITIONS ===== - 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 - classDef external fill:#6B7280,stroke:#4B5563,color:#FFFFFF,stroke-dasharray:5 5 - classDef matrix fill:#D1FAE5,stroke:#10B981,color:#000000 - - %% ===== NODE STYLING ===== - class A trigger - class B,C primary - class D,E secondary - class F,G datastore - class H matrix - class I external -``` - -### πŸ’Ύ Data Architecture - -#### Purpose - -The data architecture layer defines how configuration data, secrets, monitoring -data, and operational metadata flow through the system. It ensures data -security, integrity, and accessibility while maintaining compliance with -enterprise data governance policies. - -#### 🎯 Key Capabilities - -- **Configuration Management**: YAML-based declarative configuration for all - infrastructure resources -- **Secret Management**: Secure storage and retrieval of sensitive data via - Azure Key Vault -- **Operational Data Collection**: Centralized logging and metrics via Log - Analytics Workspace -- **Diagnostic Data**: Resource-level diagnostic settings for all Azure services -- **Environment State Management**: Azure Developer CLI environment - configuration and state tracking - -#### πŸ”„ High-Level Process - -1. **Configuration Ingestion**: YAML files define resource configurations -2. **Secret Storage**: Personal Access Tokens (PAT) stored securely in Key Vault -3. **Bicep Compilation**: Declarative templates compiled to ARM templates -4. **Resource Provisioning**: ARM templates deployed to Azure subscriptions -5. **Diagnostic Configuration**: Log Analytics workspace linked to all resources -6. **Metadata Tracking**: Resource tags and configuration metadata maintained - -#### πŸ“Š Master Data Management - -```mermaid ---- -title: Master Data Management ---- -flowchart LR - %% ===== DATA SOURCES ===== - subgraph Sources["Data Sources"] - S1["YAML Configuration Files"] - S2["Environment Variables"] - S3["Source Control Tokens"] - S4["Azure Subscription Data"] - end - - %% ===== INGESTION LAYER ===== - subgraph Ingestion["Ingestion Layer"] - I1["Setup Scripts"] - I2["Azure CLI"] - I3["AZD CLI"] - end - - %% ===== PROCESSING LAYER ===== - subgraph Processing["Processing Layer"] - P1["Bicep Compilation"] - P2["Parameter Validation"] - P3["Secret Encryption"] - P4["Resource Naming"] - end - - %% ===== STORAGE LAYER ===== - subgraph Storage["Storage Layer"] - ST1[("Key Vault Secrets")] - ST2[("Log Analytics Workspace")] - ST3[("Resource Metadata")] - ST4[("Environment State")] - end - - %% ===== GOVERNANCE LAYER ===== - subgraph Governance["Governance Layer"] - G1["RBAC Policies"] - G2["Diagnostic Settings"] - G3["Access Policies"] - G4["Tag Policies"] - end - - %% ===== SOURCE TO INGESTION ===== - S1 -->|reads| I1 - S2 -->|loads| I2 - S3 -->|authenticates| I3 - S4 -->|queries| I2 - - %% ===== INGESTION TO PROCESSING ===== - I1 -->|compiles| P1 - I2 -->|validates| P2 - I3 -->|encrypts| P3 - I2 -->|names| P4 - - %% ===== PROCESSING TO STORAGE ===== - P1 -->|stores| ST3 - P2 -->|stores| ST3 - P3 -->|stores| ST1 - P4 -->|stores| ST4 - - %% ===== STORAGE TO GOVERNANCE ===== - ST1 -->|enforces| G3 - ST2 -->|configures| G2 - ST3 -->|applies| G1 - ST4 -->|tags| G4 - - %% ===== CLASS DEFINITIONS ===== - classDef input fill:#F3F4F6,stroke:#6B7280,color:#000000 - 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 - - %% ===== NODE STYLING ===== - class S1,S2,S3,S4 input - class I1,I2,I3 primary - class P1,P2,P3,P4 secondary - class ST1,ST2,ST3,ST4 datastore - class G1,G2,G3,G4 external - - %% ===== SUBGRAPH STYLING ===== - style Sources fill:#F3F4F6,stroke:#6B7280,stroke-width:2px - style Ingestion fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px - style Processing fill:#ECFDF5,stroke:#10B981,stroke-width:2px - style Storage fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px - style Governance fill:#F9FAFB,stroke:#6B7280,stroke-width:2px -``` - -### πŸ“ Application Architecture - -#### Purpose - -The application architecture layer defines the logical organization of -infrastructure components, their relationships, and deployment patterns. It -implements a modular, reusable design that supports enterprise-scale deployments -while maintaining separation of concerns through landing zone isolation. - -#### 🎯 Key Capabilities - -- **Modular Component Design**: Reusable Bicep modules for each landing zone and - resource type -- **Identity-Based Security**: System-assigned managed identities for - service-to-service authentication -- **Catalog Integration**: GitHub and Azure DevOps repository integration for - environment definitions -- **Network Abstraction**: Support for both Microsoft-hosted (managed) and - customer-managed (unmanaged) virtual networks -- **Project Isolation**: Independent project configurations with dedicated - resource groups and RBAC -- **Diagnostic Integration**: Automated Log Analytics workspace linkage for all - resources - -#### πŸ”„ High-Level Process - -1. **Landing Zone Creation**: Resource groups provisioned for Security, - Monitoring, Connectivity, and Workload -2. **Security Provisioning**: Key Vault deployed with secrets and access - policies -3. **Monitoring Provisioning**: Log Analytics Workspace and diagnostic settings - configured -4. **DevCenter Provisioning**: Core DevCenter resource with catalogs and - environment types -5. **Project Provisioning**: Multiple projects with pools, environment types, - and network connections -6. **RBAC Configuration**: Role assignments at subscription, resource group, and - resource scopes -7. **Catalog Synchronization**: Git repositories synced for environment and - image definitions - -#### πŸ›οΈ Solution Architecture - -```mermaid ---- -title: Solution Architecture ---- -flowchart TB - %% ===== CLIENT LAYER ===== - subgraph Clients["Client Layer"] - C1["Azure Portal"] - C2["Azure CLI"] - C3["Azure Developer CLI"] - C4["PowerShell/Bash Scripts"] - end - - %% ===== MANAGEMENT LAYER ===== - subgraph Gateway["Management Layer"] - G1["Azure Resource Manager"] - end - - %% ===== SERVICE LAYER ===== - subgraph Services["Service Layer"] - SV1["DevCenter Core"] - SV2["DevCenter Projects"] - SV3["DevCenter Catalogs"] - SV4["Environment Types"] - SV5["DevBox Pools"] - end - - %% ===== SECURITY LAYER ===== - subgraph Security["Security Layer"] - SE1[("Key Vault")] - SE2["Managed Identities"] - SE3["RBAC Assignments"] - end - - %% ===== MONITORING LAYER ===== - subgraph Monitoring["Monitoring Layer"] - M1[("Log Analytics Workspace")] - M2["Diagnostic Settings"] - M3["Azure Monitor"] - end - - %% ===== CONNECTIVITY LAYER ===== - subgraph Connectivity["Connectivity Layer"] - CN1["Virtual Network"] - CN2["Network Connection"] - CN3["Subnets"] - end - - %% ===== CLIENT TO GATEWAY ===== - C1 -->|requests| G1 - C2 -->|invokes| G1 - C3 -->|deploys| G1 - C4 -->|executes| G1 - - %% ===== GATEWAY TO SERVICES ===== - G1 ==>|manages| SV1 - - %% ===== SERVICE RELATIONSHIPS ===== - SV1 -->|creates| SV2 - SV1 -->|configures| SV3 - SV1 -->|defines| SV4 - SV2 -->|provisions| SV5 - - %% ===== SERVICE TO SECURITY ===== - SV1 -.->|authenticates via| SE2 - SV2 -.->|uses| SE2 - SV3 -->|retrieves secrets| SE1 - SE2 -->|enforces| SE3 - - %% ===== SERVICE TO MONITORING ===== - SV1 -.->|logs| M2 - SV2 -.->|logs| M2 - M2 -->|streams to| M1 - M1 -->|visualizes in| M3 - - %% ===== POOLS TO CONNECTIVITY ===== - SV5 -->|connects via| CN2 - CN2 -->|uses| CN1 - CN1 -->|contains| CN3 - - %% ===== CLASS DEFINITIONS ===== - 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 - classDef external fill:#6B7280,stroke:#4B5563,color:#FFFFFF,stroke-dasharray:5 5 - classDef input fill:#F3F4F6,stroke:#6B7280,color:#000000 - - %% ===== NODE STYLING ===== - class C1,C2,C3,C4 trigger - class G1 primary - class SV1,SV2,SV3,SV4,SV5 secondary - class SE1,M1 datastore - class SE2,SE3,M2,M3 external - class CN1,CN2,CN3 input - - %% ===== SUBGRAPH STYLING ===== - style Clients fill:#E0E7FF,stroke:#818CF8,stroke-width:2px - style Gateway fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px - style Services fill:#ECFDF5,stroke:#10B981,stroke-width:2px - style Security fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px - style Monitoring fill:#F9FAFB,stroke:#6B7280,stroke-width:2px - style Connectivity fill:#F3F4F6,stroke:#6B7280,stroke-width:2px -``` - -### ☁️ Technology Architecture - -#### Purpose - -The technology architecture layer defines the specific Azure services, -deployment tools, integration patterns, and automation workflows used to -implement the solution. It ensures the use of cloud-native services, -infrastructure as code best practices, and platform engineering principles. - -#### 🎯 Key Capabilities - -- **Infrastructure as Code**: Azure Bicep for declarative infrastructure - provisioning -- **Deployment Automation**: Azure Developer CLI (azd) for repeatable - deployments -- **Source Control Integration**: GitHub and Azure DevOps for catalog and - environment definition management -- **Monitoring Integration**: Azure Monitor and Log Analytics for operational - insights -- **Identity Integration**: Azure Active Directory for authentication and - authorization -- **Secret Management**: Azure Key Vault with RBAC authorization model -- **Network Services**: Azure Virtual Network with managed or unmanaged - connectivity options - -#### πŸ”„ High-Level Process - -1. **Tool Validation**: Setup scripts verify Azure CLI, azd CLI, and source - control tools -2. **Authentication**: Azure and source control platform authentication - established -3. **Environment Initialization**: azd environment created with configuration - files -4. **Secret Storage**: PATs stored in Key Vault with encryption -5. **Resource Provisioning**: Bicep templates deployed via azd provision -6. **Diagnostic Configuration**: Log Analytics workspace linked to all resources -7. **RBAC Application**: Role assignments created at appropriate scopes -8. **Catalog Synchronization**: Git repositories synchronized for definitions - -#### ☁️ Cloud-Native Architecture - -```mermaid ---- -title: Cloud-Native Architecture ---- -flowchart LR - %% ===== CLIENT INTERFACES ===== - subgraph Clients["Client Interfaces"] - CL1["Azure Portal"] - CL2["Azure CLI"] - CL3["PowerShell/Bash"] - CL4["Azure Developer CLI"] - end - - %% ===== API GATEWAY ===== - subgraph Gateway["API Gateway"] - GW1["Azure Resource Manager"] - end - - %% ===== AZURE SERVICES ===== - subgraph Services["Azure Services"] - SR1["Microsoft DevCenter"] - SR2["DevCenter Projects"] - SR3[("Azure Key Vault")] - SR4["Virtual Network"] - end - - %% ===== EVENT INTEGRATION ===== - subgraph EventBus["Event Integration"] - EB1["Diagnostic Settings"] - end - - %% ===== DATA & STORAGE ===== - subgraph DataStorage["Data & Storage"] - DS1[("Log Analytics Workspace")] - DS2[("Key Vault Secrets")] - end - - %% ===== OBSERVABILITY & SECURITY ===== - subgraph Observability["Observability & Security"] - OB1["Azure Monitor"] - OB2["RBAC Policies"] - OB3["Managed Identities"] - end - - %% ===== CLIENT TO GATEWAY ===== - CL1 -->|requests| GW1 - CL2 -->|invokes| GW1 - CL3 -->|executes| GW1 - CL4 -->|deploys| GW1 - - %% ===== GATEWAY TO SERVICES ===== - GW1 ==>|manages| SR1 - GW1 -->|provisions| SR2 - GW1 -->|configures| SR3 - GW1 -->|creates| SR4 - - %% ===== SERVICES TO EVENT BUS ===== - SR1 -.->|emits events| EB1 - SR2 -.->|logs| EB1 - SR3 -.->|audits| EB1 - - %% ===== EVENT BUS TO STORAGE ===== - EB1 -->|streams| DS1 - SR3 -->|stores secrets| DS2 - - %% ===== STORAGE TO OBSERVABILITY ===== - DS1 -->|monitors| OB1 - SR1 -.->|authenticates via| OB3 - SR2 -.->|uses| OB3 - OB3 -->|enforces| OB2 - - %% ===== CLASS DEFINITIONS ===== - 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 - classDef external fill:#6B7280,stroke:#4B5563,color:#FFFFFF,stroke-dasharray:5 5 - classDef matrix fill:#D1FAE5,stroke:#10B981,color:#000000 - - %% ===== NODE STYLING ===== - class CL1,CL2,CL3,CL4 trigger - class GW1 primary - class SR1,SR2,SR4 secondary - class SR3,DS1,DS2 datastore - class EB1 matrix - class OB1,OB2,OB3 external - - %% ===== SUBGRAPH STYLING ===== - style Clients fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px - style Gateway fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px - style Services fill:#ECFDF5,stroke:#10B981,stroke-width:2px - style EventBus fill:#D1FAE5,stroke:#10B981,stroke-width:2px - style DataStorage fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px - style Observability fill:#F3F4F6,stroke:#6B7280,stroke-width:2px -``` - -#### πŸ”§ Platform Engineering Architecture - -```mermaid ---- -title: Platform Engineering Architecture ---- -flowchart TB - %% ===== EXTERNAL TRIGGERS ===== - subgraph Triggers["Platform Triggers"] - TR1["Infrastructure Deploy"] - TR2["Policy Changes"] - TR3["Security Updates"] - TR4["Template Updates"] - end - - %% ===== PLATFORM LAYER ===== - subgraph Platform["Platform Layer"] - PL1["Azure Developer CLI"] - PL2["Bicep Templates"] - PL3["Parameter Files"] - end - - %% ===== COMPUTE LAYER ===== - subgraph Compute["Compute Layer"] - CO1["Microsoft DevCenter"] - CO2["DevCenter Projects"] - CO3["Dev Box Definitions"] - CO4["Dev Box Pools"] - end - - %% ===== NETWORK LAYER ===== - subgraph Network["Network Layer"] - NW1["Virtual Networks"] - NW2["Network Connections"] - NW3["NSG Rules"] - end - - %% ===== DATA & SECRETS ===== - subgraph DataSecrets["Data & Secrets"] - DS1[("Azure Key Vault")] - DS2[("Log Analytics")] - end - - %% ===== IDENTITY LAYER ===== - subgraph Identity["Identity Layer"] - ID1["Managed Identity"] - ID2["RBAC Assignments"] - ID3["Entra ID Groups"] - end - - %% ===== GOVERNANCE LAYER ===== - subgraph Governance["Governance Layer"] - GV1["Catalogs"] - GV2["Environment Types"] - GV3["Pool Schedules"] - end - - %% ===== TRIGGER TO PLATFORM ===== - TR1 -->|initiates| PL1 - TR2 -.->|configures| PL2 - TR3 -.->|updates| PL2 - TR4 -.->|modifies| PL3 - - %% ===== PLATFORM TO COMPUTE ===== - PL1 ==>|deploys| CO1 - PL2 -->|defines| CO1 - PL3 -->|configures| CO1 - CO1 ==>|creates| CO2 - CO2 -->|provisions| CO3 - CO3 -->|populates| CO4 - - %% ===== COMPUTE TO NETWORK ===== - CO1 -->|connects to| NW1 - CO4 -.->|uses| NW2 - NW1 -->|secured by| NW3 - - %% ===== DATA INTEGRATION ===== - CO1 -.->|logs to| DS2 - CO1 -->|retrieves secrets| DS1 - CO2 -.->|logs to| DS2 - - %% ===== IDENTITY INTEGRATION ===== - CO1 -->|authenticates via| ID1 - CO2 -->|authorized by| ID2 - ID2 -->|syncs with| ID3 - - %% ===== GOVERNANCE INTEGRATION ===== - CO1 -->|uses| GV1 - CO2 -->|inherits| GV2 - CO4 -->|follows| GV3 - - %% ===== CLASS DEFINITIONS ===== - 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 - classDef external fill:#6B7280,stroke:#4B5563,color:#FFFFFF,stroke-dasharray:5 5 - classDef input fill:#F3F4F6,stroke:#6B7280,color:#000000 - classDef matrix fill:#D1FAE5,stroke:#10B981,color:#000000 - - %% ===== NODE STYLING ===== - class TR1,TR2,TR3,TR4 trigger - class PL1,PL2,PL3 primary - class CO1,CO2,CO3,CO4 secondary - class NW1,NW2,NW3 input - class DS1,DS2 datastore - class ID1,ID2,ID3 external - class GV1,GV2,GV3 matrix - - %% ===== SUBGRAPH STYLING ===== - style Triggers fill:#E0E7FF,stroke:#818CF8,stroke-width:2px - style Platform fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px - style Compute fill:#ECFDF5,stroke:#10B981,stroke-width:2px - style Network fill:#F3F4F6,stroke:#6B7280,stroke-width:2px - style DataSecrets fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px - style Identity fill:#F9FAFB,stroke:#6B7280,stroke-width:2px - style Governance fill:#D1FAE5,stroke:#10B981,stroke-width:2px -``` - ---- - -## ✨ Key Features and Benefits - -### 🏒 Enterprise-Scale Deployment - -- **Multi-Project Support**: Deploy multiple DevCenter projects with independent - configurations and resource isolation -- **Landing Zone Organization**: Separate resource groups for Security, - Monitoring, Connectivity, and Workload components -- **Hierarchical Resource Naming**: Consistent naming conventions using - environment name and location identifiers -- **Tag-Based Governance**: Automated tagging for cost allocation, compliance - tracking, and resource organization - -### πŸ” Security and Compliance - -- **Managed Identity Integration**: System-assigned identities for secure - service-to-service authentication without credential management -- **Azure Key Vault Integration**: Centralized secret management with purge - protection and soft delete enabled -- **Role-Based Access Control**: Fine-grained permission management at - subscription, resource group, and resource levels -- **Network Isolation**: Support for both Azure AD-joined (managed) and - customer-managed (unmanaged) virtual network scenarios -- **Diagnostic Settings**: Automated configuration for security audit logging - and compliance reporting - -### πŸ“Š Operational Excellence - -- **Centralized Logging**: Log Analytics Workspace integration for all DevCenter - and project resources -- **Diagnostic Settings Automation**: Automated configuration of diagnostic data - collection for all resources -- **Azure Monitor Integration**: Built-in monitoring and alerting capabilities - for operational insights -- **Purge Protection**: Soft delete and purge protection for Key Vault to - prevent accidental data loss - -### πŸ‘¨β€πŸ’» Developer Productivity - -- **Automated Environment Provisioning**: One-command deployment of complete - development environments -- **Catalog Integration**: Support for GitHub and Azure DevOps repository - catalogs with private and public visibility -- **Image Definition Management**: Centralized management of DevBox images with - versioning support -- **Environment Templates**: Reusable environment definitions for consistent, - repeatable deployments -- **Multi-Platform Tooling**: Support for Windows (PowerShell) and Linux/macOS - (Bash) deployment scripts - -### πŸ“œ Infrastructure as Code - -- **Declarative Configuration**: YAML-based configuration for all infrastructure - resources -- **Modular Design**: Reusable Bicep modules for each component with clear - separation of concerns -- **Parameter Validation**: Built-in validation for deployment parameters to - prevent misconfigurations -- **Idempotent Deployments**: Safe to run multiple times without unintended side - effects -- **Type-Safe Templates**: Bicep type definitions ensure configuration - correctness at compile time - ---- - -## πŸ“‹ Prerequisites - -> [!IMPORTANT] Ensure all prerequisites are met before proceeding with -> deployment to avoid configuration issues. - -### πŸ› οΈ Required Tools - -| Tool | Minimum Version | Purpose | Installation Link | -| ------------------- | ------------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | -| Azure CLI | 2.50.0+ | Azure resource management and authentication | [Install Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) | -| Azure Developer CLI | 1.5.0+ | Deployment automation and environment management | [Install Azure Developer CLI](https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd) | -| PowerShell | 5.1+ (Windows) | Setup script execution on Windows | Built-in on Windows | -| Bash | 4.0+ (Linux/macOS) | Setup script execution on Linux/macOS | Built-in on Linux/macOS | -| GitHub CLI | 2.0+ (optional) | GitHub authentication and integration | [Install GitHub CLI](https://cli.github.com/) | -| Git | 2.30.0+ | Version control and repository operations | [Install Git](https://git-scm.com/downloads) | - -### ☁️ Azure Subscription Requirements - -- Active Azure subscription with permissions to create resources -- Sufficient quota for Microsoft DevCenter resources in target region -- No existing DevCenter resources with conflicting names in target subscription -- Service principal creation permissions (if using CI/CD) - -### 🌐 Network Requirements - -- Virtual network address space available (if using unmanaged networking mode) -- Subnet delegation permissions (if using customer-managed virtual networks) -- Firewall rules configured for outbound connectivity to Azure services -- DNS resolution configured for Azure AD authentication - -### πŸ“‚ Source Control Requirements - -#### GitHub - -- GitHub account with repository access -- Personal Access Token (PAT) with `repo` scope for private repositories -- GitHub CLI authenticated (if using interactive setup) - -#### Azure DevOps - -- Azure DevOps organization and project access -- Personal Access Token (PAT) with `Code (Read)` permissions -- Azure DevOps CLI extension configured with defaults - ---- - -## πŸ” Azure RBAC Roles - -The following Azure built-in roles are required or assigned by this solution: - -| Role Name | Description | Scope | Documentation Link | -| -------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -| **Contributor** | Full access to manage all resources but cannot grant access to others. Required for deployment. | Subscription | [Contributor](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#contributor) | -| **User Access Administrator** | Manage user access to Azure resources including role assignments. Required for RBAC configuration. | Subscription | [User Access Administrator](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#user-access-administrator) | -| **Managed Identity Contributor** | Create, read, update, and delete managed identities. Assigned to service principals. | Subscription | [Managed Identity Contributor](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#managed-identity-contributor) | -| **Key Vault Secrets User** | Read secret contents from Azure Key Vault. Assigned to DevCenter managed identities. | Resource Group | [Key Vault Secrets User](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#key-vault-secrets-user) | -| **DevCenter Dev Box User** | Provides access to create and manage Dev Boxes within projects. Assigned to developer groups. | Project | [DevCenter Dev Box User](https://learn.microsoft.com/azure/dev-box/how-to-dev-box-user) | -| **DevCenter Project Admin** | Provides full access to manage DevCenter projects including pools and environment types. | Project | [DevCenter Project Admin](https://learn.microsoft.com/azure/dev-box/how-to-project-admin) | -| **Network Contributor** | Manage networks including virtual networks, subnets, and network connections. | Resource Group | [Network Contributor](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#network-contributor) | -| **Owner** | Full access to all resources and can grant access. Assigned to DevCenter identity for resource management. | Resource Group | [Owner](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#owner) | - -### 🎯 Role Assignment Strategy - -The solution implements role assignments at multiple scopes following the -principle of least privilege: - -1. **Subscription Level**: - - Service principal roles for deployment automation - - DevCenter managed identity roles for cross-resource-group operations - -2. **Resource Group Level**: - - Project managed identity roles for resource creation within security - resource group - - DevCenter managed identity roles for Key Vault access - -3. **Project Level**: - - User and Azure AD group roles for developer access to Dev Boxes - - Administrator roles for project management and configuration - -4. **Resource Level**: - - Specific resource permissions via RBAC (Key Vault, Log Analytics) - - Diagnostic settings permissions for monitoring integration - ---- - -## πŸš€ Deployment Instructions - -> [!TIP] For best results, follow each step in order and verify successful -> completion before proceeding to the next step. - -### πŸ“Œ Step 1: Clone the Repository - -```bash -git clone https://github.com/Evilazaro/DevExp-DevBox.git -cd DevExp-DevBox -``` - -### πŸ”‘ Step 2: Configure Source Control Platform - -The solution supports two source control platforms for catalog integration. -Choose one based on your organization's requirements. - -#### πŸ™ Option A: GitHub - -1. **Authenticate GitHub CLI** (if using interactive setup): - - ```bash - gh auth login - ``` - -2. **Create Personal Access Token**: - - Navigate to GitHub Settings β†’ Developer settings β†’ Personal access tokens β†’ - Tokens (classic) - - Click "Generate new token (classic)" - - Select `repo` scope (Full control of private repositories) - - Set appropriate expiration date - - Click "Generate token" and copy the token securely - -#### πŸ”΅ Option B: Azure DevOps - -1. **Create Personal Access Token**: - - Navigate to Azure DevOps β†’ User settings β†’ Personal access tokens - - Click "New Token" - - Set name and expiration - - Select `Code (Read)` scope - - Click "Create" and copy the token securely - -2. **Configure Azure DevOps CLI** (if using interactive setup): - ```bash - az devops configure --defaults organization=https://dev.azure.com/YOUR_ORG project=YOUR_PROJECT - ``` - -### ▢️ Step 3: Run the Setup Script - -#### πŸ’» Windows (PowerShell) - -```powershell -# Basic deployment with GitHub -.\setUp.ps1 -EnvName "prod" -SourceControl "github" - -# Basic deployment with Azure DevOps -.\setUp.ps1 -EnvName "prod" -SourceControl "adogit" - -# Interactive mode (prompts for source control selection) -.\setUp.ps1 -EnvName "prod" - -# Show help -.\setUp.ps1 -Help -``` - -#### 🐧 Linux/macOS (Bash) - -```bash -# Make script executable -chmod +x setUp.sh - -# Basic deployment with GitHub -./setUp.sh -e "prod" -s "github" - -# Basic deployment with Azure DevOps -./setUp.sh -e "prod" -s "adogit" - -# Interactive mode (prompts for source control selection) -./setUp.sh -e "prod" - -# Show help -./setUp.sh -h -``` - -**πŸ“‹ Script Parameters:** - -| Parameter | Aliases | Required | Description | Valid Values | -| ------------------------------ | ------- | -------- | ----------------------------- | ------------------------------------ | -| EnvName / env-name | -e | Yes | Name of the Azure environment | Any alphanumeric string (2-10 chars) | -| SourceControl / source-control | -s | No\* | Source control platform | `github`, `adogit` | -| Help / help | -h | No | Display help message | N/A | - -\*If not provided, the script will prompt for selection interactively. - -> [!NOTE] The setup script performs multiple validations and configurations -> automatically. Review the actions below to understand what happens during -> execution. - -**βš™οΈ Setup Script Actions:** - -1. Validates required tools (az, azd, gh/Azure DevOps CLI) -2. Verifies Azure and source control authentication -3. Prompts for Personal Access Token (PAT) securely -4. Initializes Azure Developer CLI environment -5. Stores PAT securely in Key Vault -6. Configures environment variables in `.azure/{ENV_NAME}/.env` -7. Provisions Azure resources using Bicep templates -8. Configures role assignments and diagnostic settings - -### βš™οΈ Step 4: Configure Environment Settings - -The solution uses YAML configuration files located in `settings/`. Customize -these files before deployment to match your organizational requirements. - -#### 🏠 Resource Organization Configuration - -**File**: `settings/resourceOrganization/azureResources.yaml` - -This file defines the landing zone resource groups and their properties. - -```yaml -security: - name: 'security' - create: true - tags: - component: 'security' - environment: 'production' - -monitoring: - name: 'monitoring' - create: true - tags: - component: 'monitoring' - environment: 'production' - -workload: - name: 'workload' - create: true - tags: - component: 'workload' - environment: 'production' -``` - -**βš™οΈ Configuration Options:** - -- `name`: Base name for the resource group (will be suffixed with environment - and location) -- `create`: Boolean flag to create new resource group or use existing -- `tags`: Custom tags for cost allocation and governance - -#### πŸ” Security Configuration - -**File**: `settings/security/security.yaml` - -This file configures Azure Key Vault settings and secret management. - -```yaml -create: true -keyVault: - name: 'keyvault' - enablePurgeProtection: true - enableSoftDelete: true - softDeleteRetentionInDays: 90 - enableRbacAuthorization: true - secretName: 'GitHubPAT' -``` - -**βš™οΈ Configuration Options:** - -- `create`: Boolean flag to create new Key Vault or use existing -- `enablePurgeProtection`: Prevents permanent deletion during retention period -- `enableSoftDelete`: Enables soft delete with retention period -- `softDeleteRetentionInDays`: Number of days to retain soft-deleted items - (7-90) -- `enableRbacAuthorization`: Use Azure RBAC instead of access policies -- `secretName`: Name of the secret to store the PAT - -#### 🏭 DevCenter Configuration - -**File**: `settings/workload/devcenter.yaml` - -This file configures the DevCenter, catalogs, projects, pools, and network -settings. - -```yaml -name: 'devcenter' -identity: - type: 'SystemAssigned' - roleAssignments: - devCenter: - - id: '8e3af657-a8ff-443c-a75c-2fe8c4bcb635' - name: 'Owner' - scope: 'ResourceGroup' - orgRoleTypes: - - type: 'Group' - azureADGroupId: 'YOUR_AZURE_AD_GROUP_OBJECT_ID' - azureADGroupName: 'DevBox Administrators' - azureRBACRoles: - - id: '8e3af657-a8ff-443c-a75c-2fe8c4bcb635' - name: 'Owner' - -catalogItemSyncEnableStatus: 'Enabled' -microsoftHostedNetworkEnableStatus: 'Enabled' -installAzureMonitorAgentEnableStatus: 'Enabled' - -catalogs: - - name: 'catalog-github' - type: 'gitHub' - visibility: 'private' - uri: 'https://github.com/YOUR_ORG/YOUR_REPO' - branch: 'main' - path: '/environments' - -environmentTypes: - - name: 'dev' - - name: 'test' - - name: 'prod' - -projects: - - name: 'project-dev' - description: 'Development Project' - identity: - type: 'SystemAssigned' - roleAssignments: - - azureADGroupId: 'YOUR_AZURE_AD_GROUP_OBJECT_ID' - azureADGroupName: 'Developers' - azureRBACRoles: - - id: '45d50f46-0b78-4001-a660-4198cbe8cd05' - name: 'DevCenter Dev Box User' - scope: 'Project' - catalogs: - - name: 'catalog-github' - type: 'imageDefinition' - sourceControl: 'gitHub' - visibility: 'private' - uri: 'https://github.com/YOUR_ORG/YOUR_REPO' - branch: 'main' - path: '/images' - environmentTypes: - - name: 'dev' - deploymentTargetId: '/subscriptions/YOUR_SUBSCRIPTION_ID' - pools: - - name: 'pool-dev' - imageDefinitionName: 'windows-11-enterprise' - vmSku: 'general_i_8c32gb256ssd_v2' - network: - name: 'vnet-devcenter' - virtualNetworkType: 'Managed' - microsoftHostedNetworkEnableStatus: 'Enabled' - create: false - resourceGroupName: 'connectivity-ENV_NAME-LOCATION-RG' - addressPrefixes: - - '10.0.0.0/16' - subnets: - - name: 'subnet-devbox' - addressPrefix: '10.0.0.0/24' - tags: - component: 'connectivity' -``` - -**πŸ“ Key Configuration Sections:** - -1. **DevCenter Identity**: Configures system-assigned managed identity and role - assignments -2. **Catalogs**: Defines Git repositories for environment and image definitions -3. **Environment Types**: Lists available environment types (dev, test, prod) -4. **Projects**: Configures individual projects with identity, catalogs, pools, - and networking -5. **Network**: Defines network configuration (Managed or Unmanaged) - -### πŸ”§ Step 5: Provision Resources - -The setup script automatically provisions resources, but you can manually -trigger provisioning: - -```bash -# Provision all resources -azd provision -e prod - -# Deploy only (assumes infrastructure exists) -azd deploy -e prod - -# Full deployment (provision + deploy) -azd up -e prod -``` - -**πŸ”„ Provisioning Process:** - -1. **Validation Phase**: - - Validates Bicep templates - - Checks parameter values - - Verifies subscription access - -2. **Security Landing Zone**: - - Creates security resource group - - Deploys Azure Key Vault - - Stores PAT as secret - - Configures access policies - -3. **Monitoring Landing Zone**: - - Creates monitoring resource group - - Deploys Log Analytics Workspace - - Configures workspace solutions - -4. **Workload Landing Zone**: - - Creates workload resource group - - Deploys DevCenter core - - Configures catalogs - - Creates environment types - -5. **Project Provisioning**: - - Creates DevCenter projects - - Configures project catalogs - - Creates environment types - - Deploys DevBox pools - -6. **Connectivity Landing Zone** (if unmanaged networking): - - Creates connectivity resource group - - Deploys virtual network - - Creates subnets - - Configures network connections - -7. **RBAC Configuration**: - - Assigns managed identity roles - - Configures Azure AD group roles - - Applies Key Vault access policies - -8. **Diagnostic Settings**: - - Links all resources to Log Analytics - - Enables AllLogs category - - Enables AllMetrics - -### βœ… Step 6: Verify Deployment - -#### πŸ“ Verify Resource Groups - -```bash -# List all resource groups with tags -az group list --query "[?tags.component].{Name:name, Component:tags.component, Location:location}" -o table -``` - -**πŸ“Š Expected Output:** - -``` -Name Component Location -security-prod-eastus2-RG security eastus2 -monitoring-prod-eastus2-RG monitoring eastus2 -workload-prod-eastus2-RG workload eastus2 -connectivity-prod-eastus2-RG connectivity eastus2 -``` - -#### 🏭 Verify DevCenter - -```bash -# Show DevCenter details -az devcenter admin devcenter show \ - --name YOUR_DEVCENTER_NAME \ - --resource-group workload-prod-eastus2-RG -``` - -#### πŸ“‚ Verify Projects - -```bash -# List all projects -az devcenter admin project list \ - --resource-group workload-prod-eastus2-RG \ - -o table -``` - -#### πŸ“– Verify Catalogs - -```bash -# List catalogs for DevCenter -az devcenter admin catalog list \ - --dev-center-name YOUR_DEVCENTER_NAME \ - --resource-group workload-prod-eastus2-RG \ - -o table -``` - -#### πŸ” Verify Key Vault - -```bash -# Show Key Vault details -az keyvault show \ - --name YOUR_KEYVAULT_NAME \ - --resource-group security-prod-eastus2-RG - -# Verify secret exists (requires permissions) -az keyvault secret show \ - --name GitHubPAT \ - --vault-name YOUR_KEYVAULT_NAME -``` - -### πŸ”— Step 7: Access DevCenter - -1. **Navigate to Azure Portal**: - - Go to [https://portal.azure.com](https://portal.azure.com) - - Search for "DevCenter" or navigate to your resource group - -2. **View DevCenter Resources**: - - Select your DevCenter instance - - Navigate to "Projects" to view deployed projects - - Navigate to "Catalogs" to view synced repositories - -3. **Developer Access**: - - Users with `DevCenter Dev Box User` role can create Dev Boxes - - Navigate to [https://devbox.microsoft.com](https://devbox.microsoft.com) - - Select project and pool - - Create and connect to Dev Box - -### πŸ“Š Step 8: Monitor Deployment - -#### πŸ“Š View Logs in Log Analytics - -```bash -# Show Log Analytics Workspace details -az monitor log-analytics workspace show \ - --resource-group monitoring-prod-eastus2-RG \ - --workspace-name YOUR_WORKSPACE_NAME -``` - -#### πŸ” Query Deployment Logs - -```bash -# Query DevCenter activity logs -az monitor log-analytics query \ - --workspace YOUR_WORKSPACE_ID \ - --analytics-query "AzureActivity | where OperationNameValue contains 'MICROSOFT.DEVCENTER' | project TimeGenerated, OperationNameValue, ActivityStatusValue, Caller" \ - --timespan P1D -``` - -#### πŸ“ˆ Monitor Resource Metrics - -```bash -# View DevCenter metrics -az monitor metrics list \ - --resource /subscriptions/YOUR_SUBSCRIPTION_ID/resourceGroups/workload-prod-eastus2-RG/providers/Microsoft.DevCenter/devcenters/YOUR_DEVCENTER_NAME \ - --metric-names "AvailableDevBoxes" -``` - -## Configuration Reference - -### 🏠 Landing Zone Configuration - -The solution organizes resources into four landing zones, each with a specific -purpose: - -| Landing Zone | Purpose | Resources | Resource Group Pattern | -| ---------------- | ------------------------- | --------------------------------------------- | ---------------------------------------- | -| **Security** | Secret and key management | Azure Key Vault, Secrets | `{name}-{environmentName}-{location}-RG` | -| **Monitoring** | Observability and logging | Log Analytics Workspace, Solutions | `{name}-{environmentName}-{location}-RG` | -| **Connectivity** | Network infrastructure | Virtual Network, Subnets, Network Connections | `{name}-{environmentName}-{location}-RG` | -| **Workload** | DevCenter resources | DevCenter, Projects, Pools, Catalogs | `{name}-{environmentName}-{location}-RG` | - -### πŸ“– Catalog Configuration - -Catalogs provide environment definitions and image definitions for Dev Boxes. -The solution supports two catalog types: - -#### πŸ™ GitHub Catalog - -```yaml -catalogs: - - name: 'catalog-github' - type: 'gitHub' - visibility: 'private' - uri: 'https://github.com/YOUR_ORG/YOUR_REPO' - branch: 'main' - path: '/environments' -``` - -#### πŸ”΅ Azure DevOps Catalog - -```yaml -catalogs: - - name: 'catalog-ado' - type: 'adoGit' - visibility: 'private' - uri: 'https://dev.azure.com/YOUR_ORG/YOUR_PROJECT/_git/YOUR_REPO' - branch: 'main' - path: '/environments' -``` - -**βš™οΈ Configuration Options:** - -- `name`: Unique identifier for the catalog -- `type`: Source control platform (`gitHub` or `adoGit`) -- `visibility`: `public` (no authentication) or `private` (requires PAT) -- `uri`: Full URL to the Git repository -- `branch`: Branch to sync from -- `path`: Path within the repository containing definitions - -### 🌐 Network Configuration - -The solution supports two networking models: - -#### ☁️ Managed Networking (Microsoft-Hosted) - -```yaml -network: - virtualNetworkType: 'Managed' - microsoftHostedNetworkEnableStatus: 'Enabled' - create: false -``` - -**✨ Characteristics:** - -- No customer-managed virtual network required -- Microsoft manages network infrastructure -- Simplified deployment and management -- Automatic Azure AD join for Dev Boxes - -#### 🏒 Unmanaged Networking (Customer-Managed) - -```yaml -network: - name: 'vnet-devcenter' - virtualNetworkType: 'Unmanaged' - create: true - resourceGroupName: 'connectivity-prod-eastus2-RG' - addressPrefixes: - - '10.0.0.0/16' - subnets: - - name: 'subnet-devbox' - addressPrefix: '10.0.0.0/24' - tags: - component: 'connectivity' -``` - -**✨ Characteristics:** - -- Customer-managed virtual network in dedicated resource group -- Full control over network topology and security -- Support for hybrid connectivity scenarios -- Custom DNS and routing configurations - -### πŸ” Identity and RBAC Configuration - -The solution implements multiple identity patterns for secure access: - -#### 🏭 DevCenter Managed Identity - -```yaml -identity: - type: 'SystemAssigned' - roleAssignments: - devCenter: - - id: '8e3af657-a8ff-443c-a75c-2fe8c4bcb635' - name: 'Owner' - scope: 'ResourceGroup' -``` - -#### πŸ“‚ Project Managed Identity - -```yaml -identity: - type: 'SystemAssigned' - roleAssignments: - - azureADGroupId: 'YOUR_AZURE_AD_GROUP_OBJECT_ID' - azureADGroupName: 'Developers' - azureRBACRoles: - - id: '45d50f46-0b78-4001-a660-4198cbe8cd05' - name: 'DevCenter Dev Box User' - scope: 'Project' -``` - -#### 🌍 Environment Type Identity - -Each environment type automatically receives a system-assigned managed identity -with the following role: - -- **Contributor** (`b24988ac-6180-42a0-ab88-20f7382dd24c`): Deployment target - subscription access - -### πŸ’» Pool Configuration - -DevBox pools define the compute resources for development environments: - -```yaml -pools: - - name: 'pool-dev' - imageDefinitionName: 'windows-11-enterprise' - vmSku: 'general_i_8c32gb256ssd_v2' -``` - -**πŸ’» Common VM SKUs:** - -- `general_i_8c32gb256ssd_v2`: 8 vCPU, 32 GB RAM, 256 GB SSD -- `general_i_16c64gb512ssd_v2`: 16 vCPU, 64 GB RAM, 512 GB SSD -- `general_i_32c128gb1024ssd_v2`: 32 vCPU, 128 GB RAM, 1024 GB SSD - ---- - -## πŸ“¦ Release Strategy - -The Dev Box Landing Zone Accelerator uses a branch-based semantic release -strategy with intelligent version management. For complete details, see -[RELEASE_STRATEGY.md](RELEASE_STRATEGY.md). - -### πŸ“Š Version Strategy Summary - -| Branch Pattern | Version Strategy | Release Publication | -| -------------- | ----------------------------- | ------------------- | -| `main` | Conditional major increment | βœ… Published | -| `feature/**` | Patch increment with overflow | ❌ Not published | -| `fix/**` | Minor increment with overflow | ❌ Not published | - -### πŸ”’ Main Branch Versioning Logic - -- **If `minor=0 AND patch=0`**: Increment major β†’ `(major+1).0.0` -- **If `minorβ‰ 0 OR patchβ‰ 0`**: Increment patch β†’ `major.minor.(patch+1)` -- **Overflow handling**: If `patch > 99` β†’ `(minor+1).0` - ---- - -## πŸ”§ Troubleshooting - -> [!TIP] Most deployment issues can be resolved by verifying authentication and -> checking resource quotas. Review the common issues below for quick solutions. - -### ⚠️ Common Issues - -#### πŸ”‘ Authentication Failures - -**πŸ’₯ Symptom**: Setup script fails with authentication errors - -**βœ… Resolution**: - -1. Verify Azure CLI authentication: - ```bash - az account show - az account list - ``` -2. Re-authenticate if necessary: - ```bash - az login - az account set --subscription YOUR_SUBSCRIPTION_ID - ``` -3. For GitHub, verify GitHub CLI authentication: - ```bash - gh auth status - gh auth login - ``` -4. For Azure DevOps, verify Azure DevOps CLI authentication and configuration - -#### ⚠️ Quota Exceeded - -**πŸ’₯ Symptom**: Deployment fails with quota error - -**βœ… Resolution**: - -1. Check DevCenter quota in target region: - ```bash - az devcenter admin usage list --location YOUR_LOCATION - ``` -2. Request quota increase via Azure Portal: - - Navigate to Subscriptions β†’ Usage + quotas - - Search for "DevCenter" - - Request increase for required resources - -#### 🌐 Network Connection Failures - -**πŸ’₯ Symptom**: Network connection attachment fails during deployment - -**βœ… Resolution**: - -1. Verify subnet exists and has available IP addresses: - ```bash - az network vnet subnet show \ - --resource-group connectivity-prod-eastus2-RG \ - --vnet-name YOUR_VNET_NAME \ - --name YOUR_SUBNET_NAME - ``` -2. Ensure subnet is not in use by other resources -3. Verify subnet delegation is not configured for other services -4. Check network security group rules for outbound connectivity - -#### 🚫 Key Vault Access Denied - -**πŸ’₯ Symptom**: Unable to retrieve secrets from Key Vault - -**βœ… Resolution**: - -1. Verify RBAC assignments: - ```bash - az role assignment list \ - --assignee YOUR_IDENTITY_OBJECT_ID \ - --scope /subscriptions/YOUR_SUBSCRIPTION_ID/resourceGroups/security-prod-eastus2-RG/providers/Microsoft.KeyVault/vaults/YOUR_KEYVAULT_NAME - ``` -2. Ensure managed identity has `Key Vault Secrets User` role -3. Verify Key Vault RBAC authorization is enabled: - ```bash - az keyvault show --name YOUR_KEYVAULT_NAME --query properties.enableRbacAuthorization - ``` - -#### πŸ”„ Catalog Synchronization Failures - -**πŸ’₯ Symptom**: Catalog fails to sync or shows error status - -**βœ… Resolution**: - -1. Verify PAT is valid and has correct permissions -2. Verify repository URL is correct and accessible -3. Verify branch and path exist in repository -4. Check catalog sync status: - ```bash - az devcenter admin catalog show \ - --dev-center-name YOUR_DEVCENTER_NAME \ - --resource-group workload-prod-eastus2-RG \ - --name YOUR_CATALOG_NAME - ``` -5. Trigger manual sync: - ```bash - az devcenter admin catalog sync \ - --dev-center-name YOUR_DEVCENTER_NAME \ - --resource-group workload-prod-eastus2-RG \ - --name YOUR_CATALOG_NAME - ``` - -### πŸ“ Diagnostic Commands - -#### πŸ“œ View Deployment History - -```bash -# List subscription-level deployments -az deployment sub list --query "[].{Name:name, State:properties.provisioningState, Timestamp:properties.timestamp}" -o table - -# Show specific deployment details -az deployment sub show --name YOUR_DEPLOYMENT_NAME -``` - -#### πŸ‘€ View Role Assignments - -```bash -# List all role assignments in subscription -az role assignment list \ - --scope /subscriptions/YOUR_SUBSCRIPTION_ID \ - --output table - -# List role assignments for specific identity -az role assignment list \ - --assignee YOUR_IDENTITY_OBJECT_ID \ - --all -``` - -#### πŸ› οΈ View Diagnostic Settings - -```bash -# List diagnostic settings for a resource -az monitor diagnostic-settings list \ - --resource /subscriptions/YOUR_SUBSCRIPTION_ID/resourceGroups/workload-prod-eastus2-RG/providers/Microsoft.DevCenter/devcenters/YOUR_DEVCENTER_NAME -``` - -#### πŸ“Š Query Log Analytics - -```bash -# Query DevCenter activity logs -az monitor log-analytics query \ - --workspace YOUR_WORKSPACE_ID \ - --analytics-query "AzureDiagnostics | where ResourceProvider == 'MICROSOFT.DEVCENTER' | limit 100" - -# Query diagnostic logs -az monitor log-analytics query \ - --workspace YOUR_WORKSPACE_ID \ - --analytics-query "AzureDiagnostics | where ResourceType == 'DEVCENTERS' | project TimeGenerated, OperationName, ResultType, Message" -``` - ---- - -## 🧹 Cleanup - -To remove all deployed resources: - -### Windows (PowerShell) - -```powershell -.\cleanSetUp.ps1 -EnvName "prod" -Location "eastus2" -``` - -### Linux/macOS (Bash) - -```bash -# Manual cleanup using azd -azd down -e prod --purge --force -``` - -> [!CAUTION] This operation is **irreversible** and will: -> -> - Delete all resource groups created by the deployment -> - Delete Key Vault secrets (with purge if purge protection is disabled) -> - Remove all RBAC role assignments -> - Delete diagnostic settings and monitoring data -> - Remove Azure Developer CLI environment configuration - ---- - -## 🀝 Contributing - -Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for -guidelines on: - -- Code of conduct -- Development workflow -- Pull request process -- Coding standards and best practices -- Testing requirements - ---- - -## πŸ”’ Security - -For reporting security vulnerabilities, please review -[SECURITY.md](SECURITY.md). - -> [!WARNING] **Security Best Practices:** -> -> - Never commit Personal Access Tokens or secrets to source control -> - Use Azure Key Vault for all sensitive data -> - Enable purge protection and soft delete for Key Vault -> - Implement least privilege RBAC assignments -> - Regularly review and rotate access credentials -> - Enable diagnostic logging for all resources -> - Monitor Log Analytics for suspicious activity - ---- - -## πŸ“„ License - -This project is licensed under the MIT License. See [LICENSE](LICENSE) for -details. - ---- - -## πŸ’¬ Support - -For issues, questions, or feature requests: - -1. Check existing - [GitHub Issues](https://github.com/Evilazaro/DevExp-DevBox/issues) -2. Search - [closed issues](https://github.com/Evilazaro/DevExp-DevBox/issues?q=is%3Aissue+is%3Aclosed) - for solutions -3. Create a new issue with detailed information: - - Environment details (OS, tool versions) - - Steps to reproduce - - Error messages and logs - - Expected vs actual behavior -4. Use appropriate labels: - - `bug`: Something isn't working - - `enhancement`: New feature or request - - `question`: Further information requested - - `documentation`: Documentation improvements - ---- - -## πŸ“š Additional Resources - -### πŸ“˜ Microsoft Documentation - -- [Microsoft Dev Box Documentation](https://learn.microsoft.com/azure/dev-box/) -- [Azure DevCenter Documentation](https://learn.microsoft.com/azure/dev-center/) -- [Azure Bicep Documentation](https://learn.microsoft.com/azure/azure-resource-manager/bicep/) -- [Azure Developer CLI Documentation](https://learn.microsoft.com/azure/developer/azure-developer-cli/) -- [Azure Landing Zones](https://learn.microsoft.com/azure/cloud-adoption-framework/ready/landing-zone/) -- [Azure RBAC Documentation](https://learn.microsoft.com/azure/role-based-access-control/) -- [Azure Key Vault Documentation](https://learn.microsoft.com/azure/key-vault/) -- [Azure Monitor Documentation](https://learn.microsoft.com/azure/azure-monitor/) - -### πŸ”— Related Projects - -- [Azure Landing Zones (Enterprise-Scale)](https://github.com/Azure/Enterprise-Scale) -- [Azure Verified Modules](https://github.com/Azure/bicep-registry-modules) -- [Cloud Adoption Framework](https://learn.microsoft.com/azure/cloud-adoption-framework/) - -### πŸ‘₯ Community Resources - -- [Microsoft Dev Box Community](https://techcommunity.microsoft.com/t5/azure-dev-box/bd-p/AzureDevBox) -- [Azure DevCenter Community](https://techcommunity.microsoft.com/t5/azure-developer-community-blog/bg-p/AzureDevCommunityBlog) -- [Bicep Community](https://github.com/Azure/bicep/discussions) - ---- - -## πŸ“Ž Related Documents - -| Document | Description | -| :----------------------------------------- | :----------------------------------------------- | -| [RELEASE_STRATEGY.md](RELEASE_STRATEGY.md) | Branch-based versioning and release workflow | -| [CONTRIBUTING.md](CONTRIBUTING.md) | Contribution guidelines and development workflow | -| [SECURITY.md](SECURITY.md) | Security policies and vulnerability reporting | -| [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Community guidelines and standards | -| [LICENSE](LICENSE) | MIT License details | - ---- - -
- -**πŸš€ Dev Box Landing Zone Accelerator** - -Maintained by: **DevExp Team**
Repository: -[Evilazaro/DevExp-DevBox](https://github.com/Evilazaro/DevExp-DevBox)
Last -Updated: 2024 - -[⬆️ Back to Top](#-dev-box-landing-zone-accelerator) Β· -[πŸ“¦ Release Strategy](RELEASE_STRATEGY.md) Β· [🀝 Contributing](CONTRIBUTING.md) - -
diff --git a/RELEASE_STRATEGY.md b/RELEASE_STRATEGY.md deleted file mode 100644 index 7b35b220..00000000 --- a/RELEASE_STRATEGY.md +++ /dev/null @@ -1,242 +0,0 @@ ---- -title: Release Strategy -description: - Comprehensive release strategy for the Dev Box Landing Zone Accelerator, - detailing branch-based versioning, automated workflows, and deployment - processes. -author: DevExp Team -date: 2024-01-01 -version: 1.0.0 -tags: [release, versioning, ci-cd, automation, devops] ---- - -# πŸ“¦ Dev Box Landing Zone Accelerator - Release Strategy - -> [!NOTE] **Target Audience:** DevOps Engineers, Release Managers, and -> Contributors
**Reading Time:** ~8 minutes - -
-πŸ“ Navigation - -| Previous | Index | Next | -| :------------------------------ | :-----------------: | ----------------------: | -| [Contributing](CONTRIBUTING.md) | [README](README.md) | [Security](SECURITY.md) | - -
- ---- - -## πŸ“‘ Table of Contents - -- [πŸ“– Overview](#-overview) -- [πŸ“Š Release Strategy Summary](#-release-strategy-summary) -- [πŸ”€ Branch-Specific Versioning Rules](#-branch-specific-versioning-rules) - - [🎯 Main Branch](#-main-branch-main) - - [✨ Feature Branches](#-feature-branches-feature) - - [πŸ”§ Fix Branches](#-fix-branches-fix) -- [πŸ“‹ Version Examples](#-version-examples) -- [πŸ“ Release Notes Structure](#-release-notes-structure) -- [βœ… Best Practices](#-best-practices) -- [πŸ”— Related Documents](#-related-documents) - ---- - -## πŸ“– Overview - -This document outlines the comprehensive release strategy for the Dev Box -landing zone accelerator, detailing branch-based versioning, automated -workflows, and deployment processes. - -> [!IMPORTANT] The Dev Box landing zone accelerator uses a **branch-based -> semantic release strategy** with intelligent overflow handling and conditional -> versioning rules. This approach ensures consistent, predictable releases while -> maintaining development flexibility across different branch types. - ---- - -## πŸ“Š Release Strategy Summary - -| Branch Pattern | Version Strategy | Release Publication | Tag Creation | Artifacts | -| -------------- | ----------------------------- | ------------------- | ------------ | ------------------- | -| `main` | Conditional major increment | βœ… Published | βœ… Created | βœ… Built & Uploaded | -| `feature/**` | Patch increment with overflow | ❌ Not published | βœ… Created | βœ… Built & Uploaded | -| `fix/**` | Minor increment with overflow | ❌ Not published | βœ… Created | βœ… Built & Uploaded | -| `pull_request` | Based on source branch | ❌ Not published | βœ… Created | βœ… Built & Uploaded | - ---- - -## πŸ”€ Branch-Specific Versioning Rules - -### 🎯 Main Branch (`main`) - -> [!TIP] The main branch uses a **conditional major increment rule** that -> intelligently determines version bumps based on the current version state. - -**New Conditional Major Increment Rule:** - -- **If `minor = 0` AND `patch = 0`**: Increment major version - - Example: `v1.0.0` β†’ `v2.0.0` -- **If `minor β‰  0` OR `patch β‰  0`**: Keep major version, increment patch - - Example: `v1.5.0` β†’ `v1.5.1` - - Example: `v1.0.3` β†’ `v1.0.4` - - Example: `v1.5.3` β†’ `v1.5.4` - -**Overflow Handling:** - -- If patch exceeds 99: Reset patch to 0, increment minor - - Example: `v1.5.99` β†’ `v1.6.0` -- If minor exceeds 99: Reset minor to 0, increment major - - Example: `v1.99.99` β†’ `v2.0.0` - -### ✨ Feature Branches (`feature/**`) - -**Patch Increment Strategy:** - -- Increments the patch version by the number of commits in the branch -- Format: `vX.Y.(Z+commits)-feature.branch-name` - -**Examples:** - -- Current: `v1.2.5`, Branch: `feature/user-authentication`, Commits: 3 -- Result: `v1.2.8-feature.user-authentication` - -**Overflow Logic:** - -- If `patch + commits > 99`: Reset patch to 0, increment minor -- If minor overflow occurs: Reset minor to 0, increment major - -### πŸ”§ Fix Branches (`fix/**`) - -**Minor Increment Strategy:** - -- Increments the minor version by the number of commits in the branch -- Format: `vX.(Y+commits).Z-fix.branch-name` - -**Examples:** - -- Current: `v1.2.5`, Branch: `fix/login-bug`, Commits: 2 -- Result: `v1.4.5-fix.login-bug` - -**Overflow Logic:** - -- If `minor + commits > 99`: Reset minor to 0, increment major - ---- - -## πŸ“‹ πŸ“‹ Version Examples - -### 🎯 Main Branch Scenarios - -| Current Version | Condition | Action | Result | Reasoning | -| --------------- | ------------------ | --------------- | -------- | -------------------------------------- | -| `v1.0.0` | minor=0, patch=0 | Major increment | `v2.0.0` | Clean state allows major bump | -| `v1.5.0` | minorβ‰ 0, patch=0 | Patch increment | `v1.5.1` | Development continues on current major | -| `v1.0.3` | minor=0, patchβ‰ 0 | Patch increment | `v1.0.4` | Development continues on current major | -| `v1.5.99` | Patch overflow | Minor increment | `v1.6.0` | Patch overflow triggers minor bump | -| `v1.99.99` | Cascading overflow | Major increment | `v2.0.0` | Full overflow resets to new major | - -### ✨ Feature Branch Scenarios - -| Current Version | Branch | Commits | Calculation | Result | -| --------------- | -------------- | ------- | ------------------ | --------------------- | -| `v1.2.5` | `feature/auth` | 3 | 5 + 3 = 8 | `v1.2.8-feature.auth` | -| `v1.2.97` | `feature/ui` | 5 | 97 + 5 = 102 > 99 | `v1.3.0-feature.ui` | -| `v1.99.95` | `feature/api` | 8 | Cascading overflow | `v2.0.0-feature.api` | - -### πŸ”§ Fix Branch Scenarios - -| Current Version | Branch | Commits | Calculation | Result | -| --------------- | -------------- | ------- | ----------------- | --------------------- | -| `v1.5.3` | `fix/bug-123` | 2 | 5 + 2 = 7 | `v1.7.3-fix.bug-123` | -| `v1.98.3` | `fix/critical` | 3 | 98 + 3 = 101 > 99 | `v2.0.3-fix.critical` | - ---- - -## πŸ“ Release Notes Structure - -> [!NOTE] Each release includes comprehensive documentation with the following -> structure: - -
-πŸ“„ Click to view Release Notes Template - -```markdown -🌟 **Branch-Based Release Strategy with Conditional Major Increment** - -πŸ”€ **Branch**: `main` 🏷️ **Version**: `v2.0.0` πŸ“¦ **Previous Version**: `v1.0.0` -πŸš€ **Release Type**: `main` πŸ€– **Trigger**: `Push` πŸ“ **Commit**: `abc123...` - -## Release Strategy Applied - -🎯 **Main Branch**: Conditional major increment (only if minor=0 AND patch=0) - -## Main Branch Logic - -- **If minor=0 AND patch=0**: Increment major β†’ `major+1.0.0` -- **If minorβ‰ 0 OR patchβ‰ 0**: Keep major, increment patch β†’ - `major.minor.(patch+1)` -- **Overflow handling**: If patch > 99 β†’ `minor+1, patch=0` - -## Artifacts - -- πŸ“„ Bicep templates compiled to ARM templates -- πŸ—οΈ Infrastructure deployment files -- πŸ“‹ Release metadata and documentation -``` - -
- ---- - -## βœ… Best Practices - -### πŸ‘¨β€πŸ’» For Developers - -1. **Branch Naming**: Use descriptive branch names following the patterns: - - `feature/descriptive-name` - - `fix/issue-description` - -2. **Commit Strategy**: Keep commits atomic and meaningful as they influence - version calculations - -3. **Testing**: Ensure all changes are tested before merging to main - -### πŸ“¦ For Release Management - -> [!TIP] Monitor version progression regularly to ensure releases follow the -> expected pattern. - -1. **Main Branch Protection**: Only merge tested, reviewed code to main -2. **Version Monitoring**: Monitor version progression to prevent unexpected - major increments -3. **Release Planning**: Use the conditional major increment rule for planned - major releases - ---- - -## πŸ”— Related Documents - -| Document | Description | -| :--------------------------------------- | :----------------------------------------------- | -| [README.md](README.md) | Main project documentation and deployment guide | -| [CONTRIBUTING.md](CONTRIBUTING.md) | Contribution guidelines and development workflow | -| [SECURITY.md](SECURITY.md) | Security policies and vulnerability reporting | -| [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Community guidelines and standards | - ---- - -> [!IMPORTANT] This release strategy provides a robust, automated approach to -> version management while maintaining flexibility for different development -> workflows and ensuring consistent, trackable releases for the Dev Box landing -> zone accelerator. - ---- - -
- -**πŸ“¦ Dev Box Landing Zone Accelerator - Release Strategy** - -[⬆️ Back to Top](#-dev-box-landing-zone-accelerator---release-strategy) Β· -[πŸ“– README](README.md) Β· [🀝 Contributing](CONTRIBUTING.md) - -
diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index a4fbff2f..00000000 --- a/SECURITY.md +++ /dev/null @@ -1,2 +0,0 @@ -# Security Policy - From e67d999afc2b7b0fb2cb8510d32ad89632592ee1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 14:45:01 -0500 Subject: [PATCH 02/49] Add comprehensive Business Architecture documentation for DevExp-DevBox --- docs/architecture/01-business-architecture.md | 468 ++++++++++++++++++ 1 file changed, 468 insertions(+) create mode 100644 docs/architecture/01-business-architecture.md diff --git a/docs/architecture/01-business-architecture.md b/docs/architecture/01-business-architecture.md new file mode 100644 index 00000000..c7d8503d --- /dev/null +++ b/docs/architecture/01-business-architecture.md @@ -0,0 +1,468 @@ +# Business Architecture + +> **DevExp-DevBox Landing Zone Accelerator** + +| Metadata | Value | +| ---------------- | ------------------------- | +| **Version** | 1.0.0 | +| **Last Updated** | January 22, 2026 | +| **Author** | Platform Engineering Team | +| **Status** | Active | + +--- + +## Table of Contents + +- [Executive Summary](#executive-summary) +- [Business Context](#business-context) +- [Stakeholder Analysis](#stakeholder-analysis) +- [Business Capabilities](#business-capabilities) +- [Value Streams](#value-streams) +- [Business Requirements](#business-requirements) +- [Success Metrics](#success-metrics) +- [References](#references) +- [Glossary](#glossary) + +--- + +## Executive Summary + +The **DevExp-DevBox Landing Zone Accelerator** is a comprehensive +infrastructure-as-code solution that automates the deployment and management of +Microsoft Dev Box environments on Azure. This accelerator enables organizations +to provision secure, compliant, and scalable developer workstations following +Azure Landing Zone best practices. + +### Key Business Value + +| Value Proposition | Description | +| ------------------------------------ | -------------------------------------------------------------- | +| **Accelerated Developer Onboarding** | Reduce new developer setup time from days to hours | +| **Standardized Environments** | Ensure consistent tooling and configurations across teams | +| **Security by Design** | Built-in RBAC, Key Vault integration, and compliance controls | +| **Cost Optimization** | Role-specific VM SKUs and resource tagging for cost allocation | +| **Operational Excellence** | Centralized monitoring, diagnostics, and lifecycle management | + +### Target Outcomes + +```mermaid +mindmap + root((DevExp-DevBox
Value)) + Developer Productivity + Faster onboarding + Consistent environments + Self-service provisioning + Security & Compliance + RBAC enforcement + Secrets management + Audit logging + Operational Efficiency + Infrastructure as Code + Automated deployments + Centralized monitoring + Cost Management + Resource tagging + Right-sized VMs + Environment isolation +``` + +--- + +## Business Context + +### Problem Statement + +Enterprise development teams face significant challenges in maintaining +consistent, secure, and scalable developer workstations: + +| Challenge | Impact | Solution Approach | +| ----------------------------- | -------------------------------------------------- | ------------------------------------------------------------------ | +| **Inconsistent Environments** | "Works on my machine" syndrome, debugging overhead | Standardized Dev Box definitions with role-specific configurations | +| **Slow Onboarding** | Days/weeks to provision new developer machines | Automated provisioning through DevCenter projects and pools | +| **Security Gaps** | Manual credential management, compliance risks | Centralized Key Vault, RBAC, and managed identities | +| **Operational Overhead** | Manual infrastructure management | Infrastructure-as-Code with Bicep, GitOps workflows | +| **Cost Visibility** | Untracked resource consumption | Consistent tagging strategy and resource grouping | + +### Target Audience + +The DevExp-DevBox accelerator serves organizations that: + +- Operate cloud-native or hybrid development teams +- Require standardized, secure development environments +- Follow DevOps and Infrastructure-as-Code practices +- Need to demonstrate compliance with security frameworks +- Manage multiple projects or product teams + +### Business Drivers + +```mermaid +flowchart LR + subgraph External["External Drivers"] + A[Security Compliance] + B[Talent Competition] + C[Remote Work] + end + + subgraph Internal["Internal Drivers"] + D[Developer Productivity] + E[Cost Optimization] + F[Operational Efficiency] + end + + subgraph Solution["DevExp-DevBox"] + G[Landing Zone
Accelerator] + end + + A --> G + B --> G + C --> G + D --> G + E --> G + F --> G + + G --> H[Secure Dev
Environments] + G --> I[Fast Onboarding] + G --> J[Centralized
Management] +``` + +--- + +## Stakeholder Analysis + +### Stakeholder Map + +```mermaid +quadrantChart + title Stakeholder Influence vs Interest Matrix + x-axis Low Interest --> High Interest + y-axis Low Influence --> High Influence + quadrant-1 Manage Closely + quadrant-2 Keep Satisfied + quadrant-3 Monitor + quadrant-4 Keep Informed + Platform Engineers: [0.85, 0.90] + Security Team: [0.80, 0.85] + Developers: [0.95, 0.40] + DevOps Engineers: [0.75, 0.70] + IT Operations: [0.60, 0.65] + Finance: [0.50, 0.55] + Project Managers: [0.65, 0.45] + Executive Sponsors: [0.40, 0.95] +``` + +### Detailed Stakeholder Analysis + +| Stakeholder | Role | Key Concerns | Interests | Communication Needs | +| ---------------------- | --------------------------------------------------- | ------------------------------------------------ | --------------------------------------------------- | --------------------------------------------------- | +| **Platform Engineers** | Design and maintain the landing zone infrastructure | Scalability, maintainability, automation | Modular architecture, IaC patterns, extensibility | Technical documentation, architecture decisions | +| **Security Team** | Ensure compliance and security posture | RBAC, secrets management, audit trails | Key Vault integration, identity management, logging | Security controls documentation, compliance reports | +| **Developers** | Consume Dev Box environments | Fast provisioning, correct tooling, self-service | Quick onboarding, consistent environments | User guides, self-service portals | +| **DevOps Engineers** | Manage CI/CD pipelines and deployments | Automation, reliability, deployment velocity | Pipeline integration, GitOps workflows | Deployment procedures, runbooks | +| **IT Operations** | Monitor and support production systems | Observability, incident response, SLA compliance | Log Analytics integration, alerting | Operational dashboards, incident procedures | +| **Finance/FinOps** | Manage cloud costs and budgets | Cost visibility, budget compliance, chargebacks | Resource tagging, cost allocation | Cost reports, budget alerts | +| **Project Managers** | Coordinate development activities | Team productivity, project timelines | Environment availability, team onboarding | Status reports, capacity planning | +| **Executive Sponsors** | Strategic oversight and funding | Business value, ROI, risk management | Success metrics, strategic alignment | Executive summaries, KPI dashboards | + +### RACI Matrix + +| Activity | Platform Engineers | Security Team | Developers | DevOps | IT Ops | Finance | +| ------------------------ | ------------------ | ------------- | ---------- | ------ | ------- | ------- | +| Landing Zone Design | **R/A** | C | I | C | C | I | +| Security Configuration | C | **R/A** | I | I | C | I | +| DevCenter Setup | **R/A** | C | I | C | I | I | +| Pool Definition | **R** | C | C | **A** | I | I | +| Environment Provisioning | C | I | **R** | **A** | I | I | +| Cost Monitoring | I | I | I | I | C | **R/A** | +| Incident Response | C | C | I | C | **R/A** | I | + +_R = Responsible, A = Accountable, C = Consulted, I = Informed_ + +--- + +## Business Capabilities + +### Business Capability Model + +```mermaid +block-beta + columns 4 + + block:header:4 + A["DevExp-DevBox Business Capabilities"] + end + + block:security:1 + B["πŸ” Security"] + B1["Key Vault Management"] + B2["RBAC Administration"] + B3["Secret Lifecycle"] + B4["Compliance Reporting"] + end + + block:monitoring:1 + C["πŸ“Š Monitoring"] + C1["Log Analytics"] + C2["Diagnostic Settings"] + C3["Performance Metrics"] + C4["Alert Management"] + end + + block:connectivity:1 + D["🌐 Connectivity"] + D1["VNet Management"] + D2["Subnet Configuration"] + D3["Network Connections"] + D4["NSG Rules"] + end + + block:workload:1 + E["πŸ’» Workload"] + E1["DevCenter Management"] + E2["Project Administration"] + E3["Pool Configuration"] + E4["Catalog Management"] + end +``` + +### Capability to Landing Zone Mapping + +| Capability Domain | Landing Zone | Azure Resources | Bicep Modules | +| ------------------------------ | ------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------ | +| **Security Management** | Security Landing Zone | Key Vault, Secrets, Access Policies | `security.bicep`, `keyVault.bicep`, `secret.bicep` | +| **Monitoring & Observability** | Monitoring Landing Zone | Log Analytics Workspace, Diagnostic Settings | `logAnalytics.bicep` | +| **Network Management** | Connectivity Landing Zone | Virtual Networks, Subnets, Network Connections | `vnet.bicep`, `networkConnection.bicep`, `connectivity.bicep` | +| **Developer Workload** | Workload Landing Zone | DevCenter, Projects, Pools, Catalogs | `devCenter.bicep`, `project.bicep`, `projectPool.bicep`, `catalog.bicep` | +| **Identity Management** | Cross-cutting | Managed Identities, Role Assignments | `devCenterRoleAssignment.bicep`, `projectIdentityRoleAssignment.bicep` | + +### Capability Details + +#### Security Capability + +| Sub-Capability | Description | Business Value | +| -------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------- | +| Key Vault Management | Centralized secrets, keys, and certificates storage | Eliminates credential sprawl, enables rotation | +| RBAC Administration | Role-based access control at subscription, resource group, and resource levels | Principle of least privilege enforcement | +| Secret Lifecycle | Automated secret creation, rotation, and expiration | Reduced security incidents from stale credentials | +| Compliance Reporting | Audit logging and diagnostic data collection | Regulatory compliance demonstration | + +#### Workload Capability + +| Sub-Capability | Description | Business Value | +| ---------------------- | --------------------------------------------------- | ----------------------------------------------- | +| DevCenter Management | Centralized control plane for Dev Box environments | Single pane of glass administration | +| Project Administration | Logical grouping of development teams and resources | Team isolation and governance | +| Pool Configuration | Role-specific VM definitions and configurations | Right-sized resources, cost optimization | +| Catalog Management | Centralized image and environment definitions | Standardized, version-controlled configurations | + +--- + +## Value Streams + +### Developer Onboarding Value Stream + +```mermaid +flowchart LR + subgraph Trigger["Trigger"] + A[New Developer
Joins Team] + end + + subgraph Process["Onboarding Process"] + B[Add to
Azure AD Group] + C[RBAC Auto-
Assignment] + D[Access
DevCenter Portal] + E[Select
Dev Box Pool] + F[Provision
Dev Box] + G[DSC Config
Applied] + end + + subgraph Outcome["Outcome"] + H[Developer
Productive] + end + + A --> B --> C --> D --> E --> F --> G --> H + + style A fill:#e1f5fe + style H fill:#c8e6c9 +``` + +### Value Stream Stages + +| Stage | Activities | Inputs | Outputs | Duration | Automation Level | +| ----------------------------- | --------------------------------------------------------- | ------------------- | ---------------------- | --------- | ---------------- | +| **Identity Setup** | Add developer to Azure AD group | HR onboarding data | Group membership | Minutes | Manual/Automated | +| **Access Provisioning** | RBAC roles automatically assigned via group membership | AD group membership | Project access | Seconds | Fully Automated | +| **Environment Selection** | Developer accesses DevCenter and selects appropriate pool | DevCenter access | Pool selection | Minutes | Self-Service | +| **Dev Box Provisioning** | Dev Box VM created from pool definition | Pool config, image | Running VM | 30-60 min | Fully Automated | +| **Configuration Application** | DSC configurations apply required tools and settings | DSC YAML configs | Configured workstation | 15-30 min | Fully Automated | +| **Productivity Start** | Developer begins work with all required tools | Configured Dev Box | Productive developer | Immediate | N/A | + +### Environment Provisioning Lifecycle + +```mermaid +sequenceDiagram + participant PM as Platform Manager + participant GH as GitHub/ADO + participant AZD as Azure Developer CLI + participant ARM as Azure Resource Manager + participant DC as DevCenter + participant KV as Key Vault + + PM->>GH: Push configuration changes + GH->>GH: CI pipeline triggered + GH->>AZD: azd provision + AZD->>ARM: Deploy main.bicep + ARM->>ARM: Create Resource Groups + ARM->>KV: Deploy Key Vault + ARM->>DC: Deploy DevCenter + DC->>DC: Configure Catalogs + DC->>DC: Create Projects + DC->>DC: Setup Pools + DC-->>PM: Deployment complete + + Note over PM,KV: Infrastructure ready for developer onboarding +``` + +--- + +## Business Requirements + +### Functional Requirements + +| ID | Requirement | Priority | Source | Acceptance Criteria | +| ---------- | ------------------------------------------------------------ | ----------- | -------------------- | -------------------------------------------------------- | +| **FR-001** | System shall provision DevCenter with configurable settings | Must Have | Platform Engineering | DevCenter deployed with YAML-defined settings | +| **FR-002** | System shall create role-specific Dev Box pools | Must Have | Development Teams | Pools created with specified VM SKUs and images | +| **FR-003** | System shall manage secrets in Azure Key Vault | Must Have | Security Team | GitHub/ADO tokens stored securely with RBAC | +| **FR-004** | System shall assign RBAC roles based on AD group membership | Must Have | Security Team | Developers receive appropriate permissions automatically | +| **FR-005** | System shall support multiple projects within DevCenter | Should Have | Project Management | Multiple projects with isolated configurations | +| **FR-006** | System shall integrate Git catalogs for image definitions | Should Have | Platform Engineering | Catalogs sync from GitHub/Azure DevOps | +| **FR-007** | System shall configure diagnostic settings for all resources | Should Have | IT Operations | All resources send logs to Log Analytics | +| **FR-008** | System shall support both managed and unmanaged networks | Could Have | Network Team | Network type configurable per project | + +### Non-Functional Requirements + +| ID | Requirement | Category | Target | Measurement | +| ----------- | ------------------------------------------------------- | --------------- | --------------- | ----------------------------- | +| **NFR-001** | Deployment shall complete within 30 minutes | Performance | < 30 min | Pipeline duration metrics | +| **NFR-002** | Infrastructure code shall be idempotent | Reliability | 100% | Repeated deployments succeed | +| **NFR-003** | All resources shall have consistent tagging | Governance | 100% compliance | Azure Policy evaluation | +| **NFR-004** | Secrets shall use RBAC authorization only | Security | RBAC enabled | Key Vault configuration audit | +| **NFR-005** | Solution shall support 12+ Azure regions | Scalability | 12 regions | Deployment validation | +| **NFR-006** | Configuration changes shall be version controlled | Maintainability | 100% | Git history tracking | +| **NFR-007** | Deployment shall work with both GitHub and Azure DevOps | Compatibility | Both platforms | CI/CD pipeline success | + +### Requirements Traceability + +```mermaid +flowchart TD + subgraph Business["Business Goals"] + BG1[Fast Onboarding] + BG2[Security Compliance] + BG3[Cost Management] + end + + subgraph Functional["Functional Requirements"] + FR1[FR-001: DevCenter] + FR2[FR-002: Pools] + FR3[FR-003: Key Vault] + FR4[FR-004: RBAC] + end + + subgraph Technical["Technical Components"] + TC1[devCenter.bicep] + TC2[projectPool.bicep] + TC3[keyVault.bicep] + TC4[roleAssignment.bicep] + end + + BG1 --> FR1 + BG1 --> FR2 + BG2 --> FR3 + BG2 --> FR4 + BG3 --> FR2 + + FR1 --> TC1 + FR2 --> TC2 + FR3 --> TC3 + FR4 --> TC4 +``` + +--- + +## Success Metrics + +### Key Performance Indicators (KPIs) + +| KPI | Description | Target | Measurement Method | Frequency | +| --------------------------------- | --------------------------------------------------- | ------------- | ----------------------- | -------------- | +| **Developer Onboarding Time** | Time from AD group addition to productive Dev Box | < 2 hours | Tracking timestamps | Per onboarding | +| **Deployment Success Rate** | Percentage of successful infrastructure deployments | > 99% | CI/CD pipeline metrics | Weekly | +| **Environment Provisioning Time** | Time to provision a new Dev Box | < 60 minutes | DevCenter metrics | Daily | +| **Security Compliance Score** | Azure Security Center compliance percentage | > 95% | Azure Security Center | Weekly | +| **Resource Tagging Compliance** | Percentage of resources with required tags | 100% | Azure Policy | Daily | +| **Cost per Developer** | Monthly Azure spend per active developer | Baseline -10% | Cost Management reports | Monthly | +| **Mean Time to Recovery** | Average time to resolve infrastructure issues | < 4 hours | Incident tracking | Per incident | + +### Success Metrics Dashboard + +```mermaid +pie showData + title Resource Distribution by Landing Zone + "Security" : 15 + "Monitoring" : 10 + "Connectivity" : 20 + "Workload" : 55 +``` + +### Business Value Realization + +| Metric | Before Accelerator | After Accelerator | Improvement | +| --------------------------------------- | ------------------ | ----------------- | --------------- | +| Developer Onboarding | 3-5 days | 2-4 hours | 90%+ reduction | +| Environment Consistency | 60% | 100% | 40% improvement | +| Security Incidents (credential-related) | 5/quarter | <1/quarter | 80%+ reduction | +| Infrastructure Deployment Time | 2-3 days | 30 minutes | 95%+ reduction | +| Compliance Audit Preparation | 2 weeks | 2 days | 85% reduction | + +--- + +## References + +### External References + +| Reference | URL | Description | +| ------------------------------- | ------------------------------------------------------------------------------ | ------------------------------ | +| Microsoft Dev Box Documentation | https://learn.microsoft.com/azure/dev-box/ | Official Dev Box documentation | +| Azure Landing Zones | https://learn.microsoft.com/azure/cloud-adoption-framework/ready/landing-zone/ | CAF Landing Zone guidance | +| DevExp-DevBox Accelerator | https://evilazaro.github.io/DevExp-DevBox/ | Project documentation site | +| TOGAF Standard | https://www.opengroup.org/togaf | TOGAF architecture framework | + +### Related Architecture Documents + +| Document | Path | Description | +| ------------------------ | ------------------------------------------------------------------ | ----------------------------------- | +| Data Architecture | [02-data-architecture.md](./02-data-architecture.md) | Data entities and information flows | +| Application Architecture | [03-application-architecture.md](./03-application-architecture.md) | Bicep module architecture | +| Technology Architecture | [04-technology-architecture.md](./04-technology-architecture.md) | Azure services and infrastructure | + +--- + +## Glossary + +| Term | Definition | +| ---------------- | -------------------------------------------------------------------------------- | +| **Dev Box** | Microsoft's cloud-powered developer workstation service | +| **DevCenter** | Azure resource that manages Dev Box projects, pools, and catalogs | +| **Landing Zone** | A pre-configured Azure environment with governance, security, and connectivity | +| **Pool** | A collection of Dev Boxes with the same configuration (VM SKU, image, network) | +| **Catalog** | A Git repository containing Dev Box image definitions or environment definitions | +| **RBAC** | Role-Based Access Control - Azure's authorization system | +| **DSC** | Desired State Configuration - declarative configuration management | +| **IaC** | Infrastructure as Code - managing infrastructure through code | +| **azd** | Azure Developer CLI - tool for deploying Azure applications | +| **Bicep** | Domain-specific language for deploying Azure resources | + +--- + +_This document follows TOGAF Architecture Development Method (ADM) principles +and aligns with the Business Architecture domain of the BDAT framework._ From e207a5a3d399256e2ecf4d3191ab69b48d22c1df Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 14:47:25 -0500 Subject: [PATCH 03/49] Add initial Data Architecture documentation for DevExp-DevBox --- docs/architecture/02-data-architecture.md | 729 ++++++++++++++++++++++ 1 file changed, 729 insertions(+) create mode 100644 docs/architecture/02-data-architecture.md diff --git a/docs/architecture/02-data-architecture.md b/docs/architecture/02-data-architecture.md new file mode 100644 index 00000000..17918028 --- /dev/null +++ b/docs/architecture/02-data-architecture.md @@ -0,0 +1,729 @@ +# Data Architecture + +> **DevExp-DevBox Landing Zone Accelerator** + +| Metadata | Value | +| ---------------- | ------------------------- | +| **Version** | 1.0.0 | +| **Last Updated** | January 22, 2026 | +| **Author** | Platform Engineering Team | +| **Status** | Active | + +--- + +## Table of Contents + +- [Data Overview](#data-overview) +- [Configuration Data Model](#configuration-data-model) +- [Secrets Management](#secrets-management) +- [Telemetry & Diagnostics](#telemetry--diagnostics) +- [Data Flow Diagrams](#data-flow-diagrams) +- [Data Governance](#data-governance) +- [Schema Documentation](#schema-documentation) +- [References](#references) +- [Glossary](#glossary) + +--- + +## Data Overview + +The DevExp-DevBox Landing Zone Accelerator manages several categories of data +that flow through the system during deployment and operation. + +### Data Categories + +| Category | Type | Storage Location | Sensitivity | Lifecycle | +| ---------------------- | ----------------------- | ---------------------------------- | ----------- | ------------------- | +| **Configuration Data** | YAML files | Git repository (`infra/settings/`) | Low | Version controlled | +| **Secrets** | PAT tokens, credentials | Azure Key Vault | High | Managed rotation | +| **Telemetry** | Logs, metrics | Log Analytics Workspace | Medium | 30-90 day retention | +| **State** | Deployment outputs | Azure Resource Manager | Low | Deployment lifetime | +| **Identity Data** | Role assignments | Azure RBAC | Medium | Resource lifetime | + +### Data Entity Overview + +```mermaid +erDiagram + AZURE_RESOURCES ||--o{ RESOURCE_GROUP : contains + RESOURCE_GROUP ||--o{ DEVCENTER : hosts + RESOURCE_GROUP ||--o{ KEY_VAULT : hosts + RESOURCE_GROUP ||--o{ LOG_ANALYTICS : hosts + + DEVCENTER ||--o{ PROJECT : manages + DEVCENTER ||--o{ CATALOG : references + DEVCENTER ||--o{ ENVIRONMENT_TYPE : defines + + PROJECT ||--o{ POOL : contains + PROJECT ||--o{ PROJECT_CATALOG : references + PROJECT ||--o{ PROJECT_ENV_TYPE : enables + + POOL ||--|| IMAGE_DEFINITION : uses + CATALOG ||--o{ IMAGE_DEFINITION : provides + + KEY_VAULT ||--o{ SECRET : stores + CATALOG }|--|| SECRET : authenticates_with + + LOG_ANALYTICS ||--o{ DIAGNOSTIC_SETTING : receives_from + DEVCENTER ||--|| DIAGNOSTIC_SETTING : sends_to + KEY_VAULT ||--|| DIAGNOSTIC_SETTING : sends_to +``` + +--- + +## Configuration Data Model + +### Configuration File Hierarchy + +``` +infra/settings/ +β”œβ”€β”€ resourceOrganization/ +β”‚ β”œβ”€β”€ azureResources.yaml # Landing zone resource groups +β”‚ └── azureResources.schema.json +β”œβ”€β”€ security/ +β”‚ β”œβ”€β”€ security.yaml # Key Vault configuration +β”‚ └── security.schema.json +└── workload/ + β”œβ”€β”€ devcenter.yaml # DevCenter, projects, pools + └── devcenter.schema.json +``` + +### Resource Organization Configuration (`azureResources.yaml`) + +Defines the landing zone resource group structure following Azure Landing Zone +principles. + +```mermaid +classDiagram + class AzureResources { + +workload: LandingZone + +security: LandingZone + +monitoring: LandingZone + } + + class LandingZone { + +create: boolean + +name: string + +description: string + +tags: Tags + } + + class Tags { + +environment: string + +division: string + +team: string + +project: string + +costCenter: string + +owner: string + +landingZone: string + +resources: string + } + + AzureResources *-- LandingZone : contains 3 + LandingZone *-- Tags : has +``` + +#### Data Model Details + +| Entity | Field | Type | Required | Description | +| --------------- | ------------- | ------- | -------- | -------------------------------------- | +| **LandingZone** | `create` | boolean | Yes | Whether to create the resource group | +| | `name` | string | Yes | Base name for the resource group | +| | `description` | string | Yes | Purpose description | +| | `tags` | object | Yes | Resource tags | +| **Tags** | `environment` | string | Yes | Deployment environment (dev/test/prod) | +| | `division` | string | Yes | Business division | +| | `team` | string | Yes | Owning team | +| | `project` | string | Yes | Project name | +| | `costCenter` | string | Yes | Cost allocation center | +| | `owner` | string | Yes | Resource owner | + +### Security Configuration (`security.yaml`) + +Defines Azure Key Vault settings for secrets management. + +```mermaid +classDiagram + class SecurityConfig { + +create: boolean + +keyVault: KeyVaultConfig + } + + class KeyVaultConfig { + +name: string + +description: string + +secretName: string + +enablePurgeProtection: boolean + +enableSoftDelete: boolean + +softDeleteRetentionInDays: integer + +enableRbacAuthorization: boolean + +tags: Tags + } + + SecurityConfig *-- KeyVaultConfig : has + KeyVaultConfig *-- Tags : has +``` + +#### Security Configuration Details + +| Field | Type | Constraints | Default | Description | +| --------------------------- | ------- | ------------------------ | ----------- | ---------------------------------- | +| `name` | string | 3-24 chars, alphanumeric | - | Globally unique Key Vault name | +| `secretName` | string | - | `gha-token` | Name for the stored secret | +| `enablePurgeProtection` | boolean | - | `true` | Prevents permanent deletion | +| `enableSoftDelete` | boolean | - | `true` | Enables recovery window | +| `softDeleteRetentionInDays` | integer | 7-90 | `7` | Retention period for deleted items | +| `enableRbacAuthorization` | boolean | - | `true` | Use Azure RBAC vs access policies | + +### DevCenter Configuration (`devcenter.yaml`) + +The most complex configuration defining the entire workload structure. + +```mermaid +classDiagram + class DevCenterConfig { + +name: string + +catalogItemSyncEnableStatus: Status + +microsoftHostedNetworkEnableStatus: Status + +installAzureMonitorAgentEnableStatus: Status + +identity: Identity + +catalogs: Catalog[] + +environmentTypes: EnvironmentType[] + +projects: Project[] + +tags: Tags + } + + class Identity { + +type: string + +roleAssignments: RoleAssignments + } + + class RoleAssignments { + +devCenter: RBACRole[] + +orgRoleTypes: OrgRoleType[] + } + + class Project { + +name: string + +description: string + +network: NetworkConfig + +identity: ProjectIdentity + +pools: Pool[] + +environmentTypes: EnvironmentType[] + +catalogs: ProjectCatalog[] + +tags: Tags + } + + class Pool { + +name: string + +imageDefinitionName: string + +vmSku: string + } + + class Catalog { + +name: string + +type: CatalogType + +visibility: Visibility + +uri: string + +branch: string + +path: string + } + + class NetworkConfig { + +name: string + +create: boolean + +resourceGroupName: string + +virtualNetworkType: string + +addressPrefixes: string[] + +subnets: Subnet[] + +tags: Tags + } + + DevCenterConfig *-- Identity + DevCenterConfig *-- "1..*" Catalog + DevCenterConfig *-- "1..*" Project + Identity *-- RoleAssignments + Project *-- NetworkConfig + Project *-- "1..*" Pool + Project *-- "0..*" Catalog : projectCatalogs +``` + +#### DevCenter Entity Details + +| Entity | Field | Type | Description | +| ------------------- | -------------------------------------- | ---------------- | -------------------------------------------------- | +| **DevCenterConfig** | `name` | string | DevCenter resource name | +| | `catalogItemSyncEnableStatus` | Enabled/Disabled | Auto-sync catalog items | +| | `microsoftHostedNetworkEnableStatus` | Enabled/Disabled | Use Microsoft-hosted networks | +| | `installAzureMonitorAgentEnableStatus` | Enabled/Disabled | Install monitoring agent on Dev Boxes | +| **Project** | `name` | string | Project identifier | +| | `description` | string | Project description | +| | `network` | NetworkConfig | Network connectivity settings | +| | `pools` | Pool[] | Dev Box pool definitions | +| **Pool** | `name` | string | Pool identifier (e.g., `backend-engineer`) | +| | `imageDefinitionName` | string | Reference to catalog image | +| | `vmSku` | string | Azure VM SKU (e.g., `general_i_32c128gb512ssd_v2`) | +| **Catalog** | `type` | gitHub/adoGit | Source control type | +| | `visibility` | public/private | Repository visibility | +| | `uri` | string | Repository URL | +| | `branch` | string | Branch to sync | +| | `path` | string | Path within repository | + +--- + +## Secrets Management + +### Secret Types + +| Secret | Storage | Purpose | Consumers | Rotation | +| ------------------------- | ----------------------- | ------------------------------ | ------------------------------- | ----------------------------- | +| **GitHub PAT** | Key Vault (`gha-token`) | Private catalog authentication | DevCenter catalogs | Manual (recommended: 90 days) | +| **Azure DevOps PAT** | Key Vault | ADO catalog authentication | DevCenter catalogs | Manual (recommended: 90 days) | +| **Federated Credentials** | Azure AD | CI/CD authentication | GitHub Actions, Azure Pipelines | Automatic | + +### Secrets Flow Diagram + +```mermaid +sequenceDiagram + participant User as Platform Engineer + participant GH as GitHub/ADO + participant CLI as Azure CLI/azd + participant KV as Key Vault + participant DC as DevCenter + participant Cat as Catalog + + Note over User,Cat: Secret Provisioning Flow + + User->>GH: Generate PAT token + User->>CLI: azd provision (with secret) + CLI->>KV: Create/Update secret + KV-->>CLI: Secret URI returned + CLI->>DC: Configure DevCenter + DC->>Cat: Create catalog with secret reference + + Note over User,Cat: Secret Consumption Flow + + Cat->>KV: Request secret (via managed identity) + KV->>KV: Validate RBAC permissions + KV-->>Cat: Return secret value + Cat->>GH: Authenticate to repository + GH-->>Cat: Return catalog content +``` + +### Key Vault Access Model + +```mermaid +flowchart TD + subgraph Identity["Identity Sources"] + DC_MI[DevCenter
Managed Identity] + PROJ_MI[Project
Managed Identity] + ADMIN[Platform Engineers
Azure AD Group] + end + + subgraph KV["Key Vault"] + SECRET[gha-token
Secret] + end + + subgraph Roles["RBAC Roles"] + R1[Key Vault
Secrets User] + R2[Key Vault
Secrets Officer] + end + + DC_MI --> R1 + DC_MI --> R2 + PROJ_MI --> R1 + PROJ_MI --> R2 + ADMIN --> R2 + + R1 --> |Get, List| SECRET + R2 --> |Get, List, Set, Delete| SECRET +``` + +### Secret Security Controls + +| Control | Implementation | Purpose | +| ---------------------- | ------------------------------------ | ------------------------------------------- | +| **RBAC Authorization** | `enableRbacAuthorization: true` | Granular access control via Azure RBAC | +| **Soft Delete** | `enableSoftDelete: true` | Recover accidentally deleted secrets | +| **Purge Protection** | `enablePurgeProtection: true` | Prevent permanent deletion during retention | +| **Retention Period** | `softDeleteRetentionInDays: 7` | Recovery window for deleted secrets | +| **Diagnostic Logging** | Log Analytics integration | Audit all secret operations | +| **Managed Identities** | SystemAssigned on DevCenter/Projects | Eliminate credential storage in code | + +--- + +## Telemetry & Diagnostics + +### Log Analytics Data Collection + +```mermaid +flowchart LR + subgraph Sources["Data Sources"] + DC[DevCenter] + KV[Key Vault] + VNET[Virtual Network] + LA_SELF[Log Analytics] + end + + subgraph LA["Log Analytics Workspace"] + LOGS[Logs] + METRICS[Metrics] + SOLUTIONS[Solutions] + end + + subgraph Outputs["Outputs"] + ALERTS[Alerts] + DASHBOARDS[Dashboards] + QUERIES[KQL Queries] + end + + DC -->|allLogs, AllMetrics| LOGS + KV -->|allLogs, AllMetrics| LOGS + VNET -->|allLogs, AllMetrics| LOGS + LA_SELF -->|allLogs, AllMetrics| LOGS + + LOGS --> ALERTS + LOGS --> DASHBOARDS + METRICS --> DASHBOARDS + LOGS --> QUERIES +``` + +### Diagnostic Settings Configuration + +All resources deploy with standardized diagnostic settings: + +| Resource | Log Categories | Metric Categories | Destination | +| ------------------- | -------------- | ----------------- | ----------------------- | +| **DevCenter** | allLogs | AllMetrics | Log Analytics Workspace | +| **Key Vault** | allLogs | AllMetrics | Log Analytics Workspace | +| **Virtual Network** | allLogs | AllMetrics | Log Analytics Workspace | +| **Log Analytics** | allLogs | AllMetrics | Self (workspace) | + +### Telemetry Data Model + +```mermaid +erDiagram + LOG_ANALYTICS_WORKSPACE ||--o{ AZURE_DIAGNOSTICS : receives + LOG_ANALYTICS_WORKSPACE ||--o{ AZURE_METRICS : receives + LOG_ANALYTICS_WORKSPACE ||--|| AZURE_ACTIVITY_SOLUTION : has + + AZURE_DIAGNOSTICS { + string TimeGenerated + string ResourceId + string Category + string OperationName + string ResultType + string Properties + } + + AZURE_METRICS { + string TimeGenerated + string ResourceId + string MetricName + float Total + float Average + float Maximum + float Minimum + } +``` + +### Data Retention + +| Data Type | Default Retention | Configurable | Purpose | +| ----------------- | ----------------- | ----------------- | --------------------------- | +| **Logs** | 30 days | Yes (30-730 days) | Operational troubleshooting | +| **Metrics** | 93 days | No | Performance analysis | +| **Activity Logs** | 90 days | No | Audit trail | +| **Security Logs** | 90 days | Yes | Compliance | + +--- + +## Data Flow Diagrams + +### Configuration Loading Flow + +```mermaid +flowchart TD + subgraph Git["Git Repository"] + YAML1[azureResources.yaml] + YAML2[security.yaml] + YAML3[devcenter.yaml] + end + + subgraph Bicep["Bicep Processing"] + MAIN[main.bicep] + LOAD1["loadYamlContent()
resourceOrganization"] + LOAD2["loadYamlContent()
security"] + LOAD3["loadYamlContent()
workload"] + end + + subgraph Modules["Module Deployment"] + MOD1[logAnalytics.bicep] + MOD2[security.bicep] + MOD3[workload.bicep] + end + + subgraph Azure["Azure Resources"] + RG[Resource Groups] + LA[Log Analytics] + KV[Key Vault] + DC[DevCenter] + end + + YAML1 --> LOAD1 + YAML2 --> LOAD2 + YAML3 --> LOAD3 + + MAIN --> LOAD1 + MAIN --> LOAD2 + MAIN --> LOAD3 + + LOAD1 --> MOD1 + LOAD1 --> MOD2 + LOAD1 --> MOD3 + + LOAD2 --> MOD2 + LOAD3 --> MOD3 + + MOD1 --> LA + MOD2 --> KV + MOD3 --> DC + + MAIN --> RG +``` + +### Deployment Data Flow + +```mermaid +flowchart LR + subgraph Input["Input Data"] + ENV[Environment Name] + LOC[Location] + SECRET[Secret Value] + end + + subgraph Transform["Parameter Transformation"] + SUFFIX["resourceNameSuffix =
{env}-{location}-RG"] + RGNAMES["createResourceGroupName =
{zone.name}-{suffix}"] + end + + subgraph Output["Output Resources"] + SEC_RG[Security RG] + MON_RG[Monitoring RG] + WRK_RG[Workload RG] + end + + ENV --> SUFFIX + LOC --> SUFFIX + SUFFIX --> RGNAMES + RGNAMES --> SEC_RG + RGNAMES --> MON_RG + RGNAMES --> WRK_RG +``` + +### Cross-Module Data Dependencies + +```mermaid +flowchart TD + subgraph main["main.bicep (Subscription Scope)"] + M_IN[/"Parameters:
location, secretValue,
environmentName"/] + end + + subgraph monitoring["monitoring module"] + LA[Log Analytics] + LA_OUT[/"Output:
AZURE_LOG_ANALYTICS_WORKSPACE_ID"/] + end + + subgraph security["security module"] + KV[Key Vault + Secret] + SEC_OUT[/"Output:
AZURE_KEY_VAULT_SECRET_IDENTIFIER"/] + end + + subgraph workload["workload module"] + DC[DevCenter] + PROJ[Projects] + end + + M_IN --> LA + LA --> LA_OUT + + LA_OUT -->|logAnalyticsId| KV + M_IN -->|secretValue| KV + KV --> SEC_OUT + + LA_OUT -->|logAnalyticsId| DC + SEC_OUT -->|secretIdentifier| DC + + DC --> PROJ +``` + +--- + +## Data Governance + +### Data Classification + +| Classification | Examples | Controls | Access | +| ---------------- | ---------------------------- | --------------------- | --------------------- | +| **Public** | Documentation, schemas | Version control | Anyone | +| **Internal** | Configuration YAML, tags | Git repository | Organization | +| **Confidential** | PAT tokens, credentials | Key Vault + RBAC | Authorized identities | +| **Restricted** | Tenant IDs, subscription IDs | Environment variables | CI/CD pipelines | + +### Compliance Considerations + +| Framework | Requirement | Implementation | +| ---------------- | ------------------ | ------------------------------------------ | +| **SOC 2** | Access logging | Key Vault diagnostic logs to Log Analytics | +| **ISO 27001** | Secrets encryption | Key Vault with software-protected keys | +| **GDPR** | Data minimization | No PII in configuration files | +| **Azure Policy** | Tagging compliance | Mandatory tags on all resources | + +### Data Lineage + +```mermaid +flowchart LR + subgraph Source["Source of Truth"] + GIT[Git Repository] + end + + subgraph CI["CI/CD"] + GHA[GitHub Actions] + ADO[Azure DevOps] + end + + subgraph Deploy["Deployment"] + AZD[azd CLI] + ARM[ARM/Bicep] + end + + subgraph Runtime["Runtime"] + AZ[Azure Resources] + end + + subgraph Audit["Audit Trail"] + LA[Log Analytics] + ACT[Activity Log] + end + + GIT -->|Push| GHA + GIT -->|Push| ADO + GHA -->|azd provision| AZD + ADO -->|azd provision| AZD + AZD -->|Deploy| ARM + ARM -->|Create/Update| AZ + AZ -->|Diagnostics| LA + AZ -->|Operations| ACT +``` + +### Data Quality Rules + +| Rule | Enforcement | Validation | +| ---------------------- | ----------------------------- | ---------------------------------- | +| **Schema Validation** | JSON Schema files | YAML files must conform to schemas | +| **Required Fields** | Schema `required` arrays | Deployment fails if missing | +| **Value Constraints** | Schema patterns, enums | Invalid values rejected | +| **Naming Conventions** | Bicep `@minLength/@maxLength` | Enforced at deployment | +| **Tag Requirements** | Azure Policy | Post-deployment compliance | + +--- + +## Schema Documentation + +### JSON Schema Files + +#### `azureResources.schema.json` + +Validates landing zone resource group configuration. + +| Property Path | Type | Constraints | Description | +| ------------------- | ------- | ----------- | -------------------- | +| `workload.create` | boolean | Required | Create workload RG | +| `workload.name` | string | Required | RG base name | +| `workload.tags` | object | Required | Resource tags | +| `security.create` | boolean | Required | Create security RG | +| `security.name` | string | Required | RG base name | +| `monitoring.create` | boolean | Required | Create monitoring RG | +| `monitoring.name` | string | Required | RG base name | + +#### `security.schema.json` + +Validates Key Vault security configuration. + +| Property Path | Type | Constraints | Description | +| ------------------------------------ | ------- | ------------------------------------------- | ---------------- | +| `create` | boolean | Required | Create Key Vault | +| `keyVault.name` | string | 3-24 chars, pattern: `^[a-zA-Z0-9-]{3,24}$` | KV name | +| `keyVault.enablePurgeProtection` | boolean | - | Purge protection | +| `keyVault.softDeleteRetentionInDays` | integer | 7-90 | Retention days | +| `keyVault.tags.environment` | string | enum: dev/test/staging/prod | Environment tag | + +#### `devcenter.schema.json` + +Validates DevCenter workload configuration. + +| Property Path | Type | Constraints | Description | +| -------------------------------------- | ------ | -------------------------------------- | --------------------- | +| `name` | string | minLength: 1 | DevCenter name | +| `identity.type` | string | enum: SystemAssigned/UserAssigned/etc. | Identity type | +| `catalogs[].type` | string | - | Catalog source type | +| `catalogs[].visibility` | string | enum: public/private | Repository visibility | +| `projects[].pools[].vmSku` | string | - | VM SKU for pool | +| `projects[].network.addressPrefixes[]` | string | CIDR pattern | VNet address space | + +### Schema Validation Flow + +```mermaid +flowchart TD + YAML[YAML Configuration File] + SCHEMA[JSON Schema] + VALIDATOR[YAML Language Server] + + YAML --> VALIDATOR + SCHEMA --> VALIDATOR + + VALIDATOR -->|Valid| SUCCESS[βœ… Proceed to Deployment] + VALIDATOR -->|Invalid| ERROR[❌ Validation Errors] + + ERROR --> FIX[Fix Configuration] + FIX --> YAML +``` + +--- + +## References + +### External References + +| Reference | URL | Description | +| ------------------------------ | --------------------------------------------------------------------------- | ----------------- | +| Azure Key Vault Best Practices | https://learn.microsoft.com/azure/key-vault/general/best-practices | Security guidance | +| Log Analytics Documentation | https://learn.microsoft.com/azure/azure-monitor/logs/log-analytics-overview | Monitoring setup | +| JSON Schema Specification | https://json-schema.org/specification | Schema validation | + +### Related Architecture Documents + +| Document | Path | Description | +| ------------------------ | ------------------------------------------------------------------ | --------------------------------- | +| Business Architecture | [01-business-architecture.md](./01-business-architecture.md) | Business context and stakeholders | +| Application Architecture | [03-application-architecture.md](./03-application-architecture.md) | Bicep module architecture | +| Technology Architecture | [04-technology-architecture.md](./04-technology-architecture.md) | Azure services and infrastructure | + +--- + +## Glossary + +| Term | Definition | +| ----------------------- | ------------------------------------------------------------------------------ | +| **loadYamlContent()** | Bicep function that loads YAML files as typed objects at compile time | +| **Diagnostic Settings** | Azure configuration that routes logs and metrics to destinations | +| **RBAC Authorization** | Key Vault access model using Azure role assignments instead of access policies | +| **Soft Delete** | Feature that retains deleted Key Vault objects for recovery | +| **Purge Protection** | Feature that prevents permanent deletion during retention period | +| **PAT** | Personal Access Token for Git repository authentication | +| **Managed Identity** | Azure AD identity automatically managed by Azure for service authentication | +| **KQL** | Kusto Query Language used for Log Analytics queries | + +--- + +_This document follows TOGAF Architecture Development Method (ADM) principles +and aligns with the Data Architecture domain of the BDAT framework._ From a8a7e1573f57dbea291d47d89ecc5b7b2cabdb9a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 14:48:55 -0500 Subject: [PATCH 04/49] Add comprehensive Application Architecture documentation for DevExp-DevBox --- .../03-application-architecture.md | 1026 +++++++++++++++++ 1 file changed, 1026 insertions(+) create mode 100644 docs/architecture/03-application-architecture.md diff --git a/docs/architecture/03-application-architecture.md b/docs/architecture/03-application-architecture.md new file mode 100644 index 00000000..b970f758 --- /dev/null +++ b/docs/architecture/03-application-architecture.md @@ -0,0 +1,1026 @@ +# Application Architecture + +> **DevExp-DevBox Landing Zone Accelerator** + +| Metadata | Value | +|----------|-------| +| **Version** | 1.0.0 | +| **Last Updated** | January 22, 2026 | +| **Author** | Platform Engineering Team | +| **Status** | Active | + +--- + +## Table of Contents + +- [Architecture Overview](#architecture-overview) +- [Module Catalog](#module-catalog) +- [Module Dependencies](#module-dependencies) +- [Deployment Orchestration](#deployment-orchestration) +- [Interface Contracts](#interface-contracts) +- [Design Patterns](#design-patterns) +- [Extension Points](#extension-points) +- [References](#references) +- [Glossary](#glossary) + +--- + +## Architecture Overview + +The DevExp-DevBox Landing Zone Accelerator implements a **modular Bicep architecture** following Azure Landing Zone patterns. The solution is organized into four distinct landing zones, each with dedicated resource groups and specialized Bicep modules. + +### Landing Zone Architecture + +```mermaid +flowchart TB + subgraph Subscription["Azure Subscription"] + subgraph Main["main.bicep (Orchestrator)"] + PARAMS[/"Parameters:
location, secretValue,
environmentName"/] + end + + subgraph Security["Security Landing Zone"] + SEC_RG[Security Resource Group] + KV[Key Vault] + SECRET[Secrets] + end + + subgraph Monitoring["Monitoring Landing Zone"] + MON_RG[Monitoring Resource Group] + LA[Log Analytics Workspace] + SOL[Solutions] + end + + subgraph Connectivity["Connectivity Landing Zone"] + CON_RG[Connectivity Resource Group] + VNET[Virtual Network] + SUBNET[Subnets] + NC[Network Connection] + end + + subgraph Workload["Workload Landing Zone"] + WRK_RG[Workload Resource Group] + DC[DevCenter] + CAT[Catalogs] + ENV[Environment Types] + PROJ[Projects] + POOL[Pools] + end + end + + PARAMS --> SEC_RG + PARAMS --> MON_RG + PARAMS --> WRK_RG + + MON_RG --> LA + LA --> SOL + + SEC_RG --> KV + KV --> SECRET + + WRK_RG --> DC + DC --> CAT + DC --> ENV + DC --> PROJ + PROJ --> POOL + + PROJ -.->|Optional| CON_RG + CON_RG --> VNET + VNET --> SUBNET + SUBNET --> NC + NC --> DC + + LA -.->|Diagnostics| KV + LA -.->|Diagnostics| DC + LA -.->|Diagnostics| VNET + + SECRET -.->|Auth| CAT +``` + +### Architecture Principles + +| Principle | Description | Implementation | +|-----------|-------------|----------------| +| **Modularity** | Each module has a single responsibility | Separate `.bicep` files per resource type | +| **Declarative Configuration** | Infrastructure defined as code | YAML configuration files with JSON schemas | +| **Separation of Concerns** | Landing zones isolate different functions | Resource groups by security, monitoring, workload | +| **Least Privilege** | Minimal permissions per identity | Scoped RBAC role assignments | +| **Configuration as Code** | All settings version controlled | Git repository with YAML files | +| **Idempotency** | Repeated deployments yield same result | Bicep's declarative model | + +--- + +## Module Catalog + +### Module Hierarchy + +``` +src/ +β”œβ”€β”€ connectivity/ # Network infrastructure +β”‚ β”œβ”€β”€ connectivity.bicep # Network orchestrator +β”‚ β”œβ”€β”€ networkConnection.bicep # DevCenter network connection +β”‚ β”œβ”€β”€ resourceGroup.bicep # Dynamic RG creation +β”‚ └── vnet.bicep # Virtual network +β”œβ”€β”€ identity/ # RBAC and identity +β”‚ β”œβ”€β”€ devCenterRoleAssignment.bicep +β”‚ β”œβ”€β”€ devCenterRoleAssignmentRG.bicep +β”‚ β”œβ”€β”€ keyVaultAccess.bicep +β”‚ β”œβ”€β”€ orgRoleAssignment.bicep +β”‚ β”œβ”€β”€ projectIdentityRoleAssignment.bicep +β”‚ └── projectIdentityRoleAssignmentRG.bicep +β”œβ”€β”€ management/ # Monitoring resources +β”‚ └── logAnalytics.bicep +β”œβ”€β”€ security/ # Security resources +β”‚ β”œβ”€β”€ keyVault.bicep +β”‚ β”œβ”€β”€ secret.bicep +β”‚ └── security.bicep # Security orchestrator +└── workload/ # DevCenter resources + β”œβ”€β”€ workload.bicep # Workload orchestrator + β”œβ”€β”€ core/ + β”‚ β”œβ”€β”€ catalog.bicep + β”‚ β”œβ”€β”€ devCenter.bicep + β”‚ └── environmentType.bicep + └── project/ + β”œβ”€β”€ project.bicep + β”œβ”€β”€ projectCatalog.bicep + β”œβ”€β”€ projectEnvironmentType.bicep + └── projectPool.bicep +``` + +--- + +### Module: main.bicep + +- **Path**: `infra/main.bicep` +- **Scope**: Subscription +- **Purpose**: Top-level orchestrator that creates resource groups and coordinates all module deployments + +**Inputs**: + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `location` | string | Yes | Azure region (validated against allowed list) | +| `secretValue` | securestring | Yes | GitHub/ADO PAT token | +| `environmentName` | string | Yes | Environment name (2-10 chars) | + +**Outputs**: + +| Output | Type | Description | +|--------|------|-------------| +| `SECURITY_AZURE_RESOURCE_GROUP_NAME` | string | Security RG name | +| `MONITORING_AZURE_RESOURCE_GROUP_NAME` | string | Monitoring RG name | +| `WORKLOAD_AZURE_RESOURCE_GROUP_NAME` | string | Workload RG name | +| `AZURE_LOG_ANALYTICS_WORKSPACE_ID` | string | Log Analytics resource ID | +| `AZURE_LOG_ANALYTICS_WORKSPACE_NAME` | string | Log Analytics workspace name | +| `AZURE_KEY_VAULT_NAME` | string | Key Vault name | +| `AZURE_KEY_VAULT_SECRET_IDENTIFIER` | string | Secret URI | +| `AZURE_KEY_VAULT_ENDPOINT` | string | Key Vault URI | +| `AZURE_DEV_CENTER_NAME` | string | DevCenter name | +| `AZURE_DEV_CENTER_PROJECTS` | array | List of project names | + +**Dependencies**: None (entry point) + +**Dependents**: All other modules + +--- + +### Module: logAnalytics.bicep + +- **Path**: `src/management/logAnalytics.bicep` +- **Scope**: Resource Group (Monitoring) +- **Purpose**: Deploy Log Analytics workspace for centralized monitoring + +**Inputs**: + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `name` | string | Yes | - | Base name (4-49 chars) | +| `location` | string | No | resourceGroup().location | Azure region | +| `tags` | object | No | {} | Resource tags | +| `sku` | string | No | PerGB2018 | Workspace SKU | + +**Outputs**: + +| Output | Type | Description | +|--------|------|-------------| +| `AZURE_LOG_ANALYTICS_WORKSPACE_ID` | string | Workspace resource ID | +| `AZURE_LOG_ANALYTICS_WORKSPACE_NAME` | string | Workspace name | + +**Dependencies**: Monitoring resource group + +**Dependents**: `security.bicep`, `workload.bicep`, `vnet.bicep` + +**Resources Created**: +- `Microsoft.OperationalInsights/workspaces` - Log Analytics workspace +- `Microsoft.OperationsManagement/solutions` - Azure Activity solution +- `Microsoft.Insights/diagnosticSettings` - Self-diagnostics + +--- + +### Module: security.bicep + +- **Path**: `src/security/security.bicep` +- **Scope**: Resource Group (Security) +- **Purpose**: Orchestrate Key Vault and secret deployment + +**Inputs**: + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `tags` | object | Yes | Resource tags | +| `secretValue` | securestring | Yes | Secret content | +| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | + +**Outputs**: + +| Output | Type | Description | +|--------|------|-------------| +| `AZURE_KEY_VAULT_NAME` | string | Key Vault name | +| `AZURE_KEY_VAULT_SECRET_IDENTIFIER` | string | Secret URI | +| `AZURE_KEY_VAULT_ENDPOINT` | string | Key Vault endpoint | + +**Dependencies**: `logAnalytics.bicep` + +**Dependents**: `workload.bicep` + +--- + +### Module: keyVault.bicep + +- **Path**: `src/security/keyVault.bicep` +- **Scope**: Resource Group (Security) +- **Purpose**: Deploy Azure Key Vault with security configuration + +**Inputs**: + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `keyvaultSettings` | object | Yes | Key Vault configuration from YAML | +| `location` | string | No | Azure region | +| `tags` | object | Yes | Resource tags | +| `unique` | string | No | Unique suffix for naming | + +**Outputs**: + +| Output | Type | Description | +|--------|------|-------------| +| `AZURE_KEY_VAULT_NAME` | string | Key Vault name | +| `AZURE_KEY_VAULT_ENDPOINT` | string | Vault URI | + +**Dependencies**: Security resource group + +**Dependents**: `secret.bicep` + +**Resources Created**: +- `Microsoft.KeyVault/vaults` - Key Vault with RBAC, soft delete, purge protection + +--- + +### Module: secret.bicep + +- **Path**: `src/security/secret.bicep` +- **Scope**: Resource Group (Security) +- **Purpose**: Create secrets in Key Vault with diagnostic settings + +**Inputs**: + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `name` | string | Yes | Secret name | +| `secretValue` | securestring | Yes | Secret content | +| `keyVaultName` | string | Yes | Target Key Vault | +| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | + +**Outputs**: + +| Output | Type | Description | +|--------|------|-------------| +| `AZURE_KEY_VAULT_SECRET_IDENTIFIER` | string | Secret URI | + +**Dependencies**: `keyVault.bicep`, `logAnalytics.bicep` + +**Dependents**: `catalog.bicep`, `projectCatalog.bicep` + +--- + +### Module: workload.bicep + +- **Path**: `src/workload/workload.bicep` +- **Scope**: Resource Group (Workload) +- **Purpose**: Orchestrate DevCenter and project deployments + +**Inputs**: + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | +| `secretIdentifier` | securestring | Yes | Key Vault secret URI | +| `securityResourceGroupName` | string | Yes | Security RG for RBAC | +| `location` | string | No | Azure region | + +**Outputs**: + +| Output | Type | Description | +|--------|------|-------------| +| `AZURE_DEV_CENTER_NAME` | string | DevCenter name | +| `AZURE_DEV_CENTER_PROJECTS` | array | List of project names | + +**Dependencies**: `logAnalytics.bicep`, `security.bicep` + +**Dependents**: None (terminal module) + +--- + +### Module: devCenter.bicep + +- **Path**: `src/workload/core/devCenter.bicep` +- **Scope**: Resource Group (Workload) +- **Purpose**: Deploy DevCenter with identity, catalogs, and environment types + +**Inputs**: + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `config` | DevCenterConfig | Yes | DevCenter configuration | +| `catalogs` | array | Yes | Catalog definitions | +| `environmentTypes` | array | Yes | Environment type definitions | +| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | +| `secretIdentifier` | securestring | Yes | Secret for private catalogs | +| `securityResourceGroupName` | string | Yes | Security RG name | +| `location` | string | No | Azure region | + +**Outputs**: + +| Output | Type | Description | +|--------|------|-------------| +| `AZURE_DEV_CENTER_NAME` | string | DevCenter name | + +**Dependencies**: `logAnalytics.bicep`, `secret.bicep` + +**Dependents**: `project.bicep`, `catalog.bicep`, `environmentType.bicep` + +**Resources Created**: +- `Microsoft.DevCenter/devcenters` - DevCenter resource +- `Microsoft.Insights/diagnosticSettings` - Diagnostic settings +- Role assignments via identity modules +- Catalogs via `catalog.bicep` +- Environment types via `environmentType.bicep` + +--- + +### Module: project.bicep + +- **Path**: `src/workload/project/project.bicep` +- **Scope**: Resource Group (Workload) +- **Purpose**: Deploy DevCenter project with identity, catalogs, pools + +**Inputs**: + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `devCenterName` | string | Yes | Parent DevCenter | +| `name` | string | Yes | Project name | +| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | +| `projectDescription` | string | Yes | Project description | +| `catalogs` | object[] | Yes | Project-specific catalogs | +| `projectEnvironmentTypes` | array | Yes | Enabled environment types | +| `projectPools` | array | Yes | Dev Box pool definitions | +| `projectNetwork` | object | Yes | Network configuration | +| `secretIdentifier` | securestring | Yes | Secret for private catalogs | +| `securityResourceGroupName` | string | Yes | Security RG name | +| `identity` | Identity | Yes | Project identity config | +| `tags` | object | No | Resource tags | +| `location` | string | No | Azure region | + +**Outputs**: + +| Output | Type | Description | +|--------|------|-------------| +| `AZURE_PROJECT_NAME` | string | Project name | + +**Dependencies**: `devCenter.bicep` + +**Dependents**: `projectPool.bicep`, `projectCatalog.bicep`, `projectEnvironmentType.bicep` + +--- + +### Module: projectPool.bicep + +- **Path**: `src/workload/project/projectPool.bicep` +- **Scope**: Resource Group (Workload) +- **Purpose**: Create Dev Box pools within a project + +**Inputs**: + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `name` | string | Yes | Pool name (e.g., `backend-engineer`) | +| `location` | string | No | Azure region | +| `catalogs` | Catalog[] | Yes | Catalog references for images | +| `imageDefinitionName` | string | Yes | Image definition name | +| `networkConnectionName` | string | Yes | Network connection name | +| `vmSku` | string | Yes | VM SKU (e.g., `general_i_32c128gb512ssd_v2`) | +| `networkType` | string | Yes | Managed or Unmanaged | +| `projectName` | string | Yes | Parent project | + +**Outputs**: None + +**Dependencies**: `project.bicep`, `connectivity.bicep`, `projectCatalog.bicep` + +**Dependents**: None (terminal module) + +**Resources Created**: +- `Microsoft.DevCenter/projects/pools` - Dev Box pool + +--- + +### Module: catalog.bicep + +- **Path**: `src/workload/core/catalog.bicep` +- **Scope**: Resource Group (Workload) +- **Purpose**: Create DevCenter-level catalogs from Git repositories + +**Inputs**: + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `devCenterName` | string | Yes | Parent DevCenter | +| `catalogConfig` | Catalog | Yes | Catalog configuration | +| `secretIdentifier` | securestring | Yes | Secret for private repos | + +**Outputs**: + +| Output | Type | Description | +|--------|------|-------------| +| `AZURE_DEV_CENTER_CATALOG_NAME` | string | Catalog name | +| `AZURE_DEV_CENTER_CATALOG_ID` | string | Catalog resource ID | +| `AZURE_DEV_CENTER_CATALOG_TYPE` | string | Catalog type (gitHub/adoGit) | + +**Dependencies**: `devCenter.bicep`, `secret.bicep` + +**Dependents**: `projectPool.bicep` + +--- + +### Module: connectivity.bicep + +- **Path**: `src/connectivity/connectivity.bicep` +- **Scope**: Resource Group (Workload/Connectivity) +- **Purpose**: Orchestrate network infrastructure for projects + +**Inputs**: + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `devCenterName` | string | Yes | DevCenter name | +| `projectNetwork` | object | Yes | Network configuration | +| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | +| `location` | string | Yes | Azure region | + +**Outputs**: + +| Output | Type | Description | +|--------|------|-------------| +| `networkConnectionName` | string | Network connection name | +| `networkType` | string | Managed or Unmanaged | + +**Dependencies**: `devCenter.bicep`, `logAnalytics.bicep` + +**Dependents**: `projectPool.bicep` + +--- + +### Module: vnet.bicep + +- **Path**: `src/connectivity/vnet.bicep` +- **Scope**: Resource Group (Connectivity) +- **Purpose**: Create or reference virtual networks + +**Inputs**: + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | +| `location` | string | Yes | Azure region | +| `tags` | object | No | Resource tags | +| `settings` | object | Yes | Network settings (name, type, subnets) | + +**Outputs**: + +| Output | Type | Description | +|--------|------|-------------| +| `AZURE_VIRTUAL_NETWORK` | object | VNet details (name, RG, subnets) | + +**Dependencies**: Connectivity resource group + +**Dependents**: `networkConnection.bicep` + +**Resources Created**: +- `Microsoft.Network/virtualNetworks` - Virtual network (if create=true) +- `Microsoft.Insights/diagnosticSettings` - VNet diagnostics + +--- + +### Module: networkConnection.bicep + +- **Path**: `src/connectivity/networkConnection.bicep` +- **Scope**: Resource Group (Workload) +- **Purpose**: Create DevCenter network connection to VNet + +**Inputs**: + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `devCenterName` | string | Yes | DevCenter name | +| `name` | string | Yes | Connection name | +| `subnetId` | string | Yes | Target subnet resource ID | + +**Outputs**: + +| Output | Type | Description | +|--------|------|-------------| +| `networkConnectionName` | string | Network connection name | + +**Dependencies**: `vnet.bicep`, `devCenter.bicep` + +**Dependents**: `projectPool.bicep` + +--- + +### Identity Modules + +| Module | Path | Purpose | +|--------|------|---------| +| `devCenterRoleAssignment.bicep` | `src/identity/` | Subscription-scope role assignments for DevCenter managed identity | +| `devCenterRoleAssignmentRG.bicep` | `src/identity/` | Resource group-scope role assignments for DevCenter managed identity | +| `projectIdentityRoleAssignment.bicep` | `src/identity/` | Project-scope role assignments for project managed identity | +| `projectIdentityRoleAssignmentRG.bicep` | `src/identity/` | Security RG role assignments for project managed identity | +| `orgRoleAssignment.bicep` | `src/identity/` | Role assignments for organizational AD groups | +| `keyVaultAccess.bicep` | `src/identity/` | Key Vault access configuration | + +--- + +## Module Dependencies + +### Dependency Graph + +```mermaid +flowchart TD + subgraph Entry["Entry Point"] + MAIN[main.bicep] + end + + subgraph Management["Management Layer"] + LA[logAnalytics.bicep] + end + + subgraph Security["Security Layer"] + SEC[security.bicep] + KV[keyVault.bicep] + SECRET[secret.bicep] + end + + subgraph Workload["Workload Layer"] + WRK[workload.bicep] + DC[devCenter.bicep] + CAT[catalog.bicep] + ENV[environmentType.bicep] + PROJ[project.bicep] + PCAT[projectCatalog.bicep] + PENV[projectEnvironmentType.bicep] + POOL[projectPool.bicep] + end + + subgraph Connectivity["Connectivity Layer"] + CONN[connectivity.bicep] + VNET[vnet.bicep] + NC[networkConnection.bicep] + RG[resourceGroup.bicep] + end + + subgraph Identity["Identity Layer"] + DCRA[devCenterRoleAssignment] + DCRA_RG[devCenterRoleAssignmentRG] + PRA[projectIdentityRoleAssignment] + PRA_RG[projectIdentityRoleAssignmentRG] + ORA[orgRoleAssignment] + end + + MAIN --> LA + MAIN --> SEC + MAIN --> WRK + + SEC --> KV + SEC --> SECRET + KV --> SECRET + LA --> SECRET + + WRK --> DC + WRK --> PROJ + LA --> DC + SECRET --> DC + + DC --> CAT + DC --> ENV + DC --> DCRA + DC --> DCRA_RG + DC --> ORA + + PROJ --> PCAT + PROJ --> PENV + PROJ --> POOL + PROJ --> CONN + PROJ --> PRA + PROJ --> PRA_RG + + CONN --> RG + CONN --> VNET + CONN --> NC + LA --> VNET + + NC --> DC +``` + +### Dependency Matrix + +| Module | Depends On | Provides To | +|--------|------------|-------------| +| `main.bicep` | - | All modules | +| `logAnalytics.bicep` | main | security, workload, connectivity | +| `keyVault.bicep` | main | secret | +| `secret.bicep` | keyVault, logAnalytics | devCenter, catalog | +| `security.bicep` | logAnalytics | workload | +| `devCenter.bicep` | logAnalytics, secret | project, catalog, envType | +| `project.bicep` | devCenter | pool, projectCatalog, projectEnvType | +| `connectivity.bicep` | devCenter, logAnalytics | projectPool | +| `projectPool.bicep` | project, connectivity, projectCatalog | - | + +--- + +## Deployment Orchestration + +### Deployment Sequence + +```mermaid +sequenceDiagram + participant User as Platform Engineer + participant AZD as Azure Developer CLI + participant ARM as Azure Resource Manager + participant RG as Resource Groups + participant MON as Monitoring Module + participant SEC as Security Module + participant WRK as Workload Module + + User->>AZD: azd provision + AZD->>ARM: Deploy main.bicep + + par Create Resource Groups + ARM->>RG: Create Security RG + ARM->>RG: Create Monitoring RG + ARM->>RG: Create Workload RG + end + + ARM->>MON: Deploy logAnalytics.bicep + MON-->>ARM: AZURE_LOG_ANALYTICS_WORKSPACE_ID + + ARM->>SEC: Deploy security.bicep + Note over SEC: Uses logAnalyticsId + SEC-->>ARM: AZURE_KEY_VAULT_SECRET_IDENTIFIER + + ARM->>WRK: Deploy workload.bicep + Note over WRK: Uses logAnalyticsId, secretIdentifier + + WRK->>WRK: Deploy devCenter.bicep + WRK->>WRK: Deploy project.bicep (loop) + + WRK-->>ARM: AZURE_DEV_CENTER_NAME, AZURE_DEV_CENTER_PROJECTS + ARM-->>AZD: Deployment outputs + AZD-->>User: Deployment complete +``` + +### Deployment Scopes + +| Scope | Modules | Purpose | +|-------|---------|---------| +| **Subscription** | `main.bicep`, `devCenterRoleAssignment.bicep` | Create RGs, subscription-level RBAC | +| **Security RG** | `keyVault.bicep`, `secret.bicep` | Security resources | +| **Monitoring RG** | `logAnalytics.bicep` | Monitoring resources | +| **Workload RG** | `devCenter.bicep`, `project.bicep`, `projectPool.bicep` | DevCenter resources | +| **Connectivity RG** | `vnet.bicep`, `networkConnection.bicep` | Network resources (conditional) | + +### Deployment Commands + +```bash +# Initialize environment +azd init + +# Provision infrastructure +azd provision --no-prompt + +# Full deployment with environment +azd provision -e dev --no-prompt +``` + +--- + +## Interface Contracts + +### Module Parameter Types + +```bicep +// DevCenter configuration type +type DevCenterConfig = { + name: string + identity: Identity + catalogItemSyncEnableStatus: Status + microsoftHostedNetworkEnableStatus: Status + installAzureMonitorAgentEnableStatus: Status + tags: object +} + +// Identity configuration type +type Identity = { + type: string + roleAssignments: RoleAssignment +} + +// Role assignment configuration +type RoleAssignment = { + devCenter: AzureRBACRole[] + orgRoleTypes: OrgRoleType[] +} + +// Azure RBAC role definition +type AzureRBACRole = { + id: string + name: string + scope: string +} + +// Catalog type definition +type Catalog = { + name: string + type: CatalogType // 'gitHub' | 'adoGit' + visibility: 'public' | 'private' + uri: string + branch: string + path: string +} + +// Network settings type +type NetworkSettings = { + name: string + virtualNetworkType: 'Unmanaged' | 'Managed' + create: bool + resourceGroupName: string + addressPrefixes: string[] + subnets: object[] + tags: object +} +``` + +### Output Contract Summary + +| Module | Key Output | Type | Consumer | +|--------|------------|------|----------| +| `logAnalytics` | `AZURE_LOG_ANALYTICS_WORKSPACE_ID` | string | security, workload, connectivity | +| `security` | `AZURE_KEY_VAULT_SECRET_IDENTIFIER` | string | workload (catalogs) | +| `devCenter` | `AZURE_DEV_CENTER_NAME` | string | projects, network connections | +| `connectivity` | `networkConnectionName` | string | projectPool | +| `vnet` | `AZURE_VIRTUAL_NETWORK` | object | networkConnection | + +--- + +## Design Patterns + +### Patterns Implemented + +| Pattern | Description | Implementation | +|---------|-------------|----------------| +| **Modular Design** | Single responsibility per module | Each `.bicep` file handles one resource type | +| **Declarative Configuration** | Configuration separate from logic | YAML files in `infra/settings/` | +| **Factory Pattern** | Loop-based resource creation | `for` loops for projects, pools, catalogs | +| **Dependency Injection** | Parameters passed between modules | Output-to-input parameter chaining | +| **Conditional Deployment** | Resources created based on conditions | `if` statements for optional resources | +| **Orchestrator Pattern** | Parent modules coordinate children | `workload.bicep` orchestrates DevCenter modules | + +### Conditional Deployment Examples + +```bicep +// Create VNet only if needed (Unmanaged network type) +resource virtualNetwork '...' = if (settings.create && settings.virtualNetworkType == 'Unmanaged') { + // ... +} + +// Deploy Key Vault or reference existing +module keyVault '...' = if (securitySettings.create) { + // ... +} + +// Create pool only for imageDefinition catalogs +resource pool '...' = [ + for (catalog, i) in catalogs: if (catalog.type == 'imageDefinition') { + // ... + } +] +``` + +### Factory Pattern for Multiple Resources + +```bicep +// Deploy multiple projects from configuration +module projects 'project/project.bicep' = [ + for (project, i) in devCenterSettings.projects: { + scope: resourceGroup() + params: { + name: project.name + // ... other parameters from project config + } + } +] + +// Output all project names +output AZURE_DEV_CENTER_PROJECTS array = [ + for (project, i) in devCenterSettings.projects: projects[i].outputs.AZURE_PROJECT_NAME +] +``` + +--- + +## Extension Points + +### Adding a New Project + +1. **Update Configuration** (`infra/settings/workload/devcenter.yaml`): + +```yaml +projects: + - name: "new-project" + description: "New project description" + network: + name: new-project + create: true + # ... network config + identity: + type: SystemAssigned + roleAssignments: + - azureADGroupId: "" + azureADGroupName: "New Project Developers" + azureRBACRoles: + - name: "Dev Box User" + id: "45d50f46-0b78-4001-a660-4198cbe8cd05" + scope: Project + pools: + - name: "developer" + imageDefinitionName: "new-project-developer" + vmSku: general_i_16c64gb256ssd_v2 + # ... rest of config +``` + +2. **Redeploy**: `azd provision` + +### Adding a New Pool + +1. **Update Project Configuration**: + +```yaml +pools: + - name: "new-pool" + imageDefinitionName: "custom-image" + vmSku: general_i_32c128gb512ssd_v2 +``` + +2. **Ensure Catalog Contains Image Definition** + +3. **Redeploy**: `azd provision` + +### Adding a New Catalog + +1. **DevCenter-Level Catalog** (in `devcenter.yaml`): + +```yaml +catalogs: + - name: "new-catalog" + type: gitHub + visibility: private + uri: "https://github.com/org/repo.git" + branch: "main" + path: "./definitions" +``` + +2. **Project-Level Catalog** (in project section): + +```yaml +projects: + - name: "project" + catalogs: + - name: "project-catalog" + type: imageDefinition + sourceControl: gitHub + visibility: private + uri: "https://github.com/org/project-repo.git" + branch: "main" + path: "/.devcenter/imageDefinitions" +``` + +### Adding a New Landing Zone + +1. **Create New Module** (`src/newzone/newzone.bicep`) + +2. **Update Resource Organization** (`infra/settings/resourceOrganization/azureResources.yaml`): + +```yaml +newzone: + create: true + name: devexp-newzone + tags: + landingZone: NewZone + # ... other tags +``` + +3. **Update `main.bicep`**: + +```bicep +resource newzoneRg 'Microsoft.Resources/resourceGroups@...' = if (landingZones.newzone.create) { + name: createResourceGroupName.newzone + location: location + tags: landingZones.newzone.tags +} + +module newzone '../src/newzone/newzone.bicep' = { + scope: resourceGroup(newzoneRgName) + params: { + // ... + } +} +``` + +### Extension Architecture + +```mermaid +flowchart TD + subgraph Config["Configuration Layer"] + YAML[YAML Files] + SCHEMA[JSON Schemas] + end + + subgraph Extension["Extension Points"] + NEW_PROJ[New Project] + NEW_POOL[New Pool] + NEW_CAT[New Catalog] + NEW_LZ[New Landing Zone] + end + + subgraph Modules["Module Layer"] + EXISTING[Existing Modules] + NEW_MOD[New Modules] + end + + YAML --> Extension + SCHEMA --> YAML + + NEW_PROJ --> |Uses| EXISTING + NEW_POOL --> |Uses| EXISTING + NEW_CAT --> |Uses| EXISTING + NEW_LZ --> |Requires| NEW_MOD + + NEW_MOD --> |Follow patterns of| EXISTING +``` + +--- + +## References + +### External References + +| Reference | URL | Description | +|-----------|-----|-------------| +| Bicep Documentation | https://learn.microsoft.com/azure/azure-resource-manager/bicep/ | Bicep language reference | +| Azure Landing Zones | https://learn.microsoft.com/azure/cloud-adoption-framework/ready/landing-zone/ | CAF guidance | +| DevCenter API Reference | https://learn.microsoft.com/azure/templates/microsoft.devcenter/ | Bicep resource reference | + +### Related Architecture Documents + +| Document | Path | Description | +|----------|------|-------------| +| Business Architecture | [01-business-architecture.md](./01-business-architecture.md) | Business context | +| Data Architecture | [02-data-architecture.md](./02-data-architecture.md) | Data models and flows | +| Technology Architecture | [04-technology-architecture.md](./04-technology-architecture.md) | Azure services | + +--- + +## Glossary + +| Term | Definition | +|------|------------| +| **Bicep** | Domain-specific language for Azure resource deployment | +| **Module** | Reusable Bicep file that can be called from other templates | +| **Scope** | Deployment level (tenant, management group, subscription, resource group) | +| **Orchestrator** | Module that coordinates deployment of multiple child modules | +| **Factory Pattern** | Design pattern using loops to create multiple similar resources | +| **loadYamlContent()** | Bicep function to load YAML as typed configuration | +| **targetScope** | Bicep declaration specifying deployment scope | +| **dependsOn** | Explicit dependency declaration between resources/modules | + +--- + +*This document follows TOGAF Architecture Development Method (ADM) principles and aligns with the Application Architecture domain of the BDAT framework.* From 8317f408a3f80f4f2fa6c88b2ef4e9d464458f93 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 14:49:11 -0500 Subject: [PATCH 05/49] Refactor Application Architecture documentation for improved formatting and clarity --- .../03-application-architecture.md | 557 +++++++++--------- 1 file changed, 285 insertions(+), 272 deletions(-) diff --git a/docs/architecture/03-application-architecture.md b/docs/architecture/03-application-architecture.md index b970f758..520e5f7f 100644 --- a/docs/architecture/03-application-architecture.md +++ b/docs/architecture/03-application-architecture.md @@ -2,12 +2,12 @@ > **DevExp-DevBox Landing Zone Accelerator** -| Metadata | Value | -|----------|-------| -| **Version** | 1.0.0 | -| **Last Updated** | January 22, 2026 | -| **Author** | Platform Engineering Team | -| **Status** | Active | +| Metadata | Value | +| ---------------- | ------------------------- | +| **Version** | 1.0.0 | +| **Last Updated** | January 22, 2026 | +| **Author** | Platform Engineering Team | +| **Status** | Active | --- @@ -27,7 +27,10 @@ ## Architecture Overview -The DevExp-DevBox Landing Zone Accelerator implements a **modular Bicep architecture** following Azure Landing Zone patterns. The solution is organized into four distinct landing zones, each with dedicated resource groups and specialized Bicep modules. +The DevExp-DevBox Landing Zone Accelerator implements a **modular Bicep +architecture** following Azure Landing Zone patterns. The solution is organized +into four distinct landing zones, each with dedicated resource groups and +specialized Bicep modules. ### Landing Zone Architecture @@ -37,26 +40,26 @@ flowchart TB subgraph Main["main.bicep (Orchestrator)"] PARAMS[/"Parameters:
location, secretValue,
environmentName"/] end - + subgraph Security["Security Landing Zone"] SEC_RG[Security Resource Group] KV[Key Vault] SECRET[Secrets] end - + subgraph Monitoring["Monitoring Landing Zone"] MON_RG[Monitoring Resource Group] LA[Log Analytics Workspace] SOL[Solutions] end - + subgraph Connectivity["Connectivity Landing Zone"] CON_RG[Connectivity Resource Group] VNET[Virtual Network] SUBNET[Subnets] NC[Network Connection] end - + subgraph Workload["Workload Landing Zone"] WRK_RG[Workload Resource Group] DC[DevCenter] @@ -66,46 +69,46 @@ flowchart TB POOL[Pools] end end - + PARAMS --> SEC_RG PARAMS --> MON_RG PARAMS --> WRK_RG - + MON_RG --> LA LA --> SOL - + SEC_RG --> KV KV --> SECRET - + WRK_RG --> DC DC --> CAT DC --> ENV DC --> PROJ PROJ --> POOL - + PROJ -.->|Optional| CON_RG CON_RG --> VNET VNET --> SUBNET SUBNET --> NC NC --> DC - + LA -.->|Diagnostics| KV LA -.->|Diagnostics| DC LA -.->|Diagnostics| VNET - + SECRET -.->|Auth| CAT ``` ### Architecture Principles -| Principle | Description | Implementation | -|-----------|-------------|----------------| -| **Modularity** | Each module has a single responsibility | Separate `.bicep` files per resource type | -| **Declarative Configuration** | Infrastructure defined as code | YAML configuration files with JSON schemas | -| **Separation of Concerns** | Landing zones isolate different functions | Resource groups by security, monitoring, workload | -| **Least Privilege** | Minimal permissions per identity | Scoped RBAC role assignments | -| **Configuration as Code** | All settings version controlled | Git repository with YAML files | -| **Idempotency** | Repeated deployments yield same result | Bicep's declarative model | +| Principle | Description | Implementation | +| ----------------------------- | ----------------------------------------- | ------------------------------------------------- | +| **Modularity** | Each module has a single responsibility | Separate `.bicep` files per resource type | +| **Declarative Configuration** | Infrastructure defined as code | YAML configuration files with JSON schemas | +| **Separation of Concerns** | Landing zones isolate different functions | Resource groups by security, monitoring, workload | +| **Least Privilege** | Minimal permissions per identity | Scoped RBAC role assignments | +| **Configuration as Code** | All settings version controlled | Git repository with YAML files | +| **Idempotency** | Repeated deployments yield same result | Bicep's declarative model | --- @@ -152,30 +155,31 @@ src/ - **Path**: `infra/main.bicep` - **Scope**: Subscription -- **Purpose**: Top-level orchestrator that creates resource groups and coordinates all module deployments +- **Purpose**: Top-level orchestrator that creates resource groups and + coordinates all module deployments **Inputs**: -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `location` | string | Yes | Azure region (validated against allowed list) | -| `secretValue` | securestring | Yes | GitHub/ADO PAT token | -| `environmentName` | string | Yes | Environment name (2-10 chars) | +| Parameter | Type | Required | Description | +| ----------------- | ------------ | -------- | --------------------------------------------- | +| `location` | string | Yes | Azure region (validated against allowed list) | +| `secretValue` | securestring | Yes | GitHub/ADO PAT token | +| `environmentName` | string | Yes | Environment name (2-10 chars) | **Outputs**: -| Output | Type | Description | -|--------|------|-------------| -| `SECURITY_AZURE_RESOURCE_GROUP_NAME` | string | Security RG name | -| `MONITORING_AZURE_RESOURCE_GROUP_NAME` | string | Monitoring RG name | -| `WORKLOAD_AZURE_RESOURCE_GROUP_NAME` | string | Workload RG name | -| `AZURE_LOG_ANALYTICS_WORKSPACE_ID` | string | Log Analytics resource ID | -| `AZURE_LOG_ANALYTICS_WORKSPACE_NAME` | string | Log Analytics workspace name | -| `AZURE_KEY_VAULT_NAME` | string | Key Vault name | -| `AZURE_KEY_VAULT_SECRET_IDENTIFIER` | string | Secret URI | -| `AZURE_KEY_VAULT_ENDPOINT` | string | Key Vault URI | -| `AZURE_DEV_CENTER_NAME` | string | DevCenter name | -| `AZURE_DEV_CENTER_PROJECTS` | array | List of project names | +| Output | Type | Description | +| -------------------------------------- | ------ | ---------------------------- | +| `SECURITY_AZURE_RESOURCE_GROUP_NAME` | string | Security RG name | +| `MONITORING_AZURE_RESOURCE_GROUP_NAME` | string | Monitoring RG name | +| `WORKLOAD_AZURE_RESOURCE_GROUP_NAME` | string | Workload RG name | +| `AZURE_LOG_ANALYTICS_WORKSPACE_ID` | string | Log Analytics resource ID | +| `AZURE_LOG_ANALYTICS_WORKSPACE_NAME` | string | Log Analytics workspace name | +| `AZURE_KEY_VAULT_NAME` | string | Key Vault name | +| `AZURE_KEY_VAULT_SECRET_IDENTIFIER` | string | Secret URI | +| `AZURE_KEY_VAULT_ENDPOINT` | string | Key Vault URI | +| `AZURE_DEV_CENTER_NAME` | string | DevCenter name | +| `AZURE_DEV_CENTER_PROJECTS` | array | List of project names | **Dependencies**: None (entry point) @@ -191,25 +195,26 @@ src/ **Inputs**: -| Parameter | Type | Required | Default | Description | -|-----------|------|----------|---------|-------------| -| `name` | string | Yes | - | Base name (4-49 chars) | -| `location` | string | No | resourceGroup().location | Azure region | -| `tags` | object | No | {} | Resource tags | -| `sku` | string | No | PerGB2018 | Workspace SKU | +| Parameter | Type | Required | Default | Description | +| ---------- | ------ | -------- | ------------------------ | ---------------------- | +| `name` | string | Yes | - | Base name (4-49 chars) | +| `location` | string | No | resourceGroup().location | Azure region | +| `tags` | object | No | {} | Resource tags | +| `sku` | string | No | PerGB2018 | Workspace SKU | **Outputs**: -| Output | Type | Description | -|--------|------|-------------| -| `AZURE_LOG_ANALYTICS_WORKSPACE_ID` | string | Workspace resource ID | -| `AZURE_LOG_ANALYTICS_WORKSPACE_NAME` | string | Workspace name | +| Output | Type | Description | +| ------------------------------------ | ------ | --------------------- | +| `AZURE_LOG_ANALYTICS_WORKSPACE_ID` | string | Workspace resource ID | +| `AZURE_LOG_ANALYTICS_WORKSPACE_NAME` | string | Workspace name | **Dependencies**: Monitoring resource group **Dependents**: `security.bicep`, `workload.bicep`, `vnet.bicep` **Resources Created**: + - `Microsoft.OperationalInsights/workspaces` - Log Analytics workspace - `Microsoft.OperationsManagement/solutions` - Azure Activity solution - `Microsoft.Insights/diagnosticSettings` - Self-diagnostics @@ -224,19 +229,19 @@ src/ **Inputs**: -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `tags` | object | Yes | Resource tags | -| `secretValue` | securestring | Yes | Secret content | -| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | +| Parameter | Type | Required | Description | +| ---------------- | ------------ | -------- | -------------------------- | +| `tags` | object | Yes | Resource tags | +| `secretValue` | securestring | Yes | Secret content | +| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | **Outputs**: -| Output | Type | Description | -|--------|------|-------------| -| `AZURE_KEY_VAULT_NAME` | string | Key Vault name | -| `AZURE_KEY_VAULT_SECRET_IDENTIFIER` | string | Secret URI | -| `AZURE_KEY_VAULT_ENDPOINT` | string | Key Vault endpoint | +| Output | Type | Description | +| ----------------------------------- | ------ | ------------------ | +| `AZURE_KEY_VAULT_NAME` | string | Key Vault name | +| `AZURE_KEY_VAULT_SECRET_IDENTIFIER` | string | Secret URI | +| `AZURE_KEY_VAULT_ENDPOINT` | string | Key Vault endpoint | **Dependencies**: `logAnalytics.bicep` @@ -252,26 +257,28 @@ src/ **Inputs**: -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `keyvaultSettings` | object | Yes | Key Vault configuration from YAML | -| `location` | string | No | Azure region | -| `tags` | object | Yes | Resource tags | -| `unique` | string | No | Unique suffix for naming | +| Parameter | Type | Required | Description | +| ------------------ | ------ | -------- | --------------------------------- | +| `keyvaultSettings` | object | Yes | Key Vault configuration from YAML | +| `location` | string | No | Azure region | +| `tags` | object | Yes | Resource tags | +| `unique` | string | No | Unique suffix for naming | **Outputs**: -| Output | Type | Description | -|--------|------|-------------| -| `AZURE_KEY_VAULT_NAME` | string | Key Vault name | -| `AZURE_KEY_VAULT_ENDPOINT` | string | Vault URI | +| Output | Type | Description | +| -------------------------- | ------ | -------------- | +| `AZURE_KEY_VAULT_NAME` | string | Key Vault name | +| `AZURE_KEY_VAULT_ENDPOINT` | string | Vault URI | **Dependencies**: Security resource group **Dependents**: `secret.bicep` **Resources Created**: -- `Microsoft.KeyVault/vaults` - Key Vault with RBAC, soft delete, purge protection + +- `Microsoft.KeyVault/vaults` - Key Vault with RBAC, soft delete, purge + protection --- @@ -283,18 +290,18 @@ src/ **Inputs**: -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `name` | string | Yes | Secret name | -| `secretValue` | securestring | Yes | Secret content | -| `keyVaultName` | string | Yes | Target Key Vault | -| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | +| Parameter | Type | Required | Description | +| ---------------- | ------------ | -------- | -------------------------- | +| `name` | string | Yes | Secret name | +| `secretValue` | securestring | Yes | Secret content | +| `keyVaultName` | string | Yes | Target Key Vault | +| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | **Outputs**: -| Output | Type | Description | -|--------|------|-------------| -| `AZURE_KEY_VAULT_SECRET_IDENTIFIER` | string | Secret URI | +| Output | Type | Description | +| ----------------------------------- | ------ | ----------- | +| `AZURE_KEY_VAULT_SECRET_IDENTIFIER` | string | Secret URI | **Dependencies**: `keyVault.bicep`, `logAnalytics.bicep` @@ -310,19 +317,19 @@ src/ **Inputs**: -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | -| `secretIdentifier` | securestring | Yes | Key Vault secret URI | -| `securityResourceGroupName` | string | Yes | Security RG for RBAC | -| `location` | string | No | Azure region | +| Parameter | Type | Required | Description | +| --------------------------- | ------------ | -------- | -------------------------- | +| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | +| `secretIdentifier` | securestring | Yes | Key Vault secret URI | +| `securityResourceGroupName` | string | Yes | Security RG for RBAC | +| `location` | string | No | Azure region | **Outputs**: -| Output | Type | Description | -|--------|------|-------------| -| `AZURE_DEV_CENTER_NAME` | string | DevCenter name | -| `AZURE_DEV_CENTER_PROJECTS` | array | List of project names | +| Output | Type | Description | +| --------------------------- | ------ | --------------------- | +| `AZURE_DEV_CENTER_NAME` | string | DevCenter name | +| `AZURE_DEV_CENTER_PROJECTS` | array | List of project names | **Dependencies**: `logAnalytics.bicep`, `security.bicep` @@ -338,20 +345,20 @@ src/ **Inputs**: -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `config` | DevCenterConfig | Yes | DevCenter configuration | -| `catalogs` | array | Yes | Catalog definitions | -| `environmentTypes` | array | Yes | Environment type definitions | -| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | -| `secretIdentifier` | securestring | Yes | Secret for private catalogs | -| `securityResourceGroupName` | string | Yes | Security RG name | -| `location` | string | No | Azure region | +| Parameter | Type | Required | Description | +| --------------------------- | --------------- | -------- | ---------------------------- | +| `config` | DevCenterConfig | Yes | DevCenter configuration | +| `catalogs` | array | Yes | Catalog definitions | +| `environmentTypes` | array | Yes | Environment type definitions | +| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | +| `secretIdentifier` | securestring | Yes | Secret for private catalogs | +| `securityResourceGroupName` | string | Yes | Security RG name | +| `location` | string | No | Azure region | **Outputs**: -| Output | Type | Description | -|--------|------|-------------| +| Output | Type | Description | +| ----------------------- | ------ | -------------- | | `AZURE_DEV_CENTER_NAME` | string | DevCenter name | **Dependencies**: `logAnalytics.bicep`, `secret.bicep` @@ -359,6 +366,7 @@ src/ **Dependents**: `project.bicep`, `catalog.bicep`, `environmentType.bicep` **Resources Created**: + - `Microsoft.DevCenter/devcenters` - DevCenter resource - `Microsoft.Insights/diagnosticSettings` - Diagnostic settings - Role assignments via identity modules @@ -375,31 +383,32 @@ src/ **Inputs**: -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `devCenterName` | string | Yes | Parent DevCenter | -| `name` | string | Yes | Project name | -| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | -| `projectDescription` | string | Yes | Project description | -| `catalogs` | object[] | Yes | Project-specific catalogs | -| `projectEnvironmentTypes` | array | Yes | Enabled environment types | -| `projectPools` | array | Yes | Dev Box pool definitions | -| `projectNetwork` | object | Yes | Network configuration | -| `secretIdentifier` | securestring | Yes | Secret for private catalogs | -| `securityResourceGroupName` | string | Yes | Security RG name | -| `identity` | Identity | Yes | Project identity config | -| `tags` | object | No | Resource tags | -| `location` | string | No | Azure region | +| Parameter | Type | Required | Description | +| --------------------------- | ------------ | -------- | --------------------------- | +| `devCenterName` | string | Yes | Parent DevCenter | +| `name` | string | Yes | Project name | +| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | +| `projectDescription` | string | Yes | Project description | +| `catalogs` | object[] | Yes | Project-specific catalogs | +| `projectEnvironmentTypes` | array | Yes | Enabled environment types | +| `projectPools` | array | Yes | Dev Box pool definitions | +| `projectNetwork` | object | Yes | Network configuration | +| `secretIdentifier` | securestring | Yes | Secret for private catalogs | +| `securityResourceGroupName` | string | Yes | Security RG name | +| `identity` | Identity | Yes | Project identity config | +| `tags` | object | No | Resource tags | +| `location` | string | No | Azure region | **Outputs**: -| Output | Type | Description | -|--------|------|-------------| +| Output | Type | Description | +| -------------------- | ------ | ------------ | | `AZURE_PROJECT_NAME` | string | Project name | **Dependencies**: `devCenter.bicep` -**Dependents**: `projectPool.bicep`, `projectCatalog.bicep`, `projectEnvironmentType.bicep` +**Dependents**: `projectPool.bicep`, `projectCatalog.bicep`, +`projectEnvironmentType.bicep` --- @@ -411,16 +420,16 @@ src/ **Inputs**: -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `name` | string | Yes | Pool name (e.g., `backend-engineer`) | -| `location` | string | No | Azure region | -| `catalogs` | Catalog[] | Yes | Catalog references for images | -| `imageDefinitionName` | string | Yes | Image definition name | -| `networkConnectionName` | string | Yes | Network connection name | -| `vmSku` | string | Yes | VM SKU (e.g., `general_i_32c128gb512ssd_v2`) | -| `networkType` | string | Yes | Managed or Unmanaged | -| `projectName` | string | Yes | Parent project | +| Parameter | Type | Required | Description | +| ----------------------- | --------- | -------- | -------------------------------------------- | +| `name` | string | Yes | Pool name (e.g., `backend-engineer`) | +| `location` | string | No | Azure region | +| `catalogs` | Catalog[] | Yes | Catalog references for images | +| `imageDefinitionName` | string | Yes | Image definition name | +| `networkConnectionName` | string | Yes | Network connection name | +| `vmSku` | string | Yes | VM SKU (e.g., `general_i_32c128gb512ssd_v2`) | +| `networkType` | string | Yes | Managed or Unmanaged | +| `projectName` | string | Yes | Parent project | **Outputs**: None @@ -429,6 +438,7 @@ src/ **Dependents**: None (terminal module) **Resources Created**: + - `Microsoft.DevCenter/projects/pools` - Dev Box pool --- @@ -441,18 +451,18 @@ src/ **Inputs**: -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `devCenterName` | string | Yes | Parent DevCenter | -| `catalogConfig` | Catalog | Yes | Catalog configuration | -| `secretIdentifier` | securestring | Yes | Secret for private repos | +| Parameter | Type | Required | Description | +| ------------------ | ------------ | -------- | ------------------------ | +| `devCenterName` | string | Yes | Parent DevCenter | +| `catalogConfig` | Catalog | Yes | Catalog configuration | +| `secretIdentifier` | securestring | Yes | Secret for private repos | **Outputs**: -| Output | Type | Description | -|--------|------|-------------| -| `AZURE_DEV_CENTER_CATALOG_NAME` | string | Catalog name | -| `AZURE_DEV_CENTER_CATALOG_ID` | string | Catalog resource ID | +| Output | Type | Description | +| ------------------------------- | ------ | ---------------------------- | +| `AZURE_DEV_CENTER_CATALOG_NAME` | string | Catalog name | +| `AZURE_DEV_CENTER_CATALOG_ID` | string | Catalog resource ID | | `AZURE_DEV_CENTER_CATALOG_TYPE` | string | Catalog type (gitHub/adoGit) | **Dependencies**: `devCenter.bicep`, `secret.bicep` @@ -469,19 +479,19 @@ src/ **Inputs**: -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `devCenterName` | string | Yes | DevCenter name | -| `projectNetwork` | object | Yes | Network configuration | -| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | -| `location` | string | Yes | Azure region | +| Parameter | Type | Required | Description | +| ---------------- | ------ | -------- | -------------------------- | +| `devCenterName` | string | Yes | DevCenter name | +| `projectNetwork` | object | Yes | Network configuration | +| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | +| `location` | string | Yes | Azure region | **Outputs**: -| Output | Type | Description | -|--------|------|-------------| +| Output | Type | Description | +| ----------------------- | ------ | ----------------------- | | `networkConnectionName` | string | Network connection name | -| `networkType` | string | Managed or Unmanaged | +| `networkType` | string | Managed or Unmanaged | **Dependencies**: `devCenter.bicep`, `logAnalytics.bicep` @@ -497,17 +507,17 @@ src/ **Inputs**: -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | -| `location` | string | Yes | Azure region | -| `tags` | object | No | Resource tags | -| `settings` | object | Yes | Network settings (name, type, subnets) | +| Parameter | Type | Required | Description | +| ---------------- | ------ | -------- | -------------------------------------- | +| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | +| `location` | string | Yes | Azure region | +| `tags` | object | No | Resource tags | +| `settings` | object | Yes | Network settings (name, type, subnets) | **Outputs**: -| Output | Type | Description | -|--------|------|-------------| +| Output | Type | Description | +| ----------------------- | ------ | -------------------------------- | | `AZURE_VIRTUAL_NETWORK` | object | VNet details (name, RG, subnets) | **Dependencies**: Connectivity resource group @@ -515,6 +525,7 @@ src/ **Dependents**: `networkConnection.bicep` **Resources Created**: + - `Microsoft.Network/virtualNetworks` - Virtual network (if create=true) - `Microsoft.Insights/diagnosticSettings` - VNet diagnostics @@ -528,16 +539,16 @@ src/ **Inputs**: -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `devCenterName` | string | Yes | DevCenter name | -| `name` | string | Yes | Connection name | -| `subnetId` | string | Yes | Target subnet resource ID | +| Parameter | Type | Required | Description | +| --------------- | ------ | -------- | ------------------------- | +| `devCenterName` | string | Yes | DevCenter name | +| `name` | string | Yes | Connection name | +| `subnetId` | string | Yes | Target subnet resource ID | **Outputs**: -| Output | Type | Description | -|--------|------|-------------| +| Output | Type | Description | +| ----------------------- | ------ | ----------------------- | | `networkConnectionName` | string | Network connection name | **Dependencies**: `vnet.bicep`, `devCenter.bicep` @@ -548,14 +559,14 @@ src/ ### Identity Modules -| Module | Path | Purpose | -|--------|------|---------| -| `devCenterRoleAssignment.bicep` | `src/identity/` | Subscription-scope role assignments for DevCenter managed identity | -| `devCenterRoleAssignmentRG.bicep` | `src/identity/` | Resource group-scope role assignments for DevCenter managed identity | -| `projectIdentityRoleAssignment.bicep` | `src/identity/` | Project-scope role assignments for project managed identity | -| `projectIdentityRoleAssignmentRG.bicep` | `src/identity/` | Security RG role assignments for project managed identity | -| `orgRoleAssignment.bicep` | `src/identity/` | Role assignments for organizational AD groups | -| `keyVaultAccess.bicep` | `src/identity/` | Key Vault access configuration | +| Module | Path | Purpose | +| --------------------------------------- | --------------- | -------------------------------------------------------------------- | +| `devCenterRoleAssignment.bicep` | `src/identity/` | Subscription-scope role assignments for DevCenter managed identity | +| `devCenterRoleAssignmentRG.bicep` | `src/identity/` | Resource group-scope role assignments for DevCenter managed identity | +| `projectIdentityRoleAssignment.bicep` | `src/identity/` | Project-scope role assignments for project managed identity | +| `projectIdentityRoleAssignmentRG.bicep` | `src/identity/` | Security RG role assignments for project managed identity | +| `orgRoleAssignment.bicep` | `src/identity/` | Role assignments for organizational AD groups | +| `keyVaultAccess.bicep` | `src/identity/` | Key Vault access configuration | --- @@ -568,17 +579,17 @@ flowchart TD subgraph Entry["Entry Point"] MAIN[main.bicep] end - + subgraph Management["Management Layer"] LA[logAnalytics.bicep] end - + subgraph Security["Security Layer"] SEC[security.bicep] KV[keyVault.bicep] SECRET[secret.bicep] end - + subgraph Workload["Workload Layer"] WRK[workload.bicep] DC[devCenter.bicep] @@ -589,14 +600,14 @@ flowchart TD PENV[projectEnvironmentType.bicep] POOL[projectPool.bicep] end - + subgraph Connectivity["Connectivity Layer"] CONN[connectivity.bicep] VNET[vnet.bicep] NC[networkConnection.bicep] RG[resourceGroup.bicep] end - + subgraph Identity["Identity Layer"] DCRA[devCenterRoleAssignment] DCRA_RG[devCenterRoleAssignmentRG] @@ -604,55 +615,55 @@ flowchart TD PRA_RG[projectIdentityRoleAssignmentRG] ORA[orgRoleAssignment] end - + MAIN --> LA MAIN --> SEC MAIN --> WRK - + SEC --> KV SEC --> SECRET KV --> SECRET LA --> SECRET - + WRK --> DC WRK --> PROJ LA --> DC SECRET --> DC - + DC --> CAT DC --> ENV DC --> DCRA DC --> DCRA_RG DC --> ORA - + PROJ --> PCAT PROJ --> PENV PROJ --> POOL PROJ --> CONN PROJ --> PRA PROJ --> PRA_RG - + CONN --> RG CONN --> VNET CONN --> NC LA --> VNET - + NC --> DC ``` ### Dependency Matrix -| Module | Depends On | Provides To | -|--------|------------|-------------| -| `main.bicep` | - | All modules | -| `logAnalytics.bicep` | main | security, workload, connectivity | -| `keyVault.bicep` | main | secret | -| `secret.bicep` | keyVault, logAnalytics | devCenter, catalog | -| `security.bicep` | logAnalytics | workload | -| `devCenter.bicep` | logAnalytics, secret | project, catalog, envType | -| `project.bicep` | devCenter | pool, projectCatalog, projectEnvType | -| `connectivity.bicep` | devCenter, logAnalytics | projectPool | -| `projectPool.bicep` | project, connectivity, projectCatalog | - | +| Module | Depends On | Provides To | +| -------------------- | ------------------------------------- | ------------------------------------ | +| `main.bicep` | - | All modules | +| `logAnalytics.bicep` | main | security, workload, connectivity | +| `keyVault.bicep` | main | secret | +| `secret.bicep` | keyVault, logAnalytics | devCenter, catalog | +| `security.bicep` | logAnalytics | workload | +| `devCenter.bicep` | logAnalytics, secret | project, catalog, envType | +| `project.bicep` | devCenter | pool, projectCatalog, projectEnvType | +| `connectivity.bicep` | devCenter, logAnalytics | projectPool | +| `projectPool.bicep` | project, connectivity, projectCatalog | - | --- @@ -669,29 +680,29 @@ sequenceDiagram participant MON as Monitoring Module participant SEC as Security Module participant WRK as Workload Module - + User->>AZD: azd provision AZD->>ARM: Deploy main.bicep - + par Create Resource Groups ARM->>RG: Create Security RG ARM->>RG: Create Monitoring RG ARM->>RG: Create Workload RG end - + ARM->>MON: Deploy logAnalytics.bicep MON-->>ARM: AZURE_LOG_ANALYTICS_WORKSPACE_ID - + ARM->>SEC: Deploy security.bicep Note over SEC: Uses logAnalyticsId SEC-->>ARM: AZURE_KEY_VAULT_SECRET_IDENTIFIER - + ARM->>WRK: Deploy workload.bicep Note over WRK: Uses logAnalyticsId, secretIdentifier - + WRK->>WRK: Deploy devCenter.bicep WRK->>WRK: Deploy project.bicep (loop) - + WRK-->>ARM: AZURE_DEV_CENTER_NAME, AZURE_DEV_CENTER_PROJECTS ARM-->>AZD: Deployment outputs AZD-->>User: Deployment complete @@ -699,13 +710,13 @@ sequenceDiagram ### Deployment Scopes -| Scope | Modules | Purpose | -|-------|---------|---------| -| **Subscription** | `main.bicep`, `devCenterRoleAssignment.bicep` | Create RGs, subscription-level RBAC | -| **Security RG** | `keyVault.bicep`, `secret.bicep` | Security resources | -| **Monitoring RG** | `logAnalytics.bicep` | Monitoring resources | -| **Workload RG** | `devCenter.bicep`, `project.bicep`, `projectPool.bicep` | DevCenter resources | -| **Connectivity RG** | `vnet.bicep`, `networkConnection.bicep` | Network resources (conditional) | +| Scope | Modules | Purpose | +| ------------------- | ------------------------------------------------------- | ----------------------------------- | +| **Subscription** | `main.bicep`, `devCenterRoleAssignment.bicep` | Create RGs, subscription-level RBAC | +| **Security RG** | `keyVault.bicep`, `secret.bicep` | Security resources | +| **Monitoring RG** | `logAnalytics.bicep` | Monitoring resources | +| **Workload RG** | `devCenter.bicep`, `project.bicep`, `projectPool.bicep` | DevCenter resources | +| **Connectivity RG** | `vnet.bicep`, `networkConnection.bicep` | Network resources (conditional) | ### Deployment Commands @@ -780,13 +791,13 @@ type NetworkSettings = { ### Output Contract Summary -| Module | Key Output | Type | Consumer | -|--------|------------|------|----------| -| `logAnalytics` | `AZURE_LOG_ANALYTICS_WORKSPACE_ID` | string | security, workload, connectivity | -| `security` | `AZURE_KEY_VAULT_SECRET_IDENTIFIER` | string | workload (catalogs) | -| `devCenter` | `AZURE_DEV_CENTER_NAME` | string | projects, network connections | -| `connectivity` | `networkConnectionName` | string | projectPool | -| `vnet` | `AZURE_VIRTUAL_NETWORK` | object | networkConnection | +| Module | Key Output | Type | Consumer | +| -------------- | ----------------------------------- | ------ | -------------------------------- | +| `logAnalytics` | `AZURE_LOG_ANALYTICS_WORKSPACE_ID` | string | security, workload, connectivity | +| `security` | `AZURE_KEY_VAULT_SECRET_IDENTIFIER` | string | workload (catalogs) | +| `devCenter` | `AZURE_DEV_CENTER_NAME` | string | projects, network connections | +| `connectivity` | `networkConnectionName` | string | projectPool | +| `vnet` | `AZURE_VIRTUAL_NETWORK` | object | networkConnection | --- @@ -794,14 +805,14 @@ type NetworkSettings = { ### Patterns Implemented -| Pattern | Description | Implementation | -|---------|-------------|----------------| -| **Modular Design** | Single responsibility per module | Each `.bicep` file handles one resource type | -| **Declarative Configuration** | Configuration separate from logic | YAML files in `infra/settings/` | -| **Factory Pattern** | Loop-based resource creation | `for` loops for projects, pools, catalogs | -| **Dependency Injection** | Parameters passed between modules | Output-to-input parameter chaining | -| **Conditional Deployment** | Resources created based on conditions | `if` statements for optional resources | -| **Orchestrator Pattern** | Parent modules coordinate children | `workload.bicep` orchestrates DevCenter modules | +| Pattern | Description | Implementation | +| ----------------------------- | ------------------------------------- | ----------------------------------------------- | +| **Modular Design** | Single responsibility per module | Each `.bicep` file handles one resource type | +| **Declarative Configuration** | Configuration separate from logic | YAML files in `infra/settings/` | +| **Factory Pattern** | Loop-based resource creation | `for` loops for projects, pools, catalogs | +| **Dependency Injection** | Parameters passed between modules | Output-to-input parameter chaining | +| **Conditional Deployment** | Resources created based on conditions | `if` statements for optional resources | +| **Orchestrator Pattern** | Parent modules coordinate children | `workload.bicep` orchestrates DevCenter modules | ### Conditional Deployment Examples @@ -854,8 +865,8 @@ output AZURE_DEV_CENTER_PROJECTS array = [ ```yaml projects: - - name: "new-project" - description: "New project description" + - name: 'new-project' + description: 'New project description' network: name: new-project create: true @@ -863,15 +874,15 @@ projects: identity: type: SystemAssigned roleAssignments: - - azureADGroupId: "" - azureADGroupName: "New Project Developers" + - azureADGroupId: '' + azureADGroupName: 'New Project Developers' azureRBACRoles: - - name: "Dev Box User" - id: "45d50f46-0b78-4001-a660-4198cbe8cd05" + - name: 'Dev Box User' + id: '45d50f46-0b78-4001-a660-4198cbe8cd05' scope: Project pools: - - name: "developer" - imageDefinitionName: "new-project-developer" + - name: 'developer' + imageDefinitionName: 'new-project-developer' vmSku: general_i_16c64gb256ssd_v2 # ... rest of config ``` @@ -884,8 +895,8 @@ projects: ```yaml pools: - - name: "new-pool" - imageDefinitionName: "custom-image" + - name: 'new-pool' + imageDefinitionName: 'custom-image' vmSku: general_i_32c128gb512ssd_v2 ``` @@ -899,34 +910,35 @@ pools: ```yaml catalogs: - - name: "new-catalog" + - name: 'new-catalog' type: gitHub visibility: private - uri: "https://github.com/org/repo.git" - branch: "main" - path: "./definitions" + uri: 'https://github.com/org/repo.git' + branch: 'main' + path: './definitions' ``` 2. **Project-Level Catalog** (in project section): ```yaml projects: - - name: "project" + - name: 'project' catalogs: - - name: "project-catalog" + - name: 'project-catalog' type: imageDefinition sourceControl: gitHub visibility: private - uri: "https://github.com/org/project-repo.git" - branch: "main" - path: "/.devcenter/imageDefinitions" + uri: 'https://github.com/org/project-repo.git' + branch: 'main' + path: '/.devcenter/imageDefinitions' ``` ### Adding a New Landing Zone 1. **Create New Module** (`src/newzone/newzone.bicep`) -2. **Update Resource Organization** (`infra/settings/resourceOrganization/azureResources.yaml`): +2. **Update Resource Organization** + (`infra/settings/resourceOrganization/azureResources.yaml`): ```yaml newzone: @@ -962,27 +974,27 @@ flowchart TD YAML[YAML Files] SCHEMA[JSON Schemas] end - + subgraph Extension["Extension Points"] NEW_PROJ[New Project] NEW_POOL[New Pool] NEW_CAT[New Catalog] NEW_LZ[New Landing Zone] end - + subgraph Modules["Module Layer"] EXISTING[Existing Modules] NEW_MOD[New Modules] end - + YAML --> Extension SCHEMA --> YAML - + NEW_PROJ --> |Uses| EXISTING NEW_POOL --> |Uses| EXISTING NEW_CAT --> |Uses| EXISTING NEW_LZ --> |Requires| NEW_MOD - + NEW_MOD --> |Follow patterns of| EXISTING ``` @@ -992,35 +1004,36 @@ flowchart TD ### External References -| Reference | URL | Description | -|-----------|-----|-------------| -| Bicep Documentation | https://learn.microsoft.com/azure/azure-resource-manager/bicep/ | Bicep language reference | -| Azure Landing Zones | https://learn.microsoft.com/azure/cloud-adoption-framework/ready/landing-zone/ | CAF guidance | -| DevCenter API Reference | https://learn.microsoft.com/azure/templates/microsoft.devcenter/ | Bicep resource reference | +| Reference | URL | Description | +| ----------------------- | ------------------------------------------------------------------------------ | ------------------------ | +| Bicep Documentation | https://learn.microsoft.com/azure/azure-resource-manager/bicep/ | Bicep language reference | +| Azure Landing Zones | https://learn.microsoft.com/azure/cloud-adoption-framework/ready/landing-zone/ | CAF guidance | +| DevCenter API Reference | https://learn.microsoft.com/azure/templates/microsoft.devcenter/ | Bicep resource reference | ### Related Architecture Documents -| Document | Path | Description | -|----------|------|-------------| -| Business Architecture | [01-business-architecture.md](./01-business-architecture.md) | Business context | -| Data Architecture | [02-data-architecture.md](./02-data-architecture.md) | Data models and flows | -| Technology Architecture | [04-technology-architecture.md](./04-technology-architecture.md) | Azure services | +| Document | Path | Description | +| ----------------------- | ---------------------------------------------------------------- | --------------------- | +| Business Architecture | [01-business-architecture.md](./01-business-architecture.md) | Business context | +| Data Architecture | [02-data-architecture.md](./02-data-architecture.md) | Data models and flows | +| Technology Architecture | [04-technology-architecture.md](./04-technology-architecture.md) | Azure services | --- ## Glossary -| Term | Definition | -|------|------------| -| **Bicep** | Domain-specific language for Azure resource deployment | -| **Module** | Reusable Bicep file that can be called from other templates | -| **Scope** | Deployment level (tenant, management group, subscription, resource group) | -| **Orchestrator** | Module that coordinates deployment of multiple child modules | -| **Factory Pattern** | Design pattern using loops to create multiple similar resources | -| **loadYamlContent()** | Bicep function to load YAML as typed configuration | -| **targetScope** | Bicep declaration specifying deployment scope | -| **dependsOn** | Explicit dependency declaration between resources/modules | +| Term | Definition | +| --------------------- | ------------------------------------------------------------------------- | +| **Bicep** | Domain-specific language for Azure resource deployment | +| **Module** | Reusable Bicep file that can be called from other templates | +| **Scope** | Deployment level (tenant, management group, subscription, resource group) | +| **Orchestrator** | Module that coordinates deployment of multiple child modules | +| **Factory Pattern** | Design pattern using loops to create multiple similar resources | +| **loadYamlContent()** | Bicep function to load YAML as typed configuration | +| **targetScope** | Bicep declaration specifying deployment scope | +| **dependsOn** | Explicit dependency declaration between resources/modules | --- -*This document follows TOGAF Architecture Development Method (ADM) principles and aligns with the Application Architecture domain of the BDAT framework.* +_This document follows TOGAF Architecture Development Method (ADM) principles +and aligns with the Application Architecture domain of the BDAT framework._ From fc31de59f56cd3ad584cfe162e1b8bb420209b59 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 14:50:51 -0500 Subject: [PATCH 06/49] Add comprehensive Technology Architecture documentation for DevExp-DevBox --- .../04-technology-architecture.md | 981 ++++++++++++++++++ 1 file changed, 981 insertions(+) create mode 100644 docs/architecture/04-technology-architecture.md diff --git a/docs/architecture/04-technology-architecture.md b/docs/architecture/04-technology-architecture.md new file mode 100644 index 00000000..3f5ede24 --- /dev/null +++ b/docs/architecture/04-technology-architecture.md @@ -0,0 +1,981 @@ +# Technology Architecture + +> **DevExp-DevBox Landing Zone Accelerator** + +| Metadata | Value | +| ---------------- | ------------------------- | +| **Version** | 1.0.0 | +| **Last Updated** | January 22, 2026 | +| **Author** | Platform Engineering Team | +| **Status** | Active | + +--- + +## Table of Contents + +- [Infrastructure Overview](#infrastructure-overview) +- [Landing Zone Design](#landing-zone-design) +- [Network Architecture](#network-architecture) +- [Identity & Access](#identity--access) +- [Security Architecture](#security-architecture) +- [Monitoring & Observability](#monitoring--observability) +- [CI/CD Infrastructure](#cicd-infrastructure) +- [Deployment Tools](#deployment-tools) +- [DevOps Practices](#devops-practices) +- [References](#references) +- [Glossary](#glossary) + +--- + +## Infrastructure Overview + +The DevExp-DevBox Landing Zone Accelerator deploys a comprehensive set of Azure +services organized into functional landing zones. + +### Azure Services Deployed + +```mermaid +flowchart TB + subgraph Azure["Azure Cloud"] + subgraph Management["Management Plane"] + ARM[Azure Resource Manager] + AAD[Microsoft Entra ID] + RBAC[Azure RBAC] + end + + subgraph Compute["Compute Services"] + DC[Microsoft DevCenter] + DEVBOX[Dev Box VMs] + end + + subgraph Security["Security Services"] + KV[Azure Key Vault] + end + + subgraph Networking["Networking Services"] + VNET[Virtual Network] + SUBNET[Subnets] + NSG[Network Security Groups] + end + + subgraph Monitoring["Monitoring Services"] + LA[Log Analytics Workspace] + DIAG[Diagnostic Settings] + SOL[Solutions] + end + + subgraph Storage["Storage Services"] + BLOB[Blob Storage
Dev Box Images] + end + end + + ARM --> DC + ARM --> KV + ARM --> VNET + ARM --> LA + + AAD --> RBAC + RBAC --> DC + RBAC --> KV + + DC --> DEVBOX + DEVBOX --> VNET + VNET --> SUBNET + SUBNET --> NSG + + DC --> DIAG + KV --> DIAG + VNET --> DIAG + DIAG --> LA + LA --> SOL +``` + +### Service Catalog + +| Service | Azure Resource Type | Purpose | API Version | +| ----------------------- | ------------------------------------------ | ------------------------------ | ------------------ | +| **DevCenter** | `Microsoft.DevCenter/devcenters` | Central management for Dev Box | 2025-10-01-preview | +| **Projects** | `Microsoft.DevCenter/projects` | Team/workstream isolation | 2025-10-01-preview | +| **Pools** | `Microsoft.DevCenter/projects/pools` | Dev Box VM configurations | 2025-10-01-preview | +| **Catalogs** | `Microsoft.DevCenter/devcenters/catalogs` | Image/environment definitions | 2025-10-01-preview | +| **Key Vault** | `Microsoft.KeyVault/vaults` | Secrets management | 2025-05-01 | +| **Secrets** | `Microsoft.KeyVault/vaults/secrets` | Store PAT tokens | 2025-05-01 | +| **Log Analytics** | `Microsoft.OperationalInsights/workspaces` | Centralized logging | 2025-07-01 | +| **Solutions** | `Microsoft.OperationsManagement/solutions` | Log analysis capabilities | 2015-11-01-preview | +| **Virtual Network** | `Microsoft.Network/virtualNetworks` | Network connectivity | 2025-01-01 | +| **Resource Groups** | `Microsoft.Resources/resourceGroups` | Resource organization | 2025-04-01 | +| **Role Assignments** | `Microsoft.Authorization/roleAssignments` | RBAC permissions | 2022-04-01 | +| **Diagnostic Settings** | `Microsoft.Insights/diagnosticSettings` | Telemetry routing | 2021-05-01-preview | + +### Supported Azure Regions + +The accelerator supports deployment to the following regions: + +| Region | Location Code | Availability | +| -------------------- | -------------------- | ------------ | +| East US | `eastus` | βœ… Supported | +| East US 2 | `eastus2` | βœ… Supported | +| West US | `westus` | βœ… Supported | +| West US 2 | `westus2` | βœ… Supported | +| West US 3 | `westus3` | βœ… Supported | +| Central US | `centralus` | βœ… Supported | +| North Europe | `northeurope` | βœ… Supported | +| West Europe | `westeurope` | βœ… Supported | +| Southeast Asia | `southeastasia` | βœ… Supported | +| Australia East | `australiaeast` | βœ… Supported | +| Japan East | `japaneast` | βœ… Supported | +| UK South | `uksouth` | βœ… Supported | +| Canada Central | `canadacentral` | βœ… Supported | +| Sweden Central | `swedencentral` | βœ… Supported | +| Switzerland North | `switzerlandnorth` | βœ… Supported | +| Germany West Central | `germanywestcentral` | βœ… Supported | + +--- + +## Landing Zone Design + +### Four-Zone Architecture + +```mermaid +flowchart TB + subgraph Subscription["Azure Subscription"] + subgraph SecurityZone["πŸ” Security Landing Zone"] + SEC_RG["devexp-security-{env}-{region}-RG"] + KV["Key Vault
contoso-{unique}-kv"] + SECRET["Secret: gha-token"] + end + + subgraph MonitoringZone["πŸ“Š Monitoring Landing Zone"] + MON_RG["devexp-monitoring-{env}-{region}-RG"] + LA["Log Analytics
logAnalytics-{unique}"] + SOL["Azure Activity Solution"] + end + + subgraph ConnectivityZone["🌐 Connectivity Landing Zone"] + CON_RG["eShop-connectivity-RG"] + VNET["Virtual Network
eShop"] + SUBNET["Subnet
eShop-subnet"] + NC["Network Connection
netconn-eShop"] + end + + subgraph WorkloadZone["πŸ’» Workload Landing Zone"] + WRK_RG["devexp-workload-{env}-{region}-RG"] + DC["DevCenter
devexp-devcenter"] + PROJ["Project: eShop"] + POOL1["Pool: backend-engineer"] + POOL2["Pool: frontend-engineer"] + end + end + + SEC_RG --> KV + KV --> SECRET + + MON_RG --> LA + LA --> SOL + + CON_RG --> VNET + VNET --> SUBNET + SUBNET --> NC + + WRK_RG --> DC + DC --> PROJ + PROJ --> POOL1 + PROJ --> POOL2 + + NC -.->|Attach| DC + SECRET -.->|Auth| DC + LA -.->|Diagnostics| KV + LA -.->|Diagnostics| DC + LA -.->|Diagnostics| VNET +``` + +### Resource Group Naming Convention + +| Landing Zone | Pattern | Example | +| ------------ | --------------------------- | ----------------------------------- | +| Security | `{name}-{env}-{region}-RG` | `devexp-security-demo-eastus2-RG` | +| Monitoring | `{name}-{env}-{region}-RG` | `devexp-monitoring-demo-eastus2-RG` | +| Workload | `{name}-{env}-{region}-RG` | `devexp-workload-demo-eastus2-RG` | +| Connectivity | `{project}-connectivity-RG` | `eShop-connectivity-RG` | + +### Resource Naming Patterns + +| Resource Type | Pattern | Example | +| ------------------ | --------------------- | ------------------------- | +| Key Vault | `{name}-{unique}-kv` | `contoso-abc123xyz-kv` | +| Log Analytics | `{name}-{unique}` | `logAnalytics-abc123xyz` | +| DevCenter | `{name}` | `devexp-devcenter` | +| Project | `{name}` | `eShop` | +| Pool | `{name}-{index}-pool` | `backend-engineer-0-pool` | +| VNet | `{project}` | `eShop` | +| Network Connection | `netconn-{vnet}` | `netconn-eShop` | + +### Tagging Strategy + +All resources are tagged with consistent metadata: + +| Tag | Purpose | Example Values | +| ------------- | ------------------- | ---------------------------------- | +| `environment` | Deployment stage | dev, test, staging, prod | +| `division` | Business unit | Platforms | +| `team` | Owning team | DevExP | +| `project` | Project name | Contoso-DevExp-DevBox | +| `costCenter` | Cost allocation | IT | +| `owner` | Resource owner | Contoso | +| `landingZone` | Zone classification | Security, Monitoring, Workload | +| `resources` | Resource type | ResourceGroup, DevCenter, KeyVault | + +--- + +## Network Architecture + +### Network Topology + +```mermaid +flowchart TB + subgraph Internet["Internet"] + DEV[Developer] + end + + subgraph Azure["Azure"] + subgraph DevCenter["DevCenter"] + DC_CTRL[Control Plane] + end + + subgraph ManagedNet["Microsoft-Hosted Network"] + MN[Managed Network
Microsoft-provided] + end + + subgraph CustomerNet["Customer-Managed Network"] + subgraph VNet["eShop VNet (10.0.0.0/16)"] + SUBNET1["eShop-subnet
10.0.1.0/24"] + end + + NC[Network Connection] + end + + subgraph DevBoxes["Dev Box VMs"] + DB1[Backend Dev Box] + DB2[Frontend Dev Box] + end + end + + DEV -->|RDP/HTTPS| DC_CTRL + DC_CTRL --> MN + DC_CTRL --> NC + + NC --> SUBNET1 + + MN --> DB1 + MN --> DB2 + SUBNET1 --> DB1 + SUBNET1 --> DB2 +``` + +### Network Options + +| Network Type | Description | Use Case | +| ------------- | --------------------------------------------------- | ----------------------------------------------- | +| **Managed** | Microsoft-hosted network, no customer VNet required | Simplified setup, no hybrid connectivity needed | +| **Unmanaged** | Customer-provided VNet with Network Connection | Hybrid connectivity, corporate network access | + +### Network Configuration (Unmanaged) + +From `devcenter.yaml`: + +```yaml +network: + name: eShop + create: true + resourceGroupName: 'eShop-connectivity-RG' + virtualNetworkType: Unmanaged + addressPrefixes: + - 10.0.0.0/16 + subnets: + - name: eShop-subnet + properties: + addressPrefix: 10.0.1.0/24 +``` + +### Network Connection Flow + +```mermaid +sequenceDiagram + participant DC as DevCenter + participant NC as Network Connection + participant VNet as Virtual Network + participant Subnet as Subnet + participant DB as Dev Box + + DC->>NC: Create Network Connection + NC->>VNet: Reference VNet + VNet->>Subnet: Validate Subnet + NC-->>DC: Connection Ready + + DC->>DB: Provision Dev Box + DB->>NC: Request Network Config + NC->>Subnet: Allocate IP + Subnet-->>DB: IP Assigned + DB-->>DC: Dev Box Ready +``` + +### Network Security + +| Control | Implementation | Purpose | +| --------------------------- | ------------------------------ | -------------------------------- | +| **Subnet Delegation** | DevCenter network connection | Controlled Dev Box placement | +| **NSG Rules** | Applied to subnets | Traffic filtering | +| **Private Endpoints** | Optional for Key Vault | Secure secret access | +| **Managed Network Regions** | `managedVirtualNetworkRegions` | Region-specific managed networks | + +--- + +## Identity & Access + +### Identity Model + +```mermaid +flowchart TB + subgraph Identities["Identity Types"] + SI_DC[DevCenter
System-Assigned MI] + SI_PROJ[Project
System-Assigned MI] + ADG[Azure AD Groups] + end + + subgraph Roles["RBAC Roles"] + R1[Contributor] + R2[User Access Administrator] + R3[Key Vault Secrets User] + R4[Key Vault Secrets Officer] + R5[DevCenter Project Admin] + R6[Dev Box User] + R7[Deployment Environment User] + end + + subgraph Scopes["Assignment Scopes"] + SUB[Subscription] + RG_SEC[Security RG] + RG_WRK[Workload RG] + DC[DevCenter] + PROJ[Project] + end + + SI_DC --> R1 + SI_DC --> R2 + SI_DC --> R3 + SI_DC --> R4 + + SI_PROJ --> R3 + SI_PROJ --> R4 + + ADG --> R5 + ADG --> R6 + ADG --> R7 + + R1 --> SUB + R2 --> SUB + R3 --> RG_SEC + R4 --> RG_SEC + R5 --> RG_WRK + R6 --> PROJ + R7 --> PROJ +``` + +### Role Assignment Matrix + +| Identity | Role | Scope | Purpose | +| ----------------------------- | --------------------------- | ------------ | -------------------------- | +| **DevCenter MI** | Contributor | Subscription | Manage DevCenter resources | +| **DevCenter MI** | User Access Administrator | Subscription | Assign roles to projects | +| **DevCenter MI** | Key Vault Secrets User | Security RG | Read secrets for catalogs | +| **DevCenter MI** | Key Vault Secrets Officer | Security RG | Manage secrets | +| **Project MI** | Key Vault Secrets User | Security RG | Read secrets for catalogs | +| **Project MI** | Key Vault Secrets Officer | Security RG | Manage secrets | +| **Platform Engineering Team** | DevCenter Project Admin | Workload RG | Manage projects | +| **eShop Developers** | Contributor | Project | Manage project resources | +| **eShop Developers** | Dev Box User | Project | Create/manage Dev Boxes | +| **eShop Developers** | Deployment Environment User | Project | Deploy environments | + +### Azure AD Group Configuration + +From `devcenter.yaml`: + +```yaml +identity: + roleAssignments: + 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 + +projects: + - name: 'eShop' + identity: + roleAssignments: + - azureADGroupId: '9d42a792-2d74-441d-8bcb-71009371725f' + azureADGroupName: 'eShop Developers' + azureRBACRoles: + - name: 'Dev Box User' + id: '45d50f46-0b78-4001-a660-4198cbe8cd05' + scope: Project +``` + +### Role Hierarchy + +```mermaid +flowchart TD + subgraph Subscription["Subscription Level"] + CONTRIB[Contributor] + UAA[User Access Administrator] + end + + subgraph ResourceGroup["Resource Group Level"] + KV_USER[Key Vault Secrets User] + KV_OFFICER[Key Vault Secrets Officer] + PROJ_ADMIN[DevCenter Project Admin] + end + + subgraph Resource["Resource Level"] + DB_USER[Dev Box User] + ENV_USER[Deployment Environment User] + end + + CONTRIB --> KV_USER + UAA --> PROJ_ADMIN + PROJ_ADMIN --> DB_USER + PROJ_ADMIN --> ENV_USER +``` + +--- + +## Security Architecture + +### Key Vault Configuration + +```mermaid +flowchart LR + subgraph KeyVault["Azure Key Vault"] + PROPS[Properties] + SECRET[Secrets] + ACCESS[Access Control] + end + + subgraph Properties["Security Properties"] + P1[RBAC Authorization: true] + P2[Soft Delete: true] + P3[Purge Protection: true] + P4[Retention: 7 days] + end + + subgraph Secrets["Stored Secrets"] + S1[gha-token
GitHub PAT] + end + + subgraph Access["RBAC Access"] + A1[DevCenter MI] + A2[Project MI] + A3[Deployer] + end + + PROPS --> Properties + SECRET --> Secrets + ACCESS --> Access + + A1 -->|Secrets User| S1 + A2 -->|Secrets User| S1 + A3 -->|Secrets Officer| S1 +``` + +### Security Controls + +| Control | Configuration | Value | Purpose | +| ---------------------- | --------------------------- | ---------------- | ----------------------------------------- | +| **RBAC Authorization** | `enableRbacAuthorization` | `true` | Use Azure RBAC instead of access policies | +| **Soft Delete** | `enableSoftDelete` | `true` | Recover accidentally deleted secrets | +| **Purge Protection** | `enablePurgeProtection` | `true` | Prevent permanent deletion | +| **Retention Period** | `softDeleteRetentionInDays` | `7` | Recovery window | +| **Managed Identities** | `identity.type` | `SystemAssigned` | No credential management | +| **Diagnostic Logging** | `diagnosticSettings` | All logs | Audit trail | + +### Security Data Flow + +```mermaid +sequenceDiagram + participant DC as DevCenter + participant MI as Managed Identity + participant AAD as Entra ID + participant RBAC as Azure RBAC + participant KV as Key Vault + participant GH as GitHub + + DC->>MI: Request token + MI->>AAD: Authenticate + AAD-->>MI: Access token + MI-->>DC: Token + + DC->>KV: Get secret (with token) + KV->>RBAC: Check permissions + RBAC-->>KV: Authorized + KV-->>DC: Secret value + + DC->>GH: Clone catalog (with PAT) + GH-->>DC: Repository content +``` + +### Compliance Alignment + +| Framework | Requirement | Implementation | +| ---------------------------- | --------------------------------- | ------------------------------------ | +| **Azure Security Benchmark** | ASB-DP-1: Data Discovery | Resource tagging, Log Analytics | +| **Azure Security Benchmark** | ASB-DP-4: Data at Rest Encryption | Key Vault software keys | +| **Azure Security Benchmark** | ASB-IM-1: Managed Identities | SystemAssigned on DevCenter/Projects | +| **Azure Security Benchmark** | ASB-PA-7: Least Privilege | Scoped RBAC role assignments | +| **Azure Security Benchmark** | ASB-LT-4: Logging | Diagnostic settings on all resources | + +--- + +## Monitoring & Observability + +### Monitoring Architecture + +```mermaid +flowchart TB + subgraph Sources["Data Sources"] + DC[DevCenter] + KV[Key Vault] + VNET[Virtual Network] + LA_SELF[Log Analytics] + end + + subgraph Collection["Data Collection"] + DIAG1[Diagnostic Settings] + DIAG2[Diagnostic Settings] + DIAG3[Diagnostic Settings] + DIAG4[Self-Diagnostics] + end + + subgraph Analytics["Log Analytics Workspace"] + LOGS[Logs
AzureDiagnostics] + METRICS[Metrics
AzureMetrics] + ACTIVITY[Activity Logs
AzureActivity] + end + + subgraph Outputs["Analysis & Action"] + QUERIES[KQL Queries] + ALERTS[Alerts] + WORKBOOKS[Workbooks] + DASHBOARD[Dashboards] + end + + DC --> DIAG1 + KV --> DIAG2 + VNET --> DIAG3 + LA_SELF --> DIAG4 + + DIAG1 --> LOGS + DIAG1 --> METRICS + DIAG2 --> LOGS + DIAG2 --> METRICS + DIAG3 --> LOGS + DIAG3 --> METRICS + DIAG4 --> LOGS + DIAG4 --> METRICS + + LOGS --> QUERIES + METRICS --> QUERIES + ACTIVITY --> QUERIES + + QUERIES --> ALERTS + QUERIES --> WORKBOOKS + QUERIES --> DASHBOARD +``` + +### Log Analytics Configuration + +| Setting | Value | Purpose | +| --------------------- | ---------------- | ---------------------- | +| **SKU** | PerGB2018 | Pay-per-GB pricing | +| **Solutions** | AzureActivity | Activity log analysis | +| **Log Categories** | allLogs | Comprehensive logging | +| **Metric Categories** | AllMetrics | Performance monitoring | +| **Destination Type** | AzureDiagnostics | Standard schema | + +### Diagnostic Settings + +All resources deploy with standardized diagnostic settings: + +```bicep +resource diagnosticSettings 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: '${resourceName}-diagnostics' + scope: targetResource + properties: { + logAnalyticsDestinationType: 'AzureDiagnostics' + logs: [ + { + categoryGroup: 'allLogs' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + workspaceId: logAnalyticsWorkspaceId + } +} +``` + +### Key Metrics + +| Resource | Metric | Description | Alert Threshold | +| ----------------- | ----------------- | --------------------- | ----------------- | +| **Key Vault** | ServiceApiLatency | API response time | > 1000ms | +| **Key Vault** | Availability | Service availability | < 99.9% | +| **DevCenter** | PoolUtilization | Pool usage percentage | > 80% | +| **VNet** | BytesDroppedDDoS | DDoS mitigation | > 0 | +| **Log Analytics** | IngestionVolume | Data ingestion rate | Anomaly detection | + +--- + +## CI/CD Infrastructure + +### CI/CD Pipeline Flow + +```mermaid +flowchart LR + subgraph Trigger["Triggers"] + PUSH[Push to feature/*] + PR[Pull Request to main] + MANUAL[Manual Dispatch] + end + + subgraph CI["Continuous Integration"] + VERSION[Generate Version] + BUILD[Build Bicep] + ARTIFACT[Upload Artifacts] + end + + subgraph CD["Continuous Deployment"] + AUTH[Azure Auth
Federated Credentials] + PROVISION[azd provision] + DEPLOY[Deploy to Azure] + end + + subgraph Release["Release"] + TAG[Create Git Tag] + RELEASE[GitHub Release] + NOTES[Release Notes] + end + + PUSH --> VERSION + PR --> VERSION + MANUAL --> VERSION + + VERSION --> BUILD + BUILD --> ARTIFACT + + ARTIFACT --> AUTH + AUTH --> PROVISION + PROVISION --> DEPLOY + + DEPLOY --> TAG + TAG --> RELEASE + RELEASE --> NOTES +``` + +### GitHub Actions Workflows + +| Workflow | File | Trigger | Purpose | +| -------------------------- | ------------------------------- | ------------------------------ | ------------------------ | +| **Continuous Integration** | `.github/workflows/ci.yml` | Push to feature/\*, PR to main | Build and validate Bicep | +| **Deploy to Azure** | `.github/workflows/deploy.yml` | Manual dispatch | Deploy infrastructure | +| **Branch-Based Release** | `.github/workflows/release.yml` | Manual dispatch | Create releases | + +### CI Workflow Details (`ci.yml`) + +```mermaid +flowchart TD + subgraph Job1["generate-tag-version"] + CHECKOUT1[Checkout Code] + GENERATE[Generate Release Info] + OUTPUT1[/new_version, release_type,
previous_tag, should_release/] + end + + subgraph Job2["build"] + CHECKOUT2[Checkout Code] + BUILD[Build Bicep Code] + UPLOAD[Upload Artifacts] + end + + CHECKOUT1 --> GENERATE + GENERATE --> OUTPUT1 + OUTPUT1 --> CHECKOUT2 + CHECKOUT2 --> BUILD + BUILD --> UPLOAD +``` + +### Deploy Workflow Details (`deploy.yml`) + +```yaml +# Key workflow steps +- name: Install azd + uses: Azure/setup-azd@v2 + +- name: Build Accelerator Bicep + run: | + az bicep build --file ./infra/main.bicep --outdir ./artifacts + +- name: Log in with Azure (Federated Credentials) + run: | + azd auth login \ + --client-id "$AZURE_CLIENT_ID" \ + --federated-credential-provider "github" \ + --tenant-id "$AZURE_TENANT_ID" + +- name: Deploy to Azure + run: azd provision --no-prompt + env: + KEY_VAULT_SECRET: ${{ secrets.KEY_VAULT_SECRET }} +``` + +### Azure DevOps Pipeline (`azure-dev.yml`) + +```yaml +# Key pipeline steps +- task: Bash@3 + displayName: Install azd + inputs: + script: curl -fsSL https://aka.ms/install-azd.sh | sudo bash + +- pwsh: azd config set auth.useAzCliAuth "true" + displayName: Configure AZD to Use AZ CLI Authentication + +- task: AzureCLI@2 + displayName: Provision Infrastructure + inputs: + azureSubscription: azconnection + scriptType: bash + inlineScript: azd provision --no-prompt +``` + +### Authentication Methods + +| Platform | Method | Configuration | +| ------------------ | -------------------------- | ------------------------------------------------------------- | +| **GitHub Actions** | OIDC Federated Credentials | `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_SUBSCRIPTION_ID` | +| **Azure DevOps** | Service Connection | `azconnection` service principal | + +--- + +## Deployment Tools + +### Azure Developer CLI (azd) + +The primary deployment tool for the accelerator. + +| Command | Purpose | Usage | +| --------------- | ------------------------- | ------------------------- | +| `azd init` | Initialize environment | First-time setup | +| `azd provision` | Deploy infrastructure | Create Azure resources | +| `azd env new` | Create new environment | Multi-environment support | +| `azd env set` | Set environment variables | Configure parameters | + +### azd Configuration (`azure.yaml`) + +```yaml +name: ContosoDevExp + +hooks: + preprovision: + shell: sh + run: | + # Set default source control platform + export SOURCE_CONTROL_PLATFORM="${SOURCE_CONTROL_PLATFORM:-github}" + ./setup.sh -e ${AZURE_ENV_NAME} -s ${SOURCE_CONTROL_PLATFORM} +``` + +### Setup Scripts + +| Script | Platform | Purpose | +| ---------------- | ---------- | ---------------------------- | +| `setUp.ps1` | PowerShell | Windows setup automation | +| `setUp.sh` | Bash | Linux/macOS setup automation | +| `cleanSetUp.ps1` | PowerShell | Resource cleanup | + +### Setup Script Flow + +```mermaid +flowchart TD + START[Start Setup] + CHECK_CLI[Check CLI Tools
az, azd, gh] + AUTH_AZ[Authenticate Azure] + AUTH_GH[Authenticate GitHub/ADO] + GET_TOKEN[Get PAT Token] + INIT_ENV[Initialize azd Environment] + SET_VARS[Set Environment Variables] + PROVISION[azd provision] + END[Setup Complete] + + START --> CHECK_CLI + CHECK_CLI --> AUTH_AZ + AUTH_AZ --> AUTH_GH + AUTH_GH --> GET_TOKEN + GET_TOKEN --> INIT_ENV + INIT_ENV --> SET_VARS + SET_VARS --> PROVISION + PROVISION --> END +``` + +### Environment Variables + +| Variable | Source | Purpose | +| ------------------------- | ----------------- | ---------------------------------- | +| `AZURE_ENV_NAME` | User input | Environment name (dev, test, prod) | +| `AZURE_LOCATION` | User input | Azure region | +| `AZURE_SUBSCRIPTION_ID` | Azure CLI | Target subscription | +| `AZURE_CLIENT_ID` | Service principal | Deployment identity | +| `AZURE_TENANT_ID` | Azure AD | Tenant identifier | +| `KEY_VAULT_SECRET` | GitHub Secret | PAT token for catalogs | +| `SOURCE_CONTROL_PLATFORM` | User input | github or adogit | + +--- + +## DevOps Practices + +### Branching Strategy + +```mermaid +gitGraph + commit id: "Initial" + branch feature/new-feature + checkout feature/new-feature + commit id: "Feature work" + commit id: "More work" + checkout main + merge feature/new-feature + commit id: "Release v1.0.0" tag: "v1.0.0" + branch fix/bug-fix + checkout fix/bug-fix + commit id: "Bug fix" + checkout main + merge fix/bug-fix + commit id: "Release v1.0.1" tag: "v1.0.1" +``` + +### Branch Types + +| Branch Pattern | Purpose | Version Impact | +| -------------- | --------------------- | --------------------- | +| `main` | Production-ready code | Major/Patch increment | +| `feature/*` | New features | Minor increment | +| `fix/*` | Bug fixes | Patch increment | +| `docs/*` | Documentation | No version change | + +### Semantic Versioning + +The accelerator follows semantic versioning (`MAJOR.MINOR.PATCH`): + +| Version Component | Increment Condition | Example | +| ----------------- | ------------------------------------------------------ | ------------- | +| **MAJOR** | Breaking changes, main branch with minor=0 AND patch=0 | 1.0.0 β†’ 2.0.0 | +| **MINOR** | Feature branches | 1.0.0 β†’ 1.1.0 | +| **PATCH** | Fix branches, main branch with minorβ‰ 0 OR patchβ‰ 0 | 1.0.0 β†’ 1.0.1 | + +### Release Process + +```mermaid +flowchart LR + subgraph Trigger["Release Trigger"] + MANUAL[Manual Dispatch] + end + + subgraph Generate["Generate Metadata"] + VERSION[Calculate Version] + NOTES[Generate Notes] + end + + subgraph Build["Build Phase"] + BICEP[Compile Bicep] + ARM[Generate ARM] + ZIP[Package Artifacts] + end + + subgraph Publish["Publish Phase"] + TAG[Create Git Tag] + RELEASE[GitHub Release] + UPLOAD[Upload Assets] + end + + MANUAL --> VERSION + VERSION --> NOTES + NOTES --> BICEP + BICEP --> ARM + ARM --> ZIP + ZIP --> TAG + TAG --> RELEASE + RELEASE --> UPLOAD +``` + +### Infrastructure as Code Practices + +| Practice | Implementation | Benefit | +| -------------------------- | -------------------------------- | -------------------------- | +| **Version Control** | All Bicep/YAML in Git | Audit trail, collaboration | +| **Code Review** | Pull requests to main | Quality assurance | +| **Automated Testing** | CI pipeline validation | Catch errors early | +| **Idempotent Deployments** | Declarative Bicep | Safe re-runs | +| **Environment Parity** | Same templates, different params | Consistent environments | +| **Documentation as Code** | Markdown in repository | Self-documenting | + +--- + +## References + +### External References + +| Reference | URL | Description | +| ------------------------ | ------------------------------------------------------------------------------ | --------------------- | +| Microsoft Dev Box | https://learn.microsoft.com/azure/dev-box/ | Dev Box documentation | +| Azure DevCenter API | https://learn.microsoft.com/azure/templates/microsoft.devcenter/ | Resource reference | +| Azure Developer CLI | https://learn.microsoft.com/azure/developer/azure-developer-cli/ | azd documentation | +| Azure Landing Zones | https://learn.microsoft.com/azure/cloud-adoption-framework/ready/landing-zone/ | CAF guidance | +| GitHub Actions for Azure | https://learn.microsoft.com/azure/developer/github/ | CI/CD integration | +| Azure RBAC | https://learn.microsoft.com/azure/role-based-access-control/ | Access control | + +### Related Architecture Documents + +| Document | Path | Description | +| ------------------------ | ------------------------------------------------------------------ | --------------------- | +| Business Architecture | [01-business-architecture.md](./01-business-architecture.md) | Business context | +| Data Architecture | [02-data-architecture.md](./02-data-architecture.md) | Data models and flows | +| Application Architecture | [03-application-architecture.md](./03-application-architecture.md) | Bicep modules | + +--- + +## Glossary + +| Term | Definition | +| ------------------------- | ------------------------------------------------------------ | +| **azd** | Azure Developer CLI - deployment tool for Azure applications | +| **Bicep** | Domain-specific language for Azure infrastructure deployment | +| **DevCenter** | Azure service for managing developer environments | +| **Dev Box** | Cloud-powered developer workstation | +| **Federated Credentials** | OIDC-based authentication without secrets | +| **Landing Zone** | Pre-configured Azure environment with governance | +| **Managed Identity** | Azure AD identity automatically managed by Azure | +| **Network Connection** | DevCenter resource linking to customer VNet | +| **RBAC** | Role-Based Access Control | +| **SKU** | Stock Keeping Unit - defines resource size/tier | +| **System-Assigned MI** | Managed identity tied to resource lifecycle | +| **VNet** | Virtual Network - isolated network in Azure | + +--- + +_This document follows TOGAF Architecture Development Method (ADM) principles +and aligns with the Technology Architecture domain of the BDAT framework._ From c4c0e1bed7c52a17c72142e5c7f49bd466e831b2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 14:55:00 -0500 Subject: [PATCH 07/49] Refactor Business Architecture documentation for improved formatting and clarity --- docs/architecture/01-business-architecture.md | 40 +++++++++---------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/architecture/01-business-architecture.md b/docs/architecture/01-business-architecture.md index c7d8503d..722dc3c8 100644 --- a/docs/architecture/01-business-architecture.md +++ b/docs/architecture/01-business-architecture.md @@ -11,21 +11,21 @@ --- -## Table of Contents - -- [Executive Summary](#executive-summary) -- [Business Context](#business-context) -- [Stakeholder Analysis](#stakeholder-analysis) -- [Business Capabilities](#business-capabilities) -- [Value Streams](#value-streams) -- [Business Requirements](#business-requirements) -- [Success Metrics](#success-metrics) -- [References](#references) -- [Glossary](#glossary) +## πŸ“‘ Table of Contents + +- [πŸ“‹ Executive Summary](#-executive-summary) +- [🏒 Business Context](#-business-context) +- [πŸ‘₯ Stakeholder Analysis](#-stakeholder-analysis) +- [πŸ’Ό Business Capabilities](#-business-capabilities) +- [πŸ”„ Value Streams](#-value-streams) +- [πŸ“ Business Requirements](#-business-requirements) +- [πŸ“Š Success Metrics](#-success-metrics) +- [πŸ“š References](#-references) +- [πŸ“– Glossary](#-glossary) --- -## Executive Summary +## πŸ“‹ Executive Summary The **DevExp-DevBox Landing Zone Accelerator** is a comprehensive infrastructure-as-code solution that automates the deployment and management of @@ -68,7 +68,7 @@ mindmap --- -## Business Context +## 🏒 Business Context ### Problem Statement @@ -127,7 +127,7 @@ flowchart LR --- -## Stakeholder Analysis +## πŸ‘₯ Stakeholder Analysis ### Stakeholder Map @@ -179,7 +179,7 @@ _R = Responsible, A = Accountable, C = Consulted, I = Informed_ --- -## Business Capabilities +## πŸ’Ό Business Capabilities ### Business Capability Model @@ -256,7 +256,7 @@ block-beta --- -## Value Streams +## πŸ”„ Value Streams ### Developer Onboarding Value Stream @@ -324,7 +324,7 @@ sequenceDiagram --- -## Business Requirements +## πŸ“ Business Requirements ### Functional Requirements @@ -389,7 +389,7 @@ flowchart TD --- -## Success Metrics +## πŸ“Š Success Metrics ### Key Performance Indicators (KPIs) @@ -426,7 +426,7 @@ pie showData --- -## References +## πŸ“š References ### External References @@ -447,7 +447,7 @@ pie showData --- -## Glossary +## πŸ“– Glossary | Term | Definition | | ---------------- | -------------------------------------------------------------------------------- | From 5775d4a5be09930edfbec28a251802f5e6d52e04 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 14:56:27 -0500 Subject: [PATCH 08/49] Refactor architecture documentation for improved formatting and clarity --- docs/architecture/02-data-architecture.md | 40 ++++++++-------- .../03-application-architecture.md | 40 ++++++++-------- .../04-technology-architecture.md | 48 +++++++++---------- 3 files changed, 64 insertions(+), 64 deletions(-) diff --git a/docs/architecture/02-data-architecture.md b/docs/architecture/02-data-architecture.md index 17918028..d9deb186 100644 --- a/docs/architecture/02-data-architecture.md +++ b/docs/architecture/02-data-architecture.md @@ -11,21 +11,21 @@ --- -## Table of Contents - -- [Data Overview](#data-overview) -- [Configuration Data Model](#configuration-data-model) -- [Secrets Management](#secrets-management) -- [Telemetry & Diagnostics](#telemetry--diagnostics) -- [Data Flow Diagrams](#data-flow-diagrams) -- [Data Governance](#data-governance) -- [Schema Documentation](#schema-documentation) -- [References](#references) -- [Glossary](#glossary) +## πŸ“‘ Table of Contents + +- [πŸ“Š Data Overview](#-data-overview) +- [βš™οΈ Configuration Data Model](#️-configuration-data-model) +- [πŸ” Secrets Management](#-secrets-management) +- [πŸ“± Telemetry & Diagnostics](#-telemetry--diagnostics) +- [πŸ”€ Data Flow Diagrams](#-data-flow-diagrams) +- [πŸ›‘οΈ Data Governance](#️-data-governance) +- [πŸ“„ Schema Documentation](#-schema-documentation) +- [πŸ“š References](#-references) +- [πŸ“– Glossary](#-glossary) --- -## Data Overview +## πŸ“Š Data Overview The DevExp-DevBox Landing Zone Accelerator manages several categories of data that flow through the system during deployment and operation. @@ -70,7 +70,7 @@ erDiagram --- -## Configuration Data Model +## βš™οΈ Configuration Data Model ### Configuration File Hierarchy @@ -270,7 +270,7 @@ classDiagram --- -## Secrets Management +## πŸ” Secrets Management ### Secret Types @@ -351,7 +351,7 @@ flowchart TD --- -## Telemetry & Diagnostics +## πŸ“± Telemetry & Diagnostics ### Log Analytics Data Collection @@ -437,7 +437,7 @@ erDiagram --- -## Data Flow Diagrams +## πŸ”€ Data Flow Diagrams ### Configuration Loading Flow @@ -558,7 +558,7 @@ flowchart TD --- -## Data Governance +## πŸ›‘οΈ Data Governance ### Data Classification @@ -627,7 +627,7 @@ flowchart LR --- -## Schema Documentation +## πŸ“„ Schema Documentation ### JSON Schema Files @@ -690,7 +690,7 @@ flowchart TD --- -## References +## πŸ“š References ### External References @@ -710,7 +710,7 @@ flowchart TD --- -## Glossary +## πŸ“– Glossary | Term | Definition | | ----------------------- | ------------------------------------------------------------------------------ | diff --git a/docs/architecture/03-application-architecture.md b/docs/architecture/03-application-architecture.md index 520e5f7f..2de617e6 100644 --- a/docs/architecture/03-application-architecture.md +++ b/docs/architecture/03-application-architecture.md @@ -11,21 +11,21 @@ --- -## Table of Contents - -- [Architecture Overview](#architecture-overview) -- [Module Catalog](#module-catalog) -- [Module Dependencies](#module-dependencies) -- [Deployment Orchestration](#deployment-orchestration) -- [Interface Contracts](#interface-contracts) -- [Design Patterns](#design-patterns) -- [Extension Points](#extension-points) -- [References](#references) -- [Glossary](#glossary) +## πŸ“‘ Table of Contents + +- [πŸ›οΈ Architecture Overview](#️-architecture-overview) +- [πŸ“¦ Module Catalog](#-module-catalog) +- [πŸ”— Module Dependencies](#-module-dependencies) +- [πŸš€ Deployment Orchestration](#-deployment-orchestration) +- [πŸ“ Interface Contracts](#-interface-contracts) +- [🎯 Design Patterns](#-design-patterns) +- [πŸ”Œ Extension Points](#-extension-points) +- [πŸ“š References](#-references) +- [πŸ“– Glossary](#-glossary) --- -## Architecture Overview +## πŸ›οΈ Architecture Overview The DevExp-DevBox Landing Zone Accelerator implements a **modular Bicep architecture** following Azure Landing Zone patterns. The solution is organized @@ -112,7 +112,7 @@ flowchart TB --- -## Module Catalog +## πŸ“¦ Module Catalog ### Module Hierarchy @@ -570,7 +570,7 @@ src/ --- -## Module Dependencies +## πŸ”— Module Dependencies ### Dependency Graph @@ -667,7 +667,7 @@ flowchart TD --- -## Deployment Orchestration +## πŸš€ Deployment Orchestration ### Deployment Sequence @@ -733,7 +733,7 @@ azd provision -e dev --no-prompt --- -## Interface Contracts +## πŸ“ Interface Contracts ### Module Parameter Types @@ -801,7 +801,7 @@ type NetworkSettings = { --- -## Design Patterns +## 🎯 Design Patterns ### Patterns Implemented @@ -857,7 +857,7 @@ output AZURE_DEV_CENTER_PROJECTS array = [ --- -## Extension Points +## πŸ”Œ Extension Points ### Adding a New Project @@ -1000,7 +1000,7 @@ flowchart TD --- -## References +## πŸ“š References ### External References @@ -1020,7 +1020,7 @@ flowchart TD --- -## Glossary +## πŸ“– Glossary | Term | Definition | | --------------------- | ------------------------------------------------------------------------- | diff --git a/docs/architecture/04-technology-architecture.md b/docs/architecture/04-technology-architecture.md index 3f5ede24..e58ec30e 100644 --- a/docs/architecture/04-technology-architecture.md +++ b/docs/architecture/04-technology-architecture.md @@ -11,23 +11,23 @@ --- -## Table of Contents - -- [Infrastructure Overview](#infrastructure-overview) -- [Landing Zone Design](#landing-zone-design) -- [Network Architecture](#network-architecture) -- [Identity & Access](#identity--access) -- [Security Architecture](#security-architecture) -- [Monitoring & Observability](#monitoring--observability) -- [CI/CD Infrastructure](#cicd-infrastructure) -- [Deployment Tools](#deployment-tools) -- [DevOps Practices](#devops-practices) -- [References](#references) -- [Glossary](#glossary) +## πŸ“‘ Table of Contents + +- [πŸ—οΈ Infrastructure Overview](#️-infrastructure-overview) +- [πŸ›οΈ Landing Zone Design](#️-landing-zone-design) +- [🌐 Network Architecture](#-network-architecture) +- [πŸ‘€ Identity & Access](#-identity--access) +- [πŸ”’ Security Architecture](#-security-architecture) +- [πŸ“Š Monitoring & Observability](#-monitoring--observability) +- [βš™οΈ CI/CD Infrastructure](#️-cicd-infrastructure) +- [πŸ› οΈ Deployment Tools](#️-deployment-tools) +- [πŸ’» DevOps Practices](#-devops-practices) +- [πŸ“š References](#-references) +- [πŸ“– Glossary](#-glossary) --- -## Infrastructure Overview +## πŸ—οΈ Infrastructure Overview The DevExp-DevBox Landing Zone Accelerator deploys a comprehensive set of Azure services organized into functional landing zones. @@ -132,7 +132,7 @@ The accelerator supports deployment to the following regions: --- -## Landing Zone Design +## πŸ›οΈ Landing Zone Design ### Four-Zone Architecture @@ -227,7 +227,7 @@ All resources are tagged with consistent metadata: --- -## Network Architecture +## 🌐 Network Architecture ### Network Topology @@ -330,7 +330,7 @@ sequenceDiagram --- -## Identity & Access +## πŸ‘€ Identity & Access ### Identity Model @@ -452,7 +452,7 @@ flowchart TD --- -## Security Architecture +## πŸ”’ Security Architecture ### Key Vault Configuration @@ -538,7 +538,7 @@ sequenceDiagram --- -## Monitoring & Observability +## πŸ“Š Monitoring & Observability ### Monitoring Architecture @@ -643,7 +643,7 @@ resource diagnosticSettings 'Microsoft.Insights/diagnosticSettings@2021-05-01-pr --- -## CI/CD Infrastructure +## βš™οΈ CI/CD Infrastructure ### CI/CD Pipeline Flow @@ -773,7 +773,7 @@ flowchart TD --- -## Deployment Tools +## πŸ› οΈ Deployment Tools ### Azure Developer CLI (azd) @@ -846,7 +846,7 @@ flowchart TD --- -## DevOps Practices +## πŸ’» DevOps Practices ### Branching Strategy @@ -935,7 +935,7 @@ flowchart LR --- -## References +## πŸ“š References ### External References @@ -958,7 +958,7 @@ flowchart LR --- -## Glossary +## πŸ“– Glossary | Term | Definition | | ------------------------- | ------------------------------------------------------------ | From f8fac671050a62e68e75d7b29ba3c567041235a4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 14:59:24 -0500 Subject: [PATCH 09/49] Refactor architecture documentation for improved structure and clarity --- docs/architecture/01-business-architecture.md | 41 +++++++- docs/architecture/02-data-architecture.md | 42 +++++++- .../03-application-architecture.md | 42 +++++++- .../04-technology-architecture.md | 42 +++++++- docs/architecture/README.md | 95 +++++++++++++++++++ 5 files changed, 258 insertions(+), 4 deletions(-) create mode 100644 docs/architecture/README.md diff --git a/docs/architecture/01-business-architecture.md b/docs/architecture/01-business-architecture.md index 722dc3c8..c0a73842 100644 --- a/docs/architecture/01-business-architecture.md +++ b/docs/architecture/01-business-architecture.md @@ -1,7 +1,37 @@ -# Business Architecture +--- +title: Business Architecture +description: + TOGAF Business Architecture documentation for DevExp-DevBox Landing Zone + Accelerator covering stakeholders, capabilities, value streams, and business + requirements +author: Platform Engineering Team +date: 2026-01-22 +version: 1.0.0 +tags: + - TOGAF + - Business Architecture + - BDAT + - DevExp-DevBox + - Landing Zone +--- + +# 🏒 Business Architecture > **DevExp-DevBox Landing Zone Accelerator** +> [!NOTE] **Target Audience:** Business Decision Makers, Enterprise Architects, +> Platform Engineers +> **Reading Time:** ~15 minutes + +
+πŸ“ Navigation + +| Previous | Index | Next | +| :------- | :----------------------------------: | --------------------------------------------------: | +| - | [🏠 Architecture Index](./README.md) | [πŸ“Š Data Architecture β†’](./02-data-architecture.md) | + +
+ | Metadata | Value | | ---------------- | ------------------------- | | **Version** | 1.0.0 | @@ -466,3 +496,12 @@ pie showData _This document follows TOGAF Architecture Development Method (ADM) principles and aligns with the Business Architecture domain of the BDAT framework._ + +--- + +
+ +**[⬆️ Back to Top](#-business-architecture)** | +**[πŸ“Š Data Architecture β†’](./02-data-architecture.md)** + +
diff --git a/docs/architecture/02-data-architecture.md b/docs/architecture/02-data-architecture.md index d9deb186..6e6a24d3 100644 --- a/docs/architecture/02-data-architecture.md +++ b/docs/architecture/02-data-architecture.md @@ -1,7 +1,37 @@ -# Data Architecture +--- +title: Data Architecture +description: + TOGAF Data Architecture documentation for DevExp-DevBox covering configuration + data models, secrets management, telemetry, and data governance +author: Platform Engineering Team +date: 2026-01-22 +version: 1.0.0 +tags: + - TOGAF + - Data Architecture + - BDAT + - DevExp-DevBox + - Configuration + - Key Vault +--- + +# πŸ“Š Data Architecture > **DevExp-DevBox Landing Zone Accelerator** +> [!NOTE] **Target Audience:** Data Architects, Platform Engineers, Security +> Engineers +> **Reading Time:** ~20 minutes + +
+πŸ“ Navigation + +| Previous | Index | Next | +| :------------------------------------------------------- | :----------------------------------: | ----------------------------------------------------------------: | +| [← Business Architecture](./01-business-architecture.md) | [🏠 Architecture Index](./README.md) | [πŸ›οΈ Application Architecture β†’](./03-application-architecture.md) | + +
+ | Metadata | Value | | ---------------- | ------------------------- | | **Version** | 1.0.0 | @@ -727,3 +757,13 @@ flowchart TD _This document follows TOGAF Architecture Development Method (ADM) principles and aligns with the Data Architecture domain of the BDAT framework._ + +--- + +
+ +**[← Business Architecture](./01-business-architecture.md)** | +**[⬆️ Back to Top](#-data-architecture)** | +**[πŸ›οΈ Application Architecture β†’](./03-application-architecture.md)** + +
diff --git a/docs/architecture/03-application-architecture.md b/docs/architecture/03-application-architecture.md index 2de617e6..227c8ff9 100644 --- a/docs/architecture/03-application-architecture.md +++ b/docs/architecture/03-application-architecture.md @@ -1,7 +1,37 @@ -# Application Architecture +--- +title: Application Architecture +description: + TOGAF Application Architecture documentation for DevExp-DevBox covering Bicep + module catalog, dependencies, deployment orchestration, and design patterns +author: Platform Engineering Team +date: 2026-01-22 +version: 1.0.0 +tags: + - TOGAF + - Application Architecture + - BDAT + - DevExp-DevBox + - Bicep + - IaC +--- + +# πŸ›οΈ Application Architecture > **DevExp-DevBox Landing Zone Accelerator** +> [!NOTE] **Target Audience:** Platform Engineers, DevOps Engineers, Cloud +> Architects +> **Reading Time:** ~25 minutes + +
+πŸ“ Navigation + +| Previous | Index | Next | +| :----------------------------------------------- | :----------------------------------: | --------------------------------------------------------------: | +| [← Data Architecture](./02-data-architecture.md) | [🏠 Architecture Index](./README.md) | [πŸ—οΈ Technology Architecture β†’](./04-technology-architecture.md) | + +
+ | Metadata | Value | | ---------------- | ------------------------- | | **Version** | 1.0.0 | @@ -1037,3 +1067,13 @@ flowchart TD _This document follows TOGAF Architecture Development Method (ADM) principles and aligns with the Application Architecture domain of the BDAT framework._ + +--- + +
+ +**[← Data Architecture](./02-data-architecture.md)** | +**[⬆️ Back to Top](#-application-architecture)** | +**[πŸ—οΈ Technology Architecture β†’](./04-technology-architecture.md)** + +
diff --git a/docs/architecture/04-technology-architecture.md b/docs/architecture/04-technology-architecture.md index e58ec30e..73d917f5 100644 --- a/docs/architecture/04-technology-architecture.md +++ b/docs/architecture/04-technology-architecture.md @@ -1,7 +1,38 @@ -# Technology Architecture +--- +title: Technology Architecture +description: + TOGAF Technology Architecture documentation for DevExp-DevBox covering Azure + services, networking, identity, security, monitoring, and CI/CD infrastructure +author: Platform Engineering Team +date: 2026-01-22 +version: 1.0.0 +tags: + - TOGAF + - Technology Architecture + - BDAT + - DevExp-DevBox + - Azure + - DevCenter + - CI/CD +--- + +# πŸ—οΈ Technology Architecture > **DevExp-DevBox Landing Zone Accelerator** +> [!NOTE] **Target Audience:** Cloud Architects, DevOps Engineers, IT +> Operations +> **Reading Time:** ~25 minutes + +
+πŸ“ Navigation + +| Previous | Index | Next | +| :------------------------------------------------------------- | :----------------------------------: | ---: | +| [← Application Architecture](./03-application-architecture.md) | [🏠 Architecture Index](./README.md) | - | + +
+ | Metadata | Value | | ---------------- | ------------------------- | | **Version** | 1.0.0 | @@ -979,3 +1010,12 @@ flowchart LR _This document follows TOGAF Architecture Development Method (ADM) principles and aligns with the Technology Architecture domain of the BDAT framework._ + +--- + +
+ +**[← Application Architecture](./03-application-architecture.md)** | +**[⬆️ Back to Top](#-technology-architecture)** + +
diff --git a/docs/architecture/README.md b/docs/architecture/README.md new file mode 100644 index 00000000..f99fc5d2 --- /dev/null +++ b/docs/architecture/README.md @@ -0,0 +1,95 @@ +--- +title: Architecture Documentation Index +description: + Index of TOGAF BDAT architecture documentation for DevExp-DevBox Landing Zone + Accelerator +author: Platform Engineering Team +date: 2026-01-22 +version: 1.0.0 +tags: + - TOGAF + - BDAT + - Architecture + - DevExp-DevBox + - Index +--- + +# 🏠 DevExp-DevBox Architecture Documentation + +> **TOGAF BDAT Architecture Framework** + +> [!NOTE] **Target Audience:** All Stakeholders +> **Purpose:** Central navigation hub for architecture documentation + +## πŸ“‹ Overview + +This documentation follows the **TOGAF Architecture Development Method (ADM)** +and implements the **BDAT (Business, Data, Application, Technology)** framework +to provide comprehensive architecture documentation for the DevExp-DevBox +Landing Zone Accelerator. + +## πŸ“š Architecture Documents + +| # | Document | Description | Audience | +| :-: | :-------------------------------------------------------------- | :-------------------------------------------------------------------------------- | :---------------------------------- | +| 1 | [🏒 Business Architecture](./01-business-architecture.md) | Business context, stakeholders, capabilities, value streams, and requirements | BDMs, Enterprise Architects | +| 2 | [πŸ“Š Data Architecture](./02-data-architecture.md) | Configuration data models, secrets management, telemetry, and data governance | Data Architects, Security Engineers | +| 3 | [πŸ›οΈ Application Architecture](./03-application-architecture.md) | Bicep module catalog, dependencies, deployment orchestration, and design patterns | Platform Engineers, DevOps | +| 4 | [πŸ—οΈ Technology Architecture](./04-technology-architecture.md) | Azure services, networking, identity, security, monitoring, and CI/CD | Cloud Architects, IT Operations | + +## πŸ”„ Document Relationships + +```mermaid +flowchart TB + subgraph TOGAF["TOGAF BDAT Framework"] + BA[🏒 Business Architecture] + DA[πŸ“Š Data Architecture] + AA[πŸ›οΈ Application Architecture] + TA[πŸ—οΈ Technology Architecture] + end + + BA --> DA + BA --> AA + DA --> AA + AA --> TA + DA --> TA + + BA -.->|Defines Requirements| AA + DA -.->|Defines Data Flows| TA + AA -.->|Implements| TA +``` + +## 🎯 Quick Start Guide + +> [!TIP] **Recommended Reading Order:** +> +> 1. Start with **Business Architecture** to understand the context and +> requirements +> 2. Review **Data Architecture** for configuration and data flow patterns +> 3. Explore **Application Architecture** for Bicep module details +> 4. Finish with **Technology Architecture** for infrastructure specifics + +## πŸ“– Framework Reference + +| Framework | Component | Purpose | +| :------------ | :-------------------------------------- | :--------------------------------------------- | +| **TOGAF** | Architecture Development Method (ADM) | Structured approach to enterprise architecture | +| **BDAT** | Business, Data, Application, Technology | Four-domain architecture framework | +| **Azure CAF** | Cloud Adoption Framework | Azure best practices and landing zones | + +## πŸ”— External Resources + +| Resource | Description | +| :---------------------------------------------------------------------------------------------------- | :----------------------------- | +| [Microsoft Dev Box](https://learn.microsoft.com/azure/dev-box/) | Official Dev Box documentation | +| [Azure Landing Zones](https://learn.microsoft.com/azure/cloud-adoption-framework/ready/landing-zone/) | CAF Landing Zone guidance | +| [TOGAF Standard](https://www.opengroup.org/togaf) | TOGAF architecture framework | +| [DevExp-DevBox Accelerator](https://evilazaro.github.io/DevExp-DevBox/) | Project documentation site | + +--- + +
+ +**πŸ“… Last Updated:** January 22, 2026 | **πŸ“Œ Version:** 1.0.0 + +
From f860a6aecc5c54f2442e53c0d4968082f41e3ae9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 15:00:20 -0500 Subject: [PATCH 10/49] Refactor architecture documentation to enhance clarity and add important notes on business, data, application, and technology architectures --- docs/architecture/01-business-architecture.md | 3 +++ docs/architecture/02-data-architecture.md | 3 +++ docs/architecture/03-application-architecture.md | 4 ++++ docs/architecture/04-technology-architecture.md | 4 ++++ 4 files changed, 14 insertions(+) diff --git a/docs/architecture/01-business-architecture.md b/docs/architecture/01-business-architecture.md index c0a73842..0cd54c65 100644 --- a/docs/architecture/01-business-architecture.md +++ b/docs/architecture/01-business-architecture.md @@ -63,6 +63,9 @@ Microsoft Dev Box environments on Azure. This accelerator enables organizations to provision secure, compliant, and scalable developer workstations following Azure Landing Zone best practices. +> [!TIP] **Quick Value Summary:** This accelerator reduces developer onboarding +> from days to hours while ensuring security compliance and cost visibility. + ### Key Business Value | Value Proposition | Description | diff --git a/docs/architecture/02-data-architecture.md b/docs/architecture/02-data-architecture.md index 6e6a24d3..f504feb3 100644 --- a/docs/architecture/02-data-architecture.md +++ b/docs/architecture/02-data-architecture.md @@ -302,6 +302,9 @@ classDiagram ## πŸ” Secrets Management +> [!CAUTION] **Secret Rotation:** PAT tokens should be rotated every 90 days. +> Federated credentials are automatically managed by Azure AD. + ### Secret Types | Secret | Storage | Purpose | Consumers | Rotation | diff --git a/docs/architecture/03-application-architecture.md b/docs/architecture/03-application-architecture.md index 227c8ff9..9eb9037f 100644 --- a/docs/architecture/03-application-architecture.md +++ b/docs/architecture/03-application-architecture.md @@ -129,6 +129,10 @@ flowchart TB SECRET -.->|Auth| CAT ``` +> [!IMPORTANT] **Key Design Decision:** The accelerator follows a strict modular +> architecture where each Bicep module handles a single resource type, enabling +> independent testing and reusability. + ### Architecture Principles | Principle | Description | Implementation | diff --git a/docs/architecture/04-technology-architecture.md b/docs/architecture/04-technology-architecture.md index 73d917f5..3bf576e0 100644 --- a/docs/architecture/04-technology-architecture.md +++ b/docs/architecture/04-technology-architecture.md @@ -521,6 +521,10 @@ flowchart LR A3 -->|Secrets Officer| S1 ``` +> [!WARNING] **Security Requirement:** All Key Vault secrets must use RBAC +> authorization. Access policies are not supported in this accelerator for +> compliance reasons. + ### Security Controls | Control | Configuration | Value | Purpose | From 9613df5f518c1e2f979421b9d4e98c133e812ccf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 15:02:24 -0500 Subject: [PATCH 11/49] Refactor architecture documentation for improved link formatting in Table of Contents --- docs/architecture/02-data-architecture.md | 4 ++-- docs/architecture/03-application-architecture.md | 4 ++-- docs/architecture/04-technology-architecture.md | 10 +++++----- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/architecture/02-data-architecture.md b/docs/architecture/02-data-architecture.md index f504feb3..25bb877f 100644 --- a/docs/architecture/02-data-architecture.md +++ b/docs/architecture/02-data-architecture.md @@ -44,11 +44,11 @@ tags: ## πŸ“‘ Table of Contents - [πŸ“Š Data Overview](#-data-overview) -- [βš™οΈ Configuration Data Model](#️-configuration-data-model) +- [βš™οΈ Configuration Data Model](#%EF%B8%8F-configuration-data-model) - [πŸ” Secrets Management](#-secrets-management) - [πŸ“± Telemetry & Diagnostics](#-telemetry--diagnostics) - [πŸ”€ Data Flow Diagrams](#-data-flow-diagrams) -- [πŸ›‘οΈ Data Governance](#️-data-governance) +- [πŸ›‘οΈ Data Governance](#%EF%B8%8F-data-governance) - [πŸ“„ Schema Documentation](#-schema-documentation) - [πŸ“š References](#-references) - [πŸ“– Glossary](#-glossary) diff --git a/docs/architecture/03-application-architecture.md b/docs/architecture/03-application-architecture.md index 9eb9037f..3e832c6c 100644 --- a/docs/architecture/03-application-architecture.md +++ b/docs/architecture/03-application-architecture.md @@ -43,7 +43,7 @@ tags: ## πŸ“‘ Table of Contents -- [πŸ›οΈ Architecture Overview](#️-architecture-overview) +- [πŸ›οΈ Architecture Overview](#%EF%B8%8F-architecture-overview) - [πŸ“¦ Module Catalog](#-module-catalog) - [πŸ”— Module Dependencies](#-module-dependencies) - [πŸš€ Deployment Orchestration](#-deployment-orchestration) @@ -1077,7 +1077,7 @@ and aligns with the Application Architecture domain of the BDAT framework._
**[← Data Architecture](./02-data-architecture.md)** | -**[⬆️ Back to Top](#-application-architecture)** | +**[⬆️ Back to Top](#%EF%B8%8F-application-architecture)** | **[πŸ—οΈ Technology Architecture β†’](./04-technology-architecture.md)**
diff --git a/docs/architecture/04-technology-architecture.md b/docs/architecture/04-technology-architecture.md index 3bf576e0..5332a5f7 100644 --- a/docs/architecture/04-technology-architecture.md +++ b/docs/architecture/04-technology-architecture.md @@ -44,14 +44,14 @@ tags: ## πŸ“‘ Table of Contents -- [πŸ—οΈ Infrastructure Overview](#️-infrastructure-overview) -- [πŸ›οΈ Landing Zone Design](#️-landing-zone-design) +- [πŸ—οΈ Infrastructure Overview](#%EF%B8%8F-infrastructure-overview) +- [πŸ›οΈ Landing Zone Design](#%EF%B8%8F-landing-zone-design) - [🌐 Network Architecture](#-network-architecture) - [πŸ‘€ Identity & Access](#-identity--access) - [πŸ”’ Security Architecture](#-security-architecture) - [πŸ“Š Monitoring & Observability](#-monitoring--observability) -- [βš™οΈ CI/CD Infrastructure](#️-cicd-infrastructure) -- [πŸ› οΈ Deployment Tools](#️-deployment-tools) +- [βš™οΈ CI/CD Infrastructure](#%EF%B8%8F-cicd-infrastructure) +- [πŸ› οΈ Deployment Tools](#%EF%B8%8F-deployment-tools) - [πŸ’» DevOps Practices](#-devops-practices) - [πŸ“š References](#-references) - [πŸ“– Glossary](#-glossary) @@ -1020,6 +1020,6 @@ and aligns with the Technology Architecture domain of the BDAT framework._
**[← Application Architecture](./03-application-architecture.md)** | -**[⬆️ Back to Top](#-technology-architecture)** +**[⬆️ Back to Top](#%EF%B8%8F-technology-architecture)**
From 3283b8f0ac2325227ab530d419f3b5cbb908f500 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 15:04:07 -0500 Subject: [PATCH 12/49] Refactor architecture documentation to improve formatting and clarity of target audience notes --- docs/architecture/01-business-architecture.md | 3 ++- docs/architecture/02-data-architecture.md | 3 ++- docs/architecture/03-application-architecture.md | 3 ++- docs/architecture/04-technology-architecture.md | 4 ++-- docs/architecture/README.md | 3 ++- 5 files changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/architecture/01-business-architecture.md b/docs/architecture/01-business-architecture.md index 0cd54c65..95627989 100644 --- a/docs/architecture/01-business-architecture.md +++ b/docs/architecture/01-business-architecture.md @@ -20,7 +20,8 @@ tags: > **DevExp-DevBox Landing Zone Accelerator** > [!NOTE] **Target Audience:** Business Decision Makers, Enterprise Architects, -> Platform Engineers +> Platform Engineers +> > **Reading Time:** ~15 minutes
diff --git a/docs/architecture/02-data-architecture.md b/docs/architecture/02-data-architecture.md index 25bb877f..dc434e81 100644 --- a/docs/architecture/02-data-architecture.md +++ b/docs/architecture/02-data-architecture.md @@ -20,7 +20,8 @@ tags: > **DevExp-DevBox Landing Zone Accelerator** > [!NOTE] **Target Audience:** Data Architects, Platform Engineers, Security -> Engineers +> Engineers +> > **Reading Time:** ~20 minutes
diff --git a/docs/architecture/03-application-architecture.md b/docs/architecture/03-application-architecture.md index 3e832c6c..3697eb45 100644 --- a/docs/architecture/03-application-architecture.md +++ b/docs/architecture/03-application-architecture.md @@ -20,7 +20,8 @@ tags: > **DevExp-DevBox Landing Zone Accelerator** > [!NOTE] **Target Audience:** Platform Engineers, DevOps Engineers, Cloud -> Architects +> Architects +> > **Reading Time:** ~25 minutes
diff --git a/docs/architecture/04-technology-architecture.md b/docs/architecture/04-technology-architecture.md index 5332a5f7..62342117 100644 --- a/docs/architecture/04-technology-architecture.md +++ b/docs/architecture/04-technology-architecture.md @@ -20,8 +20,8 @@ tags: > **DevExp-DevBox Landing Zone Accelerator** -> [!NOTE] **Target Audience:** Cloud Architects, DevOps Engineers, IT -> Operations +> [!NOTE] **Target Audience:** Cloud Architects, DevOps Engineers, IT Operations +> > **Reading Time:** ~25 minutes
diff --git a/docs/architecture/README.md b/docs/architecture/README.md index f99fc5d2..d84e4f31 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -18,7 +18,8 @@ tags: > **TOGAF BDAT Architecture Framework** -> [!NOTE] **Target Audience:** All Stakeholders +> [!NOTE] **Target Audience:** All Stakeholders +> > **Purpose:** Central navigation hub for architecture documentation ## πŸ“‹ Overview From a94ffcd7af8dfed80b54d3bf1f92c2ed0ae89a5e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 15:09:46 -0500 Subject: [PATCH 13/49] Refactor architecture documentation to improve formatting and clarity of target audience notes --- docs/architecture/01-business-architecture.md | 12 ++++++++---- docs/architecture/02-data-architecture.md | 11 +++++++---- docs/architecture/03-application-architecture.md | 13 ++++++++----- docs/architecture/04-technology-architecture.md | 11 +++++++---- docs/architecture/README.md | 8 ++++++-- 5 files changed, 36 insertions(+), 19 deletions(-) diff --git a/docs/architecture/01-business-architecture.md b/docs/architecture/01-business-architecture.md index 95627989..73e4331c 100644 --- a/docs/architecture/01-business-architecture.md +++ b/docs/architecture/01-business-architecture.md @@ -19,8 +19,10 @@ tags: > **DevExp-DevBox Landing Zone Accelerator** -> [!NOTE] **Target Audience:** Business Decision Makers, Enterprise Architects, -> Platform Engineers +> [!NOTE] +> +> **Target Audience:** Business Decision Makers, Enterprise Architects, Platform +> Engineers > > **Reading Time:** ~15 minutes @@ -64,8 +66,10 @@ Microsoft Dev Box environments on Azure. This accelerator enables organizations to provision secure, compliant, and scalable developer workstations following Azure Landing Zone best practices. -> [!TIP] **Quick Value Summary:** This accelerator reduces developer onboarding -> from days to hours while ensuring security compliance and cost visibility. +> [!TIP] +> +> **Quick Value Summary:** This accelerator reduces developer onboarding from +> days to hours while ensuring security compliance and cost visibility. ### Key Business Value diff --git a/docs/architecture/02-data-architecture.md b/docs/architecture/02-data-architecture.md index dc434e81..2051fb07 100644 --- a/docs/architecture/02-data-architecture.md +++ b/docs/architecture/02-data-architecture.md @@ -19,8 +19,9 @@ tags: > **DevExp-DevBox Landing Zone Accelerator** -> [!NOTE] **Target Audience:** Data Architects, Platform Engineers, Security -> Engineers +> [!NOTE] +> +> **Target Audience:** Data Architects, Platform Engineers, Security Engineers > > **Reading Time:** ~20 minutes @@ -303,8 +304,10 @@ classDiagram ## πŸ” Secrets Management -> [!CAUTION] **Secret Rotation:** PAT tokens should be rotated every 90 days. -> Federated credentials are automatically managed by Azure AD. +> [!CAUTION] +> +> **Secret Rotation:** PAT tokens should be rotated every 90 days. Federated +> credentials are automatically managed by Azure AD. ### Secret Types diff --git a/docs/architecture/03-application-architecture.md b/docs/architecture/03-application-architecture.md index 3697eb45..0e855dc1 100644 --- a/docs/architecture/03-application-architecture.md +++ b/docs/architecture/03-application-architecture.md @@ -19,8 +19,9 @@ tags: > **DevExp-DevBox Landing Zone Accelerator** -> [!NOTE] **Target Audience:** Platform Engineers, DevOps Engineers, Cloud -> Architects +> [!NOTE] +> +> **Target Audience:** Platform Engineers, DevOps Engineers, Cloud Architects > > **Reading Time:** ~25 minutes @@ -130,9 +131,11 @@ flowchart TB SECRET -.->|Auth| CAT ``` -> [!IMPORTANT] **Key Design Decision:** The accelerator follows a strict modular -> architecture where each Bicep module handles a single resource type, enabling -> independent testing and reusability. +> [!IMPORTANT] +> +> **Key Design Decision:** The accelerator follows a strict modular architecture +> where each Bicep module handles a single resource type, enabling independent +> testing and reusability. ### Architecture Principles diff --git a/docs/architecture/04-technology-architecture.md b/docs/architecture/04-technology-architecture.md index 62342117..b00fe9ce 100644 --- a/docs/architecture/04-technology-architecture.md +++ b/docs/architecture/04-technology-architecture.md @@ -20,7 +20,9 @@ tags: > **DevExp-DevBox Landing Zone Accelerator** -> [!NOTE] **Target Audience:** Cloud Architects, DevOps Engineers, IT Operations +> [!NOTE] +> +> **Target Audience:** Cloud Architects, DevOps Engineers, IT Operations > > **Reading Time:** ~25 minutes @@ -521,9 +523,10 @@ flowchart LR A3 -->|Secrets Officer| S1 ``` -> [!WARNING] **Security Requirement:** All Key Vault secrets must use RBAC -> authorization. Access policies are not supported in this accelerator for -> compliance reasons. +> [!WARNING] +> +> **Security Requirement:** All Key Vault secrets must use RBAC authorization. +> Access policies are not supported in this accelerator for compliance reasons. ### Security Controls diff --git a/docs/architecture/README.md b/docs/architecture/README.md index d84e4f31..a2723582 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -18,7 +18,9 @@ tags: > **TOGAF BDAT Architecture Framework** -> [!NOTE] **Target Audience:** All Stakeholders +> [!NOTE] +> +> **Target Audience:** All Stakeholders > > **Purpose:** Central navigation hub for architecture documentation @@ -62,7 +64,9 @@ flowchart TB ## 🎯 Quick Start Guide -> [!TIP] **Recommended Reading Order:** +> [!TIP] +> +> **Recommended Reading Order:** > > 1. Start with **Business Architecture** to understand the context and > requirements From 7a68b6ee73ba70768a4b19095f2235e6fd242392 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 15:26:30 -0500 Subject: [PATCH 14/49] Refactor architecture documentation to enhance clarity and detail in document relationships --- docs/architecture/README.md | 41 ++++++++++++++++++++++++++----------- 1 file changed, 29 insertions(+), 12 deletions(-) diff --git a/docs/architecture/README.md b/docs/architecture/README.md index a2723582..6745a76c 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -43,23 +43,40 @@ Landing Zone Accelerator. ## πŸ”„ Document Relationships ```mermaid +--- +title: TOGAF BDAT Framework Document Relationships +--- flowchart TB + %% ===== STYLE DEFINITIONS ===== + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + + %% ===== FRAMEWORK DOCUMENTS ===== subgraph TOGAF["TOGAF BDAT Framework"] - BA[🏒 Business Architecture] - DA[πŸ“Š Data Architecture] - AA[πŸ›οΈ Application Architecture] - TA[πŸ—οΈ Technology Architecture] + BA["🏒 Business Architecture"] + DA["πŸ“Š Data Architecture"] + AA["πŸ›οΈ Application Architecture"] + TA["πŸ—οΈ Technology Architecture"] end - BA --> DA - BA --> AA - DA --> AA - AA --> TA - DA --> TA + %% ===== DOCUMENT RELATIONSHIPS ===== + BA -->|"defines requirements"| DA + BA -->|"defines requirements"| AA + DA -->|"defines data flows"| AA + AA -->|"implements"| TA + DA -->|"defines data flows"| TA + + %% ===== CROSS-DOMAIN RELATIONSHIPS ===== + BA -.->|"Defines Requirements"| AA + DA -.->|"Defines Data Flows"| TA + AA -.->|"Implements"| TA + + %% ===== APPLY STYLES ===== + class BA,DA,AA,TA primary - BA -.->|Defines Requirements| AA - DA -.->|Defines Data Flows| TA - AA -.->|Implements| TA + %% ===== SUBGRAPH STYLING ===== + style TOGAF fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px ``` ## 🎯 Quick Start Guide From d4ce820d057d362db7c48b2eda7ed11e8c93bbfe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 15:27:41 -0500 Subject: [PATCH 15/49] Refactor business architecture documentation to enhance clarity and detail in diagrams and value propositions --- docs/architecture/01-business-architecture.md | 134 ++++++++++++++---- 1 file changed, 105 insertions(+), 29 deletions(-) diff --git a/docs/architecture/01-business-architecture.md b/docs/architecture/01-business-architecture.md index 73e4331c..8eb70128 100644 --- a/docs/architecture/01-business-architecture.md +++ b/docs/architecture/01-business-architecture.md @@ -84,6 +84,9 @@ Azure Landing Zone best practices. ### Target Outcomes ```mermaid +--- +title: DevExp-DevBox Value Proposition +--- mindmap root((DevExp-DevBox
Value)) Developer Productivity @@ -134,33 +137,58 @@ The DevExp-DevBox accelerator serves organizations that: ### Business Drivers ```mermaid +--- +title: Business Drivers for DevExp-DevBox +--- flowchart LR + %% ===== STYLE DEFINITIONS ===== + classDef external fill:#6B7280,stroke:#4B5563,color:#FFFFFF,stroke-dasharray:5 5 + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + + %% ===== EXTERNAL DRIVERS ===== subgraph External["External Drivers"] - A[Security Compliance] - B[Talent Competition] - C[Remote Work] + A["Security Compliance"] + B["Talent Competition"] + C["Remote Work"] end + %% ===== INTERNAL DRIVERS ===== subgraph Internal["Internal Drivers"] - D[Developer Productivity] - E[Cost Optimization] - F[Operational Efficiency] + D["Developer Productivity"] + E["Cost Optimization"] + F["Operational Efficiency"] end + %% ===== SOLUTION ===== subgraph Solution["DevExp-DevBox"] - G[Landing Zone
Accelerator] + G["Landing Zone
Accelerator"] end - A --> G - B --> G - C --> G - D --> G - E --> G - F --> G - - G --> H[Secure Dev
Environments] - G --> I[Fast Onboarding] - G --> J[Centralized
Management] + %% ===== CONNECTIONS ===== + A -->|"drives"| G + B -->|"drives"| G + C -->|"drives"| G + D -->|"drives"| G + E -->|"drives"| G + F -->|"drives"| G + + %% ===== OUTCOMES ===== + G -->|"enables"| H["Secure Dev
Environments"] + G -->|"enables"| I["Fast Onboarding"] + G -->|"enables"| J["Centralized
Management"] + + %% ===== APPLY STYLES ===== + class A,B,C external + class D,E,F primary + class G secondary + class H,I,J datastore + + %% ===== SUBGRAPH STYLING ===== + style External fill:#F3F4F6,stroke:#6B7280,stroke-width:2px + style Internal fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style Solution fill:#ECFDF5,stroke:#10B981,stroke-width:2px ``` --- @@ -170,6 +198,9 @@ flowchart LR ### Stakeholder Map ```mermaid +--- +title: Stakeholder Influence vs Interest Matrix +--- quadrantChart title Stakeholder Influence vs Interest Matrix x-axis Low Interest --> High Interest @@ -222,13 +253,18 @@ _R = Responsible, A = Accountable, C = Consulted, I = Informed_ ### Business Capability Model ```mermaid +--- +title: DevExp-DevBox Business Capabilities +--- block-beta columns 4 + %% ===== HEADER ===== block:header:4 A["DevExp-DevBox Business Capabilities"] end + %% ===== SECURITY CAPABILITY ===== block:security:1 B["πŸ” Security"] B1["Key Vault Management"] @@ -237,6 +273,7 @@ block-beta B4["Compliance Reporting"] end + %% ===== MONITORING CAPABILITY ===== block:monitoring:1 C["πŸ“Š Monitoring"] C1["Log Analytics"] @@ -245,6 +282,7 @@ block-beta C4["Alert Management"] end + %% ===== CONNECTIVITY CAPABILITY ===== block:connectivity:1 D["🌐 Connectivity"] D1["VNet Management"] @@ -253,6 +291,7 @@ block-beta D4["NSG Rules"] end + %% ===== WORKLOAD CAPABILITY ===== block:workload:1 E["πŸ’» Workload"] E1["DevCenter Management"] @@ -260,6 +299,13 @@ block-beta E3["Pool Configuration"] E4["Catalog Management"] end + + %% ===== SUBGRAPH STYLING ===== + style header fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style security fill:#FEE2E2,stroke:#F44336,stroke-width:2px + style monitoring fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style connectivity fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style workload fill:#ECFDF5,stroke:#10B981,stroke-width:2px ``` ### Capability to Landing Zone Mapping @@ -299,28 +345,53 @@ block-beta ### Developer Onboarding Value Stream ```mermaid +--- +title: Developer Onboarding Value Stream +--- flowchart LR + %% ===== STYLE DEFINITIONS ===== + classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + + %% ===== TRIGGER STAGE ===== subgraph Trigger["Trigger"] - A[New Developer
Joins Team] + A["New Developer
Joins Team"] end + %% ===== PROCESS STAGE ===== subgraph Process["Onboarding Process"] - B[Add to
Azure AD Group] - C[RBAC Auto-
Assignment] - D[Access
DevCenter Portal] - E[Select
Dev Box Pool] - F[Provision
Dev Box] - G[DSC Config
Applied] + B["Add to
Azure AD Group"] + C["RBAC Auto-
Assignment"] + D["Access
DevCenter Portal"] + E["Select
Dev Box Pool"] + F["Provision
Dev Box"] + G["DSC Config
Applied"] end + %% ===== OUTCOME STAGE ===== subgraph Outcome["Outcome"] - H[Developer
Productive] + H["Developer
Productive"] end - A --> B --> C --> D --> E --> F --> G --> H - - style A fill:#e1f5fe - style H fill:#c8e6c9 + %% ===== FLOW CONNECTIONS ===== + A -->|"initiates"| B + B -->|"triggers"| C + C -->|"enables"| D + D -->|"leads to"| E + E -->|"triggers"| F + F -->|"applies"| G + G -->|"results in"| H + + %% ===== APPLY STYLES ===== + class A trigger + class B,C,D,E,F,G primary + class H secondary + + %% ===== SUBGRAPH STYLING ===== + style Trigger fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style Process fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style Outcome fill:#ECFDF5,stroke:#10B981,stroke-width:2px ``` ### Value Stream Stages @@ -337,7 +408,11 @@ flowchart LR ### Environment Provisioning Lifecycle ```mermaid +--- +title: Environment Provisioning Lifecycle +--- sequenceDiagram + %% ===== PARTICIPANTS ===== participant PM as Platform Manager participant GH as GitHub/ADO participant AZD as Azure Developer CLI @@ -345,6 +420,7 @@ sequenceDiagram participant DC as DevCenter participant KV as Key Vault + %% ===== PROVISIONING FLOW ===== PM->>GH: Push configuration changes GH->>GH: CI pipeline triggered GH->>AZD: azd provision From 77cee1afcd47fa03d46b66c311ae0496adac1282 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 15:28:24 -0500 Subject: [PATCH 16/49] Refactor business architecture documentation to enhance clarity and detail in requirements traceability and success metrics visualizations --- docs/architecture/01-business-architecture.md | 65 +++++++++++++------ 1 file changed, 45 insertions(+), 20 deletions(-) diff --git a/docs/architecture/01-business-architecture.md b/docs/architecture/01-business-architecture.md index 8eb70128..a23b1125 100644 --- a/docs/architecture/01-business-architecture.md +++ b/docs/architecture/01-business-architecture.md @@ -468,37 +468,59 @@ sequenceDiagram ### Requirements Traceability ```mermaid +--- +title: Requirements Traceability Matrix +--- flowchart TD + %% ===== STYLE DEFINITIONS ===== + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + + %% ===== BUSINESS GOALS ===== subgraph Business["Business Goals"] - BG1[Fast Onboarding] - BG2[Security Compliance] - BG3[Cost Management] + BG1["Fast Onboarding"] + BG2["Security Compliance"] + BG3["Cost Management"] end + %% ===== FUNCTIONAL REQUIREMENTS ===== subgraph Functional["Functional Requirements"] - FR1[FR-001: DevCenter] - FR2[FR-002: Pools] - FR3[FR-003: Key Vault] - FR4[FR-004: RBAC] + FR1["FR-001: DevCenter"] + FR2["FR-002: Pools"] + FR3["FR-003: Key Vault"] + FR4["FR-004: RBAC"] end + %% ===== TECHNICAL COMPONENTS ===== subgraph Technical["Technical Components"] - TC1[devCenter.bicep] - TC2[projectPool.bicep] - TC3[keyVault.bicep] - TC4[roleAssignment.bicep] + TC1["devCenter.bicep"] + TC2["projectPool.bicep"] + TC3["keyVault.bicep"] + TC4["roleAssignment.bicep"] end - BG1 --> FR1 - BG1 --> FR2 - BG2 --> FR3 - BG2 --> FR4 - BG3 --> FR2 + %% ===== TRACEABILITY LINKS ===== + BG1 -->|"requires"| FR1 + BG1 -->|"requires"| FR2 + BG2 -->|"requires"| FR3 + BG2 -->|"requires"| FR4 + BG3 -->|"requires"| FR2 - FR1 --> TC1 - FR2 --> TC2 - FR3 --> TC3 - FR4 --> TC4 + FR1 -->|"implemented by"| TC1 + FR2 -->|"implemented by"| TC2 + FR3 -->|"implemented by"| TC3 + FR4 -->|"implemented by"| TC4 + + %% ===== APPLY STYLES ===== + class BG1,BG2,BG3 primary + class FR1,FR2,FR3,FR4 secondary + class TC1,TC2,TC3,TC4 datastore + + %% ===== SUBGRAPH STYLING ===== + style Business fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style Functional fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Technical fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px ``` --- @@ -520,6 +542,9 @@ flowchart TD ### Success Metrics Dashboard ```mermaid +--- +title: Resource Distribution by Landing Zone +--- pie showData title Resource Distribution by Landing Zone "Security" : 15 From a5af985c749f1af9e76c7fa5013c4f69c5b78761 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 15:32:44 -0500 Subject: [PATCH 17/49] Refactor data architecture documentation to enhance clarity and detail in diagrams and relationships --- docs/architecture/02-data-architecture.md | 256 ++++++++++++++++------ 1 file changed, 185 insertions(+), 71 deletions(-) diff --git a/docs/architecture/02-data-architecture.md b/docs/architecture/02-data-architecture.md index 2051fb07..ae81f82f 100644 --- a/docs/architecture/02-data-architecture.md +++ b/docs/architecture/02-data-architecture.md @@ -75,6 +75,9 @@ that flow through the system during deployment and operation. ### Data Entity Overview ```mermaid +--- +title: Data Entity Relationships +--- erDiagram AZURE_RESOURCES ||--o{ RESOURCE_GROUP : contains RESOURCE_GROUP ||--o{ DEVCENTER : hosts @@ -125,6 +128,9 @@ Defines the landing zone resource group structure following Azure Landing Zone principles. ```mermaid +--- +title: Azure Resources Configuration Model +--- classDiagram class AzureResources { +workload: LandingZone @@ -174,6 +180,9 @@ classDiagram Defines Azure Key Vault settings for secrets management. ```mermaid +--- +title: Security Configuration Model +--- classDiagram class SecurityConfig { +create: boolean @@ -211,6 +220,9 @@ classDiagram The most complex configuration defining the entire workload structure. ```mermaid +--- +title: DevCenter Configuration Model +--- classDiagram class DevCenterConfig { +name: string @@ -320,7 +332,11 @@ classDiagram ### Secrets Flow Diagram ```mermaid +--- +title: Secrets Provisioning and Consumption +--- sequenceDiagram + %% ===== PARTICIPANTS ===== participant User as Platform Engineer participant GH as GitHub/ADO participant CLI as Azure CLI/azd @@ -328,6 +344,7 @@ sequenceDiagram participant DC as DevCenter participant Cat as Catalog + %% ===== PROVISIONING FLOW ===== Note over User,Cat: Secret Provisioning Flow User->>GH: Generate PAT token @@ -337,6 +354,7 @@ sequenceDiagram CLI->>DC: Configure DevCenter DC->>Cat: Create catalog with secret reference + %% ===== CONSUMPTION FLOW ===== Note over User,Cat: Secret Consumption Flow Cat->>KV: Request secret (via managed identity) @@ -349,30 +367,52 @@ sequenceDiagram ### Key Vault Access Model ```mermaid +--- +title: Key Vault RBAC Access Model +--- flowchart TD + %% ===== STYLE DEFINITIONS ===== + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + + %% ===== IDENTITY SOURCES ===== subgraph Identity["Identity Sources"] - DC_MI[DevCenter
Managed Identity] - PROJ_MI[Project
Managed Identity] - ADMIN[Platform Engineers
Azure AD Group] + DC_MI["DevCenter
Managed Identity"] + PROJ_MI["Project
Managed Identity"] + ADMIN["Platform Engineers
Azure AD Group"] end + %% ===== KEY VAULT ===== subgraph KV["Key Vault"] - SECRET[gha-token
Secret] + SECRET["gha-token
Secret"] end + %% ===== RBAC ROLES ===== subgraph Roles["RBAC Roles"] - R1[Key Vault
Secrets User] - R2[Key Vault
Secrets Officer] + R1["Key Vault
Secrets User"] + R2["Key Vault
Secrets Officer"] end - DC_MI --> R1 - DC_MI --> R2 - PROJ_MI --> R1 - PROJ_MI --> R2 - ADMIN --> R2 - - R1 --> |Get, List| SECRET - R2 --> |Get, List, Set, Delete| SECRET + %% ===== CONNECTIONS ===== + DC_MI -->|"assigned"| R1 + DC_MI -->|"assigned"| R2 + PROJ_MI -->|"assigned"| R1 + PROJ_MI -->|"assigned"| R2 + ADMIN -->|"assigned"| R2 + + R1 -->|"Get, List"| SECRET + R2 -->|"Get, List, Set, Delete"| SECRET + + %% ===== APPLY STYLES ===== + class DC_MI,PROJ_MI primary + class ADMIN secondary + class SECRET datastore + + %% ===== SUBGRAPH STYLING ===== + style Identity fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style KV fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style Roles fill:#ECFDF5,stroke:#10B981,stroke-width:2px ``` ### Secret Security Controls @@ -393,35 +433,57 @@ flowchart TD ### Log Analytics Data Collection ```mermaid +--- +title: Log Analytics Data Collection +--- flowchart LR + %% ===== STYLE DEFINITIONS ===== + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + + %% ===== SOURCES ===== subgraph Sources["Data Sources"] - DC[DevCenter] - KV[Key Vault] - VNET[Virtual Network] - LA_SELF[Log Analytics] + DC["DevCenter"] + KV["Key Vault"] + VNET["Virtual Network"] + LA_SELF["Log Analytics"] end + %% ===== LOG ANALYTICS WORKSPACE ===== subgraph LA["Log Analytics Workspace"] - LOGS[Logs] - METRICS[Metrics] - SOLUTIONS[Solutions] + LOGS["Logs"] + METRICS["Metrics"] + SOLUTIONS["Solutions"] end + %% ===== OUTPUTS ===== subgraph Outputs["Outputs"] - ALERTS[Alerts] - DASHBOARDS[Dashboards] - QUERIES[KQL Queries] + ALERTS["Alerts"] + DASHBOARDS["Dashboards"] + QUERIES["KQL Queries"] end - DC -->|allLogs, AllMetrics| LOGS - KV -->|allLogs, AllMetrics| LOGS - VNET -->|allLogs, AllMetrics| LOGS - LA_SELF -->|allLogs, AllMetrics| LOGS - - LOGS --> ALERTS - LOGS --> DASHBOARDS - METRICS --> DASHBOARDS - LOGS --> QUERIES + %% ===== CONNECTIONS ===== + DC -->|"allLogs, AllMetrics"| LOGS + KV -->|"allLogs, AllMetrics"| LOGS + VNET -->|"allLogs, AllMetrics"| LOGS + LA_SELF -->|"allLogs, AllMetrics"| LOGS + + LOGS -->|"triggers"| ALERTS + LOGS -->|"visualizes"| DASHBOARDS + METRICS -->|"visualizes"| DASHBOARDS + LOGS -->|"queries"| QUERIES + + %% ===== APPLY STYLES ===== + class DC,KV,VNET,LA_SELF primary + class LOGS,METRICS,SOLUTIONS datastore + class ALERTS,DASHBOARDS,QUERIES secondary + + %% ===== SUBGRAPH STYLING ===== + style Sources fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style LA fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style Outputs fill:#ECFDF5,stroke:#10B981,stroke-width:2px ``` ### Diagnostic Settings Configuration @@ -438,6 +500,9 @@ All resources deploy with standardized diagnostic settings: ### Telemetry Data Model ```mermaid +--- +title: Telemetry Data Model +--- erDiagram LOG_ANALYTICS_WORKSPACE ||--o{ AZURE_DIAGNOSTICS : receives LOG_ANALYTICS_WORKSPACE ||--o{ AZURE_METRICS : receives @@ -479,82 +544,131 @@ erDiagram ### Configuration Loading Flow ```mermaid +--- +title: Configuration Loading Flow +--- flowchart TD + %% ===== STYLE DEFINITIONS ===== + 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 input fill:#F3F4F6,stroke:#6B7280,color:#000000 + + %% ===== GIT REPOSITORY ===== subgraph Git["Git Repository"] - YAML1[azureResources.yaml] - YAML2[security.yaml] - YAML3[devcenter.yaml] + YAML1["azureResources.yaml"] + YAML2["security.yaml"] + YAML3["devcenter.yaml"] end + %% ===== BICEP PROCESSING ===== subgraph Bicep["Bicep Processing"] - MAIN[main.bicep] + MAIN["main.bicep"] LOAD1["loadYamlContent()
resourceOrganization"] LOAD2["loadYamlContent()
security"] LOAD3["loadYamlContent()
workload"] end + %% ===== MODULE DEPLOYMENT ===== subgraph Modules["Module Deployment"] - MOD1[logAnalytics.bicep] - MOD2[security.bicep] - MOD3[workload.bicep] + MOD1["logAnalytics.bicep"] + MOD2["security.bicep"] + MOD3["workload.bicep"] end + %% ===== AZURE RESOURCES ===== subgraph Azure["Azure Resources"] - RG[Resource Groups] - LA[Log Analytics] - KV[Key Vault] - DC[DevCenter] + RG["Resource Groups"] + LA["Log Analytics"] + KV["Key Vault"] + DC["DevCenter"] end - YAML1 --> LOAD1 - YAML2 --> LOAD2 - YAML3 --> LOAD3 + %% ===== CONNECTIONS ===== + YAML1 -->|"loads"| LOAD1 + YAML2 -->|"loads"| LOAD2 + YAML3 -->|"loads"| LOAD3 + + MAIN -->|"invokes"| LOAD1 + MAIN -->|"invokes"| LOAD2 + MAIN -->|"invokes"| LOAD3 + + LOAD1 -->|"passes config"| MOD1 + LOAD1 -->|"passes config"| MOD2 + LOAD1 -->|"passes config"| MOD3 - MAIN --> LOAD1 - MAIN --> LOAD2 - MAIN --> LOAD3 + LOAD2 -->|"passes config"| MOD2 + LOAD3 -->|"passes config"| MOD3 - LOAD1 --> MOD1 - LOAD1 --> MOD2 - LOAD1 --> MOD3 + MOD1 -->|"creates"| LA + MOD2 -->|"creates"| KV + MOD3 -->|"creates"| DC - LOAD2 --> MOD2 - LOAD3 --> MOD3 + MAIN -->|"creates"| RG - MOD1 --> LA - MOD2 --> KV - MOD3 --> DC + %% ===== APPLY STYLES ===== + class YAML1,YAML2,YAML3 input + class MAIN,LOAD1,LOAD2,LOAD3 primary + class MOD1,MOD2,MOD3 secondary + class RG,LA,KV,DC datastore - MAIN --> RG + %% ===== SUBGRAPH STYLING ===== + style Git fill:#F3F4F6,stroke:#6B7280,stroke-width:2px + style Bicep fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style Modules fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Azure fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px ``` ### Deployment Data Flow ```mermaid +--- +title: Deployment Data Flow +--- flowchart LR + %% ===== STYLE DEFINITIONS ===== + 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 input fill:#F3F4F6,stroke:#6B7280,color:#000000 + + %% ===== INPUT DATA ===== subgraph Input["Input Data"] - ENV[Environment Name] - LOC[Location] - SECRET[Secret Value] + ENV["Environment Name"] + LOC["Location"] + SECRET["Secret Value"] end + %% ===== PARAMETER TRANSFORMATION ===== subgraph Transform["Parameter Transformation"] SUFFIX["resourceNameSuffix =
{env}-{location}-RG"] RGNAMES["createResourceGroupName =
{zone.name}-{suffix}"] end + %% ===== OUTPUT RESOURCES ===== subgraph Output["Output Resources"] - SEC_RG[Security RG] - MON_RG[Monitoring RG] - WRK_RG[Workload RG] + SEC_RG["Security RG"] + MON_RG["Monitoring RG"] + WRK_RG["Workload RG"] end - ENV --> SUFFIX - LOC --> SUFFIX - SUFFIX --> RGNAMES - RGNAMES --> SEC_RG - RGNAMES --> MON_RG - RGNAMES --> WRK_RG + %% ===== CONNECTIONS ===== + ENV -->|"concatenates"| SUFFIX + LOC -->|"concatenates"| SUFFIX + SUFFIX -->|"generates"| RGNAMES + RGNAMES -->|"creates"| SEC_RG + RGNAMES -->|"creates"| MON_RG + RGNAMES -->|"creates"| WRK_RG + + %% ===== APPLY STYLES ===== + class ENV,LOC,SECRET input + class SUFFIX,RGNAMES primary + class SEC_RG,MON_RG,WRK_RG datastore + + %% ===== SUBGRAPH STYLING ===== + style Input fill:#F3F4F6,stroke:#6B7280,stroke-width:2px + style Transform fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style Output fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px ``` ### Cross-Module Data Dependencies From 1cf5d48fa6f2ff411cd4f9a97c3f830b42dccf28 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 15:33:46 -0500 Subject: [PATCH 18/49] Refactor data architecture documentation to enhance clarity and detail in cross-module data dependencies, data lineage, and schema validation flow diagrams --- docs/architecture/02-data-architecture.md | 152 ++++++++++++++++------ 1 file changed, 115 insertions(+), 37 deletions(-) diff --git a/docs/architecture/02-data-architecture.md b/docs/architecture/02-data-architecture.md index ae81f82f..ef841e8b 100644 --- a/docs/architecture/02-data-architecture.md +++ b/docs/architecture/02-data-architecture.md @@ -674,37 +674,63 @@ flowchart LR ### Cross-Module Data Dependencies ```mermaid +--- +title: Cross-Module Data Dependencies +--- flowchart TD + %% ===== STYLE DEFINITIONS ===== + 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 input fill:#F3F4F6,stroke:#6B7280,color:#000000 + + %% ===== MAIN BICEP ===== subgraph main["main.bicep (Subscription Scope)"] M_IN[/"Parameters:
location, secretValue,
environmentName"/] end + %% ===== MONITORING MODULE ===== subgraph monitoring["monitoring module"] - LA[Log Analytics] + LA["Log Analytics"] LA_OUT[/"Output:
AZURE_LOG_ANALYTICS_WORKSPACE_ID"/] end + %% ===== SECURITY MODULE ===== subgraph security["security module"] - KV[Key Vault + Secret] + KV["Key Vault + Secret"] SEC_OUT[/"Output:
AZURE_KEY_VAULT_SECRET_IDENTIFIER"/] end + %% ===== WORKLOAD MODULE ===== subgraph workload["workload module"] - DC[DevCenter] - PROJ[Projects] + DC["DevCenter"] + PROJ["Projects"] end - M_IN --> LA - LA --> LA_OUT + %% ===== CONNECTIONS ===== + M_IN -->|"provides parameters"| LA + LA -->|"outputs"| LA_OUT + + LA_OUT -->|"logAnalyticsId"| KV + M_IN -->|"secretValue"| KV + KV -->|"outputs"| SEC_OUT - LA_OUT -->|logAnalyticsId| KV - M_IN -->|secretValue| KV - KV --> SEC_OUT + LA_OUT -->|"logAnalyticsId"| DC + SEC_OUT -->|"secretIdentifier"| DC - LA_OUT -->|logAnalyticsId| DC - SEC_OUT -->|secretIdentifier| DC + DC -->|"configures"| PROJ - DC --> PROJ + %% ===== APPLY STYLES ===== + class M_IN input + class LA,LA_OUT secondary + class KV,SEC_OUT primary + class DC,PROJ datastore + + %% ===== SUBGRAPH STYLING ===== + style main fill:#F3F4F6,stroke:#6B7280,stroke-width:2px + style monitoring fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style security fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style workload fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px ``` --- @@ -732,38 +758,67 @@ flowchart TD ### Data Lineage ```mermaid +--- +title: Data Lineage +--- flowchart LR + %% ===== STYLE DEFINITIONS ===== + 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 + + %% ===== SOURCE OF TRUTH ===== subgraph Source["Source of Truth"] - GIT[Git Repository] + GIT["Git Repository"] end + %% ===== CI/CD ===== subgraph CI["CI/CD"] - GHA[GitHub Actions] - ADO[Azure DevOps] + GHA["GitHub Actions"] + ADO["Azure DevOps"] end + %% ===== DEPLOYMENT ===== subgraph Deploy["Deployment"] - AZD[azd CLI] - ARM[ARM/Bicep] + AZD["azd CLI"] + ARM["ARM/Bicep"] end + %% ===== RUNTIME ===== subgraph Runtime["Runtime"] - AZ[Azure Resources] + AZ["Azure Resources"] end + %% ===== AUDIT TRAIL ===== subgraph Audit["Audit Trail"] - LA[Log Analytics] - ACT[Activity Log] + LA["Log Analytics"] + ACT["Activity Log"] end - GIT -->|Push| GHA - GIT -->|Push| ADO - GHA -->|azd provision| AZD - ADO -->|azd provision| AZD - AZD -->|Deploy| ARM - ARM -->|Create/Update| AZ - AZ -->|Diagnostics| LA - AZ -->|Operations| ACT + %% ===== CONNECTIONS ===== + GIT -->|"push"| GHA + GIT -->|"push"| ADO + GHA -->|"azd provision"| AZD + ADO -->|"azd provision"| AZD + AZD -->|"deploy"| ARM + ARM -->|"create/update"| AZ + AZ -->|"diagnostics"| LA + AZ -->|"operations"| ACT + + %% ===== APPLY STYLES ===== + class GIT external + class GHA,ADO primary + class AZD,ARM secondary + class AZ datastore + class LA,ACT datastore + + %% ===== SUBGRAPH STYLING ===== + style Source fill:#F3F4F6,stroke:#6B7280,stroke-width:2px + style CI fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style Deploy fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Runtime fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style Audit fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px ``` ### Data Quality Rules @@ -824,19 +879,42 @@ Validates DevCenter workload configuration. ### Schema Validation Flow ```mermaid +--- +title: Schema Validation Flow +--- flowchart TD - YAML[YAML Configuration File] - SCHEMA[JSON Schema] - VALIDATOR[YAML Language Server] + %% ===== STYLE DEFINITIONS ===== + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef failed fill:#F44336,stroke:#C62828,color:#FFFFFF + classDef input fill:#F3F4F6,stroke:#6B7280,color:#000000 + + %% ===== INPUTS ===== + YAML["YAML Configuration File"] + SCHEMA["JSON Schema"] + VALIDATOR["YAML Language Server"] - YAML --> VALIDATOR - SCHEMA --> VALIDATOR + %% ===== OUTPUTS ===== + SUCCESS["βœ… Proceed to Deployment"] + ERROR["❌ Validation Errors"] + FIX["Fix Configuration"] + + %% ===== CONNECTIONS ===== + YAML -->|"validates against"| VALIDATOR + SCHEMA -->|"defines rules"| VALIDATOR - VALIDATOR -->|Valid| SUCCESS[βœ… Proceed to Deployment] - VALIDATOR -->|Invalid| ERROR[❌ Validation Errors] + VALIDATOR -->|"valid"| SUCCESS + VALIDATOR -->|"invalid"| ERROR - ERROR --> FIX[Fix Configuration] - FIX --> YAML + ERROR -->|"requires"| FIX + FIX -->|"updates"| YAML + + %% ===== APPLY STYLES ===== + class YAML,SCHEMA input + class VALIDATOR primary + class SUCCESS secondary + class ERROR failed + class FIX primary ``` --- From 076b6df4b4340ad97922e6a8b980f4d90e6b02c9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 15:34:58 -0500 Subject: [PATCH 19/49] Refactor application architecture documentation to enhance clarity and detail in landing zone diagrams, module dependency graphs, and deployment sequences --- .../03-application-architecture.md | 322 ++++++++++++------ 1 file changed, 209 insertions(+), 113 deletions(-) diff --git a/docs/architecture/03-application-architecture.md b/docs/architecture/03-application-architecture.md index 0e855dc1..a8c242ad 100644 --- a/docs/architecture/03-application-architecture.md +++ b/docs/architecture/03-application-architecture.md @@ -67,68 +67,99 @@ specialized Bicep modules. ### Landing Zone Architecture ```mermaid +--- +title: Landing Zone Architecture +--- flowchart TB + %% ===== STYLE DEFINITIONS ===== + 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 input fill:#F3F4F6,stroke:#6B7280,color:#000000 + classDef external fill:#6B7280,stroke:#4B5563,color:#FFFFFF,stroke-dasharray:5 5 + + %% ===== SUBSCRIPTION ===== subgraph Subscription["Azure Subscription"] + %% ===== MAIN ORCHESTRATOR ===== subgraph Main["main.bicep (Orchestrator)"] PARAMS[/"Parameters:
location, secretValue,
environmentName"/] end + %% ===== SECURITY LANDING ZONE ===== subgraph Security["Security Landing Zone"] - SEC_RG[Security Resource Group] - KV[Key Vault] - SECRET[Secrets] + SEC_RG["Security Resource Group"] + KV["Key Vault"] + SECRET["Secrets"] end + %% ===== MONITORING LANDING ZONE ===== subgraph Monitoring["Monitoring Landing Zone"] - MON_RG[Monitoring Resource Group] - LA[Log Analytics Workspace] - SOL[Solutions] + MON_RG["Monitoring Resource Group"] + LA["Log Analytics Workspace"] + SOL["Solutions"] end + %% ===== CONNECTIVITY LANDING ZONE ===== subgraph Connectivity["Connectivity Landing Zone"] - CON_RG[Connectivity Resource Group] - VNET[Virtual Network] - SUBNET[Subnets] - NC[Network Connection] + CON_RG["Connectivity Resource Group"] + VNET["Virtual Network"] + SUBNET["Subnets"] + NC["Network Connection"] end + %% ===== WORKLOAD LANDING ZONE ===== subgraph Workload["Workload Landing Zone"] - WRK_RG[Workload Resource Group] - DC[DevCenter] - CAT[Catalogs] - ENV[Environment Types] - PROJ[Projects] - POOL[Pools] + WRK_RG["Workload Resource Group"] + DC["DevCenter"] + CAT["Catalogs"] + ENV["Environment Types"] + PROJ["Projects"] + POOL["Pools"] end end - PARAMS --> SEC_RG - PARAMS --> MON_RG - PARAMS --> WRK_RG - - MON_RG --> LA - LA --> SOL - - SEC_RG --> KV - KV --> SECRET - - WRK_RG --> DC - DC --> CAT - DC --> ENV - DC --> PROJ - PROJ --> POOL - - PROJ -.->|Optional| CON_RG - CON_RG --> VNET - VNET --> SUBNET - SUBNET --> NC - NC --> DC - - LA -.->|Diagnostics| KV - LA -.->|Diagnostics| DC - LA -.->|Diagnostics| VNET - - SECRET -.->|Auth| CAT + %% ===== CONNECTIONS ===== + PARAMS -->|"creates"| SEC_RG + PARAMS -->|"creates"| MON_RG + PARAMS -->|"creates"| WRK_RG + + MON_RG -->|"hosts"| LA + LA -->|"installs"| SOL + + SEC_RG -->|"hosts"| KV + KV -->|"stores"| SECRET + + WRK_RG -->|"hosts"| DC + DC -->|"configures"| CAT + DC -->|"defines"| ENV + DC -->|"manages"| PROJ + PROJ -->|"contains"| POOL + + PROJ -.->|"optional"| CON_RG + CON_RG -->|"hosts"| VNET + VNET -->|"contains"| SUBNET + SUBNET -->|"attaches"| NC + NC -->|"connects to"| DC + + LA -.->|"diagnostics"| KV + LA -.->|"diagnostics"| DC + LA -.->|"diagnostics"| VNET + + SECRET -.->|"authenticates"| CAT + + %% ===== APPLY STYLES ===== + class PARAMS input + class SEC_RG,MON_RG,CON_RG,WRK_RG primary + class LA,KV,DC secondary + class SECRET,CAT,ENV,PROJ,POOL,VNET,SUBNET,NC,SOL datastore + + %% ===== SUBGRAPH STYLING ===== + style Subscription fill:#F3F4F6,stroke:#6B7280,stroke-width:2px + style Main fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style Security fill:#FEE2E2,stroke:#F44336,stroke-width:2px + style Monitoring fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Connectivity fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style Workload fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px ``` > [!IMPORTANT] @@ -613,80 +644,112 @@ src/ ### Dependency Graph ```mermaid +--- +title: Module Dependency Graph +--- flowchart TD + %% ===== STYLE DEFINITIONS ===== + 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 + + %% ===== ENTRY POINT ===== subgraph Entry["Entry Point"] - MAIN[main.bicep] + MAIN["main.bicep"] end + %% ===== MANAGEMENT LAYER ===== subgraph Management["Management Layer"] - LA[logAnalytics.bicep] + LA["logAnalytics.bicep"] end + %% ===== SECURITY LAYER ===== subgraph Security["Security Layer"] - SEC[security.bicep] - KV[keyVault.bicep] - SECRET[secret.bicep] + SEC["security.bicep"] + KV["keyVault.bicep"] + SECRET["secret.bicep"] end + %% ===== WORKLOAD LAYER ===== subgraph Workload["Workload Layer"] - WRK[workload.bicep] - DC[devCenter.bicep] - CAT[catalog.bicep] - ENV[environmentType.bicep] - PROJ[project.bicep] - PCAT[projectCatalog.bicep] - PENV[projectEnvironmentType.bicep] - POOL[projectPool.bicep] + WRK["workload.bicep"] + DC["devCenter.bicep"] + CAT["catalog.bicep"] + ENV["environmentType.bicep"] + PROJ["project.bicep"] + PCAT["projectCatalog.bicep"] + PENV["projectEnvironmentType.bicep"] + POOL["projectPool.bicep"] end + %% ===== CONNECTIVITY LAYER ===== subgraph Connectivity["Connectivity Layer"] - CONN[connectivity.bicep] - VNET[vnet.bicep] - NC[networkConnection.bicep] - RG[resourceGroup.bicep] + CONN["connectivity.bicep"] + VNET["vnet.bicep"] + NC["networkConnection.bicep"] + RG["resourceGroup.bicep"] end + %% ===== IDENTITY LAYER ===== subgraph Identity["Identity Layer"] - DCRA[devCenterRoleAssignment] - DCRA_RG[devCenterRoleAssignmentRG] - PRA[projectIdentityRoleAssignment] - PRA_RG[projectIdentityRoleAssignmentRG] - ORA[orgRoleAssignment] + DCRA["devCenterRoleAssignment"] + DCRA_RG["devCenterRoleAssignmentRG"] + PRA["projectIdentityRoleAssignment"] + PRA_RG["projectIdentityRoleAssignmentRG"] + ORA["orgRoleAssignment"] end - MAIN --> LA - MAIN --> SEC - MAIN --> WRK - - SEC --> KV - SEC --> SECRET - KV --> SECRET - LA --> SECRET - - WRK --> DC - WRK --> PROJ - LA --> DC - SECRET --> DC - - DC --> CAT - DC --> ENV - DC --> DCRA - DC --> DCRA_RG - DC --> ORA - - PROJ --> PCAT - PROJ --> PENV - PROJ --> POOL - PROJ --> CONN - PROJ --> PRA - PROJ --> PRA_RG - - CONN --> RG - CONN --> VNET - CONN --> NC - LA --> VNET - - NC --> DC + %% ===== CONNECTIONS ===== + MAIN -->|"deploys"| LA + MAIN -->|"deploys"| SEC + MAIN -->|"deploys"| WRK + + SEC -->|"creates"| KV + SEC -->|"creates"| SECRET + KV -->|"provides to"| SECRET + LA -->|"provides to"| SECRET + + WRK -->|"creates"| DC + WRK -->|"creates"| PROJ + LA -->|"provides to"| DC + SECRET -->|"provides to"| DC + + DC -->|"creates"| CAT + DC -->|"creates"| ENV + DC -->|"assigns"| DCRA + DC -->|"assigns"| DCRA_RG + DC -->|"assigns"| ORA + + PROJ -->|"creates"| PCAT + PROJ -->|"creates"| PENV + PROJ -->|"creates"| POOL + PROJ -->|"creates"| CONN + PROJ -->|"assigns"| PRA + PROJ -->|"assigns"| PRA_RG + + CONN -->|"creates"| RG + CONN -->|"creates"| VNET + CONN -->|"creates"| NC + LA -->|"provides to"| VNET + + NC -->|"connects to"| DC + + %% ===== APPLY STYLES ===== + class MAIN primary + class LA secondary + class SEC,KV,SECRET primary + class WRK,DC,CAT,ENV,PROJ,PCAT,PENV,POOL datastore + class CONN,VNET,NC,RG secondary + class DCRA,DCRA_RG,PRA,PRA_RG,ORA external + + %% ===== SUBGRAPH STYLING ===== + style Entry fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style Management fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Security fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style Workload fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style Connectivity fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Identity fill:#F3F4F6,stroke:#6B7280,stroke-width:2px ``` ### Dependency Matrix @@ -710,7 +773,11 @@ flowchart TD ### Deployment Sequence ```mermaid +--- +title: Deployment Sequence +--- sequenceDiagram + %% ===== PARTICIPANTS ===== participant User as Platform Engineer participant AZD as Azure Developer CLI participant ARM as Azure Resource Manager @@ -719,15 +786,18 @@ sequenceDiagram participant SEC as Security Module participant WRK as Workload Module + %% ===== INITIATE DEPLOYMENT ===== User->>AZD: azd provision AZD->>ARM: Deploy main.bicep + %% ===== PARALLEL RESOURCE GROUP CREATION ===== par Create Resource Groups ARM->>RG: Create Security RG ARM->>RG: Create Monitoring RG ARM->>RG: Create Workload RG end + %% ===== SEQUENTIAL MODULE DEPLOYMENT ===== ARM->>MON: Deploy logAnalytics.bicep MON-->>ARM: AZURE_LOG_ANALYTICS_WORKSPACE_ID @@ -738,9 +808,11 @@ sequenceDiagram ARM->>WRK: Deploy workload.bicep Note over WRK: Uses logAnalyticsId, secretIdentifier + %% ===== NESTED WORKLOAD DEPLOYMENT ===== WRK->>WRK: Deploy devCenter.bicep WRK->>WRK: Deploy project.bicep (loop) + %% ===== RETURN OUTPUTS ===== WRK-->>ARM: AZURE_DEV_CENTER_NAME, AZURE_DEV_CENTER_PROJECTS ARM-->>AZD: Deployment outputs AZD-->>User: Deployment complete @@ -1007,33 +1079,57 @@ module newzone '../src/newzone/newzone.bicep' = { ### Extension Architecture ```mermaid +--- +title: Extension Architecture +--- flowchart TD + %% ===== STYLE DEFINITIONS ===== + 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 input fill:#F3F4F6,stroke:#6B7280,color:#000000 + + %% ===== CONFIGURATION LAYER ===== subgraph Config["Configuration Layer"] - YAML[YAML Files] - SCHEMA[JSON Schemas] + YAML["YAML Files"] + SCHEMA["JSON Schemas"] end + %% ===== EXTENSION POINTS ===== subgraph Extension["Extension Points"] - NEW_PROJ[New Project] - NEW_POOL[New Pool] - NEW_CAT[New Catalog] - NEW_LZ[New Landing Zone] + NEW_PROJ["New Project"] + NEW_POOL["New Pool"] + NEW_CAT["New Catalog"] + NEW_LZ["New Landing Zone"] end + %% ===== MODULE LAYER ===== subgraph Modules["Module Layer"] - EXISTING[Existing Modules] - NEW_MOD[New Modules] + EXISTING["Existing Modules"] + NEW_MOD["New Modules"] end - YAML --> Extension - SCHEMA --> YAML + %% ===== CONNECTIONS ===== + YAML -->|"configures"| Extension + SCHEMA -->|"validates"| YAML + + NEW_PROJ -->|"uses"| EXISTING + NEW_POOL -->|"uses"| EXISTING + NEW_CAT -->|"uses"| EXISTING + NEW_LZ -->|"requires"| NEW_MOD + + NEW_MOD -->|"follow patterns of"| EXISTING - NEW_PROJ --> |Uses| EXISTING - NEW_POOL --> |Uses| EXISTING - NEW_CAT --> |Uses| EXISTING - NEW_LZ --> |Requires| NEW_MOD + %% ===== APPLY STYLES ===== + class YAML,SCHEMA input + class NEW_PROJ,NEW_POOL,NEW_CAT,NEW_LZ primary + class EXISTING secondary + class NEW_MOD datastore - NEW_MOD --> |Follow patterns of| EXISTING + %% ===== SUBGRAPH STYLING ===== + style Config fill:#F3F4F6,stroke:#6B7280,stroke-width:2px + style Extension fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style Modules fill:#ECFDF5,stroke:#10B981,stroke-width:2px ``` --- From a619953a512b2c9f3e0c3109a06a6cd0a0c6543a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 15:37:59 -0500 Subject: [PATCH 20/49] Refactor technology architecture documentation to enhance clarity and detail in Azure services flowcharts and four-zone architecture diagrams --- .../04-technology-architecture.md | 233 +++++++++++++----- 1 file changed, 165 insertions(+), 68 deletions(-) diff --git a/docs/architecture/04-technology-architecture.md b/docs/architecture/04-technology-architecture.md index b00fe9ce..3565fb0f 100644 --- a/docs/architecture/04-technology-architecture.md +++ b/docs/architecture/04-technology-architecture.md @@ -68,59 +68,93 @@ services organized into functional landing zones. ### Azure Services Deployed ```mermaid +--- +title: Azure Services Overview +--- flowchart TB + %% ===== STYLE DEFINITIONS ===== + 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 + + %% ===== AZURE CLOUD ===== subgraph Azure["Azure Cloud"] + %% ===== MANAGEMENT PLANE ===== subgraph Management["Management Plane"] - ARM[Azure Resource Manager] - AAD[Microsoft Entra ID] - RBAC[Azure RBAC] + ARM["Azure Resource Manager"] + AAD["Microsoft Entra ID"] + RBAC["Azure RBAC"] end + %% ===== COMPUTE SERVICES ===== subgraph Compute["Compute Services"] - DC[Microsoft DevCenter] - DEVBOX[Dev Box VMs] + DC["Microsoft DevCenter"] + DEVBOX["Dev Box VMs"] end + %% ===== SECURITY SERVICES ===== subgraph Security["Security Services"] - KV[Azure Key Vault] + KV["Azure Key Vault"] end + %% ===== NETWORKING SERVICES ===== subgraph Networking["Networking Services"] - VNET[Virtual Network] - SUBNET[Subnets] - NSG[Network Security Groups] + VNET["Virtual Network"] + SUBNET["Subnets"] + NSG["Network Security Groups"] end + %% ===== MONITORING SERVICES ===== subgraph Monitoring["Monitoring Services"] - LA[Log Analytics Workspace] - DIAG[Diagnostic Settings] - SOL[Solutions] + LA["Log Analytics Workspace"] + DIAG["Diagnostic Settings"] + SOL["Solutions"] end + %% ===== STORAGE SERVICES ===== subgraph Storage["Storage Services"] - BLOB[Blob Storage
Dev Box Images] + BLOB["Blob Storage
Dev Box Images"] end end - ARM --> DC - ARM --> KV - ARM --> VNET - ARM --> LA - - AAD --> RBAC - RBAC --> DC - RBAC --> KV - - DC --> DEVBOX - DEVBOX --> VNET - VNET --> SUBNET - SUBNET --> NSG - - DC --> DIAG - KV --> DIAG - VNET --> DIAG - DIAG --> LA - LA --> SOL + %% ===== CONNECTIONS ===== + ARM -->|"deploys"| DC + ARM -->|"deploys"| KV + ARM -->|"deploys"| VNET + ARM -->|"deploys"| LA + + AAD -->|"authenticates"| RBAC + RBAC -->|"authorizes"| DC + RBAC -->|"authorizes"| KV + + DC -->|"provisions"| DEVBOX + DEVBOX -->|"connects to"| VNET + VNET -->|"contains"| SUBNET + SUBNET -->|"secured by"| NSG + + DC -->|"sends logs"| DIAG + KV -->|"sends logs"| DIAG + VNET -->|"sends logs"| DIAG + DIAG -->|"routes to"| LA + LA -->|"analyzes"| SOL + + %% ===== APPLY STYLES ===== + class ARM,AAD,RBAC external + class DC,DEVBOX primary + class KV primary + class VNET,SUBNET,NSG secondary + class LA,DIAG,SOL datastore + class BLOB datastore + + %% ===== SUBGRAPH STYLING ===== + style Azure fill:#F3F4F6,stroke:#6B7280,stroke-width:2px + style Management fill:#F3F4F6,stroke:#6B7280,stroke-width:2px + style Compute fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style Security fill:#FEE2E2,stroke:#F44336,stroke-width:2px + style Networking fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Monitoring fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style Storage fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px ``` ### Service Catalog @@ -170,20 +204,32 @@ The accelerator supports deployment to the following regions: ### Four-Zone Architecture ```mermaid +--- +title: Four-Zone Landing Zone Architecture +--- flowchart TB + %% ===== STYLE DEFINITIONS ===== + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + + %% ===== SUBSCRIPTION ===== subgraph Subscription["Azure Subscription"] + %% ===== SECURITY ZONE ===== subgraph SecurityZone["πŸ” Security Landing Zone"] SEC_RG["devexp-security-{env}-{region}-RG"] KV["Key Vault
contoso-{unique}-kv"] SECRET["Secret: gha-token"] end + %% ===== MONITORING ZONE ===== subgraph MonitoringZone["πŸ“Š Monitoring Landing Zone"] MON_RG["devexp-monitoring-{env}-{region}-RG"] LA["Log Analytics
logAnalytics-{unique}"] SOL["Azure Activity Solution"] end + %% ===== CONNECTIVITY ZONE ===== subgraph ConnectivityZone["🌐 Connectivity Landing Zone"] CON_RG["eShop-connectivity-RG"] VNET["Virtual Network
eShop"] @@ -191,6 +237,7 @@ flowchart TB NC["Network Connection
netconn-eShop"] end + %% ===== WORKLOAD ZONE ===== subgraph WorkloadZone["πŸ’» Workload Landing Zone"] WRK_RG["devexp-workload-{env}-{region}-RG"] DC["DevCenter
devexp-devcenter"] @@ -200,26 +247,39 @@ flowchart TB end end - SEC_RG --> KV - KV --> SECRET - - MON_RG --> LA - LA --> SOL - - CON_RG --> VNET - VNET --> SUBNET - SUBNET --> NC - - WRK_RG --> DC - DC --> PROJ - PROJ --> POOL1 - PROJ --> POOL2 - - NC -.->|Attach| DC - SECRET -.->|Auth| DC - LA -.->|Diagnostics| KV - LA -.->|Diagnostics| DC - LA -.->|Diagnostics| VNET + %% ===== CONNECTIONS ===== + SEC_RG -->|"hosts"| KV + KV -->|"stores"| SECRET + + MON_RG -->|"hosts"| LA + LA -->|"installs"| SOL + + CON_RG -->|"hosts"| VNET + VNET -->|"contains"| SUBNET + SUBNET -->|"attaches to"| NC + + WRK_RG -->|"hosts"| DC + DC -->|"manages"| PROJ + PROJ -->|"contains"| POOL1 + PROJ -->|"contains"| POOL2 + + NC -.->|"attaches to"| DC + SECRET -.->|"authenticates"| DC + LA -.->|"diagnostics"| KV + LA -.->|"diagnostics"| DC + LA -.->|"diagnostics"| VNET + + %% ===== APPLY STYLES ===== + class SEC_RG,MON_RG,CON_RG,WRK_RG primary + class KV,LA secondary + class SECRET,SOL,VNET,SUBNET,NC,DC,PROJ,POOL1,POOL2 datastore + + %% ===== SUBGRAPH STYLING ===== + style Subscription fill:#F3F4F6,stroke:#6B7280,stroke-width:2px + style SecurityZone fill:#FEE2E2,stroke:#F44336,stroke-width:2px + style MonitoringZone fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style ConnectivityZone fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style WorkloadZone fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px ``` ### Resource Group Naming Convention @@ -265,44 +325,75 @@ All resources are tagged with consistent metadata: ### Network Topology ```mermaid +--- +title: Network Topology +--- flowchart TB + %% ===== STYLE DEFINITIONS ===== + 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 + + %% ===== INTERNET ===== subgraph Internet["Internet"] - DEV[Developer] + DEV["Developer"] end + %% ===== AZURE ===== subgraph Azure["Azure"] + %% ===== DEVCENTER ===== subgraph DevCenter["DevCenter"] - DC_CTRL[Control Plane] + DC_CTRL["Control Plane"] end + %% ===== MANAGED NETWORK ===== subgraph ManagedNet["Microsoft-Hosted Network"] - MN[Managed Network
Microsoft-provided] + MN["Managed Network
Microsoft-provided"] end + %% ===== CUSTOMER NETWORK ===== subgraph CustomerNet["Customer-Managed Network"] subgraph VNet["eShop VNet (10.0.0.0/16)"] SUBNET1["eShop-subnet
10.0.1.0/24"] end - NC[Network Connection] + NC["Network Connection"] end + %% ===== DEV BOXES ===== subgraph DevBoxes["Dev Box VMs"] - DB1[Backend Dev Box] - DB2[Frontend Dev Box] + DB1["Backend Dev Box"] + DB2["Frontend Dev Box"] end end - DEV -->|RDP/HTTPS| DC_CTRL - DC_CTRL --> MN - DC_CTRL --> NC - - NC --> SUBNET1 - - MN --> DB1 - MN --> DB2 - SUBNET1 --> DB1 - SUBNET1 --> DB2 + %% ===== CONNECTIONS ===== + DEV -->|"RDP/HTTPS"| DC_CTRL + DC_CTRL -->|"manages"| MN + DC_CTRL -->|"connects via"| NC + + NC -->|"attaches to"| SUBNET1 + + MN -->|"provides network"| DB1 + MN -->|"provides network"| DB2 + SUBNET1 -->|"provides network"| DB1 + SUBNET1 -->|"provides network"| DB2 + + %% ===== APPLY STYLES ===== + class DEV external + class DC_CTRL,NC primary + class MN,SUBNET1 secondary + class DB1,DB2 datastore + + %% ===== SUBGRAPH STYLING ===== + style Internet fill:#F3F4F6,stroke:#6B7280,stroke-width:2px + style Azure fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style DevCenter fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style ManagedNet fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style CustomerNet fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style VNet fill:#D1FAE5,stroke:#059669,stroke-width:1px + style DevBoxes fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px ``` ### Network Options @@ -333,18 +424,24 @@ network: ### Network Connection Flow ```mermaid +--- +title: Network Connection Flow +--- sequenceDiagram + %% ===== PARTICIPANTS ===== participant DC as DevCenter participant NC as Network Connection participant VNet as Virtual Network participant Subnet as Subnet participant DB as Dev Box + %% ===== CONNECTION SETUP ===== DC->>NC: Create Network Connection NC->>VNet: Reference VNet VNet->>Subnet: Validate Subnet NC-->>DC: Connection Ready + %% ===== DEV BOX PROVISIONING ===== DC->>DB: Provision Dev Box DB->>NC: Request Network Config NC->>Subnet: Allocate IP From 9bf7610e78c8d25f50e8f2a27a7712d422e6ebd5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 15:39:17 -0500 Subject: [PATCH 21/49] Refactor identity and role diagrams to enhance clarity and detail in the technology architecture documentation --- .../04-technology-architecture.md | 413 ++++++++++++------ 1 file changed, 281 insertions(+), 132 deletions(-) diff --git a/docs/architecture/04-technology-architecture.md b/docs/architecture/04-technology-architecture.md index 3565fb0f..90fd65c4 100644 --- a/docs/architecture/04-technology-architecture.md +++ b/docs/architecture/04-technology-architecture.md @@ -465,50 +465,74 @@ sequenceDiagram ### Identity Model ```mermaid +--- +title: Identity Model +--- flowchart TB + %% ===== STYLE DEFINITIONS ===== + 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 + + %% ===== IDENTITIES ===== subgraph Identities["Identity Types"] - SI_DC[DevCenter
System-Assigned MI] - SI_PROJ[Project
System-Assigned MI] - ADG[Azure AD Groups] + SI_DC["DevCenter
System-Assigned MI"] + SI_PROJ["Project
System-Assigned MI"] + ADG["Azure AD Groups"] end + %% ===== ROLES ===== subgraph Roles["RBAC Roles"] - R1[Contributor] - R2[User Access Administrator] - R3[Key Vault Secrets User] - R4[Key Vault Secrets Officer] - R5[DevCenter Project Admin] - R6[Dev Box User] - R7[Deployment Environment User] + R1["Contributor"] + R2["User Access Administrator"] + R3["Key Vault Secrets User"] + R4["Key Vault Secrets Officer"] + R5["DevCenter Project Admin"] + R6["Dev Box User"] + R7["Deployment Environment User"] end + %% ===== SCOPES ===== subgraph Scopes["Assignment Scopes"] - SUB[Subscription] - RG_SEC[Security RG] - RG_WRK[Workload RG] - DC[DevCenter] - PROJ[Project] + SUB["Subscription"] + RG_SEC["Security RG"] + RG_WRK["Workload RG"] + DC["DevCenter"] + PROJ["Project"] end - SI_DC --> R1 - SI_DC --> R2 - SI_DC --> R3 - SI_DC --> R4 - - SI_PROJ --> R3 - SI_PROJ --> R4 - - ADG --> R5 - ADG --> R6 - ADG --> R7 - - R1 --> SUB - R2 --> SUB - R3 --> RG_SEC - R4 --> RG_SEC - R5 --> RG_WRK - R6 --> PROJ - R7 --> PROJ + %% ===== CONNECTIONS ===== + SI_DC -->|"assigned"| R1 + SI_DC -->|"assigned"| R2 + SI_DC -->|"assigned"| R3 + SI_DC -->|"assigned"| R4 + + SI_PROJ -->|"assigned"| R3 + SI_PROJ -->|"assigned"| R4 + + ADG -->|"assigned"| R5 + ADG -->|"assigned"| R6 + ADG -->|"assigned"| R7 + + R1 -->|"scoped to"| SUB + R2 -->|"scoped to"| SUB + R3 -->|"scoped to"| RG_SEC + R4 -->|"scoped to"| RG_SEC + R5 -->|"scoped to"| RG_WRK + R6 -->|"scoped to"| PROJ + R7 -->|"scoped to"| PROJ + + %% ===== APPLY STYLES ===== + class SI_DC,SI_PROJ primary + class ADG external + class R1,R2,R3,R4,R5,R6,R7 secondary + class SUB,RG_SEC,RG_WRK,DC,PROJ datastore + + %% ===== SUBGRAPH STYLING ===== + style Identities fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style Roles fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Scopes fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px ``` ### Role Assignment Matrix @@ -557,27 +581,49 @@ projects: ### Role Hierarchy ```mermaid +--- +title: Role Hierarchy +--- flowchart TD + %% ===== STYLE DEFINITIONS ===== + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + + %% ===== SUBSCRIPTION LEVEL ===== subgraph Subscription["Subscription Level"] - CONTRIB[Contributor] - UAA[User Access Administrator] + CONTRIB["Contributor"] + UAA["User Access Administrator"] end + %% ===== RESOURCE GROUP LEVEL ===== subgraph ResourceGroup["Resource Group Level"] - KV_USER[Key Vault Secrets User] - KV_OFFICER[Key Vault Secrets Officer] - PROJ_ADMIN[DevCenter Project Admin] + KV_USER["Key Vault Secrets User"] + KV_OFFICER["Key Vault Secrets Officer"] + PROJ_ADMIN["DevCenter Project Admin"] end + %% ===== RESOURCE LEVEL ===== subgraph Resource["Resource Level"] - DB_USER[Dev Box User] - ENV_USER[Deployment Environment User] + DB_USER["Dev Box User"] + ENV_USER["Deployment Environment User"] end - CONTRIB --> KV_USER - UAA --> PROJ_ADMIN - PROJ_ADMIN --> DB_USER - PROJ_ADMIN --> ENV_USER + %% ===== CONNECTIONS ===== + CONTRIB -->|"enables"| KV_USER + UAA -->|"enables"| PROJ_ADMIN + PROJ_ADMIN -->|"enables"| DB_USER + PROJ_ADMIN -->|"enables"| ENV_USER + + %% ===== APPLY STYLES ===== + class CONTRIB,UAA primary + class KV_USER,KV_OFFICER,PROJ_ADMIN secondary + class DB_USER,ENV_USER datastore + + %% ===== SUBGRAPH STYLING ===== + style Subscription fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style ResourceGroup fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Resource fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px ``` --- @@ -587,37 +633,62 @@ flowchart TD ### Key Vault Configuration ```mermaid +--- +title: Key Vault Security Configuration +--- flowchart LR + %% ===== STYLE DEFINITIONS ===== + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + + %% ===== KEY VAULT ===== subgraph KeyVault["Azure Key Vault"] - PROPS[Properties] - SECRET[Secrets] - ACCESS[Access Control] + PROPS["Properties"] + SECRET["Secrets"] + ACCESS["Access Control"] end + %% ===== PROPERTIES ===== subgraph Properties["Security Properties"] - P1[RBAC Authorization: true] - P2[Soft Delete: true] - P3[Purge Protection: true] - P4[Retention: 7 days] + P1["RBAC Authorization: true"] + P2["Soft Delete: true"] + P3["Purge Protection: true"] + P4["Retention: 7 days"] end + %% ===== SECRETS ===== subgraph Secrets["Stored Secrets"] - S1[gha-token
GitHub PAT] + S1["gha-token
GitHub PAT"] end + %% ===== ACCESS ===== subgraph Access["RBAC Access"] - A1[DevCenter MI] - A2[Project MI] - A3[Deployer] + A1["DevCenter MI"] + A2["Project MI"] + A3["Deployer"] end - PROPS --> Properties - SECRET --> Secrets - ACCESS --> Access + %% ===== CONNECTIONS ===== + PROPS -->|"defines"| Properties + SECRET -->|"contains"| Secrets + ACCESS -->|"controls"| Access + + A1 -->|"Secrets User"| S1 + A2 -->|"Secrets User"| S1 + A3 -->|"Secrets Officer"| S1 + + %% ===== APPLY STYLES ===== + class PROPS,SECRET,ACCESS primary + class P1,P2,P3,P4 secondary + class S1 datastore + class A1,A2,A3 secondary - A1 -->|Secrets User| S1 - A2 -->|Secrets User| S1 - A3 -->|Secrets Officer| S1 + %% ===== SUBGRAPH STYLING ===== + style KeyVault fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style Properties fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Secrets fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style Access fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px ``` > [!WARNING] @@ -639,7 +710,11 @@ flowchart LR ### Security Data Flow ```mermaid +--- +title: Security Data Flow +--- sequenceDiagram + %% ===== PARTICIPANTS ===== participant DC as DevCenter participant MI as Managed Identity participant AAD as Entra ID @@ -647,16 +722,19 @@ sequenceDiagram participant KV as Key Vault participant GH as GitHub + %% ===== AUTHENTICATION FLOW ===== DC->>MI: Request token MI->>AAD: Authenticate AAD-->>MI: Access token MI-->>DC: Token + %% ===== SECRET ACCESS FLOW ===== DC->>KV: Get secret (with token) KV->>RBAC: Check permissions RBAC-->>KV: Authorized KV-->>DC: Secret value + %% ===== CATALOG ACCESS FLOW ===== DC->>GH: Clone catalog (with PAT) GH-->>DC: Repository content ``` @@ -678,55 +756,80 @@ sequenceDiagram ### Monitoring Architecture ```mermaid +--- +title: Monitoring Architecture +--- flowchart TB + %% ===== STYLE DEFINITIONS ===== + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + + %% ===== DATA SOURCES ===== subgraph Sources["Data Sources"] - DC[DevCenter] - KV[Key Vault] - VNET[Virtual Network] - LA_SELF[Log Analytics] + DC["DevCenter"] + KV["Key Vault"] + VNET["Virtual Network"] + LA_SELF["Log Analytics"] end + %% ===== DATA COLLECTION ===== subgraph Collection["Data Collection"] - DIAG1[Diagnostic Settings] - DIAG2[Diagnostic Settings] - DIAG3[Diagnostic Settings] - DIAG4[Self-Diagnostics] + DIAG1["Diagnostic Settings"] + DIAG2["Diagnostic Settings"] + DIAG3["Diagnostic Settings"] + DIAG4["Self-Diagnostics"] end + %% ===== LOG ANALYTICS ===== subgraph Analytics["Log Analytics Workspace"] - LOGS[Logs
AzureDiagnostics] - METRICS[Metrics
AzureMetrics] - ACTIVITY[Activity Logs
AzureActivity] + LOGS["Logs
AzureDiagnostics"] + METRICS["Metrics
AzureMetrics"] + ACTIVITY["Activity Logs
AzureActivity"] end + %% ===== OUTPUTS ===== subgraph Outputs["Analysis & Action"] - QUERIES[KQL Queries] - ALERTS[Alerts] - WORKBOOKS[Workbooks] - DASHBOARD[Dashboards] + QUERIES["KQL Queries"] + ALERTS["Alerts"] + WORKBOOKS["Workbooks"] + DASHBOARD["Dashboards"] end - DC --> DIAG1 - KV --> DIAG2 - VNET --> DIAG3 - LA_SELF --> DIAG4 - - DIAG1 --> LOGS - DIAG1 --> METRICS - DIAG2 --> LOGS - DIAG2 --> METRICS - DIAG3 --> LOGS - DIAG3 --> METRICS - DIAG4 --> LOGS - DIAG4 --> METRICS - - LOGS --> QUERIES - METRICS --> QUERIES - ACTIVITY --> QUERIES - - QUERIES --> ALERTS - QUERIES --> WORKBOOKS - QUERIES --> DASHBOARD + %% ===== CONNECTIONS ===== + DC -->|"sends"| DIAG1 + KV -->|"sends"| DIAG2 + VNET -->|"sends"| DIAG3 + LA_SELF -->|"sends"| DIAG4 + + DIAG1 -->|"logs"| LOGS + DIAG1 -->|"metrics"| METRICS + DIAG2 -->|"logs"| LOGS + DIAG2 -->|"metrics"| METRICS + DIAG3 -->|"logs"| LOGS + DIAG3 -->|"metrics"| METRICS + DIAG4 -->|"logs"| LOGS + DIAG4 -->|"metrics"| METRICS + + LOGS -->|"analyzed by"| QUERIES + METRICS -->|"analyzed by"| QUERIES + ACTIVITY -->|"analyzed by"| QUERIES + + QUERIES -->|"triggers"| ALERTS + QUERIES -->|"visualizes"| WORKBOOKS + QUERIES -->|"displays"| DASHBOARD + + %% ===== APPLY STYLES ===== + class DC,KV,VNET,LA_SELF primary + class DIAG1,DIAG2,DIAG3,DIAG4 secondary + class LOGS,METRICS,ACTIVITY datastore + class QUERIES,ALERTS,WORKBOOKS,DASHBOARD secondary + + %% ===== SUBGRAPH STYLING ===== + style Sources fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style Collection fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Analytics fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style Outputs fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px ``` ### Log Analytics Configuration @@ -783,45 +886,71 @@ resource diagnosticSettings 'Microsoft.Insights/diagnosticSettings@2021-05-01-pr ### CI/CD Pipeline Flow ```mermaid +--- +title: CI/CD Pipeline Flow +--- flowchart LR + %% ===== STYLE DEFINITIONS ===== + 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 trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + + %% ===== TRIGGERS ===== subgraph Trigger["Triggers"] - PUSH[Push to feature/*] - PR[Pull Request to main] - MANUAL[Manual Dispatch] + PUSH["Push to feature/*"] + PR["Pull Request to main"] + MANUAL["Manual Dispatch"] end + %% ===== CI ===== subgraph CI["Continuous Integration"] - VERSION[Generate Version] - BUILD[Build Bicep] - ARTIFACT[Upload Artifacts] + VERSION["Generate Version"] + BUILD["Build Bicep"] + ARTIFACT["Upload Artifacts"] end + %% ===== CD ===== subgraph CD["Continuous Deployment"] - AUTH[Azure Auth
Federated Credentials] - PROVISION[azd provision] - DEPLOY[Deploy to Azure] + AUTH["Azure Auth
Federated Credentials"] + PROVISION["azd provision"] + DEPLOY["Deploy to Azure"] end + %% ===== RELEASE ===== subgraph Release["Release"] - TAG[Create Git Tag] - RELEASE[GitHub Release] - NOTES[Release Notes] + TAG["Create Git Tag"] + RELEASE["GitHub Release"] + NOTES["Release Notes"] end - PUSH --> VERSION - PR --> VERSION - MANUAL --> VERSION + %% ===== CONNECTIONS ===== + PUSH -->|"triggers"| VERSION + PR -->|"triggers"| VERSION + MANUAL -->|"triggers"| VERSION - VERSION --> BUILD - BUILD --> ARTIFACT + VERSION -->|"generates"| BUILD + BUILD -->|"produces"| ARTIFACT - ARTIFACT --> AUTH - AUTH --> PROVISION - PROVISION --> DEPLOY + ARTIFACT -->|"starts"| AUTH + AUTH -->|"authenticates"| PROVISION + PROVISION -->|"executes"| DEPLOY - DEPLOY --> TAG - TAG --> RELEASE - RELEASE --> NOTES + DEPLOY -->|"completes"| TAG + TAG -->|"creates"| RELEASE + RELEASE -->|"generates"| NOTES + + %% ===== APPLY STYLES ===== + class PUSH,PR,MANUAL trigger + class VERSION,BUILD,ARTIFACT primary + class AUTH,PROVISION,DEPLOY secondary + class TAG,RELEASE,NOTES datastore + + %% ===== SUBGRAPH STYLING ===== + style Trigger fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style CI fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style CD fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Release fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px ``` ### GitHub Actions Workflows @@ -835,24 +964,44 @@ flowchart LR ### CI Workflow Details (`ci.yml`) ```mermaid +--- +title: CI Workflow Details +--- flowchart TD + %% ===== STYLE DEFINITIONS ===== + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + + %% ===== JOB 1 ===== subgraph Job1["generate-tag-version"] - CHECKOUT1[Checkout Code] - GENERATE[Generate Release Info] - OUTPUT1[/new_version, release_type,
previous_tag, should_release/] + CHECKOUT1["Checkout Code"] + GENERATE["Generate Release Info"] + OUTPUT1[/"new_version, release_type,
previous_tag, should_release"/] end + %% ===== JOB 2 ===== subgraph Job2["build"] - CHECKOUT2[Checkout Code] - BUILD[Build Bicep Code] - UPLOAD[Upload Artifacts] + CHECKOUT2["Checkout Code"] + BUILD["Build Bicep Code"] + UPLOAD["Upload Artifacts"] end - CHECKOUT1 --> GENERATE - GENERATE --> OUTPUT1 - OUTPUT1 --> CHECKOUT2 - CHECKOUT2 --> BUILD - BUILD --> UPLOAD + %% ===== CONNECTIONS ===== + CHECKOUT1 -->|"runs"| GENERATE + GENERATE -->|"outputs"| OUTPUT1 + OUTPUT1 -->|"triggers"| CHECKOUT2 + CHECKOUT2 -->|"runs"| BUILD + BUILD -->|"produces"| UPLOAD + + %% ===== APPLY STYLES ===== + class CHECKOUT1,CHECKOUT2 primary + class GENERATE,BUILD secondary + class OUTPUT1,UPLOAD datastore + + %% ===== SUBGRAPH STYLING ===== + style Job1 fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style Job2 fill:#ECFDF5,stroke:#10B981,stroke-width:2px ``` ### Deploy Workflow Details (`deploy.yml`) From d1eeb6a4086ae977eed553d3fad713e84755aafc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 15:40:28 -0500 Subject: [PATCH 22/49] Refactor setup script flow, Git branching strategy, and release process diagrams to enhance clarity and detail in technology architecture documentation --- .../04-technology-architecture.md | 116 ++++++++++++------ 1 file changed, 81 insertions(+), 35 deletions(-) diff --git a/docs/architecture/04-technology-architecture.md b/docs/architecture/04-technology-architecture.md index 90fd65c4..8fc2864c 100644 --- a/docs/architecture/04-technology-architecture.md +++ b/docs/architecture/04-technology-architecture.md @@ -1095,25 +1095,42 @@ hooks: ### Setup Script Flow ```mermaid +--- +title: Setup Script Flow +--- flowchart TD - START[Start Setup] - CHECK_CLI[Check CLI Tools
az, azd, gh] - AUTH_AZ[Authenticate Azure] - AUTH_GH[Authenticate GitHub/ADO] - GET_TOKEN[Get PAT Token] - INIT_ENV[Initialize azd Environment] - SET_VARS[Set Environment Variables] - PROVISION[azd provision] - END[Setup Complete] - - START --> CHECK_CLI - CHECK_CLI --> AUTH_AZ - AUTH_AZ --> AUTH_GH - AUTH_GH --> GET_TOKEN - GET_TOKEN --> INIT_ENV - INIT_ENV --> SET_VARS - SET_VARS --> PROVISION - PROVISION --> END + %% ===== STYLE DEFINITIONS ===== + 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 decision fill:#FFFBEB,stroke:#F59E0B,color:#000000 + + %% ===== FLOW ===== + START["Start Setup"] + CHECK_CLI["Check CLI Tools
az, azd, gh"] + AUTH_AZ["Authenticate Azure"] + AUTH_GH["Authenticate GitHub/ADO"] + GET_TOKEN["Get PAT Token"] + INIT_ENV["Initialize azd Environment"] + SET_VARS["Set Environment Variables"] + PROVISION["azd provision"] + END_NODE["Setup Complete"] + + %% ===== CONNECTIONS ===== + START -->|"begins"| CHECK_CLI + CHECK_CLI -->|"validates"| AUTH_AZ + AUTH_AZ -->|"authenticates"| AUTH_GH + AUTH_GH -->|"retrieves"| GET_TOKEN + GET_TOKEN -->|"initializes"| INIT_ENV + INIT_ENV -->|"configures"| SET_VARS + SET_VARS -->|"deploys"| PROVISION + PROVISION -->|"completes"| END_NODE + + %% ===== APPLY STYLES ===== + class START,END_NODE datastore + class CHECK_CLI,AUTH_AZ,AUTH_GH decision + class GET_TOKEN,INIT_ENV,SET_VARS primary + class PROVISION secondary ``` ### Environment Variables @@ -1135,6 +1152,9 @@ flowchart TD ### Branching Strategy ```mermaid +--- +title: Git Branching Strategy +--- gitGraph commit id: "Initial" branch feature/new-feature @@ -1174,36 +1194,62 @@ The accelerator follows semantic versioning (`MAJOR.MINOR.PATCH`): ### Release Process ```mermaid +--- +title: Release Process +--- flowchart LR + %% ===== STYLE DEFINITIONS ===== + 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 trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + + %% ===== TRIGGER ===== subgraph Trigger["Release Trigger"] - MANUAL[Manual Dispatch] + MANUAL["Manual Dispatch"] end + %% ===== GENERATE ===== subgraph Generate["Generate Metadata"] - VERSION[Calculate Version] - NOTES[Generate Notes] + VERSION["Calculate Version"] + NOTES["Generate Notes"] end + %% ===== BUILD ===== subgraph Build["Build Phase"] - BICEP[Compile Bicep] - ARM[Generate ARM] - ZIP[Package Artifacts] + BICEP["Compile Bicep"] + ARM["Generate ARM"] + ZIP["Package Artifacts"] end + %% ===== PUBLISH ===== subgraph Publish["Publish Phase"] - TAG[Create Git Tag] - RELEASE[GitHub Release] - UPLOAD[Upload Assets] + TAG["Create Git Tag"] + RELEASE["GitHub Release"] + UPLOAD["Upload Assets"] end - MANUAL --> VERSION - VERSION --> NOTES - NOTES --> BICEP - BICEP --> ARM - ARM --> ZIP - ZIP --> TAG - TAG --> RELEASE - RELEASE --> UPLOAD + %% ===== CONNECTIONS ===== + MANUAL -->|"triggers"| VERSION + VERSION -->|"generates"| NOTES + NOTES -->|"starts"| BICEP + BICEP -->|"produces"| ARM + ARM -->|"packages"| ZIP + ZIP -->|"creates"| TAG + TAG -->|"creates"| RELEASE + RELEASE -->|"attaches"| UPLOAD + + %% ===== APPLY STYLES ===== + class MANUAL trigger + class VERSION,NOTES primary + class BICEP,ARM,ZIP secondary + class TAG,RELEASE,UPLOAD datastore + + %% ===== SUBGRAPH STYLING ===== + style Trigger fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style Generate fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style Build fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Publish fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px ``` ### Infrastructure as Code Practices From 282da72da4c688ca38e08be9157381a76a73c0f1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 15:44:10 -0500 Subject: [PATCH 23/49] Remove architecture documentation index for DevExp-DevBox Landing Zone Accelerator --- docs/architecture/01-business-architecture.md | 616 -------- docs/architecture/02-data-architecture.md | 968 ------------ .../03-application-architecture.md | 1183 --------------- .../04-technology-architecture.md | 1320 ----------------- docs/architecture/README.md | 117 -- 5 files changed, 4204 deletions(-) delete mode 100644 docs/architecture/01-business-architecture.md delete mode 100644 docs/architecture/02-data-architecture.md delete mode 100644 docs/architecture/03-application-architecture.md delete mode 100644 docs/architecture/04-technology-architecture.md delete mode 100644 docs/architecture/README.md diff --git a/docs/architecture/01-business-architecture.md b/docs/architecture/01-business-architecture.md deleted file mode 100644 index a23b1125..00000000 --- a/docs/architecture/01-business-architecture.md +++ /dev/null @@ -1,616 +0,0 @@ ---- -title: Business Architecture -description: - TOGAF Business Architecture documentation for DevExp-DevBox Landing Zone - Accelerator covering stakeholders, capabilities, value streams, and business - requirements -author: Platform Engineering Team -date: 2026-01-22 -version: 1.0.0 -tags: - - TOGAF - - Business Architecture - - BDAT - - DevExp-DevBox - - Landing Zone ---- - -# 🏒 Business Architecture - -> **DevExp-DevBox Landing Zone Accelerator** - -> [!NOTE] -> -> **Target Audience:** Business Decision Makers, Enterprise Architects, Platform -> Engineers -> -> **Reading Time:** ~15 minutes - -
-πŸ“ Navigation - -| Previous | Index | Next | -| :------- | :----------------------------------: | --------------------------------------------------: | -| - | [🏠 Architecture Index](./README.md) | [πŸ“Š Data Architecture β†’](./02-data-architecture.md) | - -
- -| Metadata | Value | -| ---------------- | ------------------------- | -| **Version** | 1.0.0 | -| **Last Updated** | January 22, 2026 | -| **Author** | Platform Engineering Team | -| **Status** | Active | - ---- - -## πŸ“‘ Table of Contents - -- [πŸ“‹ Executive Summary](#-executive-summary) -- [🏒 Business Context](#-business-context) -- [πŸ‘₯ Stakeholder Analysis](#-stakeholder-analysis) -- [πŸ’Ό Business Capabilities](#-business-capabilities) -- [πŸ”„ Value Streams](#-value-streams) -- [πŸ“ Business Requirements](#-business-requirements) -- [πŸ“Š Success Metrics](#-success-metrics) -- [πŸ“š References](#-references) -- [πŸ“– Glossary](#-glossary) - ---- - -## πŸ“‹ Executive Summary - -The **DevExp-DevBox Landing Zone Accelerator** is a comprehensive -infrastructure-as-code solution that automates the deployment and management of -Microsoft Dev Box environments on Azure. This accelerator enables organizations -to provision secure, compliant, and scalable developer workstations following -Azure Landing Zone best practices. - -> [!TIP] -> -> **Quick Value Summary:** This accelerator reduces developer onboarding from -> days to hours while ensuring security compliance and cost visibility. - -### Key Business Value - -| Value Proposition | Description | -| ------------------------------------ | -------------------------------------------------------------- | -| **Accelerated Developer Onboarding** | Reduce new developer setup time from days to hours | -| **Standardized Environments** | Ensure consistent tooling and configurations across teams | -| **Security by Design** | Built-in RBAC, Key Vault integration, and compliance controls | -| **Cost Optimization** | Role-specific VM SKUs and resource tagging for cost allocation | -| **Operational Excellence** | Centralized monitoring, diagnostics, and lifecycle management | - -### Target Outcomes - -```mermaid ---- -title: DevExp-DevBox Value Proposition ---- -mindmap - root((DevExp-DevBox
Value)) - Developer Productivity - Faster onboarding - Consistent environments - Self-service provisioning - Security & Compliance - RBAC enforcement - Secrets management - Audit logging - Operational Efficiency - Infrastructure as Code - Automated deployments - Centralized monitoring - Cost Management - Resource tagging - Right-sized VMs - Environment isolation -``` - ---- - -## 🏒 Business Context - -### Problem Statement - -Enterprise development teams face significant challenges in maintaining -consistent, secure, and scalable developer workstations: - -| Challenge | Impact | Solution Approach | -| ----------------------------- | -------------------------------------------------- | ------------------------------------------------------------------ | -| **Inconsistent Environments** | "Works on my machine" syndrome, debugging overhead | Standardized Dev Box definitions with role-specific configurations | -| **Slow Onboarding** | Days/weeks to provision new developer machines | Automated provisioning through DevCenter projects and pools | -| **Security Gaps** | Manual credential management, compliance risks | Centralized Key Vault, RBAC, and managed identities | -| **Operational Overhead** | Manual infrastructure management | Infrastructure-as-Code with Bicep, GitOps workflows | -| **Cost Visibility** | Untracked resource consumption | Consistent tagging strategy and resource grouping | - -### Target Audience - -The DevExp-DevBox accelerator serves organizations that: - -- Operate cloud-native or hybrid development teams -- Require standardized, secure development environments -- Follow DevOps and Infrastructure-as-Code practices -- Need to demonstrate compliance with security frameworks -- Manage multiple projects or product teams - -### Business Drivers - -```mermaid ---- -title: Business Drivers for DevExp-DevBox ---- -flowchart LR - %% ===== STYLE DEFINITIONS ===== - classDef external fill:#6B7280,stroke:#4B5563,color:#FFFFFF,stroke-dasharray:5 5 - classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF - classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF - classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 - - %% ===== EXTERNAL DRIVERS ===== - subgraph External["External Drivers"] - A["Security Compliance"] - B["Talent Competition"] - C["Remote Work"] - end - - %% ===== INTERNAL DRIVERS ===== - subgraph Internal["Internal Drivers"] - D["Developer Productivity"] - E["Cost Optimization"] - F["Operational Efficiency"] - end - - %% ===== SOLUTION ===== - subgraph Solution["DevExp-DevBox"] - G["Landing Zone
Accelerator"] - end - - %% ===== CONNECTIONS ===== - A -->|"drives"| G - B -->|"drives"| G - C -->|"drives"| G - D -->|"drives"| G - E -->|"drives"| G - F -->|"drives"| G - - %% ===== OUTCOMES ===== - G -->|"enables"| H["Secure Dev
Environments"] - G -->|"enables"| I["Fast Onboarding"] - G -->|"enables"| J["Centralized
Management"] - - %% ===== APPLY STYLES ===== - class A,B,C external - class D,E,F primary - class G secondary - class H,I,J datastore - - %% ===== SUBGRAPH STYLING ===== - style External fill:#F3F4F6,stroke:#6B7280,stroke-width:2px - style Internal fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px - style Solution fill:#ECFDF5,stroke:#10B981,stroke-width:2px -``` - ---- - -## πŸ‘₯ Stakeholder Analysis - -### Stakeholder Map - -```mermaid ---- -title: Stakeholder Influence vs Interest Matrix ---- -quadrantChart - title Stakeholder Influence vs Interest Matrix - x-axis Low Interest --> High Interest - y-axis Low Influence --> High Influence - quadrant-1 Manage Closely - quadrant-2 Keep Satisfied - quadrant-3 Monitor - quadrant-4 Keep Informed - Platform Engineers: [0.85, 0.90] - Security Team: [0.80, 0.85] - Developers: [0.95, 0.40] - DevOps Engineers: [0.75, 0.70] - IT Operations: [0.60, 0.65] - Finance: [0.50, 0.55] - Project Managers: [0.65, 0.45] - Executive Sponsors: [0.40, 0.95] -``` - -### Detailed Stakeholder Analysis - -| Stakeholder | Role | Key Concerns | Interests | Communication Needs | -| ---------------------- | --------------------------------------------------- | ------------------------------------------------ | --------------------------------------------------- | --------------------------------------------------- | -| **Platform Engineers** | Design and maintain the landing zone infrastructure | Scalability, maintainability, automation | Modular architecture, IaC patterns, extensibility | Technical documentation, architecture decisions | -| **Security Team** | Ensure compliance and security posture | RBAC, secrets management, audit trails | Key Vault integration, identity management, logging | Security controls documentation, compliance reports | -| **Developers** | Consume Dev Box environments | Fast provisioning, correct tooling, self-service | Quick onboarding, consistent environments | User guides, self-service portals | -| **DevOps Engineers** | Manage CI/CD pipelines and deployments | Automation, reliability, deployment velocity | Pipeline integration, GitOps workflows | Deployment procedures, runbooks | -| **IT Operations** | Monitor and support production systems | Observability, incident response, SLA compliance | Log Analytics integration, alerting | Operational dashboards, incident procedures | -| **Finance/FinOps** | Manage cloud costs and budgets | Cost visibility, budget compliance, chargebacks | Resource tagging, cost allocation | Cost reports, budget alerts | -| **Project Managers** | Coordinate development activities | Team productivity, project timelines | Environment availability, team onboarding | Status reports, capacity planning | -| **Executive Sponsors** | Strategic oversight and funding | Business value, ROI, risk management | Success metrics, strategic alignment | Executive summaries, KPI dashboards | - -### RACI Matrix - -| Activity | Platform Engineers | Security Team | Developers | DevOps | IT Ops | Finance | -| ------------------------ | ------------------ | ------------- | ---------- | ------ | ------- | ------- | -| Landing Zone Design | **R/A** | C | I | C | C | I | -| Security Configuration | C | **R/A** | I | I | C | I | -| DevCenter Setup | **R/A** | C | I | C | I | I | -| Pool Definition | **R** | C | C | **A** | I | I | -| Environment Provisioning | C | I | **R** | **A** | I | I | -| Cost Monitoring | I | I | I | I | C | **R/A** | -| Incident Response | C | C | I | C | **R/A** | I | - -_R = Responsible, A = Accountable, C = Consulted, I = Informed_ - ---- - -## πŸ’Ό Business Capabilities - -### Business Capability Model - -```mermaid ---- -title: DevExp-DevBox Business Capabilities ---- -block-beta - columns 4 - - %% ===== HEADER ===== - block:header:4 - A["DevExp-DevBox Business Capabilities"] - end - - %% ===== SECURITY CAPABILITY ===== - block:security:1 - B["πŸ” Security"] - B1["Key Vault Management"] - B2["RBAC Administration"] - B3["Secret Lifecycle"] - B4["Compliance Reporting"] - end - - %% ===== MONITORING CAPABILITY ===== - block:monitoring:1 - C["πŸ“Š Monitoring"] - C1["Log Analytics"] - C2["Diagnostic Settings"] - C3["Performance Metrics"] - C4["Alert Management"] - end - - %% ===== CONNECTIVITY CAPABILITY ===== - block:connectivity:1 - D["🌐 Connectivity"] - D1["VNet Management"] - D2["Subnet Configuration"] - D3["Network Connections"] - D4["NSG Rules"] - end - - %% ===== WORKLOAD CAPABILITY ===== - block:workload:1 - E["πŸ’» Workload"] - E1["DevCenter Management"] - E2["Project Administration"] - E3["Pool Configuration"] - E4["Catalog Management"] - end - - %% ===== SUBGRAPH STYLING ===== - style header fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px - style security fill:#FEE2E2,stroke:#F44336,stroke-width:2px - style monitoring fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px - style connectivity fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px - style workload fill:#ECFDF5,stroke:#10B981,stroke-width:2px -``` - -### Capability to Landing Zone Mapping - -| Capability Domain | Landing Zone | Azure Resources | Bicep Modules | -| ------------------------------ | ------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------ | -| **Security Management** | Security Landing Zone | Key Vault, Secrets, Access Policies | `security.bicep`, `keyVault.bicep`, `secret.bicep` | -| **Monitoring & Observability** | Monitoring Landing Zone | Log Analytics Workspace, Diagnostic Settings | `logAnalytics.bicep` | -| **Network Management** | Connectivity Landing Zone | Virtual Networks, Subnets, Network Connections | `vnet.bicep`, `networkConnection.bicep`, `connectivity.bicep` | -| **Developer Workload** | Workload Landing Zone | DevCenter, Projects, Pools, Catalogs | `devCenter.bicep`, `project.bicep`, `projectPool.bicep`, `catalog.bicep` | -| **Identity Management** | Cross-cutting | Managed Identities, Role Assignments | `devCenterRoleAssignment.bicep`, `projectIdentityRoleAssignment.bicep` | - -### Capability Details - -#### Security Capability - -| Sub-Capability | Description | Business Value | -| -------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------- | -| Key Vault Management | Centralized secrets, keys, and certificates storage | Eliminates credential sprawl, enables rotation | -| RBAC Administration | Role-based access control at subscription, resource group, and resource levels | Principle of least privilege enforcement | -| Secret Lifecycle | Automated secret creation, rotation, and expiration | Reduced security incidents from stale credentials | -| Compliance Reporting | Audit logging and diagnostic data collection | Regulatory compliance demonstration | - -#### Workload Capability - -| Sub-Capability | Description | Business Value | -| ---------------------- | --------------------------------------------------- | ----------------------------------------------- | -| DevCenter Management | Centralized control plane for Dev Box environments | Single pane of glass administration | -| Project Administration | Logical grouping of development teams and resources | Team isolation and governance | -| Pool Configuration | Role-specific VM definitions and configurations | Right-sized resources, cost optimization | -| Catalog Management | Centralized image and environment definitions | Standardized, version-controlled configurations | - ---- - -## πŸ”„ Value Streams - -### Developer Onboarding Value Stream - -```mermaid ---- -title: Developer Onboarding Value Stream ---- -flowchart LR - %% ===== STYLE DEFINITIONS ===== - classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF - classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF - classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF - - %% ===== TRIGGER STAGE ===== - subgraph Trigger["Trigger"] - A["New Developer
Joins Team"] - end - - %% ===== PROCESS STAGE ===== - subgraph Process["Onboarding Process"] - B["Add to
Azure AD Group"] - C["RBAC Auto-
Assignment"] - D["Access
DevCenter Portal"] - E["Select
Dev Box Pool"] - F["Provision
Dev Box"] - G["DSC Config
Applied"] - end - - %% ===== OUTCOME STAGE ===== - subgraph Outcome["Outcome"] - H["Developer
Productive"] - end - - %% ===== FLOW CONNECTIONS ===== - A -->|"initiates"| B - B -->|"triggers"| C - C -->|"enables"| D - D -->|"leads to"| E - E -->|"triggers"| F - F -->|"applies"| G - G -->|"results in"| H - - %% ===== APPLY STYLES ===== - class A trigger - class B,C,D,E,F,G primary - class H secondary - - %% ===== SUBGRAPH STYLING ===== - style Trigger fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px - style Process fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px - style Outcome fill:#ECFDF5,stroke:#10B981,stroke-width:2px -``` - -### Value Stream Stages - -| Stage | Activities | Inputs | Outputs | Duration | Automation Level | -| ----------------------------- | --------------------------------------------------------- | ------------------- | ---------------------- | --------- | ---------------- | -| **Identity Setup** | Add developer to Azure AD group | HR onboarding data | Group membership | Minutes | Manual/Automated | -| **Access Provisioning** | RBAC roles automatically assigned via group membership | AD group membership | Project access | Seconds | Fully Automated | -| **Environment Selection** | Developer accesses DevCenter and selects appropriate pool | DevCenter access | Pool selection | Minutes | Self-Service | -| **Dev Box Provisioning** | Dev Box VM created from pool definition | Pool config, image | Running VM | 30-60 min | Fully Automated | -| **Configuration Application** | DSC configurations apply required tools and settings | DSC YAML configs | Configured workstation | 15-30 min | Fully Automated | -| **Productivity Start** | Developer begins work with all required tools | Configured Dev Box | Productive developer | Immediate | N/A | - -### Environment Provisioning Lifecycle - -```mermaid ---- -title: Environment Provisioning Lifecycle ---- -sequenceDiagram - %% ===== PARTICIPANTS ===== - participant PM as Platform Manager - participant GH as GitHub/ADO - participant AZD as Azure Developer CLI - participant ARM as Azure Resource Manager - participant DC as DevCenter - participant KV as Key Vault - - %% ===== PROVISIONING FLOW ===== - PM->>GH: Push configuration changes - GH->>GH: CI pipeline triggered - GH->>AZD: azd provision - AZD->>ARM: Deploy main.bicep - ARM->>ARM: Create Resource Groups - ARM->>KV: Deploy Key Vault - ARM->>DC: Deploy DevCenter - DC->>DC: Configure Catalogs - DC->>DC: Create Projects - DC->>DC: Setup Pools - DC-->>PM: Deployment complete - - Note over PM,KV: Infrastructure ready for developer onboarding -``` - ---- - -## πŸ“ Business Requirements - -### Functional Requirements - -| ID | Requirement | Priority | Source | Acceptance Criteria | -| ---------- | ------------------------------------------------------------ | ----------- | -------------------- | -------------------------------------------------------- | -| **FR-001** | System shall provision DevCenter with configurable settings | Must Have | Platform Engineering | DevCenter deployed with YAML-defined settings | -| **FR-002** | System shall create role-specific Dev Box pools | Must Have | Development Teams | Pools created with specified VM SKUs and images | -| **FR-003** | System shall manage secrets in Azure Key Vault | Must Have | Security Team | GitHub/ADO tokens stored securely with RBAC | -| **FR-004** | System shall assign RBAC roles based on AD group membership | Must Have | Security Team | Developers receive appropriate permissions automatically | -| **FR-005** | System shall support multiple projects within DevCenter | Should Have | Project Management | Multiple projects with isolated configurations | -| **FR-006** | System shall integrate Git catalogs for image definitions | Should Have | Platform Engineering | Catalogs sync from GitHub/Azure DevOps | -| **FR-007** | System shall configure diagnostic settings for all resources | Should Have | IT Operations | All resources send logs to Log Analytics | -| **FR-008** | System shall support both managed and unmanaged networks | Could Have | Network Team | Network type configurable per project | - -### Non-Functional Requirements - -| ID | Requirement | Category | Target | Measurement | -| ----------- | ------------------------------------------------------- | --------------- | --------------- | ----------------------------- | -| **NFR-001** | Deployment shall complete within 30 minutes | Performance | < 30 min | Pipeline duration metrics | -| **NFR-002** | Infrastructure code shall be idempotent | Reliability | 100% | Repeated deployments succeed | -| **NFR-003** | All resources shall have consistent tagging | Governance | 100% compliance | Azure Policy evaluation | -| **NFR-004** | Secrets shall use RBAC authorization only | Security | RBAC enabled | Key Vault configuration audit | -| **NFR-005** | Solution shall support 12+ Azure regions | Scalability | 12 regions | Deployment validation | -| **NFR-006** | Configuration changes shall be version controlled | Maintainability | 100% | Git history tracking | -| **NFR-007** | Deployment shall work with both GitHub and Azure DevOps | Compatibility | Both platforms | CI/CD pipeline success | - -### Requirements Traceability - -```mermaid ---- -title: Requirements Traceability Matrix ---- -flowchart TD - %% ===== STYLE DEFINITIONS ===== - classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF - classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF - classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 - - %% ===== BUSINESS GOALS ===== - subgraph Business["Business Goals"] - BG1["Fast Onboarding"] - BG2["Security Compliance"] - BG3["Cost Management"] - end - - %% ===== FUNCTIONAL REQUIREMENTS ===== - subgraph Functional["Functional Requirements"] - FR1["FR-001: DevCenter"] - FR2["FR-002: Pools"] - FR3["FR-003: Key Vault"] - FR4["FR-004: RBAC"] - end - - %% ===== TECHNICAL COMPONENTS ===== - subgraph Technical["Technical Components"] - TC1["devCenter.bicep"] - TC2["projectPool.bicep"] - TC3["keyVault.bicep"] - TC4["roleAssignment.bicep"] - end - - %% ===== TRACEABILITY LINKS ===== - BG1 -->|"requires"| FR1 - BG1 -->|"requires"| FR2 - BG2 -->|"requires"| FR3 - BG2 -->|"requires"| FR4 - BG3 -->|"requires"| FR2 - - FR1 -->|"implemented by"| TC1 - FR2 -->|"implemented by"| TC2 - FR3 -->|"implemented by"| TC3 - FR4 -->|"implemented by"| TC4 - - %% ===== APPLY STYLES ===== - class BG1,BG2,BG3 primary - class FR1,FR2,FR3,FR4 secondary - class TC1,TC2,TC3,TC4 datastore - - %% ===== SUBGRAPH STYLING ===== - style Business fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px - style Functional fill:#ECFDF5,stroke:#10B981,stroke-width:2px - style Technical fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px -``` - ---- - -## πŸ“Š Success Metrics - -### Key Performance Indicators (KPIs) - -| KPI | Description | Target | Measurement Method | Frequency | -| --------------------------------- | --------------------------------------------------- | ------------- | ----------------------- | -------------- | -| **Developer Onboarding Time** | Time from AD group addition to productive Dev Box | < 2 hours | Tracking timestamps | Per onboarding | -| **Deployment Success Rate** | Percentage of successful infrastructure deployments | > 99% | CI/CD pipeline metrics | Weekly | -| **Environment Provisioning Time** | Time to provision a new Dev Box | < 60 minutes | DevCenter metrics | Daily | -| **Security Compliance Score** | Azure Security Center compliance percentage | > 95% | Azure Security Center | Weekly | -| **Resource Tagging Compliance** | Percentage of resources with required tags | 100% | Azure Policy | Daily | -| **Cost per Developer** | Monthly Azure spend per active developer | Baseline -10% | Cost Management reports | Monthly | -| **Mean Time to Recovery** | Average time to resolve infrastructure issues | < 4 hours | Incident tracking | Per incident | - -### Success Metrics Dashboard - -```mermaid ---- -title: Resource Distribution by Landing Zone ---- -pie showData - title Resource Distribution by Landing Zone - "Security" : 15 - "Monitoring" : 10 - "Connectivity" : 20 - "Workload" : 55 -``` - -### Business Value Realization - -| Metric | Before Accelerator | After Accelerator | Improvement | -| --------------------------------------- | ------------------ | ----------------- | --------------- | -| Developer Onboarding | 3-5 days | 2-4 hours | 90%+ reduction | -| Environment Consistency | 60% | 100% | 40% improvement | -| Security Incidents (credential-related) | 5/quarter | <1/quarter | 80%+ reduction | -| Infrastructure Deployment Time | 2-3 days | 30 minutes | 95%+ reduction | -| Compliance Audit Preparation | 2 weeks | 2 days | 85% reduction | - ---- - -## πŸ“š References - -### External References - -| Reference | URL | Description | -| ------------------------------- | ------------------------------------------------------------------------------ | ------------------------------ | -| Microsoft Dev Box Documentation | https://learn.microsoft.com/azure/dev-box/ | Official Dev Box documentation | -| Azure Landing Zones | https://learn.microsoft.com/azure/cloud-adoption-framework/ready/landing-zone/ | CAF Landing Zone guidance | -| DevExp-DevBox Accelerator | https://evilazaro.github.io/DevExp-DevBox/ | Project documentation site | -| TOGAF Standard | https://www.opengroup.org/togaf | TOGAF architecture framework | - -### Related Architecture Documents - -| Document | Path | Description | -| ------------------------ | ------------------------------------------------------------------ | ----------------------------------- | -| Data Architecture | [02-data-architecture.md](./02-data-architecture.md) | Data entities and information flows | -| Application Architecture | [03-application-architecture.md](./03-application-architecture.md) | Bicep module architecture | -| Technology Architecture | [04-technology-architecture.md](./04-technology-architecture.md) | Azure services and infrastructure | - ---- - -## πŸ“– Glossary - -| Term | Definition | -| ---------------- | -------------------------------------------------------------------------------- | -| **Dev Box** | Microsoft's cloud-powered developer workstation service | -| **DevCenter** | Azure resource that manages Dev Box projects, pools, and catalogs | -| **Landing Zone** | A pre-configured Azure environment with governance, security, and connectivity | -| **Pool** | A collection of Dev Boxes with the same configuration (VM SKU, image, network) | -| **Catalog** | A Git repository containing Dev Box image definitions or environment definitions | -| **RBAC** | Role-Based Access Control - Azure's authorization system | -| **DSC** | Desired State Configuration - declarative configuration management | -| **IaC** | Infrastructure as Code - managing infrastructure through code | -| **azd** | Azure Developer CLI - tool for deploying Azure applications | -| **Bicep** | Domain-specific language for deploying Azure resources | - ---- - -_This document follows TOGAF Architecture Development Method (ADM) principles -and aligns with the Business Architecture domain of the BDAT framework._ - ---- - -
- -**[⬆️ Back to Top](#-business-architecture)** | -**[πŸ“Š Data Architecture β†’](./02-data-architecture.md)** - -
diff --git a/docs/architecture/02-data-architecture.md b/docs/architecture/02-data-architecture.md deleted file mode 100644 index ef841e8b..00000000 --- a/docs/architecture/02-data-architecture.md +++ /dev/null @@ -1,968 +0,0 @@ ---- -title: Data Architecture -description: - TOGAF Data Architecture documentation for DevExp-DevBox covering configuration - data models, secrets management, telemetry, and data governance -author: Platform Engineering Team -date: 2026-01-22 -version: 1.0.0 -tags: - - TOGAF - - Data Architecture - - BDAT - - DevExp-DevBox - - Configuration - - Key Vault ---- - -# πŸ“Š Data Architecture - -> **DevExp-DevBox Landing Zone Accelerator** - -> [!NOTE] -> -> **Target Audience:** Data Architects, Platform Engineers, Security Engineers -> -> **Reading Time:** ~20 minutes - -
-πŸ“ Navigation - -| Previous | Index | Next | -| :------------------------------------------------------- | :----------------------------------: | ----------------------------------------------------------------: | -| [← Business Architecture](./01-business-architecture.md) | [🏠 Architecture Index](./README.md) | [πŸ›οΈ Application Architecture β†’](./03-application-architecture.md) | - -
- -| Metadata | Value | -| ---------------- | ------------------------- | -| **Version** | 1.0.0 | -| **Last Updated** | January 22, 2026 | -| **Author** | Platform Engineering Team | -| **Status** | Active | - ---- - -## πŸ“‘ Table of Contents - -- [πŸ“Š Data Overview](#-data-overview) -- [βš™οΈ Configuration Data Model](#%EF%B8%8F-configuration-data-model) -- [πŸ” Secrets Management](#-secrets-management) -- [πŸ“± Telemetry & Diagnostics](#-telemetry--diagnostics) -- [πŸ”€ Data Flow Diagrams](#-data-flow-diagrams) -- [πŸ›‘οΈ Data Governance](#%EF%B8%8F-data-governance) -- [πŸ“„ Schema Documentation](#-schema-documentation) -- [πŸ“š References](#-references) -- [πŸ“– Glossary](#-glossary) - ---- - -## πŸ“Š Data Overview - -The DevExp-DevBox Landing Zone Accelerator manages several categories of data -that flow through the system during deployment and operation. - -### Data Categories - -| Category | Type | Storage Location | Sensitivity | Lifecycle | -| ---------------------- | ----------------------- | ---------------------------------- | ----------- | ------------------- | -| **Configuration Data** | YAML files | Git repository (`infra/settings/`) | Low | Version controlled | -| **Secrets** | PAT tokens, credentials | Azure Key Vault | High | Managed rotation | -| **Telemetry** | Logs, metrics | Log Analytics Workspace | Medium | 30-90 day retention | -| **State** | Deployment outputs | Azure Resource Manager | Low | Deployment lifetime | -| **Identity Data** | Role assignments | Azure RBAC | Medium | Resource lifetime | - -### Data Entity Overview - -```mermaid ---- -title: Data Entity Relationships ---- -erDiagram - AZURE_RESOURCES ||--o{ RESOURCE_GROUP : contains - RESOURCE_GROUP ||--o{ DEVCENTER : hosts - RESOURCE_GROUP ||--o{ KEY_VAULT : hosts - RESOURCE_GROUP ||--o{ LOG_ANALYTICS : hosts - - DEVCENTER ||--o{ PROJECT : manages - DEVCENTER ||--o{ CATALOG : references - DEVCENTER ||--o{ ENVIRONMENT_TYPE : defines - - PROJECT ||--o{ POOL : contains - PROJECT ||--o{ PROJECT_CATALOG : references - PROJECT ||--o{ PROJECT_ENV_TYPE : enables - - POOL ||--|| IMAGE_DEFINITION : uses - CATALOG ||--o{ IMAGE_DEFINITION : provides - - KEY_VAULT ||--o{ SECRET : stores - CATALOG }|--|| SECRET : authenticates_with - - LOG_ANALYTICS ||--o{ DIAGNOSTIC_SETTING : receives_from - DEVCENTER ||--|| DIAGNOSTIC_SETTING : sends_to - KEY_VAULT ||--|| DIAGNOSTIC_SETTING : sends_to -``` - ---- - -## βš™οΈ Configuration Data Model - -### Configuration File Hierarchy - -``` -infra/settings/ -β”œβ”€β”€ resourceOrganization/ -β”‚ β”œβ”€β”€ azureResources.yaml # Landing zone resource groups -β”‚ └── azureResources.schema.json -β”œβ”€β”€ security/ -β”‚ β”œβ”€β”€ security.yaml # Key Vault configuration -β”‚ └── security.schema.json -└── workload/ - β”œβ”€β”€ devcenter.yaml # DevCenter, projects, pools - └── devcenter.schema.json -``` - -### Resource Organization Configuration (`azureResources.yaml`) - -Defines the landing zone resource group structure following Azure Landing Zone -principles. - -```mermaid ---- -title: Azure Resources Configuration Model ---- -classDiagram - class AzureResources { - +workload: LandingZone - +security: LandingZone - +monitoring: LandingZone - } - - class LandingZone { - +create: boolean - +name: string - +description: string - +tags: Tags - } - - class Tags { - +environment: string - +division: string - +team: string - +project: string - +costCenter: string - +owner: string - +landingZone: string - +resources: string - } - - AzureResources *-- LandingZone : contains 3 - LandingZone *-- Tags : has -``` - -#### Data Model Details - -| Entity | Field | Type | Required | Description | -| --------------- | ------------- | ------- | -------- | -------------------------------------- | -| **LandingZone** | `create` | boolean | Yes | Whether to create the resource group | -| | `name` | string | Yes | Base name for the resource group | -| | `description` | string | Yes | Purpose description | -| | `tags` | object | Yes | Resource tags | -| **Tags** | `environment` | string | Yes | Deployment environment (dev/test/prod) | -| | `division` | string | Yes | Business division | -| | `team` | string | Yes | Owning team | -| | `project` | string | Yes | Project name | -| | `costCenter` | string | Yes | Cost allocation center | -| | `owner` | string | Yes | Resource owner | - -### Security Configuration (`security.yaml`) - -Defines Azure Key Vault settings for secrets management. - -```mermaid ---- -title: Security Configuration Model ---- -classDiagram - class SecurityConfig { - +create: boolean - +keyVault: KeyVaultConfig - } - - class KeyVaultConfig { - +name: string - +description: string - +secretName: string - +enablePurgeProtection: boolean - +enableSoftDelete: boolean - +softDeleteRetentionInDays: integer - +enableRbacAuthorization: boolean - +tags: Tags - } - - SecurityConfig *-- KeyVaultConfig : has - KeyVaultConfig *-- Tags : has -``` - -#### Security Configuration Details - -| Field | Type | Constraints | Default | Description | -| --------------------------- | ------- | ------------------------ | ----------- | ---------------------------------- | -| `name` | string | 3-24 chars, alphanumeric | - | Globally unique Key Vault name | -| `secretName` | string | - | `gha-token` | Name for the stored secret | -| `enablePurgeProtection` | boolean | - | `true` | Prevents permanent deletion | -| `enableSoftDelete` | boolean | - | `true` | Enables recovery window | -| `softDeleteRetentionInDays` | integer | 7-90 | `7` | Retention period for deleted items | -| `enableRbacAuthorization` | boolean | - | `true` | Use Azure RBAC vs access policies | - -### DevCenter Configuration (`devcenter.yaml`) - -The most complex configuration defining the entire workload structure. - -```mermaid ---- -title: DevCenter Configuration Model ---- -classDiagram - class DevCenterConfig { - +name: string - +catalogItemSyncEnableStatus: Status - +microsoftHostedNetworkEnableStatus: Status - +installAzureMonitorAgentEnableStatus: Status - +identity: Identity - +catalogs: Catalog[] - +environmentTypes: EnvironmentType[] - +projects: Project[] - +tags: Tags - } - - class Identity { - +type: string - +roleAssignments: RoleAssignments - } - - class RoleAssignments { - +devCenter: RBACRole[] - +orgRoleTypes: OrgRoleType[] - } - - class Project { - +name: string - +description: string - +network: NetworkConfig - +identity: ProjectIdentity - +pools: Pool[] - +environmentTypes: EnvironmentType[] - +catalogs: ProjectCatalog[] - +tags: Tags - } - - class Pool { - +name: string - +imageDefinitionName: string - +vmSku: string - } - - class Catalog { - +name: string - +type: CatalogType - +visibility: Visibility - +uri: string - +branch: string - +path: string - } - - class NetworkConfig { - +name: string - +create: boolean - +resourceGroupName: string - +virtualNetworkType: string - +addressPrefixes: string[] - +subnets: Subnet[] - +tags: Tags - } - - DevCenterConfig *-- Identity - DevCenterConfig *-- "1..*" Catalog - DevCenterConfig *-- "1..*" Project - Identity *-- RoleAssignments - Project *-- NetworkConfig - Project *-- "1..*" Pool - Project *-- "0..*" Catalog : projectCatalogs -``` - -#### DevCenter Entity Details - -| Entity | Field | Type | Description | -| ------------------- | -------------------------------------- | ---------------- | -------------------------------------------------- | -| **DevCenterConfig** | `name` | string | DevCenter resource name | -| | `catalogItemSyncEnableStatus` | Enabled/Disabled | Auto-sync catalog items | -| | `microsoftHostedNetworkEnableStatus` | Enabled/Disabled | Use Microsoft-hosted networks | -| | `installAzureMonitorAgentEnableStatus` | Enabled/Disabled | Install monitoring agent on Dev Boxes | -| **Project** | `name` | string | Project identifier | -| | `description` | string | Project description | -| | `network` | NetworkConfig | Network connectivity settings | -| | `pools` | Pool[] | Dev Box pool definitions | -| **Pool** | `name` | string | Pool identifier (e.g., `backend-engineer`) | -| | `imageDefinitionName` | string | Reference to catalog image | -| | `vmSku` | string | Azure VM SKU (e.g., `general_i_32c128gb512ssd_v2`) | -| **Catalog** | `type` | gitHub/adoGit | Source control type | -| | `visibility` | public/private | Repository visibility | -| | `uri` | string | Repository URL | -| | `branch` | string | Branch to sync | -| | `path` | string | Path within repository | - ---- - -## πŸ” Secrets Management - -> [!CAUTION] -> -> **Secret Rotation:** PAT tokens should be rotated every 90 days. Federated -> credentials are automatically managed by Azure AD. - -### Secret Types - -| Secret | Storage | Purpose | Consumers | Rotation | -| ------------------------- | ----------------------- | ------------------------------ | ------------------------------- | ----------------------------- | -| **GitHub PAT** | Key Vault (`gha-token`) | Private catalog authentication | DevCenter catalogs | Manual (recommended: 90 days) | -| **Azure DevOps PAT** | Key Vault | ADO catalog authentication | DevCenter catalogs | Manual (recommended: 90 days) | -| **Federated Credentials** | Azure AD | CI/CD authentication | GitHub Actions, Azure Pipelines | Automatic | - -### Secrets Flow Diagram - -```mermaid ---- -title: Secrets Provisioning and Consumption ---- -sequenceDiagram - %% ===== PARTICIPANTS ===== - participant User as Platform Engineer - participant GH as GitHub/ADO - participant CLI as Azure CLI/azd - participant KV as Key Vault - participant DC as DevCenter - participant Cat as Catalog - - %% ===== PROVISIONING FLOW ===== - Note over User,Cat: Secret Provisioning Flow - - User->>GH: Generate PAT token - User->>CLI: azd provision (with secret) - CLI->>KV: Create/Update secret - KV-->>CLI: Secret URI returned - CLI->>DC: Configure DevCenter - DC->>Cat: Create catalog with secret reference - - %% ===== CONSUMPTION FLOW ===== - Note over User,Cat: Secret Consumption Flow - - Cat->>KV: Request secret (via managed identity) - KV->>KV: Validate RBAC permissions - KV-->>Cat: Return secret value - Cat->>GH: Authenticate to repository - GH-->>Cat: Return catalog content -``` - -### Key Vault Access Model - -```mermaid ---- -title: Key Vault RBAC Access Model ---- -flowchart TD - %% ===== STYLE DEFINITIONS ===== - classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF - classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF - classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 - - %% ===== IDENTITY SOURCES ===== - subgraph Identity["Identity Sources"] - DC_MI["DevCenter
Managed Identity"] - PROJ_MI["Project
Managed Identity"] - ADMIN["Platform Engineers
Azure AD Group"] - end - - %% ===== KEY VAULT ===== - subgraph KV["Key Vault"] - SECRET["gha-token
Secret"] - end - - %% ===== RBAC ROLES ===== - subgraph Roles["RBAC Roles"] - R1["Key Vault
Secrets User"] - R2["Key Vault
Secrets Officer"] - end - - %% ===== CONNECTIONS ===== - DC_MI -->|"assigned"| R1 - DC_MI -->|"assigned"| R2 - PROJ_MI -->|"assigned"| R1 - PROJ_MI -->|"assigned"| R2 - ADMIN -->|"assigned"| R2 - - R1 -->|"Get, List"| SECRET - R2 -->|"Get, List, Set, Delete"| SECRET - - %% ===== APPLY STYLES ===== - class DC_MI,PROJ_MI primary - class ADMIN secondary - class SECRET datastore - - %% ===== SUBGRAPH STYLING ===== - style Identity fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px - style KV fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px - style Roles fill:#ECFDF5,stroke:#10B981,stroke-width:2px -``` - -### Secret Security Controls - -| Control | Implementation | Purpose | -| ---------------------- | ------------------------------------ | ------------------------------------------- | -| **RBAC Authorization** | `enableRbacAuthorization: true` | Granular access control via Azure RBAC | -| **Soft Delete** | `enableSoftDelete: true` | Recover accidentally deleted secrets | -| **Purge Protection** | `enablePurgeProtection: true` | Prevent permanent deletion during retention | -| **Retention Period** | `softDeleteRetentionInDays: 7` | Recovery window for deleted secrets | -| **Diagnostic Logging** | Log Analytics integration | Audit all secret operations | -| **Managed Identities** | SystemAssigned on DevCenter/Projects | Eliminate credential storage in code | - ---- - -## πŸ“± Telemetry & Diagnostics - -### Log Analytics Data Collection - -```mermaid ---- -title: Log Analytics Data Collection ---- -flowchart LR - %% ===== STYLE DEFINITIONS ===== - classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF - classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF - classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 - - %% ===== SOURCES ===== - subgraph Sources["Data Sources"] - DC["DevCenter"] - KV["Key Vault"] - VNET["Virtual Network"] - LA_SELF["Log Analytics"] - end - - %% ===== LOG ANALYTICS WORKSPACE ===== - subgraph LA["Log Analytics Workspace"] - LOGS["Logs"] - METRICS["Metrics"] - SOLUTIONS["Solutions"] - end - - %% ===== OUTPUTS ===== - subgraph Outputs["Outputs"] - ALERTS["Alerts"] - DASHBOARDS["Dashboards"] - QUERIES["KQL Queries"] - end - - %% ===== CONNECTIONS ===== - DC -->|"allLogs, AllMetrics"| LOGS - KV -->|"allLogs, AllMetrics"| LOGS - VNET -->|"allLogs, AllMetrics"| LOGS - LA_SELF -->|"allLogs, AllMetrics"| LOGS - - LOGS -->|"triggers"| ALERTS - LOGS -->|"visualizes"| DASHBOARDS - METRICS -->|"visualizes"| DASHBOARDS - LOGS -->|"queries"| QUERIES - - %% ===== APPLY STYLES ===== - class DC,KV,VNET,LA_SELF primary - class LOGS,METRICS,SOLUTIONS datastore - class ALERTS,DASHBOARDS,QUERIES secondary - - %% ===== SUBGRAPH STYLING ===== - style Sources fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px - style LA fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px - style Outputs fill:#ECFDF5,stroke:#10B981,stroke-width:2px -``` - -### Diagnostic Settings Configuration - -All resources deploy with standardized diagnostic settings: - -| Resource | Log Categories | Metric Categories | Destination | -| ------------------- | -------------- | ----------------- | ----------------------- | -| **DevCenter** | allLogs | AllMetrics | Log Analytics Workspace | -| **Key Vault** | allLogs | AllMetrics | Log Analytics Workspace | -| **Virtual Network** | allLogs | AllMetrics | Log Analytics Workspace | -| **Log Analytics** | allLogs | AllMetrics | Self (workspace) | - -### Telemetry Data Model - -```mermaid ---- -title: Telemetry Data Model ---- -erDiagram - LOG_ANALYTICS_WORKSPACE ||--o{ AZURE_DIAGNOSTICS : receives - LOG_ANALYTICS_WORKSPACE ||--o{ AZURE_METRICS : receives - LOG_ANALYTICS_WORKSPACE ||--|| AZURE_ACTIVITY_SOLUTION : has - - AZURE_DIAGNOSTICS { - string TimeGenerated - string ResourceId - string Category - string OperationName - string ResultType - string Properties - } - - AZURE_METRICS { - string TimeGenerated - string ResourceId - string MetricName - float Total - float Average - float Maximum - float Minimum - } -``` - -### Data Retention - -| Data Type | Default Retention | Configurable | Purpose | -| ----------------- | ----------------- | ----------------- | --------------------------- | -| **Logs** | 30 days | Yes (30-730 days) | Operational troubleshooting | -| **Metrics** | 93 days | No | Performance analysis | -| **Activity Logs** | 90 days | No | Audit trail | -| **Security Logs** | 90 days | Yes | Compliance | - ---- - -## πŸ”€ Data Flow Diagrams - -### Configuration Loading Flow - -```mermaid ---- -title: Configuration Loading Flow ---- -flowchart TD - %% ===== STYLE DEFINITIONS ===== - 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 input fill:#F3F4F6,stroke:#6B7280,color:#000000 - - %% ===== GIT REPOSITORY ===== - subgraph Git["Git Repository"] - YAML1["azureResources.yaml"] - YAML2["security.yaml"] - YAML3["devcenter.yaml"] - end - - %% ===== BICEP PROCESSING ===== - subgraph Bicep["Bicep Processing"] - MAIN["main.bicep"] - LOAD1["loadYamlContent()
resourceOrganization"] - LOAD2["loadYamlContent()
security"] - LOAD3["loadYamlContent()
workload"] - end - - %% ===== MODULE DEPLOYMENT ===== - subgraph Modules["Module Deployment"] - MOD1["logAnalytics.bicep"] - MOD2["security.bicep"] - MOD3["workload.bicep"] - end - - %% ===== AZURE RESOURCES ===== - subgraph Azure["Azure Resources"] - RG["Resource Groups"] - LA["Log Analytics"] - KV["Key Vault"] - DC["DevCenter"] - end - - %% ===== CONNECTIONS ===== - YAML1 -->|"loads"| LOAD1 - YAML2 -->|"loads"| LOAD2 - YAML3 -->|"loads"| LOAD3 - - MAIN -->|"invokes"| LOAD1 - MAIN -->|"invokes"| LOAD2 - MAIN -->|"invokes"| LOAD3 - - LOAD1 -->|"passes config"| MOD1 - LOAD1 -->|"passes config"| MOD2 - LOAD1 -->|"passes config"| MOD3 - - LOAD2 -->|"passes config"| MOD2 - LOAD3 -->|"passes config"| MOD3 - - MOD1 -->|"creates"| LA - MOD2 -->|"creates"| KV - MOD3 -->|"creates"| DC - - MAIN -->|"creates"| RG - - %% ===== APPLY STYLES ===== - class YAML1,YAML2,YAML3 input - class MAIN,LOAD1,LOAD2,LOAD3 primary - class MOD1,MOD2,MOD3 secondary - class RG,LA,KV,DC datastore - - %% ===== SUBGRAPH STYLING ===== - style Git fill:#F3F4F6,stroke:#6B7280,stroke-width:2px - style Bicep fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px - style Modules fill:#ECFDF5,stroke:#10B981,stroke-width:2px - style Azure fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px -``` - -### Deployment Data Flow - -```mermaid ---- -title: Deployment Data Flow ---- -flowchart LR - %% ===== STYLE DEFINITIONS ===== - 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 input fill:#F3F4F6,stroke:#6B7280,color:#000000 - - %% ===== INPUT DATA ===== - subgraph Input["Input Data"] - ENV["Environment Name"] - LOC["Location"] - SECRET["Secret Value"] - end - - %% ===== PARAMETER TRANSFORMATION ===== - subgraph Transform["Parameter Transformation"] - SUFFIX["resourceNameSuffix =
{env}-{location}-RG"] - RGNAMES["createResourceGroupName =
{zone.name}-{suffix}"] - end - - %% ===== OUTPUT RESOURCES ===== - subgraph Output["Output Resources"] - SEC_RG["Security RG"] - MON_RG["Monitoring RG"] - WRK_RG["Workload RG"] - end - - %% ===== CONNECTIONS ===== - ENV -->|"concatenates"| SUFFIX - LOC -->|"concatenates"| SUFFIX - SUFFIX -->|"generates"| RGNAMES - RGNAMES -->|"creates"| SEC_RG - RGNAMES -->|"creates"| MON_RG - RGNAMES -->|"creates"| WRK_RG - - %% ===== APPLY STYLES ===== - class ENV,LOC,SECRET input - class SUFFIX,RGNAMES primary - class SEC_RG,MON_RG,WRK_RG datastore - - %% ===== SUBGRAPH STYLING ===== - style Input fill:#F3F4F6,stroke:#6B7280,stroke-width:2px - style Transform fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px - style Output fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px -``` - -### Cross-Module Data Dependencies - -```mermaid ---- -title: Cross-Module Data Dependencies ---- -flowchart TD - %% ===== STYLE DEFINITIONS ===== - 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 input fill:#F3F4F6,stroke:#6B7280,color:#000000 - - %% ===== MAIN BICEP ===== - subgraph main["main.bicep (Subscription Scope)"] - M_IN[/"Parameters:
location, secretValue,
environmentName"/] - end - - %% ===== MONITORING MODULE ===== - subgraph monitoring["monitoring module"] - LA["Log Analytics"] - LA_OUT[/"Output:
AZURE_LOG_ANALYTICS_WORKSPACE_ID"/] - end - - %% ===== SECURITY MODULE ===== - subgraph security["security module"] - KV["Key Vault + Secret"] - SEC_OUT[/"Output:
AZURE_KEY_VAULT_SECRET_IDENTIFIER"/] - end - - %% ===== WORKLOAD MODULE ===== - subgraph workload["workload module"] - DC["DevCenter"] - PROJ["Projects"] - end - - %% ===== CONNECTIONS ===== - M_IN -->|"provides parameters"| LA - LA -->|"outputs"| LA_OUT - - LA_OUT -->|"logAnalyticsId"| KV - M_IN -->|"secretValue"| KV - KV -->|"outputs"| SEC_OUT - - LA_OUT -->|"logAnalyticsId"| DC - SEC_OUT -->|"secretIdentifier"| DC - - DC -->|"configures"| PROJ - - %% ===== APPLY STYLES ===== - class M_IN input - class LA,LA_OUT secondary - class KV,SEC_OUT primary - class DC,PROJ datastore - - %% ===== SUBGRAPH STYLING ===== - style main fill:#F3F4F6,stroke:#6B7280,stroke-width:2px - style monitoring fill:#ECFDF5,stroke:#10B981,stroke-width:2px - style security fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px - style workload fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px -``` - ---- - -## πŸ›‘οΈ Data Governance - -### Data Classification - -| Classification | Examples | Controls | Access | -| ---------------- | ---------------------------- | --------------------- | --------------------- | -| **Public** | Documentation, schemas | Version control | Anyone | -| **Internal** | Configuration YAML, tags | Git repository | Organization | -| **Confidential** | PAT tokens, credentials | Key Vault + RBAC | Authorized identities | -| **Restricted** | Tenant IDs, subscription IDs | Environment variables | CI/CD pipelines | - -### Compliance Considerations - -| Framework | Requirement | Implementation | -| ---------------- | ------------------ | ------------------------------------------ | -| **SOC 2** | Access logging | Key Vault diagnostic logs to Log Analytics | -| **ISO 27001** | Secrets encryption | Key Vault with software-protected keys | -| **GDPR** | Data minimization | No PII in configuration files | -| **Azure Policy** | Tagging compliance | Mandatory tags on all resources | - -### Data Lineage - -```mermaid ---- -title: Data Lineage ---- -flowchart LR - %% ===== STYLE DEFINITIONS ===== - 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 - - %% ===== SOURCE OF TRUTH ===== - subgraph Source["Source of Truth"] - GIT["Git Repository"] - end - - %% ===== CI/CD ===== - subgraph CI["CI/CD"] - GHA["GitHub Actions"] - ADO["Azure DevOps"] - end - - %% ===== DEPLOYMENT ===== - subgraph Deploy["Deployment"] - AZD["azd CLI"] - ARM["ARM/Bicep"] - end - - %% ===== RUNTIME ===== - subgraph Runtime["Runtime"] - AZ["Azure Resources"] - end - - %% ===== AUDIT TRAIL ===== - subgraph Audit["Audit Trail"] - LA["Log Analytics"] - ACT["Activity Log"] - end - - %% ===== CONNECTIONS ===== - GIT -->|"push"| GHA - GIT -->|"push"| ADO - GHA -->|"azd provision"| AZD - ADO -->|"azd provision"| AZD - AZD -->|"deploy"| ARM - ARM -->|"create/update"| AZ - AZ -->|"diagnostics"| LA - AZ -->|"operations"| ACT - - %% ===== APPLY STYLES ===== - class GIT external - class GHA,ADO primary - class AZD,ARM secondary - class AZ datastore - class LA,ACT datastore - - %% ===== SUBGRAPH STYLING ===== - style Source fill:#F3F4F6,stroke:#6B7280,stroke-width:2px - style CI fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px - style Deploy fill:#ECFDF5,stroke:#10B981,stroke-width:2px - style Runtime fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px - style Audit fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px -``` - -### Data Quality Rules - -| Rule | Enforcement | Validation | -| ---------------------- | ----------------------------- | ---------------------------------- | -| **Schema Validation** | JSON Schema files | YAML files must conform to schemas | -| **Required Fields** | Schema `required` arrays | Deployment fails if missing | -| **Value Constraints** | Schema patterns, enums | Invalid values rejected | -| **Naming Conventions** | Bicep `@minLength/@maxLength` | Enforced at deployment | -| **Tag Requirements** | Azure Policy | Post-deployment compliance | - ---- - -## πŸ“„ Schema Documentation - -### JSON Schema Files - -#### `azureResources.schema.json` - -Validates landing zone resource group configuration. - -| Property Path | Type | Constraints | Description | -| ------------------- | ------- | ----------- | -------------------- | -| `workload.create` | boolean | Required | Create workload RG | -| `workload.name` | string | Required | RG base name | -| `workload.tags` | object | Required | Resource tags | -| `security.create` | boolean | Required | Create security RG | -| `security.name` | string | Required | RG base name | -| `monitoring.create` | boolean | Required | Create monitoring RG | -| `monitoring.name` | string | Required | RG base name | - -#### `security.schema.json` - -Validates Key Vault security configuration. - -| Property Path | Type | Constraints | Description | -| ------------------------------------ | ------- | ------------------------------------------- | ---------------- | -| `create` | boolean | Required | Create Key Vault | -| `keyVault.name` | string | 3-24 chars, pattern: `^[a-zA-Z0-9-]{3,24}$` | KV name | -| `keyVault.enablePurgeProtection` | boolean | - | Purge protection | -| `keyVault.softDeleteRetentionInDays` | integer | 7-90 | Retention days | -| `keyVault.tags.environment` | string | enum: dev/test/staging/prod | Environment tag | - -#### `devcenter.schema.json` - -Validates DevCenter workload configuration. - -| Property Path | Type | Constraints | Description | -| -------------------------------------- | ------ | -------------------------------------- | --------------------- | -| `name` | string | minLength: 1 | DevCenter name | -| `identity.type` | string | enum: SystemAssigned/UserAssigned/etc. | Identity type | -| `catalogs[].type` | string | - | Catalog source type | -| `catalogs[].visibility` | string | enum: public/private | Repository visibility | -| `projects[].pools[].vmSku` | string | - | VM SKU for pool | -| `projects[].network.addressPrefixes[]` | string | CIDR pattern | VNet address space | - -### Schema Validation Flow - -```mermaid ---- -title: Schema Validation Flow ---- -flowchart TD - %% ===== STYLE DEFINITIONS ===== - classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF - classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF - classDef failed fill:#F44336,stroke:#C62828,color:#FFFFFF - classDef input fill:#F3F4F6,stroke:#6B7280,color:#000000 - - %% ===== INPUTS ===== - YAML["YAML Configuration File"] - SCHEMA["JSON Schema"] - VALIDATOR["YAML Language Server"] - - %% ===== OUTPUTS ===== - SUCCESS["βœ… Proceed to Deployment"] - ERROR["❌ Validation Errors"] - FIX["Fix Configuration"] - - %% ===== CONNECTIONS ===== - YAML -->|"validates against"| VALIDATOR - SCHEMA -->|"defines rules"| VALIDATOR - - VALIDATOR -->|"valid"| SUCCESS - VALIDATOR -->|"invalid"| ERROR - - ERROR -->|"requires"| FIX - FIX -->|"updates"| YAML - - %% ===== APPLY STYLES ===== - class YAML,SCHEMA input - class VALIDATOR primary - class SUCCESS secondary - class ERROR failed - class FIX primary -``` - ---- - -## πŸ“š References - -### External References - -| Reference | URL | Description | -| ------------------------------ | --------------------------------------------------------------------------- | ----------------- | -| Azure Key Vault Best Practices | https://learn.microsoft.com/azure/key-vault/general/best-practices | Security guidance | -| Log Analytics Documentation | https://learn.microsoft.com/azure/azure-monitor/logs/log-analytics-overview | Monitoring setup | -| JSON Schema Specification | https://json-schema.org/specification | Schema validation | - -### Related Architecture Documents - -| Document | Path | Description | -| ------------------------ | ------------------------------------------------------------------ | --------------------------------- | -| Business Architecture | [01-business-architecture.md](./01-business-architecture.md) | Business context and stakeholders | -| Application Architecture | [03-application-architecture.md](./03-application-architecture.md) | Bicep module architecture | -| Technology Architecture | [04-technology-architecture.md](./04-technology-architecture.md) | Azure services and infrastructure | - ---- - -## πŸ“– Glossary - -| Term | Definition | -| ----------------------- | ------------------------------------------------------------------------------ | -| **loadYamlContent()** | Bicep function that loads YAML files as typed objects at compile time | -| **Diagnostic Settings** | Azure configuration that routes logs and metrics to destinations | -| **RBAC Authorization** | Key Vault access model using Azure role assignments instead of access policies | -| **Soft Delete** | Feature that retains deleted Key Vault objects for recovery | -| **Purge Protection** | Feature that prevents permanent deletion during retention period | -| **PAT** | Personal Access Token for Git repository authentication | -| **Managed Identity** | Azure AD identity automatically managed by Azure for service authentication | -| **KQL** | Kusto Query Language used for Log Analytics queries | - ---- - -_This document follows TOGAF Architecture Development Method (ADM) principles -and aligns with the Data Architecture domain of the BDAT framework._ - ---- - -
- -**[← Business Architecture](./01-business-architecture.md)** | -**[⬆️ Back to Top](#-data-architecture)** | -**[πŸ›οΈ Application Architecture β†’](./03-application-architecture.md)** - -
diff --git a/docs/architecture/03-application-architecture.md b/docs/architecture/03-application-architecture.md deleted file mode 100644 index a8c242ad..00000000 --- a/docs/architecture/03-application-architecture.md +++ /dev/null @@ -1,1183 +0,0 @@ ---- -title: Application Architecture -description: - TOGAF Application Architecture documentation for DevExp-DevBox covering Bicep - module catalog, dependencies, deployment orchestration, and design patterns -author: Platform Engineering Team -date: 2026-01-22 -version: 1.0.0 -tags: - - TOGAF - - Application Architecture - - BDAT - - DevExp-DevBox - - Bicep - - IaC ---- - -# πŸ›οΈ Application Architecture - -> **DevExp-DevBox Landing Zone Accelerator** - -> [!NOTE] -> -> **Target Audience:** Platform Engineers, DevOps Engineers, Cloud Architects -> -> **Reading Time:** ~25 minutes - -
-πŸ“ Navigation - -| Previous | Index | Next | -| :----------------------------------------------- | :----------------------------------: | --------------------------------------------------------------: | -| [← Data Architecture](./02-data-architecture.md) | [🏠 Architecture Index](./README.md) | [πŸ—οΈ Technology Architecture β†’](./04-technology-architecture.md) | - -
- -| Metadata | Value | -| ---------------- | ------------------------- | -| **Version** | 1.0.0 | -| **Last Updated** | January 22, 2026 | -| **Author** | Platform Engineering Team | -| **Status** | Active | - ---- - -## πŸ“‘ Table of Contents - -- [πŸ›οΈ Architecture Overview](#%EF%B8%8F-architecture-overview) -- [πŸ“¦ Module Catalog](#-module-catalog) -- [πŸ”— Module Dependencies](#-module-dependencies) -- [πŸš€ Deployment Orchestration](#-deployment-orchestration) -- [πŸ“ Interface Contracts](#-interface-contracts) -- [🎯 Design Patterns](#-design-patterns) -- [πŸ”Œ Extension Points](#-extension-points) -- [πŸ“š References](#-references) -- [πŸ“– Glossary](#-glossary) - ---- - -## πŸ›οΈ Architecture Overview - -The DevExp-DevBox Landing Zone Accelerator implements a **modular Bicep -architecture** following Azure Landing Zone patterns. The solution is organized -into four distinct landing zones, each with dedicated resource groups and -specialized Bicep modules. - -### Landing Zone Architecture - -```mermaid ---- -title: Landing Zone Architecture ---- -flowchart TB - %% ===== STYLE DEFINITIONS ===== - 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 input fill:#F3F4F6,stroke:#6B7280,color:#000000 - classDef external fill:#6B7280,stroke:#4B5563,color:#FFFFFF,stroke-dasharray:5 5 - - %% ===== SUBSCRIPTION ===== - subgraph Subscription["Azure Subscription"] - %% ===== MAIN ORCHESTRATOR ===== - subgraph Main["main.bicep (Orchestrator)"] - PARAMS[/"Parameters:
location, secretValue,
environmentName"/] - end - - %% ===== SECURITY LANDING ZONE ===== - subgraph Security["Security Landing Zone"] - SEC_RG["Security Resource Group"] - KV["Key Vault"] - SECRET["Secrets"] - end - - %% ===== MONITORING LANDING ZONE ===== - subgraph Monitoring["Monitoring Landing Zone"] - MON_RG["Monitoring Resource Group"] - LA["Log Analytics Workspace"] - SOL["Solutions"] - end - - %% ===== CONNECTIVITY LANDING ZONE ===== - subgraph Connectivity["Connectivity Landing Zone"] - CON_RG["Connectivity Resource Group"] - VNET["Virtual Network"] - SUBNET["Subnets"] - NC["Network Connection"] - end - - %% ===== WORKLOAD LANDING ZONE ===== - subgraph Workload["Workload Landing Zone"] - WRK_RG["Workload Resource Group"] - DC["DevCenter"] - CAT["Catalogs"] - ENV["Environment Types"] - PROJ["Projects"] - POOL["Pools"] - end - end - - %% ===== CONNECTIONS ===== - PARAMS -->|"creates"| SEC_RG - PARAMS -->|"creates"| MON_RG - PARAMS -->|"creates"| WRK_RG - - MON_RG -->|"hosts"| LA - LA -->|"installs"| SOL - - SEC_RG -->|"hosts"| KV - KV -->|"stores"| SECRET - - WRK_RG -->|"hosts"| DC - DC -->|"configures"| CAT - DC -->|"defines"| ENV - DC -->|"manages"| PROJ - PROJ -->|"contains"| POOL - - PROJ -.->|"optional"| CON_RG - CON_RG -->|"hosts"| VNET - VNET -->|"contains"| SUBNET - SUBNET -->|"attaches"| NC - NC -->|"connects to"| DC - - LA -.->|"diagnostics"| KV - LA -.->|"diagnostics"| DC - LA -.->|"diagnostics"| VNET - - SECRET -.->|"authenticates"| CAT - - %% ===== APPLY STYLES ===== - class PARAMS input - class SEC_RG,MON_RG,CON_RG,WRK_RG primary - class LA,KV,DC secondary - class SECRET,CAT,ENV,PROJ,POOL,VNET,SUBNET,NC,SOL datastore - - %% ===== SUBGRAPH STYLING ===== - style Subscription fill:#F3F4F6,stroke:#6B7280,stroke-width:2px - style Main fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px - style Security fill:#FEE2E2,stroke:#F44336,stroke-width:2px - style Monitoring fill:#ECFDF5,stroke:#10B981,stroke-width:2px - style Connectivity fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px - style Workload fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px -``` - -> [!IMPORTANT] -> -> **Key Design Decision:** The accelerator follows a strict modular architecture -> where each Bicep module handles a single resource type, enabling independent -> testing and reusability. - -### Architecture Principles - -| Principle | Description | Implementation | -| ----------------------------- | ----------------------------------------- | ------------------------------------------------- | -| **Modularity** | Each module has a single responsibility | Separate `.bicep` files per resource type | -| **Declarative Configuration** | Infrastructure defined as code | YAML configuration files with JSON schemas | -| **Separation of Concerns** | Landing zones isolate different functions | Resource groups by security, monitoring, workload | -| **Least Privilege** | Minimal permissions per identity | Scoped RBAC role assignments | -| **Configuration as Code** | All settings version controlled | Git repository with YAML files | -| **Idempotency** | Repeated deployments yield same result | Bicep's declarative model | - ---- - -## πŸ“¦ Module Catalog - -### Module Hierarchy - -``` -src/ -β”œβ”€β”€ connectivity/ # Network infrastructure -β”‚ β”œβ”€β”€ connectivity.bicep # Network orchestrator -β”‚ β”œβ”€β”€ networkConnection.bicep # DevCenter network connection -β”‚ β”œβ”€β”€ resourceGroup.bicep # Dynamic RG creation -β”‚ └── vnet.bicep # Virtual network -β”œβ”€β”€ identity/ # RBAC and identity -β”‚ β”œβ”€β”€ devCenterRoleAssignment.bicep -β”‚ β”œβ”€β”€ devCenterRoleAssignmentRG.bicep -β”‚ β”œβ”€β”€ keyVaultAccess.bicep -β”‚ β”œβ”€β”€ orgRoleAssignment.bicep -β”‚ β”œβ”€β”€ projectIdentityRoleAssignment.bicep -β”‚ └── projectIdentityRoleAssignmentRG.bicep -β”œβ”€β”€ management/ # Monitoring resources -β”‚ └── logAnalytics.bicep -β”œβ”€β”€ security/ # Security resources -β”‚ β”œβ”€β”€ keyVault.bicep -β”‚ β”œβ”€β”€ secret.bicep -β”‚ └── security.bicep # Security orchestrator -└── workload/ # DevCenter resources - β”œβ”€β”€ workload.bicep # Workload orchestrator - β”œβ”€β”€ core/ - β”‚ β”œβ”€β”€ catalog.bicep - β”‚ β”œβ”€β”€ devCenter.bicep - β”‚ └── environmentType.bicep - └── project/ - β”œβ”€β”€ project.bicep - β”œβ”€β”€ projectCatalog.bicep - β”œβ”€β”€ projectEnvironmentType.bicep - └── projectPool.bicep -``` - ---- - -### Module: main.bicep - -- **Path**: `infra/main.bicep` -- **Scope**: Subscription -- **Purpose**: Top-level orchestrator that creates resource groups and - coordinates all module deployments - -**Inputs**: - -| Parameter | Type | Required | Description | -| ----------------- | ------------ | -------- | --------------------------------------------- | -| `location` | string | Yes | Azure region (validated against allowed list) | -| `secretValue` | securestring | Yes | GitHub/ADO PAT token | -| `environmentName` | string | Yes | Environment name (2-10 chars) | - -**Outputs**: - -| Output | Type | Description | -| -------------------------------------- | ------ | ---------------------------- | -| `SECURITY_AZURE_RESOURCE_GROUP_NAME` | string | Security RG name | -| `MONITORING_AZURE_RESOURCE_GROUP_NAME` | string | Monitoring RG name | -| `WORKLOAD_AZURE_RESOURCE_GROUP_NAME` | string | Workload RG name | -| `AZURE_LOG_ANALYTICS_WORKSPACE_ID` | string | Log Analytics resource ID | -| `AZURE_LOG_ANALYTICS_WORKSPACE_NAME` | string | Log Analytics workspace name | -| `AZURE_KEY_VAULT_NAME` | string | Key Vault name | -| `AZURE_KEY_VAULT_SECRET_IDENTIFIER` | string | Secret URI | -| `AZURE_KEY_VAULT_ENDPOINT` | string | Key Vault URI | -| `AZURE_DEV_CENTER_NAME` | string | DevCenter name | -| `AZURE_DEV_CENTER_PROJECTS` | array | List of project names | - -**Dependencies**: None (entry point) - -**Dependents**: All other modules - ---- - -### Module: logAnalytics.bicep - -- **Path**: `src/management/logAnalytics.bicep` -- **Scope**: Resource Group (Monitoring) -- **Purpose**: Deploy Log Analytics workspace for centralized monitoring - -**Inputs**: - -| Parameter | Type | Required | Default | Description | -| ---------- | ------ | -------- | ------------------------ | ---------------------- | -| `name` | string | Yes | - | Base name (4-49 chars) | -| `location` | string | No | resourceGroup().location | Azure region | -| `tags` | object | No | {} | Resource tags | -| `sku` | string | No | PerGB2018 | Workspace SKU | - -**Outputs**: - -| Output | Type | Description | -| ------------------------------------ | ------ | --------------------- | -| `AZURE_LOG_ANALYTICS_WORKSPACE_ID` | string | Workspace resource ID | -| `AZURE_LOG_ANALYTICS_WORKSPACE_NAME` | string | Workspace name | - -**Dependencies**: Monitoring resource group - -**Dependents**: `security.bicep`, `workload.bicep`, `vnet.bicep` - -**Resources Created**: - -- `Microsoft.OperationalInsights/workspaces` - Log Analytics workspace -- `Microsoft.OperationsManagement/solutions` - Azure Activity solution -- `Microsoft.Insights/diagnosticSettings` - Self-diagnostics - ---- - -### Module: security.bicep - -- **Path**: `src/security/security.bicep` -- **Scope**: Resource Group (Security) -- **Purpose**: Orchestrate Key Vault and secret deployment - -**Inputs**: - -| Parameter | Type | Required | Description | -| ---------------- | ------------ | -------- | -------------------------- | -| `tags` | object | Yes | Resource tags | -| `secretValue` | securestring | Yes | Secret content | -| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | - -**Outputs**: - -| Output | Type | Description | -| ----------------------------------- | ------ | ------------------ | -| `AZURE_KEY_VAULT_NAME` | string | Key Vault name | -| `AZURE_KEY_VAULT_SECRET_IDENTIFIER` | string | Secret URI | -| `AZURE_KEY_VAULT_ENDPOINT` | string | Key Vault endpoint | - -**Dependencies**: `logAnalytics.bicep` - -**Dependents**: `workload.bicep` - ---- - -### Module: keyVault.bicep - -- **Path**: `src/security/keyVault.bicep` -- **Scope**: Resource Group (Security) -- **Purpose**: Deploy Azure Key Vault with security configuration - -**Inputs**: - -| Parameter | Type | Required | Description | -| ------------------ | ------ | -------- | --------------------------------- | -| `keyvaultSettings` | object | Yes | Key Vault configuration from YAML | -| `location` | string | No | Azure region | -| `tags` | object | Yes | Resource tags | -| `unique` | string | No | Unique suffix for naming | - -**Outputs**: - -| Output | Type | Description | -| -------------------------- | ------ | -------------- | -| `AZURE_KEY_VAULT_NAME` | string | Key Vault name | -| `AZURE_KEY_VAULT_ENDPOINT` | string | Vault URI | - -**Dependencies**: Security resource group - -**Dependents**: `secret.bicep` - -**Resources Created**: - -- `Microsoft.KeyVault/vaults` - Key Vault with RBAC, soft delete, purge - protection - ---- - -### Module: secret.bicep - -- **Path**: `src/security/secret.bicep` -- **Scope**: Resource Group (Security) -- **Purpose**: Create secrets in Key Vault with diagnostic settings - -**Inputs**: - -| Parameter | Type | Required | Description | -| ---------------- | ------------ | -------- | -------------------------- | -| `name` | string | Yes | Secret name | -| `secretValue` | securestring | Yes | Secret content | -| `keyVaultName` | string | Yes | Target Key Vault | -| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | - -**Outputs**: - -| Output | Type | Description | -| ----------------------------------- | ------ | ----------- | -| `AZURE_KEY_VAULT_SECRET_IDENTIFIER` | string | Secret URI | - -**Dependencies**: `keyVault.bicep`, `logAnalytics.bicep` - -**Dependents**: `catalog.bicep`, `projectCatalog.bicep` - ---- - -### Module: workload.bicep - -- **Path**: `src/workload/workload.bicep` -- **Scope**: Resource Group (Workload) -- **Purpose**: Orchestrate DevCenter and project deployments - -**Inputs**: - -| Parameter | Type | Required | Description | -| --------------------------- | ------------ | -------- | -------------------------- | -| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | -| `secretIdentifier` | securestring | Yes | Key Vault secret URI | -| `securityResourceGroupName` | string | Yes | Security RG for RBAC | -| `location` | string | No | Azure region | - -**Outputs**: - -| Output | Type | Description | -| --------------------------- | ------ | --------------------- | -| `AZURE_DEV_CENTER_NAME` | string | DevCenter name | -| `AZURE_DEV_CENTER_PROJECTS` | array | List of project names | - -**Dependencies**: `logAnalytics.bicep`, `security.bicep` - -**Dependents**: None (terminal module) - ---- - -### Module: devCenter.bicep - -- **Path**: `src/workload/core/devCenter.bicep` -- **Scope**: Resource Group (Workload) -- **Purpose**: Deploy DevCenter with identity, catalogs, and environment types - -**Inputs**: - -| Parameter | Type | Required | Description | -| --------------------------- | --------------- | -------- | ---------------------------- | -| `config` | DevCenterConfig | Yes | DevCenter configuration | -| `catalogs` | array | Yes | Catalog definitions | -| `environmentTypes` | array | Yes | Environment type definitions | -| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | -| `secretIdentifier` | securestring | Yes | Secret for private catalogs | -| `securityResourceGroupName` | string | Yes | Security RG name | -| `location` | string | No | Azure region | - -**Outputs**: - -| Output | Type | Description | -| ----------------------- | ------ | -------------- | -| `AZURE_DEV_CENTER_NAME` | string | DevCenter name | - -**Dependencies**: `logAnalytics.bicep`, `secret.bicep` - -**Dependents**: `project.bicep`, `catalog.bicep`, `environmentType.bicep` - -**Resources Created**: - -- `Microsoft.DevCenter/devcenters` - DevCenter resource -- `Microsoft.Insights/diagnosticSettings` - Diagnostic settings -- Role assignments via identity modules -- Catalogs via `catalog.bicep` -- Environment types via `environmentType.bicep` - ---- - -### Module: project.bicep - -- **Path**: `src/workload/project/project.bicep` -- **Scope**: Resource Group (Workload) -- **Purpose**: Deploy DevCenter project with identity, catalogs, pools - -**Inputs**: - -| Parameter | Type | Required | Description | -| --------------------------- | ------------ | -------- | --------------------------- | -| `devCenterName` | string | Yes | Parent DevCenter | -| `name` | string | Yes | Project name | -| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | -| `projectDescription` | string | Yes | Project description | -| `catalogs` | object[] | Yes | Project-specific catalogs | -| `projectEnvironmentTypes` | array | Yes | Enabled environment types | -| `projectPools` | array | Yes | Dev Box pool definitions | -| `projectNetwork` | object | Yes | Network configuration | -| `secretIdentifier` | securestring | Yes | Secret for private catalogs | -| `securityResourceGroupName` | string | Yes | Security RG name | -| `identity` | Identity | Yes | Project identity config | -| `tags` | object | No | Resource tags | -| `location` | string | No | Azure region | - -**Outputs**: - -| Output | Type | Description | -| -------------------- | ------ | ------------ | -| `AZURE_PROJECT_NAME` | string | Project name | - -**Dependencies**: `devCenter.bicep` - -**Dependents**: `projectPool.bicep`, `projectCatalog.bicep`, -`projectEnvironmentType.bicep` - ---- - -### Module: projectPool.bicep - -- **Path**: `src/workload/project/projectPool.bicep` -- **Scope**: Resource Group (Workload) -- **Purpose**: Create Dev Box pools within a project - -**Inputs**: - -| Parameter | Type | Required | Description | -| ----------------------- | --------- | -------- | -------------------------------------------- | -| `name` | string | Yes | Pool name (e.g., `backend-engineer`) | -| `location` | string | No | Azure region | -| `catalogs` | Catalog[] | Yes | Catalog references for images | -| `imageDefinitionName` | string | Yes | Image definition name | -| `networkConnectionName` | string | Yes | Network connection name | -| `vmSku` | string | Yes | VM SKU (e.g., `general_i_32c128gb512ssd_v2`) | -| `networkType` | string | Yes | Managed or Unmanaged | -| `projectName` | string | Yes | Parent project | - -**Outputs**: None - -**Dependencies**: `project.bicep`, `connectivity.bicep`, `projectCatalog.bicep` - -**Dependents**: None (terminal module) - -**Resources Created**: - -- `Microsoft.DevCenter/projects/pools` - Dev Box pool - ---- - -### Module: catalog.bicep - -- **Path**: `src/workload/core/catalog.bicep` -- **Scope**: Resource Group (Workload) -- **Purpose**: Create DevCenter-level catalogs from Git repositories - -**Inputs**: - -| Parameter | Type | Required | Description | -| ------------------ | ------------ | -------- | ------------------------ | -| `devCenterName` | string | Yes | Parent DevCenter | -| `catalogConfig` | Catalog | Yes | Catalog configuration | -| `secretIdentifier` | securestring | Yes | Secret for private repos | - -**Outputs**: - -| Output | Type | Description | -| ------------------------------- | ------ | ---------------------------- | -| `AZURE_DEV_CENTER_CATALOG_NAME` | string | Catalog name | -| `AZURE_DEV_CENTER_CATALOG_ID` | string | Catalog resource ID | -| `AZURE_DEV_CENTER_CATALOG_TYPE` | string | Catalog type (gitHub/adoGit) | - -**Dependencies**: `devCenter.bicep`, `secret.bicep` - -**Dependents**: `projectPool.bicep` - ---- - -### Module: connectivity.bicep - -- **Path**: `src/connectivity/connectivity.bicep` -- **Scope**: Resource Group (Workload/Connectivity) -- **Purpose**: Orchestrate network infrastructure for projects - -**Inputs**: - -| Parameter | Type | Required | Description | -| ---------------- | ------ | -------- | -------------------------- | -| `devCenterName` | string | Yes | DevCenter name | -| `projectNetwork` | object | Yes | Network configuration | -| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | -| `location` | string | Yes | Azure region | - -**Outputs**: - -| Output | Type | Description | -| ----------------------- | ------ | ----------------------- | -| `networkConnectionName` | string | Network connection name | -| `networkType` | string | Managed or Unmanaged | - -**Dependencies**: `devCenter.bicep`, `logAnalytics.bicep` - -**Dependents**: `projectPool.bicep` - ---- - -### Module: vnet.bicep - -- **Path**: `src/connectivity/vnet.bicep` -- **Scope**: Resource Group (Connectivity) -- **Purpose**: Create or reference virtual networks - -**Inputs**: - -| Parameter | Type | Required | Description | -| ---------------- | ------ | -------- | -------------------------------------- | -| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | -| `location` | string | Yes | Azure region | -| `tags` | object | No | Resource tags | -| `settings` | object | Yes | Network settings (name, type, subnets) | - -**Outputs**: - -| Output | Type | Description | -| ----------------------- | ------ | -------------------------------- | -| `AZURE_VIRTUAL_NETWORK` | object | VNet details (name, RG, subnets) | - -**Dependencies**: Connectivity resource group - -**Dependents**: `networkConnection.bicep` - -**Resources Created**: - -- `Microsoft.Network/virtualNetworks` - Virtual network (if create=true) -- `Microsoft.Insights/diagnosticSettings` - VNet diagnostics - ---- - -### Module: networkConnection.bicep - -- **Path**: `src/connectivity/networkConnection.bicep` -- **Scope**: Resource Group (Workload) -- **Purpose**: Create DevCenter network connection to VNet - -**Inputs**: - -| Parameter | Type | Required | Description | -| --------------- | ------ | -------- | ------------------------- | -| `devCenterName` | string | Yes | DevCenter name | -| `name` | string | Yes | Connection name | -| `subnetId` | string | Yes | Target subnet resource ID | - -**Outputs**: - -| Output | Type | Description | -| ----------------------- | ------ | ----------------------- | -| `networkConnectionName` | string | Network connection name | - -**Dependencies**: `vnet.bicep`, `devCenter.bicep` - -**Dependents**: `projectPool.bicep` - ---- - -### Identity Modules - -| Module | Path | Purpose | -| --------------------------------------- | --------------- | -------------------------------------------------------------------- | -| `devCenterRoleAssignment.bicep` | `src/identity/` | Subscription-scope role assignments for DevCenter managed identity | -| `devCenterRoleAssignmentRG.bicep` | `src/identity/` | Resource group-scope role assignments for DevCenter managed identity | -| `projectIdentityRoleAssignment.bicep` | `src/identity/` | Project-scope role assignments for project managed identity | -| `projectIdentityRoleAssignmentRG.bicep` | `src/identity/` | Security RG role assignments for project managed identity | -| `orgRoleAssignment.bicep` | `src/identity/` | Role assignments for organizational AD groups | -| `keyVaultAccess.bicep` | `src/identity/` | Key Vault access configuration | - ---- - -## πŸ”— Module Dependencies - -### Dependency Graph - -```mermaid ---- -title: Module Dependency Graph ---- -flowchart TD - %% ===== STYLE DEFINITIONS ===== - 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 - - %% ===== ENTRY POINT ===== - subgraph Entry["Entry Point"] - MAIN["main.bicep"] - end - - %% ===== MANAGEMENT LAYER ===== - subgraph Management["Management Layer"] - LA["logAnalytics.bicep"] - end - - %% ===== SECURITY LAYER ===== - subgraph Security["Security Layer"] - SEC["security.bicep"] - KV["keyVault.bicep"] - SECRET["secret.bicep"] - end - - %% ===== WORKLOAD LAYER ===== - subgraph Workload["Workload Layer"] - WRK["workload.bicep"] - DC["devCenter.bicep"] - CAT["catalog.bicep"] - ENV["environmentType.bicep"] - PROJ["project.bicep"] - PCAT["projectCatalog.bicep"] - PENV["projectEnvironmentType.bicep"] - POOL["projectPool.bicep"] - end - - %% ===== CONNECTIVITY LAYER ===== - subgraph Connectivity["Connectivity Layer"] - CONN["connectivity.bicep"] - VNET["vnet.bicep"] - NC["networkConnection.bicep"] - RG["resourceGroup.bicep"] - end - - %% ===== IDENTITY LAYER ===== - subgraph Identity["Identity Layer"] - DCRA["devCenterRoleAssignment"] - DCRA_RG["devCenterRoleAssignmentRG"] - PRA["projectIdentityRoleAssignment"] - PRA_RG["projectIdentityRoleAssignmentRG"] - ORA["orgRoleAssignment"] - end - - %% ===== CONNECTIONS ===== - MAIN -->|"deploys"| LA - MAIN -->|"deploys"| SEC - MAIN -->|"deploys"| WRK - - SEC -->|"creates"| KV - SEC -->|"creates"| SECRET - KV -->|"provides to"| SECRET - LA -->|"provides to"| SECRET - - WRK -->|"creates"| DC - WRK -->|"creates"| PROJ - LA -->|"provides to"| DC - SECRET -->|"provides to"| DC - - DC -->|"creates"| CAT - DC -->|"creates"| ENV - DC -->|"assigns"| DCRA - DC -->|"assigns"| DCRA_RG - DC -->|"assigns"| ORA - - PROJ -->|"creates"| PCAT - PROJ -->|"creates"| PENV - PROJ -->|"creates"| POOL - PROJ -->|"creates"| CONN - PROJ -->|"assigns"| PRA - PROJ -->|"assigns"| PRA_RG - - CONN -->|"creates"| RG - CONN -->|"creates"| VNET - CONN -->|"creates"| NC - LA -->|"provides to"| VNET - - NC -->|"connects to"| DC - - %% ===== APPLY STYLES ===== - class MAIN primary - class LA secondary - class SEC,KV,SECRET primary - class WRK,DC,CAT,ENV,PROJ,PCAT,PENV,POOL datastore - class CONN,VNET,NC,RG secondary - class DCRA,DCRA_RG,PRA,PRA_RG,ORA external - - %% ===== SUBGRAPH STYLING ===== - style Entry fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px - style Management fill:#ECFDF5,stroke:#10B981,stroke-width:2px - style Security fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px - style Workload fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px - style Connectivity fill:#ECFDF5,stroke:#10B981,stroke-width:2px - style Identity fill:#F3F4F6,stroke:#6B7280,stroke-width:2px -``` - -### Dependency Matrix - -| Module | Depends On | Provides To | -| -------------------- | ------------------------------------- | ------------------------------------ | -| `main.bicep` | - | All modules | -| `logAnalytics.bicep` | main | security, workload, connectivity | -| `keyVault.bicep` | main | secret | -| `secret.bicep` | keyVault, logAnalytics | devCenter, catalog | -| `security.bicep` | logAnalytics | workload | -| `devCenter.bicep` | logAnalytics, secret | project, catalog, envType | -| `project.bicep` | devCenter | pool, projectCatalog, projectEnvType | -| `connectivity.bicep` | devCenter, logAnalytics | projectPool | -| `projectPool.bicep` | project, connectivity, projectCatalog | - | - ---- - -## πŸš€ Deployment Orchestration - -### Deployment Sequence - -```mermaid ---- -title: Deployment Sequence ---- -sequenceDiagram - %% ===== PARTICIPANTS ===== - participant User as Platform Engineer - participant AZD as Azure Developer CLI - participant ARM as Azure Resource Manager - participant RG as Resource Groups - participant MON as Monitoring Module - participant SEC as Security Module - participant WRK as Workload Module - - %% ===== INITIATE DEPLOYMENT ===== - User->>AZD: azd provision - AZD->>ARM: Deploy main.bicep - - %% ===== PARALLEL RESOURCE GROUP CREATION ===== - par Create Resource Groups - ARM->>RG: Create Security RG - ARM->>RG: Create Monitoring RG - ARM->>RG: Create Workload RG - end - - %% ===== SEQUENTIAL MODULE DEPLOYMENT ===== - ARM->>MON: Deploy logAnalytics.bicep - MON-->>ARM: AZURE_LOG_ANALYTICS_WORKSPACE_ID - - ARM->>SEC: Deploy security.bicep - Note over SEC: Uses logAnalyticsId - SEC-->>ARM: AZURE_KEY_VAULT_SECRET_IDENTIFIER - - ARM->>WRK: Deploy workload.bicep - Note over WRK: Uses logAnalyticsId, secretIdentifier - - %% ===== NESTED WORKLOAD DEPLOYMENT ===== - WRK->>WRK: Deploy devCenter.bicep - WRK->>WRK: Deploy project.bicep (loop) - - %% ===== RETURN OUTPUTS ===== - WRK-->>ARM: AZURE_DEV_CENTER_NAME, AZURE_DEV_CENTER_PROJECTS - ARM-->>AZD: Deployment outputs - AZD-->>User: Deployment complete -``` - -### Deployment Scopes - -| Scope | Modules | Purpose | -| ------------------- | ------------------------------------------------------- | ----------------------------------- | -| **Subscription** | `main.bicep`, `devCenterRoleAssignment.bicep` | Create RGs, subscription-level RBAC | -| **Security RG** | `keyVault.bicep`, `secret.bicep` | Security resources | -| **Monitoring RG** | `logAnalytics.bicep` | Monitoring resources | -| **Workload RG** | `devCenter.bicep`, `project.bicep`, `projectPool.bicep` | DevCenter resources | -| **Connectivity RG** | `vnet.bicep`, `networkConnection.bicep` | Network resources (conditional) | - -### Deployment Commands - -```bash -# Initialize environment -azd init - -# Provision infrastructure -azd provision --no-prompt - -# Full deployment with environment -azd provision -e dev --no-prompt -``` - ---- - -## πŸ“ Interface Contracts - -### Module Parameter Types - -```bicep -// DevCenter configuration type -type DevCenterConfig = { - name: string - identity: Identity - catalogItemSyncEnableStatus: Status - microsoftHostedNetworkEnableStatus: Status - installAzureMonitorAgentEnableStatus: Status - tags: object -} - -// Identity configuration type -type Identity = { - type: string - roleAssignments: RoleAssignment -} - -// Role assignment configuration -type RoleAssignment = { - devCenter: AzureRBACRole[] - orgRoleTypes: OrgRoleType[] -} - -// Azure RBAC role definition -type AzureRBACRole = { - id: string - name: string - scope: string -} - -// Catalog type definition -type Catalog = { - name: string - type: CatalogType // 'gitHub' | 'adoGit' - visibility: 'public' | 'private' - uri: string - branch: string - path: string -} - -// Network settings type -type NetworkSettings = { - name: string - virtualNetworkType: 'Unmanaged' | 'Managed' - create: bool - resourceGroupName: string - addressPrefixes: string[] - subnets: object[] - tags: object -} -``` - -### Output Contract Summary - -| Module | Key Output | Type | Consumer | -| -------------- | ----------------------------------- | ------ | -------------------------------- | -| `logAnalytics` | `AZURE_LOG_ANALYTICS_WORKSPACE_ID` | string | security, workload, connectivity | -| `security` | `AZURE_KEY_VAULT_SECRET_IDENTIFIER` | string | workload (catalogs) | -| `devCenter` | `AZURE_DEV_CENTER_NAME` | string | projects, network connections | -| `connectivity` | `networkConnectionName` | string | projectPool | -| `vnet` | `AZURE_VIRTUAL_NETWORK` | object | networkConnection | - ---- - -## 🎯 Design Patterns - -### Patterns Implemented - -| Pattern | Description | Implementation | -| ----------------------------- | ------------------------------------- | ----------------------------------------------- | -| **Modular Design** | Single responsibility per module | Each `.bicep` file handles one resource type | -| **Declarative Configuration** | Configuration separate from logic | YAML files in `infra/settings/` | -| **Factory Pattern** | Loop-based resource creation | `for` loops for projects, pools, catalogs | -| **Dependency Injection** | Parameters passed between modules | Output-to-input parameter chaining | -| **Conditional Deployment** | Resources created based on conditions | `if` statements for optional resources | -| **Orchestrator Pattern** | Parent modules coordinate children | `workload.bicep` orchestrates DevCenter modules | - -### Conditional Deployment Examples - -```bicep -// Create VNet only if needed (Unmanaged network type) -resource virtualNetwork '...' = if (settings.create && settings.virtualNetworkType == 'Unmanaged') { - // ... -} - -// Deploy Key Vault or reference existing -module keyVault '...' = if (securitySettings.create) { - // ... -} - -// Create pool only for imageDefinition catalogs -resource pool '...' = [ - for (catalog, i) in catalogs: if (catalog.type == 'imageDefinition') { - // ... - } -] -``` - -### Factory Pattern for Multiple Resources - -```bicep -// Deploy multiple projects from configuration -module projects 'project/project.bicep' = [ - for (project, i) in devCenterSettings.projects: { - scope: resourceGroup() - params: { - name: project.name - // ... other parameters from project config - } - } -] - -// Output all project names -output AZURE_DEV_CENTER_PROJECTS array = [ - for (project, i) in devCenterSettings.projects: projects[i].outputs.AZURE_PROJECT_NAME -] -``` - ---- - -## πŸ”Œ Extension Points - -### Adding a New Project - -1. **Update Configuration** (`infra/settings/workload/devcenter.yaml`): - -```yaml -projects: - - name: 'new-project' - description: 'New project description' - network: - name: new-project - create: true - # ... network config - identity: - type: SystemAssigned - roleAssignments: - - azureADGroupId: '' - azureADGroupName: 'New Project Developers' - azureRBACRoles: - - name: 'Dev Box User' - id: '45d50f46-0b78-4001-a660-4198cbe8cd05' - scope: Project - pools: - - name: 'developer' - imageDefinitionName: 'new-project-developer' - vmSku: general_i_16c64gb256ssd_v2 - # ... rest of config -``` - -2. **Redeploy**: `azd provision` - -### Adding a New Pool - -1. **Update Project Configuration**: - -```yaml -pools: - - name: 'new-pool' - imageDefinitionName: 'custom-image' - vmSku: general_i_32c128gb512ssd_v2 -``` - -2. **Ensure Catalog Contains Image Definition** - -3. **Redeploy**: `azd provision` - -### Adding a New Catalog - -1. **DevCenter-Level Catalog** (in `devcenter.yaml`): - -```yaml -catalogs: - - name: 'new-catalog' - type: gitHub - visibility: private - uri: 'https://github.com/org/repo.git' - branch: 'main' - path: './definitions' -``` - -2. **Project-Level Catalog** (in project section): - -```yaml -projects: - - name: 'project' - catalogs: - - name: 'project-catalog' - type: imageDefinition - sourceControl: gitHub - visibility: private - uri: 'https://github.com/org/project-repo.git' - branch: 'main' - path: '/.devcenter/imageDefinitions' -``` - -### Adding a New Landing Zone - -1. **Create New Module** (`src/newzone/newzone.bicep`) - -2. **Update Resource Organization** - (`infra/settings/resourceOrganization/azureResources.yaml`): - -```yaml -newzone: - create: true - name: devexp-newzone - tags: - landingZone: NewZone - # ... other tags -``` - -3. **Update `main.bicep`**: - -```bicep -resource newzoneRg 'Microsoft.Resources/resourceGroups@...' = if (landingZones.newzone.create) { - name: createResourceGroupName.newzone - location: location - tags: landingZones.newzone.tags -} - -module newzone '../src/newzone/newzone.bicep' = { - scope: resourceGroup(newzoneRgName) - params: { - // ... - } -} -``` - -### Extension Architecture - -```mermaid ---- -title: Extension Architecture ---- -flowchart TD - %% ===== STYLE DEFINITIONS ===== - 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 input fill:#F3F4F6,stroke:#6B7280,color:#000000 - - %% ===== CONFIGURATION LAYER ===== - subgraph Config["Configuration Layer"] - YAML["YAML Files"] - SCHEMA["JSON Schemas"] - end - - %% ===== EXTENSION POINTS ===== - subgraph Extension["Extension Points"] - NEW_PROJ["New Project"] - NEW_POOL["New Pool"] - NEW_CAT["New Catalog"] - NEW_LZ["New Landing Zone"] - end - - %% ===== MODULE LAYER ===== - subgraph Modules["Module Layer"] - EXISTING["Existing Modules"] - NEW_MOD["New Modules"] - end - - %% ===== CONNECTIONS ===== - YAML -->|"configures"| Extension - SCHEMA -->|"validates"| YAML - - NEW_PROJ -->|"uses"| EXISTING - NEW_POOL -->|"uses"| EXISTING - NEW_CAT -->|"uses"| EXISTING - NEW_LZ -->|"requires"| NEW_MOD - - NEW_MOD -->|"follow patterns of"| EXISTING - - %% ===== APPLY STYLES ===== - class YAML,SCHEMA input - class NEW_PROJ,NEW_POOL,NEW_CAT,NEW_LZ primary - class EXISTING secondary - class NEW_MOD datastore - - %% ===== SUBGRAPH STYLING ===== - style Config fill:#F3F4F6,stroke:#6B7280,stroke-width:2px - style Extension fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px - style Modules fill:#ECFDF5,stroke:#10B981,stroke-width:2px -``` - ---- - -## πŸ“š References - -### External References - -| Reference | URL | Description | -| ----------------------- | ------------------------------------------------------------------------------ | ------------------------ | -| Bicep Documentation | https://learn.microsoft.com/azure/azure-resource-manager/bicep/ | Bicep language reference | -| Azure Landing Zones | https://learn.microsoft.com/azure/cloud-adoption-framework/ready/landing-zone/ | CAF guidance | -| DevCenter API Reference | https://learn.microsoft.com/azure/templates/microsoft.devcenter/ | Bicep resource reference | - -### Related Architecture Documents - -| Document | Path | Description | -| ----------------------- | ---------------------------------------------------------------- | --------------------- | -| Business Architecture | [01-business-architecture.md](./01-business-architecture.md) | Business context | -| Data Architecture | [02-data-architecture.md](./02-data-architecture.md) | Data models and flows | -| Technology Architecture | [04-technology-architecture.md](./04-technology-architecture.md) | Azure services | - ---- - -## πŸ“– Glossary - -| Term | Definition | -| --------------------- | ------------------------------------------------------------------------- | -| **Bicep** | Domain-specific language for Azure resource deployment | -| **Module** | Reusable Bicep file that can be called from other templates | -| **Scope** | Deployment level (tenant, management group, subscription, resource group) | -| **Orchestrator** | Module that coordinates deployment of multiple child modules | -| **Factory Pattern** | Design pattern using loops to create multiple similar resources | -| **loadYamlContent()** | Bicep function to load YAML as typed configuration | -| **targetScope** | Bicep declaration specifying deployment scope | -| **dependsOn** | Explicit dependency declaration between resources/modules | - ---- - -_This document follows TOGAF Architecture Development Method (ADM) principles -and aligns with the Application Architecture domain of the BDAT framework._ - ---- - -
- -**[← Data Architecture](./02-data-architecture.md)** | -**[⬆️ Back to Top](#%EF%B8%8F-application-architecture)** | -**[πŸ—οΈ Technology Architecture β†’](./04-technology-architecture.md)** - -
diff --git a/docs/architecture/04-technology-architecture.md b/docs/architecture/04-technology-architecture.md deleted file mode 100644 index 8fc2864c..00000000 --- a/docs/architecture/04-technology-architecture.md +++ /dev/null @@ -1,1320 +0,0 @@ ---- -title: Technology Architecture -description: - TOGAF Technology Architecture documentation for DevExp-DevBox covering Azure - services, networking, identity, security, monitoring, and CI/CD infrastructure -author: Platform Engineering Team -date: 2026-01-22 -version: 1.0.0 -tags: - - TOGAF - - Technology Architecture - - BDAT - - DevExp-DevBox - - Azure - - DevCenter - - CI/CD ---- - -# πŸ—οΈ Technology Architecture - -> **DevExp-DevBox Landing Zone Accelerator** - -> [!NOTE] -> -> **Target Audience:** Cloud Architects, DevOps Engineers, IT Operations -> -> **Reading Time:** ~25 minutes - -
-πŸ“ Navigation - -| Previous | Index | Next | -| :------------------------------------------------------------- | :----------------------------------: | ---: | -| [← Application Architecture](./03-application-architecture.md) | [🏠 Architecture Index](./README.md) | - | - -
- -| Metadata | Value | -| ---------------- | ------------------------- | -| **Version** | 1.0.0 | -| **Last Updated** | January 22, 2026 | -| **Author** | Platform Engineering Team | -| **Status** | Active | - ---- - -## πŸ“‘ Table of Contents - -- [πŸ—οΈ Infrastructure Overview](#%EF%B8%8F-infrastructure-overview) -- [πŸ›οΈ Landing Zone Design](#%EF%B8%8F-landing-zone-design) -- [🌐 Network Architecture](#-network-architecture) -- [πŸ‘€ Identity & Access](#-identity--access) -- [πŸ”’ Security Architecture](#-security-architecture) -- [πŸ“Š Monitoring & Observability](#-monitoring--observability) -- [βš™οΈ CI/CD Infrastructure](#%EF%B8%8F-cicd-infrastructure) -- [πŸ› οΈ Deployment Tools](#%EF%B8%8F-deployment-tools) -- [πŸ’» DevOps Practices](#-devops-practices) -- [πŸ“š References](#-references) -- [πŸ“– Glossary](#-glossary) - ---- - -## πŸ—οΈ Infrastructure Overview - -The DevExp-DevBox Landing Zone Accelerator deploys a comprehensive set of Azure -services organized into functional landing zones. - -### Azure Services Deployed - -```mermaid ---- -title: Azure Services Overview ---- -flowchart TB - %% ===== STYLE DEFINITIONS ===== - 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 - - %% ===== AZURE CLOUD ===== - subgraph Azure["Azure Cloud"] - %% ===== MANAGEMENT PLANE ===== - subgraph Management["Management Plane"] - ARM["Azure Resource Manager"] - AAD["Microsoft Entra ID"] - RBAC["Azure RBAC"] - end - - %% ===== COMPUTE SERVICES ===== - subgraph Compute["Compute Services"] - DC["Microsoft DevCenter"] - DEVBOX["Dev Box VMs"] - end - - %% ===== SECURITY SERVICES ===== - subgraph Security["Security Services"] - KV["Azure Key Vault"] - end - - %% ===== NETWORKING SERVICES ===== - subgraph Networking["Networking Services"] - VNET["Virtual Network"] - SUBNET["Subnets"] - NSG["Network Security Groups"] - end - - %% ===== MONITORING SERVICES ===== - subgraph Monitoring["Monitoring Services"] - LA["Log Analytics Workspace"] - DIAG["Diagnostic Settings"] - SOL["Solutions"] - end - - %% ===== STORAGE SERVICES ===== - subgraph Storage["Storage Services"] - BLOB["Blob Storage
Dev Box Images"] - end - end - - %% ===== CONNECTIONS ===== - ARM -->|"deploys"| DC - ARM -->|"deploys"| KV - ARM -->|"deploys"| VNET - ARM -->|"deploys"| LA - - AAD -->|"authenticates"| RBAC - RBAC -->|"authorizes"| DC - RBAC -->|"authorizes"| KV - - DC -->|"provisions"| DEVBOX - DEVBOX -->|"connects to"| VNET - VNET -->|"contains"| SUBNET - SUBNET -->|"secured by"| NSG - - DC -->|"sends logs"| DIAG - KV -->|"sends logs"| DIAG - VNET -->|"sends logs"| DIAG - DIAG -->|"routes to"| LA - LA -->|"analyzes"| SOL - - %% ===== APPLY STYLES ===== - class ARM,AAD,RBAC external - class DC,DEVBOX primary - class KV primary - class VNET,SUBNET,NSG secondary - class LA,DIAG,SOL datastore - class BLOB datastore - - %% ===== SUBGRAPH STYLING ===== - style Azure fill:#F3F4F6,stroke:#6B7280,stroke-width:2px - style Management fill:#F3F4F6,stroke:#6B7280,stroke-width:2px - style Compute fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px - style Security fill:#FEE2E2,stroke:#F44336,stroke-width:2px - style Networking fill:#ECFDF5,stroke:#10B981,stroke-width:2px - style Monitoring fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px - style Storage fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px -``` - -### Service Catalog - -| Service | Azure Resource Type | Purpose | API Version | -| ----------------------- | ------------------------------------------ | ------------------------------ | ------------------ | -| **DevCenter** | `Microsoft.DevCenter/devcenters` | Central management for Dev Box | 2025-10-01-preview | -| **Projects** | `Microsoft.DevCenter/projects` | Team/workstream isolation | 2025-10-01-preview | -| **Pools** | `Microsoft.DevCenter/projects/pools` | Dev Box VM configurations | 2025-10-01-preview | -| **Catalogs** | `Microsoft.DevCenter/devcenters/catalogs` | Image/environment definitions | 2025-10-01-preview | -| **Key Vault** | `Microsoft.KeyVault/vaults` | Secrets management | 2025-05-01 | -| **Secrets** | `Microsoft.KeyVault/vaults/secrets` | Store PAT tokens | 2025-05-01 | -| **Log Analytics** | `Microsoft.OperationalInsights/workspaces` | Centralized logging | 2025-07-01 | -| **Solutions** | `Microsoft.OperationsManagement/solutions` | Log analysis capabilities | 2015-11-01-preview | -| **Virtual Network** | `Microsoft.Network/virtualNetworks` | Network connectivity | 2025-01-01 | -| **Resource Groups** | `Microsoft.Resources/resourceGroups` | Resource organization | 2025-04-01 | -| **Role Assignments** | `Microsoft.Authorization/roleAssignments` | RBAC permissions | 2022-04-01 | -| **Diagnostic Settings** | `Microsoft.Insights/diagnosticSettings` | Telemetry routing | 2021-05-01-preview | - -### Supported Azure Regions - -The accelerator supports deployment to the following regions: - -| Region | Location Code | Availability | -| -------------------- | -------------------- | ------------ | -| East US | `eastus` | βœ… Supported | -| East US 2 | `eastus2` | βœ… Supported | -| West US | `westus` | βœ… Supported | -| West US 2 | `westus2` | βœ… Supported | -| West US 3 | `westus3` | βœ… Supported | -| Central US | `centralus` | βœ… Supported | -| North Europe | `northeurope` | βœ… Supported | -| West Europe | `westeurope` | βœ… Supported | -| Southeast Asia | `southeastasia` | βœ… Supported | -| Australia East | `australiaeast` | βœ… Supported | -| Japan East | `japaneast` | βœ… Supported | -| UK South | `uksouth` | βœ… Supported | -| Canada Central | `canadacentral` | βœ… Supported | -| Sweden Central | `swedencentral` | βœ… Supported | -| Switzerland North | `switzerlandnorth` | βœ… Supported | -| Germany West Central | `germanywestcentral` | βœ… Supported | - ---- - -## πŸ›οΈ Landing Zone Design - -### Four-Zone Architecture - -```mermaid ---- -title: Four-Zone Landing Zone Architecture ---- -flowchart TB - %% ===== STYLE DEFINITIONS ===== - classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF - classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF - classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 - - %% ===== SUBSCRIPTION ===== - subgraph Subscription["Azure Subscription"] - %% ===== SECURITY ZONE ===== - subgraph SecurityZone["πŸ” Security Landing Zone"] - SEC_RG["devexp-security-{env}-{region}-RG"] - KV["Key Vault
contoso-{unique}-kv"] - SECRET["Secret: gha-token"] - end - - %% ===== MONITORING ZONE ===== - subgraph MonitoringZone["πŸ“Š Monitoring Landing Zone"] - MON_RG["devexp-monitoring-{env}-{region}-RG"] - LA["Log Analytics
logAnalytics-{unique}"] - SOL["Azure Activity Solution"] - end - - %% ===== CONNECTIVITY ZONE ===== - subgraph ConnectivityZone["🌐 Connectivity Landing Zone"] - CON_RG["eShop-connectivity-RG"] - VNET["Virtual Network
eShop"] - SUBNET["Subnet
eShop-subnet"] - NC["Network Connection
netconn-eShop"] - end - - %% ===== WORKLOAD ZONE ===== - subgraph WorkloadZone["πŸ’» Workload Landing Zone"] - WRK_RG["devexp-workload-{env}-{region}-RG"] - DC["DevCenter
devexp-devcenter"] - PROJ["Project: eShop"] - POOL1["Pool: backend-engineer"] - POOL2["Pool: frontend-engineer"] - end - end - - %% ===== CONNECTIONS ===== - SEC_RG -->|"hosts"| KV - KV -->|"stores"| SECRET - - MON_RG -->|"hosts"| LA - LA -->|"installs"| SOL - - CON_RG -->|"hosts"| VNET - VNET -->|"contains"| SUBNET - SUBNET -->|"attaches to"| NC - - WRK_RG -->|"hosts"| DC - DC -->|"manages"| PROJ - PROJ -->|"contains"| POOL1 - PROJ -->|"contains"| POOL2 - - NC -.->|"attaches to"| DC - SECRET -.->|"authenticates"| DC - LA -.->|"diagnostics"| KV - LA -.->|"diagnostics"| DC - LA -.->|"diagnostics"| VNET - - %% ===== APPLY STYLES ===== - class SEC_RG,MON_RG,CON_RG,WRK_RG primary - class KV,LA secondary - class SECRET,SOL,VNET,SUBNET,NC,DC,PROJ,POOL1,POOL2 datastore - - %% ===== SUBGRAPH STYLING ===== - style Subscription fill:#F3F4F6,stroke:#6B7280,stroke-width:2px - style SecurityZone fill:#FEE2E2,stroke:#F44336,stroke-width:2px - style MonitoringZone fill:#ECFDF5,stroke:#10B981,stroke-width:2px - style ConnectivityZone fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px - style WorkloadZone fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px -``` - -### Resource Group Naming Convention - -| Landing Zone | Pattern | Example | -| ------------ | --------------------------- | ----------------------------------- | -| Security | `{name}-{env}-{region}-RG` | `devexp-security-demo-eastus2-RG` | -| Monitoring | `{name}-{env}-{region}-RG` | `devexp-monitoring-demo-eastus2-RG` | -| Workload | `{name}-{env}-{region}-RG` | `devexp-workload-demo-eastus2-RG` | -| Connectivity | `{project}-connectivity-RG` | `eShop-connectivity-RG` | - -### Resource Naming Patterns - -| Resource Type | Pattern | Example | -| ------------------ | --------------------- | ------------------------- | -| Key Vault | `{name}-{unique}-kv` | `contoso-abc123xyz-kv` | -| Log Analytics | `{name}-{unique}` | `logAnalytics-abc123xyz` | -| DevCenter | `{name}` | `devexp-devcenter` | -| Project | `{name}` | `eShop` | -| Pool | `{name}-{index}-pool` | `backend-engineer-0-pool` | -| VNet | `{project}` | `eShop` | -| Network Connection | `netconn-{vnet}` | `netconn-eShop` | - -### Tagging Strategy - -All resources are tagged with consistent metadata: - -| Tag | Purpose | Example Values | -| ------------- | ------------------- | ---------------------------------- | -| `environment` | Deployment stage | dev, test, staging, prod | -| `division` | Business unit | Platforms | -| `team` | Owning team | DevExP | -| `project` | Project name | Contoso-DevExp-DevBox | -| `costCenter` | Cost allocation | IT | -| `owner` | Resource owner | Contoso | -| `landingZone` | Zone classification | Security, Monitoring, Workload | -| `resources` | Resource type | ResourceGroup, DevCenter, KeyVault | - ---- - -## 🌐 Network Architecture - -### Network Topology - -```mermaid ---- -title: Network Topology ---- -flowchart TB - %% ===== STYLE DEFINITIONS ===== - 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 - - %% ===== INTERNET ===== - subgraph Internet["Internet"] - DEV["Developer"] - end - - %% ===== AZURE ===== - subgraph Azure["Azure"] - %% ===== DEVCENTER ===== - subgraph DevCenter["DevCenter"] - DC_CTRL["Control Plane"] - end - - %% ===== MANAGED NETWORK ===== - subgraph ManagedNet["Microsoft-Hosted Network"] - MN["Managed Network
Microsoft-provided"] - end - - %% ===== CUSTOMER NETWORK ===== - subgraph CustomerNet["Customer-Managed Network"] - subgraph VNet["eShop VNet (10.0.0.0/16)"] - SUBNET1["eShop-subnet
10.0.1.0/24"] - end - - NC["Network Connection"] - end - - %% ===== DEV BOXES ===== - subgraph DevBoxes["Dev Box VMs"] - DB1["Backend Dev Box"] - DB2["Frontend Dev Box"] - end - end - - %% ===== CONNECTIONS ===== - DEV -->|"RDP/HTTPS"| DC_CTRL - DC_CTRL -->|"manages"| MN - DC_CTRL -->|"connects via"| NC - - NC -->|"attaches to"| SUBNET1 - - MN -->|"provides network"| DB1 - MN -->|"provides network"| DB2 - SUBNET1 -->|"provides network"| DB1 - SUBNET1 -->|"provides network"| DB2 - - %% ===== APPLY STYLES ===== - class DEV external - class DC_CTRL,NC primary - class MN,SUBNET1 secondary - class DB1,DB2 datastore - - %% ===== SUBGRAPH STYLING ===== - style Internet fill:#F3F4F6,stroke:#6B7280,stroke-width:2px - style Azure fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px - style DevCenter fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px - style ManagedNet fill:#ECFDF5,stroke:#10B981,stroke-width:2px - style CustomerNet fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px - style VNet fill:#D1FAE5,stroke:#059669,stroke-width:1px - style DevBoxes fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px -``` - -### Network Options - -| Network Type | Description | Use Case | -| ------------- | --------------------------------------------------- | ----------------------------------------------- | -| **Managed** | Microsoft-hosted network, no customer VNet required | Simplified setup, no hybrid connectivity needed | -| **Unmanaged** | Customer-provided VNet with Network Connection | Hybrid connectivity, corporate network access | - -### Network Configuration (Unmanaged) - -From `devcenter.yaml`: - -```yaml -network: - name: eShop - create: true - resourceGroupName: 'eShop-connectivity-RG' - virtualNetworkType: Unmanaged - addressPrefixes: - - 10.0.0.0/16 - subnets: - - name: eShop-subnet - properties: - addressPrefix: 10.0.1.0/24 -``` - -### Network Connection Flow - -```mermaid ---- -title: Network Connection Flow ---- -sequenceDiagram - %% ===== PARTICIPANTS ===== - participant DC as DevCenter - participant NC as Network Connection - participant VNet as Virtual Network - participant Subnet as Subnet - participant DB as Dev Box - - %% ===== CONNECTION SETUP ===== - DC->>NC: Create Network Connection - NC->>VNet: Reference VNet - VNet->>Subnet: Validate Subnet - NC-->>DC: Connection Ready - - %% ===== DEV BOX PROVISIONING ===== - DC->>DB: Provision Dev Box - DB->>NC: Request Network Config - NC->>Subnet: Allocate IP - Subnet-->>DB: IP Assigned - DB-->>DC: Dev Box Ready -``` - -### Network Security - -| Control | Implementation | Purpose | -| --------------------------- | ------------------------------ | -------------------------------- | -| **Subnet Delegation** | DevCenter network connection | Controlled Dev Box placement | -| **NSG Rules** | Applied to subnets | Traffic filtering | -| **Private Endpoints** | Optional for Key Vault | Secure secret access | -| **Managed Network Regions** | `managedVirtualNetworkRegions` | Region-specific managed networks | - ---- - -## πŸ‘€ Identity & Access - -### Identity Model - -```mermaid ---- -title: Identity Model ---- -flowchart TB - %% ===== STYLE DEFINITIONS ===== - 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 - - %% ===== IDENTITIES ===== - subgraph Identities["Identity Types"] - SI_DC["DevCenter
System-Assigned MI"] - SI_PROJ["Project
System-Assigned MI"] - ADG["Azure AD Groups"] - end - - %% ===== ROLES ===== - subgraph Roles["RBAC Roles"] - R1["Contributor"] - R2["User Access Administrator"] - R3["Key Vault Secrets User"] - R4["Key Vault Secrets Officer"] - R5["DevCenter Project Admin"] - R6["Dev Box User"] - R7["Deployment Environment User"] - end - - %% ===== SCOPES ===== - subgraph Scopes["Assignment Scopes"] - SUB["Subscription"] - RG_SEC["Security RG"] - RG_WRK["Workload RG"] - DC["DevCenter"] - PROJ["Project"] - end - - %% ===== CONNECTIONS ===== - SI_DC -->|"assigned"| R1 - SI_DC -->|"assigned"| R2 - SI_DC -->|"assigned"| R3 - SI_DC -->|"assigned"| R4 - - SI_PROJ -->|"assigned"| R3 - SI_PROJ -->|"assigned"| R4 - - ADG -->|"assigned"| R5 - ADG -->|"assigned"| R6 - ADG -->|"assigned"| R7 - - R1 -->|"scoped to"| SUB - R2 -->|"scoped to"| SUB - R3 -->|"scoped to"| RG_SEC - R4 -->|"scoped to"| RG_SEC - R5 -->|"scoped to"| RG_WRK - R6 -->|"scoped to"| PROJ - R7 -->|"scoped to"| PROJ - - %% ===== APPLY STYLES ===== - class SI_DC,SI_PROJ primary - class ADG external - class R1,R2,R3,R4,R5,R6,R7 secondary - class SUB,RG_SEC,RG_WRK,DC,PROJ datastore - - %% ===== SUBGRAPH STYLING ===== - style Identities fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px - style Roles fill:#ECFDF5,stroke:#10B981,stroke-width:2px - style Scopes fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px -``` - -### Role Assignment Matrix - -| Identity | Role | Scope | Purpose | -| ----------------------------- | --------------------------- | ------------ | -------------------------- | -| **DevCenter MI** | Contributor | Subscription | Manage DevCenter resources | -| **DevCenter MI** | User Access Administrator | Subscription | Assign roles to projects | -| **DevCenter MI** | Key Vault Secrets User | Security RG | Read secrets for catalogs | -| **DevCenter MI** | Key Vault Secrets Officer | Security RG | Manage secrets | -| **Project MI** | Key Vault Secrets User | Security RG | Read secrets for catalogs | -| **Project MI** | Key Vault Secrets Officer | Security RG | Manage secrets | -| **Platform Engineering Team** | DevCenter Project Admin | Workload RG | Manage projects | -| **eShop Developers** | Contributor | Project | Manage project resources | -| **eShop Developers** | Dev Box User | Project | Create/manage Dev Boxes | -| **eShop Developers** | Deployment Environment User | Project | Deploy environments | - -### Azure AD Group Configuration - -From `devcenter.yaml`: - -```yaml -identity: - roleAssignments: - 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 - -projects: - - name: 'eShop' - identity: - roleAssignments: - - azureADGroupId: '9d42a792-2d74-441d-8bcb-71009371725f' - azureADGroupName: 'eShop Developers' - azureRBACRoles: - - name: 'Dev Box User' - id: '45d50f46-0b78-4001-a660-4198cbe8cd05' - scope: Project -``` - -### Role Hierarchy - -```mermaid ---- -title: Role Hierarchy ---- -flowchart TD - %% ===== STYLE DEFINITIONS ===== - classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF - classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF - classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 - - %% ===== SUBSCRIPTION LEVEL ===== - subgraph Subscription["Subscription Level"] - CONTRIB["Contributor"] - UAA["User Access Administrator"] - end - - %% ===== RESOURCE GROUP LEVEL ===== - subgraph ResourceGroup["Resource Group Level"] - KV_USER["Key Vault Secrets User"] - KV_OFFICER["Key Vault Secrets Officer"] - PROJ_ADMIN["DevCenter Project Admin"] - end - - %% ===== RESOURCE LEVEL ===== - subgraph Resource["Resource Level"] - DB_USER["Dev Box User"] - ENV_USER["Deployment Environment User"] - end - - %% ===== CONNECTIONS ===== - CONTRIB -->|"enables"| KV_USER - UAA -->|"enables"| PROJ_ADMIN - PROJ_ADMIN -->|"enables"| DB_USER - PROJ_ADMIN -->|"enables"| ENV_USER - - %% ===== APPLY STYLES ===== - class CONTRIB,UAA primary - class KV_USER,KV_OFFICER,PROJ_ADMIN secondary - class DB_USER,ENV_USER datastore - - %% ===== SUBGRAPH STYLING ===== - style Subscription fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px - style ResourceGroup fill:#ECFDF5,stroke:#10B981,stroke-width:2px - style Resource fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px -``` - ---- - -## πŸ”’ Security Architecture - -### Key Vault Configuration - -```mermaid ---- -title: Key Vault Security Configuration ---- -flowchart LR - %% ===== STYLE DEFINITIONS ===== - classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF - classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF - classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 - - %% ===== KEY VAULT ===== - subgraph KeyVault["Azure Key Vault"] - PROPS["Properties"] - SECRET["Secrets"] - ACCESS["Access Control"] - end - - %% ===== PROPERTIES ===== - subgraph Properties["Security Properties"] - P1["RBAC Authorization: true"] - P2["Soft Delete: true"] - P3["Purge Protection: true"] - P4["Retention: 7 days"] - end - - %% ===== SECRETS ===== - subgraph Secrets["Stored Secrets"] - S1["gha-token
GitHub PAT"] - end - - %% ===== ACCESS ===== - subgraph Access["RBAC Access"] - A1["DevCenter MI"] - A2["Project MI"] - A3["Deployer"] - end - - %% ===== CONNECTIONS ===== - PROPS -->|"defines"| Properties - SECRET -->|"contains"| Secrets - ACCESS -->|"controls"| Access - - A1 -->|"Secrets User"| S1 - A2 -->|"Secrets User"| S1 - A3 -->|"Secrets Officer"| S1 - - %% ===== APPLY STYLES ===== - class PROPS,SECRET,ACCESS primary - class P1,P2,P3,P4 secondary - class S1 datastore - class A1,A2,A3 secondary - - %% ===== SUBGRAPH STYLING ===== - style KeyVault fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px - style Properties fill:#ECFDF5,stroke:#10B981,stroke-width:2px - style Secrets fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px - style Access fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px -``` - -> [!WARNING] -> -> **Security Requirement:** All Key Vault secrets must use RBAC authorization. -> Access policies are not supported in this accelerator for compliance reasons. - -### Security Controls - -| Control | Configuration | Value | Purpose | -| ---------------------- | --------------------------- | ---------------- | ----------------------------------------- | -| **RBAC Authorization** | `enableRbacAuthorization` | `true` | Use Azure RBAC instead of access policies | -| **Soft Delete** | `enableSoftDelete` | `true` | Recover accidentally deleted secrets | -| **Purge Protection** | `enablePurgeProtection` | `true` | Prevent permanent deletion | -| **Retention Period** | `softDeleteRetentionInDays` | `7` | Recovery window | -| **Managed Identities** | `identity.type` | `SystemAssigned` | No credential management | -| **Diagnostic Logging** | `diagnosticSettings` | All logs | Audit trail | - -### Security Data Flow - -```mermaid ---- -title: Security Data Flow ---- -sequenceDiagram - %% ===== PARTICIPANTS ===== - participant DC as DevCenter - participant MI as Managed Identity - participant AAD as Entra ID - participant RBAC as Azure RBAC - participant KV as Key Vault - participant GH as GitHub - - %% ===== AUTHENTICATION FLOW ===== - DC->>MI: Request token - MI->>AAD: Authenticate - AAD-->>MI: Access token - MI-->>DC: Token - - %% ===== SECRET ACCESS FLOW ===== - DC->>KV: Get secret (with token) - KV->>RBAC: Check permissions - RBAC-->>KV: Authorized - KV-->>DC: Secret value - - %% ===== CATALOG ACCESS FLOW ===== - DC->>GH: Clone catalog (with PAT) - GH-->>DC: Repository content -``` - -### Compliance Alignment - -| Framework | Requirement | Implementation | -| ---------------------------- | --------------------------------- | ------------------------------------ | -| **Azure Security Benchmark** | ASB-DP-1: Data Discovery | Resource tagging, Log Analytics | -| **Azure Security Benchmark** | ASB-DP-4: Data at Rest Encryption | Key Vault software keys | -| **Azure Security Benchmark** | ASB-IM-1: Managed Identities | SystemAssigned on DevCenter/Projects | -| **Azure Security Benchmark** | ASB-PA-7: Least Privilege | Scoped RBAC role assignments | -| **Azure Security Benchmark** | ASB-LT-4: Logging | Diagnostic settings on all resources | - ---- - -## πŸ“Š Monitoring & Observability - -### Monitoring Architecture - -```mermaid ---- -title: Monitoring Architecture ---- -flowchart TB - %% ===== STYLE DEFINITIONS ===== - classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF - classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF - classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 - - %% ===== DATA SOURCES ===== - subgraph Sources["Data Sources"] - DC["DevCenter"] - KV["Key Vault"] - VNET["Virtual Network"] - LA_SELF["Log Analytics"] - end - - %% ===== DATA COLLECTION ===== - subgraph Collection["Data Collection"] - DIAG1["Diagnostic Settings"] - DIAG2["Diagnostic Settings"] - DIAG3["Diagnostic Settings"] - DIAG4["Self-Diagnostics"] - end - - %% ===== LOG ANALYTICS ===== - subgraph Analytics["Log Analytics Workspace"] - LOGS["Logs
AzureDiagnostics"] - METRICS["Metrics
AzureMetrics"] - ACTIVITY["Activity Logs
AzureActivity"] - end - - %% ===== OUTPUTS ===== - subgraph Outputs["Analysis & Action"] - QUERIES["KQL Queries"] - ALERTS["Alerts"] - WORKBOOKS["Workbooks"] - DASHBOARD["Dashboards"] - end - - %% ===== CONNECTIONS ===== - DC -->|"sends"| DIAG1 - KV -->|"sends"| DIAG2 - VNET -->|"sends"| DIAG3 - LA_SELF -->|"sends"| DIAG4 - - DIAG1 -->|"logs"| LOGS - DIAG1 -->|"metrics"| METRICS - DIAG2 -->|"logs"| LOGS - DIAG2 -->|"metrics"| METRICS - DIAG3 -->|"logs"| LOGS - DIAG3 -->|"metrics"| METRICS - DIAG4 -->|"logs"| LOGS - DIAG4 -->|"metrics"| METRICS - - LOGS -->|"analyzed by"| QUERIES - METRICS -->|"analyzed by"| QUERIES - ACTIVITY -->|"analyzed by"| QUERIES - - QUERIES -->|"triggers"| ALERTS - QUERIES -->|"visualizes"| WORKBOOKS - QUERIES -->|"displays"| DASHBOARD - - %% ===== APPLY STYLES ===== - class DC,KV,VNET,LA_SELF primary - class DIAG1,DIAG2,DIAG3,DIAG4 secondary - class LOGS,METRICS,ACTIVITY datastore - class QUERIES,ALERTS,WORKBOOKS,DASHBOARD secondary - - %% ===== SUBGRAPH STYLING ===== - style Sources fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px - style Collection fill:#ECFDF5,stroke:#10B981,stroke-width:2px - style Analytics fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px - style Outputs fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px -``` - -### Log Analytics Configuration - -| Setting | Value | Purpose | -| --------------------- | ---------------- | ---------------------- | -| **SKU** | PerGB2018 | Pay-per-GB pricing | -| **Solutions** | AzureActivity | Activity log analysis | -| **Log Categories** | allLogs | Comprehensive logging | -| **Metric Categories** | AllMetrics | Performance monitoring | -| **Destination Type** | AzureDiagnostics | Standard schema | - -### Diagnostic Settings - -All resources deploy with standardized diagnostic settings: - -```bicep -resource diagnosticSettings 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { - name: '${resourceName}-diagnostics' - scope: targetResource - properties: { - logAnalyticsDestinationType: 'AzureDiagnostics' - logs: [ - { - categoryGroup: 'allLogs' - enabled: true - } - ] - metrics: [ - { - category: 'AllMetrics' - enabled: true - } - ] - workspaceId: logAnalyticsWorkspaceId - } -} -``` - -### Key Metrics - -| Resource | Metric | Description | Alert Threshold | -| ----------------- | ----------------- | --------------------- | ----------------- | -| **Key Vault** | ServiceApiLatency | API response time | > 1000ms | -| **Key Vault** | Availability | Service availability | < 99.9% | -| **DevCenter** | PoolUtilization | Pool usage percentage | > 80% | -| **VNet** | BytesDroppedDDoS | DDoS mitigation | > 0 | -| **Log Analytics** | IngestionVolume | Data ingestion rate | Anomaly detection | - ---- - -## βš™οΈ CI/CD Infrastructure - -### CI/CD Pipeline Flow - -```mermaid ---- -title: CI/CD Pipeline Flow ---- -flowchart LR - %% ===== STYLE DEFINITIONS ===== - 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 trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF - - %% ===== TRIGGERS ===== - subgraph Trigger["Triggers"] - PUSH["Push to feature/*"] - PR["Pull Request to main"] - MANUAL["Manual Dispatch"] - end - - %% ===== CI ===== - subgraph CI["Continuous Integration"] - VERSION["Generate Version"] - BUILD["Build Bicep"] - ARTIFACT["Upload Artifacts"] - end - - %% ===== CD ===== - subgraph CD["Continuous Deployment"] - AUTH["Azure Auth
Federated Credentials"] - PROVISION["azd provision"] - DEPLOY["Deploy to Azure"] - end - - %% ===== RELEASE ===== - subgraph Release["Release"] - TAG["Create Git Tag"] - RELEASE["GitHub Release"] - NOTES["Release Notes"] - end - - %% ===== CONNECTIONS ===== - PUSH -->|"triggers"| VERSION - PR -->|"triggers"| VERSION - MANUAL -->|"triggers"| VERSION - - VERSION -->|"generates"| BUILD - BUILD -->|"produces"| ARTIFACT - - ARTIFACT -->|"starts"| AUTH - AUTH -->|"authenticates"| PROVISION - PROVISION -->|"executes"| DEPLOY - - DEPLOY -->|"completes"| TAG - TAG -->|"creates"| RELEASE - RELEASE -->|"generates"| NOTES - - %% ===== APPLY STYLES ===== - class PUSH,PR,MANUAL trigger - class VERSION,BUILD,ARTIFACT primary - class AUTH,PROVISION,DEPLOY secondary - class TAG,RELEASE,NOTES datastore - - %% ===== SUBGRAPH STYLING ===== - style Trigger fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px - style CI fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px - style CD fill:#ECFDF5,stroke:#10B981,stroke-width:2px - style Release fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px -``` - -### GitHub Actions Workflows - -| Workflow | File | Trigger | Purpose | -| -------------------------- | ------------------------------- | ------------------------------ | ------------------------ | -| **Continuous Integration** | `.github/workflows/ci.yml` | Push to feature/\*, PR to main | Build and validate Bicep | -| **Deploy to Azure** | `.github/workflows/deploy.yml` | Manual dispatch | Deploy infrastructure | -| **Branch-Based Release** | `.github/workflows/release.yml` | Manual dispatch | Create releases | - -### CI Workflow Details (`ci.yml`) - -```mermaid ---- -title: CI Workflow Details ---- -flowchart TD - %% ===== STYLE DEFINITIONS ===== - classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF - classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF - classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 - - %% ===== JOB 1 ===== - subgraph Job1["generate-tag-version"] - CHECKOUT1["Checkout Code"] - GENERATE["Generate Release Info"] - OUTPUT1[/"new_version, release_type,
previous_tag, should_release"/] - end - - %% ===== JOB 2 ===== - subgraph Job2["build"] - CHECKOUT2["Checkout Code"] - BUILD["Build Bicep Code"] - UPLOAD["Upload Artifacts"] - end - - %% ===== CONNECTIONS ===== - CHECKOUT1 -->|"runs"| GENERATE - GENERATE -->|"outputs"| OUTPUT1 - OUTPUT1 -->|"triggers"| CHECKOUT2 - CHECKOUT2 -->|"runs"| BUILD - BUILD -->|"produces"| UPLOAD - - %% ===== APPLY STYLES ===== - class CHECKOUT1,CHECKOUT2 primary - class GENERATE,BUILD secondary - class OUTPUT1,UPLOAD datastore - - %% ===== SUBGRAPH STYLING ===== - style Job1 fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px - style Job2 fill:#ECFDF5,stroke:#10B981,stroke-width:2px -``` - -### Deploy Workflow Details (`deploy.yml`) - -```yaml -# Key workflow steps -- name: Install azd - uses: Azure/setup-azd@v2 - -- name: Build Accelerator Bicep - run: | - az bicep build --file ./infra/main.bicep --outdir ./artifacts - -- name: Log in with Azure (Federated Credentials) - run: | - azd auth login \ - --client-id "$AZURE_CLIENT_ID" \ - --federated-credential-provider "github" \ - --tenant-id "$AZURE_TENANT_ID" - -- name: Deploy to Azure - run: azd provision --no-prompt - env: - KEY_VAULT_SECRET: ${{ secrets.KEY_VAULT_SECRET }} -``` - -### Azure DevOps Pipeline (`azure-dev.yml`) - -```yaml -# Key pipeline steps -- task: Bash@3 - displayName: Install azd - inputs: - script: curl -fsSL https://aka.ms/install-azd.sh | sudo bash - -- pwsh: azd config set auth.useAzCliAuth "true" - displayName: Configure AZD to Use AZ CLI Authentication - -- task: AzureCLI@2 - displayName: Provision Infrastructure - inputs: - azureSubscription: azconnection - scriptType: bash - inlineScript: azd provision --no-prompt -``` - -### Authentication Methods - -| Platform | Method | Configuration | -| ------------------ | -------------------------- | ------------------------------------------------------------- | -| **GitHub Actions** | OIDC Federated Credentials | `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_SUBSCRIPTION_ID` | -| **Azure DevOps** | Service Connection | `azconnection` service principal | - ---- - -## πŸ› οΈ Deployment Tools - -### Azure Developer CLI (azd) - -The primary deployment tool for the accelerator. - -| Command | Purpose | Usage | -| --------------- | ------------------------- | ------------------------- | -| `azd init` | Initialize environment | First-time setup | -| `azd provision` | Deploy infrastructure | Create Azure resources | -| `azd env new` | Create new environment | Multi-environment support | -| `azd env set` | Set environment variables | Configure parameters | - -### azd Configuration (`azure.yaml`) - -```yaml -name: ContosoDevExp - -hooks: - preprovision: - shell: sh - run: | - # Set default source control platform - export SOURCE_CONTROL_PLATFORM="${SOURCE_CONTROL_PLATFORM:-github}" - ./setup.sh -e ${AZURE_ENV_NAME} -s ${SOURCE_CONTROL_PLATFORM} -``` - -### Setup Scripts - -| Script | Platform | Purpose | -| ---------------- | ---------- | ---------------------------- | -| `setUp.ps1` | PowerShell | Windows setup automation | -| `setUp.sh` | Bash | Linux/macOS setup automation | -| `cleanSetUp.ps1` | PowerShell | Resource cleanup | - -### Setup Script Flow - -```mermaid ---- -title: Setup Script Flow ---- -flowchart TD - %% ===== STYLE DEFINITIONS ===== - 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 decision fill:#FFFBEB,stroke:#F59E0B,color:#000000 - - %% ===== FLOW ===== - START["Start Setup"] - CHECK_CLI["Check CLI Tools
az, azd, gh"] - AUTH_AZ["Authenticate Azure"] - AUTH_GH["Authenticate GitHub/ADO"] - GET_TOKEN["Get PAT Token"] - INIT_ENV["Initialize azd Environment"] - SET_VARS["Set Environment Variables"] - PROVISION["azd provision"] - END_NODE["Setup Complete"] - - %% ===== CONNECTIONS ===== - START -->|"begins"| CHECK_CLI - CHECK_CLI -->|"validates"| AUTH_AZ - AUTH_AZ -->|"authenticates"| AUTH_GH - AUTH_GH -->|"retrieves"| GET_TOKEN - GET_TOKEN -->|"initializes"| INIT_ENV - INIT_ENV -->|"configures"| SET_VARS - SET_VARS -->|"deploys"| PROVISION - PROVISION -->|"completes"| END_NODE - - %% ===== APPLY STYLES ===== - class START,END_NODE datastore - class CHECK_CLI,AUTH_AZ,AUTH_GH decision - class GET_TOKEN,INIT_ENV,SET_VARS primary - class PROVISION secondary -``` - -### Environment Variables - -| Variable | Source | Purpose | -| ------------------------- | ----------------- | ---------------------------------- | -| `AZURE_ENV_NAME` | User input | Environment name (dev, test, prod) | -| `AZURE_LOCATION` | User input | Azure region | -| `AZURE_SUBSCRIPTION_ID` | Azure CLI | Target subscription | -| `AZURE_CLIENT_ID` | Service principal | Deployment identity | -| `AZURE_TENANT_ID` | Azure AD | Tenant identifier | -| `KEY_VAULT_SECRET` | GitHub Secret | PAT token for catalogs | -| `SOURCE_CONTROL_PLATFORM` | User input | github or adogit | - ---- - -## πŸ’» DevOps Practices - -### Branching Strategy - -```mermaid ---- -title: Git Branching Strategy ---- -gitGraph - commit id: "Initial" - branch feature/new-feature - checkout feature/new-feature - commit id: "Feature work" - commit id: "More work" - checkout main - merge feature/new-feature - commit id: "Release v1.0.0" tag: "v1.0.0" - branch fix/bug-fix - checkout fix/bug-fix - commit id: "Bug fix" - checkout main - merge fix/bug-fix - commit id: "Release v1.0.1" tag: "v1.0.1" -``` - -### Branch Types - -| Branch Pattern | Purpose | Version Impact | -| -------------- | --------------------- | --------------------- | -| `main` | Production-ready code | Major/Patch increment | -| `feature/*` | New features | Minor increment | -| `fix/*` | Bug fixes | Patch increment | -| `docs/*` | Documentation | No version change | - -### Semantic Versioning - -The accelerator follows semantic versioning (`MAJOR.MINOR.PATCH`): - -| Version Component | Increment Condition | Example | -| ----------------- | ------------------------------------------------------ | ------------- | -| **MAJOR** | Breaking changes, main branch with minor=0 AND patch=0 | 1.0.0 β†’ 2.0.0 | -| **MINOR** | Feature branches | 1.0.0 β†’ 1.1.0 | -| **PATCH** | Fix branches, main branch with minorβ‰ 0 OR patchβ‰ 0 | 1.0.0 β†’ 1.0.1 | - -### Release Process - -```mermaid ---- -title: Release Process ---- -flowchart LR - %% ===== STYLE DEFINITIONS ===== - 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 trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF - - %% ===== TRIGGER ===== - subgraph Trigger["Release Trigger"] - MANUAL["Manual Dispatch"] - end - - %% ===== GENERATE ===== - subgraph Generate["Generate Metadata"] - VERSION["Calculate Version"] - NOTES["Generate Notes"] - end - - %% ===== BUILD ===== - subgraph Build["Build Phase"] - BICEP["Compile Bicep"] - ARM["Generate ARM"] - ZIP["Package Artifacts"] - end - - %% ===== PUBLISH ===== - subgraph Publish["Publish Phase"] - TAG["Create Git Tag"] - RELEASE["GitHub Release"] - UPLOAD["Upload Assets"] - end - - %% ===== CONNECTIONS ===== - MANUAL -->|"triggers"| VERSION - VERSION -->|"generates"| NOTES - NOTES -->|"starts"| BICEP - BICEP -->|"produces"| ARM - ARM -->|"packages"| ZIP - ZIP -->|"creates"| TAG - TAG -->|"creates"| RELEASE - RELEASE -->|"attaches"| UPLOAD - - %% ===== APPLY STYLES ===== - class MANUAL trigger - class VERSION,NOTES primary - class BICEP,ARM,ZIP secondary - class TAG,RELEASE,UPLOAD datastore - - %% ===== SUBGRAPH STYLING ===== - style Trigger fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px - style Generate fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px - style Build fill:#ECFDF5,stroke:#10B981,stroke-width:2px - style Publish fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px -``` - -### Infrastructure as Code Practices - -| Practice | Implementation | Benefit | -| -------------------------- | -------------------------------- | -------------------------- | -| **Version Control** | All Bicep/YAML in Git | Audit trail, collaboration | -| **Code Review** | Pull requests to main | Quality assurance | -| **Automated Testing** | CI pipeline validation | Catch errors early | -| **Idempotent Deployments** | Declarative Bicep | Safe re-runs | -| **Environment Parity** | Same templates, different params | Consistent environments | -| **Documentation as Code** | Markdown in repository | Self-documenting | - ---- - -## πŸ“š References - -### External References - -| Reference | URL | Description | -| ------------------------ | ------------------------------------------------------------------------------ | --------------------- | -| Microsoft Dev Box | https://learn.microsoft.com/azure/dev-box/ | Dev Box documentation | -| Azure DevCenter API | https://learn.microsoft.com/azure/templates/microsoft.devcenter/ | Resource reference | -| Azure Developer CLI | https://learn.microsoft.com/azure/developer/azure-developer-cli/ | azd documentation | -| Azure Landing Zones | https://learn.microsoft.com/azure/cloud-adoption-framework/ready/landing-zone/ | CAF guidance | -| GitHub Actions for Azure | https://learn.microsoft.com/azure/developer/github/ | CI/CD integration | -| Azure RBAC | https://learn.microsoft.com/azure/role-based-access-control/ | Access control | - -### Related Architecture Documents - -| Document | Path | Description | -| ------------------------ | ------------------------------------------------------------------ | --------------------- | -| Business Architecture | [01-business-architecture.md](./01-business-architecture.md) | Business context | -| Data Architecture | [02-data-architecture.md](./02-data-architecture.md) | Data models and flows | -| Application Architecture | [03-application-architecture.md](./03-application-architecture.md) | Bicep modules | - ---- - -## πŸ“– Glossary - -| Term | Definition | -| ------------------------- | ------------------------------------------------------------ | -| **azd** | Azure Developer CLI - deployment tool for Azure applications | -| **Bicep** | Domain-specific language for Azure infrastructure deployment | -| **DevCenter** | Azure service for managing developer environments | -| **Dev Box** | Cloud-powered developer workstation | -| **Federated Credentials** | OIDC-based authentication without secrets | -| **Landing Zone** | Pre-configured Azure environment with governance | -| **Managed Identity** | Azure AD identity automatically managed by Azure | -| **Network Connection** | DevCenter resource linking to customer VNet | -| **RBAC** | Role-Based Access Control | -| **SKU** | Stock Keeping Unit - defines resource size/tier | -| **System-Assigned MI** | Managed identity tied to resource lifecycle | -| **VNet** | Virtual Network - isolated network in Azure | - ---- - -_This document follows TOGAF Architecture Development Method (ADM) principles -and aligns with the Technology Architecture domain of the BDAT framework._ - ---- - -
- -**[← Application Architecture](./03-application-architecture.md)** | -**[⬆️ Back to Top](#%EF%B8%8F-technology-architecture)** - -
diff --git a/docs/architecture/README.md b/docs/architecture/README.md deleted file mode 100644 index 6745a76c..00000000 --- a/docs/architecture/README.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: Architecture Documentation Index -description: - Index of TOGAF BDAT architecture documentation for DevExp-DevBox Landing Zone - Accelerator -author: Platform Engineering Team -date: 2026-01-22 -version: 1.0.0 -tags: - - TOGAF - - BDAT - - Architecture - - DevExp-DevBox - - Index ---- - -# 🏠 DevExp-DevBox Architecture Documentation - -> **TOGAF BDAT Architecture Framework** - -> [!NOTE] -> -> **Target Audience:** All Stakeholders -> -> **Purpose:** Central navigation hub for architecture documentation - -## πŸ“‹ Overview - -This documentation follows the **TOGAF Architecture Development Method (ADM)** -and implements the **BDAT (Business, Data, Application, Technology)** framework -to provide comprehensive architecture documentation for the DevExp-DevBox -Landing Zone Accelerator. - -## πŸ“š Architecture Documents - -| # | Document | Description | Audience | -| :-: | :-------------------------------------------------------------- | :-------------------------------------------------------------------------------- | :---------------------------------- | -| 1 | [🏒 Business Architecture](./01-business-architecture.md) | Business context, stakeholders, capabilities, value streams, and requirements | BDMs, Enterprise Architects | -| 2 | [πŸ“Š Data Architecture](./02-data-architecture.md) | Configuration data models, secrets management, telemetry, and data governance | Data Architects, Security Engineers | -| 3 | [πŸ›οΈ Application Architecture](./03-application-architecture.md) | Bicep module catalog, dependencies, deployment orchestration, and design patterns | Platform Engineers, DevOps | -| 4 | [πŸ—οΈ Technology Architecture](./04-technology-architecture.md) | Azure services, networking, identity, security, monitoring, and CI/CD | Cloud Architects, IT Operations | - -## πŸ”„ Document Relationships - -```mermaid ---- -title: TOGAF BDAT Framework Document Relationships ---- -flowchart TB - %% ===== STYLE DEFINITIONS ===== - classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF - classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF - classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 - - %% ===== FRAMEWORK DOCUMENTS ===== - subgraph TOGAF["TOGAF BDAT Framework"] - BA["🏒 Business Architecture"] - DA["πŸ“Š Data Architecture"] - AA["πŸ›οΈ Application Architecture"] - TA["πŸ—οΈ Technology Architecture"] - end - - %% ===== DOCUMENT RELATIONSHIPS ===== - BA -->|"defines requirements"| DA - BA -->|"defines requirements"| AA - DA -->|"defines data flows"| AA - AA -->|"implements"| TA - DA -->|"defines data flows"| TA - - %% ===== CROSS-DOMAIN RELATIONSHIPS ===== - BA -.->|"Defines Requirements"| AA - DA -.->|"Defines Data Flows"| TA - AA -.->|"Implements"| TA - - %% ===== APPLY STYLES ===== - class BA,DA,AA,TA primary - - %% ===== SUBGRAPH STYLING ===== - style TOGAF fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px -``` - -## 🎯 Quick Start Guide - -> [!TIP] -> -> **Recommended Reading Order:** -> -> 1. Start with **Business Architecture** to understand the context and -> requirements -> 2. Review **Data Architecture** for configuration and data flow patterns -> 3. Explore **Application Architecture** for Bicep module details -> 4. Finish with **Technology Architecture** for infrastructure specifics - -## πŸ“– Framework Reference - -| Framework | Component | Purpose | -| :------------ | :-------------------------------------- | :--------------------------------------------- | -| **TOGAF** | Architecture Development Method (ADM) | Structured approach to enterprise architecture | -| **BDAT** | Business, Data, Application, Technology | Four-domain architecture framework | -| **Azure CAF** | Cloud Adoption Framework | Azure best practices and landing zones | - -## πŸ”— External Resources - -| Resource | Description | -| :---------------------------------------------------------------------------------------------------- | :----------------------------- | -| [Microsoft Dev Box](https://learn.microsoft.com/azure/dev-box/) | Official Dev Box documentation | -| [Azure Landing Zones](https://learn.microsoft.com/azure/cloud-adoption-framework/ready/landing-zone/) | CAF Landing Zone guidance | -| [TOGAF Standard](https://www.opengroup.org/togaf) | TOGAF architecture framework | -| [DevExp-DevBox Accelerator](https://evilazaro.github.io/DevExp-DevBox/) | Project documentation site | - ---- - -
- -**πŸ“… Last Updated:** January 22, 2026 | **πŸ“Œ Version:** 1.0.0 - -
From 0a7f718cc6f6c9ae9f926958a8606f4d2f0dae81 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 15:52:34 -0500 Subject: [PATCH 24/49] Add initial Business Architecture documentation for DevExp-DevBox Landing Zone Accelerator --- docs/architecture/01-business-architecture.md | 443 ++++++++++++++++++ 1 file changed, 443 insertions(+) create mode 100644 docs/architecture/01-business-architecture.md diff --git a/docs/architecture/01-business-architecture.md b/docs/architecture/01-business-architecture.md new file mode 100644 index 00000000..a38316ab --- /dev/null +++ b/docs/architecture/01-business-architecture.md @@ -0,0 +1,443 @@ +# Business Architecture + +> **TOGAF Layer**: Business Architecture +> **Version**: 1.0.0 +> **Last Updated**: January 22, 2026 +> **Author**: DevExp Team + +--- + +## Table of Contents + +- [Executive Summary](#executive-summary) +- [Business Context](#business-context) +- [Stakeholder Analysis](#stakeholder-analysis) +- [Business Capabilities](#business-capabilities) +- [Value Streams](#value-streams) +- [Business Requirements](#business-requirements) +- [Success Metrics](#success-metrics) +- [References](#references) +- [Glossary](#glossary) + +--- + +## Executive Summary + +The **DevExp-DevBox Landing Zone Accelerator** is an enterprise-grade infrastructure-as-code solution that streamlines the deployment and management of Microsoft Dev Box environments on Azure. This accelerator enables organizations to rapidly provision secure, compliant, and scalable developer workstations while maintaining governance controls and operational excellence. + +### Key Business Value Propositions + +| Value Area | Description | +|------------|-------------| +| **Accelerated Developer Onboarding** | Reduce new developer setup time from days to minutes through pre-configured Dev Box environments | +| **Standardized Development Environments** | Ensure consistency across teams with role-specific configurations (backend, frontend engineers) | +| **Security & Compliance** | Built-in security controls with Key Vault integration, RBAC, and Azure AD authentication | +| **Cost Optimization** | Right-sized VM SKUs per role and centralized resource management | +| **Operational Efficiency** | Automated provisioning via Azure Developer CLI (azd) with CI/CD integration | + +--- + +## Business Context + +### Problem Statement + +Modern enterprises face significant challenges in managing developer environments: + +1. **Environment Inconsistency**: Developers spend excessive time configuring local machines, leading to "works on my machine" issues +2. **Security Risks**: Unmanaged developer workstations create security vulnerabilities +3. **Slow Onboarding**: New developer setup can take days or weeks +4. **Compliance Gaps**: Difficulty enforcing organizational policies on distributed workstations +5. **Cost Visibility**: Lack of centralized tracking for developer infrastructure costs + +### Target Audience + +```mermaid +mindmap + root((DevExp-DevBox
Accelerator)) + Enterprise Organizations + Large development teams + Multiple project portfolios + Strict compliance requirements + Platform Engineering Teams + Infrastructure automation + Developer experience focus + Self-service enablement + Regulated Industries + Financial services + Healthcare + Government + Cloud-First Companies + Azure-native tooling + DevOps maturity + Remote workforce +``` + +### Business Drivers + +| Driver | Description | Priority | +|--------|-------------|----------| +| **Developer Productivity** | Eliminate environment setup overhead | High | +| **Security Posture** | Centralized security controls and monitoring | High | +| **Operational Excellence** | Automated, repeatable deployments | High | +| **Cost Management** | Predictable infrastructure costs | Medium | +| **Talent Retention** | Modern developer experience | Medium | +| **Compliance** | Meet regulatory requirements | High | + +--- + +## Stakeholder Analysis + +### Stakeholder Map + +```mermaid +graph TB + subgraph "Executive Stakeholders" + CTO[CTO/CIO] + CISO[CISO] + CFO[CFO] + end + + subgraph "Technical Stakeholders" + PE[Platform Engineers] + DE[Development Teams] + SEC[Security Team] + OPS[Operations Team] + end + + subgraph "Business Stakeholders" + PM[Project Managers] + BU[Business Units] + end + + CTO -->|Strategic Direction| PE + CISO -->|Security Requirements| SEC + CFO -->|Budget Approval| PE + + PE -->|Platform Services| DE + SEC -->|Security Controls| PE + OPS -->|Operational Support| PE + + PM -->|Project Requirements| DE + BU -->|Business Needs| PM + + DE -->|Feedback| PE + + style PE fill:#4CAF50,color:#fff + style DE fill:#2196F3,color:#fff + style SEC fill:#FF9800,color:#fff + style OPS fill:#9C27B0,color:#fff +``` + +### Stakeholder Registry + +| Stakeholder | Role | Concerns | Interests | Engagement Level | +|-------------|------|----------|-----------|------------------| +| **Platform Engineers** | Build & maintain landing zones | Automation, scalability, maintainability | Infrastructure as Code, self-service capabilities | High - Primary implementers | +| **Development Teams** | Consume Dev Box environments | Fast onboarding, reliable environments, tool availability | Productivity, modern tooling, minimal friction | High - Primary users | +| **Security Team** | Ensure security compliance | Access control, secrets management, audit trails | Zero-trust architecture, compliance reporting | High - Governance | +| **Operations Team** | Monitor & support infrastructure | Observability, incident response, cost management | Centralized monitoring, automated remediation | Medium - Ongoing support | +| **Project Managers** | Coordinate project delivery | Resource allocation, timeline management | Predictable provisioning, clear ownership | Medium - Coordination | +| **CTO/CIO** | Strategic technology direction | ROI, innovation, competitive advantage | Developer productivity metrics, cost optimization | Low - Strategic oversight | +| **CISO** | Security governance | Risk mitigation, compliance adherence | Security posture, audit readiness | Medium - Policy approval | +| **CFO** | Financial oversight | Cost control, budget planning | Infrastructure cost visibility, optimization | Low - Budget approval | + +### RACI Matrix + +| Activity | Platform Engineers | Dev Teams | Security | Operations | Project Managers | +|----------|-------------------|-----------|----------|------------|------------------| +| Landing Zone Design | **R/A** | C | C | C | I | +| Dev Box Provisioning | R | **A** | I | C | I | +| Security Configuration | C | I | **R/A** | C | I | +| Monitoring Setup | R | I | C | **A** | I | +| Cost Management | R | I | I | C | **A** | +| Incident Response | C | I | C | **R/A** | I | + +*R = Responsible, A = Accountable, C = Consulted, I = Informed* + +--- + +## Business Capabilities + +### Business Capability Model + +```mermaid +graph TB + subgraph "Level 0: Developer Experience Platform" + L0[DevExp-DevBox
Landing Zone Accelerator] + end + + subgraph "Level 1: Core Capability Domains" + SEC[Security
Management] + MON[Monitoring &
Observability] + CON[Connectivity
Management] + WRK[Workload
Management] + end + + subgraph "Level 2: Security Capabilities" + SEC1[Secrets Management] + SEC2[Identity & Access] + SEC3[Compliance Controls] + end + + subgraph "Level 2: Monitoring Capabilities" + MON1[Log Analytics] + MON2[Diagnostics] + MON3[Alerting] + end + + subgraph "Level 2: Connectivity Capabilities" + CON1[Network Provisioning] + CON2[Network Isolation] + CON3[Hybrid Connectivity] + end + + subgraph "Level 2: Workload Capabilities" + WRK1[DevCenter Management] + WRK2[Project Management] + WRK3[Pool Management] + WRK4[Catalog Management] + end + + L0 --> SEC + L0 --> MON + L0 --> CON + L0 --> WRK + + SEC --> SEC1 + SEC --> SEC2 + SEC --> SEC3 + + MON --> MON1 + MON --> MON2 + MON --> MON3 + + CON --> CON1 + CON --> CON2 + CON --> CON3 + + WRK --> WRK1 + WRK --> WRK2 + WRK --> WRK3 + WRK --> WRK4 + + style L0 fill:#1976D2,color:#fff + style SEC fill:#D32F2F,color:#fff + style MON fill:#388E3C,color:#fff + style CON fill:#7B1FA2,color:#fff + style WRK fill:#F57C00,color:#fff +``` + +### Capability to Landing Zone Mapping + +| Business Capability | Landing Zone | Key Resources | Business Value | +|---------------------|--------------|---------------|----------------| +| **Secrets Management** | Security | Azure Key Vault | Secure credential storage for PAT tokens and service credentials | +| **Identity & Access** | Security | Azure RBAC, Managed Identities | Fine-grained access control with least privilege | +| **Compliance Controls** | Security | Purge Protection, Soft Delete | Data protection and audit compliance | +| **Log Analytics** | Monitoring | Log Analytics Workspace | Centralized logging for troubleshooting and compliance | +| **Diagnostics** | Monitoring | Diagnostic Settings | Resource health and performance monitoring | +| **Network Provisioning** | Connectivity | Virtual Networks, Subnets | Secure network infrastructure for Dev Box | +| **Network Isolation** | Connectivity | NSGs, Network Connections | Workload segmentation and security boundaries | +| **DevCenter Management** | Workload | Azure DevCenter | Central management for developer environments | +| **Project Management** | Workload | DevCenter Projects | Team-level environment organization | +| **Pool Management** | Workload | Dev Box Pools | Role-specific workstation configurations | +| **Catalog Management** | Workload | Git Catalogs | Configuration-as-code for Dev Box definitions | + +--- + +## Value Streams + +### Developer Onboarding Value Stream + +```mermaid +graph LR + subgraph "Stage 1: Request" + A1[Developer
Joins Team] + A2[Access
Request] + end + + subgraph "Stage 2: Provisioning" + B1[Azure AD
Group Assignment] + B2[Project
Access Granted] + B3[Dev Box
Provisioned] + end + + subgraph "Stage 3: Configuration" + C1[Image
Downloaded] + C2[Tools
Installed] + C3[Secrets
Configured] + end + + subgraph "Stage 4: Productive" + D1[Developer
Coding] + D2[Feedback
Loop] + end + + A1 --> A2 + A2 --> B1 + B1 --> B2 + B2 --> B3 + B3 --> C1 + C1 --> C2 + C2 --> C3 + C3 --> D1 + D1 --> D2 + D2 -.->|Improvements| B3 + + style A1 fill:#E3F2FD + style D1 fill:#E8F5E9 +``` + +### Value Stream Metrics + +| Stage | Traditional Approach | With DevExp-DevBox | Improvement | +|-------|---------------------|-------------------|-------------| +| **Request to Access** | 1-3 days | < 1 hour | 95% faster | +| **Environment Provisioning** | 4-8 hours | 15-30 minutes | 90% faster | +| **Tool Configuration** | 2-4 hours | Automated | 100% automated | +| **Time to First Commit** | 2-5 days | Same day | 80% faster | +| **Environment Consistency** | Variable | 100% consistent | Standardized | + +### Environment Provisioning Lifecycle + +```mermaid +stateDiagram-v2 + [*] --> Requested: Developer Request + Requested --> Approved: Manager Approval + Approved --> Provisioning: Azure RBAC + Provisioning --> Configuring: Dev Box Created + Configuring --> Ready: Tools Installed + Ready --> InUse: Developer Connected + InUse --> Updating: Scheduled Maintenance + Updating --> InUse: Updates Applied + InUse --> Deprovisioning: Project Complete + Deprovisioning --> [*]: Resources Cleaned + + InUse --> Suspended: Cost Optimization + Suspended --> InUse: Developer Resume +``` + +--- + +## Business Requirements + +### Functional Requirements + +| ID | Requirement | Priority | Landing Zone | +|----|-------------|----------|--------------| +| **FR-001** | Deploy Azure DevCenter with project organization | Must Have | Workload | +| **FR-002** | Provision Dev Box pools with role-specific configurations | Must Have | Workload | +| **FR-003** | Integrate Git catalogs for image definitions | Must Have | Workload | +| **FR-004** | Store secrets securely in Azure Key Vault | Must Have | Security | +| **FR-005** | Assign RBAC roles based on Azure AD groups | Must Have | Security | +| **FR-006** | Deploy virtual networks for Dev Box connectivity | Should Have | Connectivity | +| **FR-007** | Enable centralized logging via Log Analytics | Must Have | Monitoring | +| **FR-008** | Support multiple environment types (dev, staging, UAT) | Should Have | Workload | +| **FR-009** | Enable catalog synchronization from GitHub/Azure DevOps | Must Have | Workload | +| **FR-010** | Support managed and unmanaged network configurations | Should Have | Connectivity | + +### Non-Functional Requirements + +| ID | Requirement | Category | Target | Measurement | +|----|-------------|----------|--------|-------------| +| **NFR-001** | Infrastructure deployment time | Performance | < 30 minutes | azd provision duration | +| **NFR-002** | Dev Box startup time | Performance | < 15 minutes | DevCenter metrics | +| **NFR-003** | System availability | Reliability | 99.9% | Azure Monitor | +| **NFR-004** | Secret access latency | Performance | < 100ms | Key Vault diagnostics | +| **NFR-005** | Audit log retention | Compliance | 90 days minimum | Log Analytics | +| **NFR-006** | RBAC propagation time | Performance | < 5 minutes | Manual testing | +| **NFR-007** | Disaster recovery | Reliability | RPO < 24 hours | Bicep redeployment | +| **NFR-008** | Cost visibility | Manageability | Per-project breakdown | Azure Cost Management | + +--- + +## Success Metrics + +### Key Performance Indicators (KPIs) + +```mermaid +graph TB + subgraph "Developer Productivity KPIs" + KPI1[Time to
First Commit] + KPI2[Environment
Setup Time] + KPI3[Developer
Satisfaction Score] + end + + subgraph "Operational KPIs" + KPI4[Deployment
Success Rate] + KPI5[Mean Time
to Recovery] + KPI6[Infrastructure
Drift Score] + end + + subgraph "Security KPIs" + KPI7[Compliance
Score] + KPI8[Security
Incidents] + KPI9[Access Review
Completion] + end + + subgraph "Cost KPIs" + KPI10[Cost per
Developer] + KPI11[Resource
Utilization] + KPI12[Budget
Variance] + end +``` + +### Success Metrics Dashboard + +| Metric | Baseline | Target | Current | Status | +|--------|----------|--------|---------|--------| +| **Developer Onboarding Time** | 5 days | < 1 day | - | 🎯 Target | +| **Environment Consistency** | 60% | 100% | - | 🎯 Target | +| **Deployment Success Rate** | - | > 95% | - | 🎯 Target | +| **Security Compliance Score** | - | 100% | - | 🎯 Target | +| **Cost per Developer/Month** | Variable | Predictable | - | 🎯 Target | +| **Mean Time to Recovery** | - | < 1 hour | - | 🎯 Target | +| **Developer Satisfaction (NPS)** | - | > 50 | - | 🎯 Target | + +### Business Value Realization + +| Value Area | Metric | Expected Outcome | +|------------|--------|------------------| +| **Productivity** | Developer hours saved per onboarding | 16-32 hours | +| **Quality** | Environment-related incidents reduced | 70% reduction | +| **Security** | Security findings in developer environments | Zero critical findings | +| **Cost** | Infrastructure cost predictability | ±10% budget variance | +| **Speed** | Time to market for new projects | 2 weeks faster | + +--- + +## References + +### Internal Documents + +- [Data Architecture](02-data-architecture.md) - Configuration schemas and data flows +- [Application Architecture](03-application-architecture.md) - Module design and dependencies +- [Technology Architecture](04-technology-architecture.md) - Azure services and infrastructure +- [Security Architecture](05-security-architecture.md) - Security controls and compliance + +### External References + +- [Microsoft Dev Box Documentation](https://learn.microsoft.com/en-us/azure/dev-box/overview-what-is-microsoft-dev-box) +- [Azure Landing Zones](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/landing-zone/) +- [Azure DevCenter Documentation](https://learn.microsoft.com/en-us/azure/dev-box/concept-dev-box-concepts) +- [TOGAF Architecture Framework](https://www.opengroup.org/togaf) + +--- + +## Glossary + +| Term | Definition | +|------|------------| +| **Dev Box** | A cloud-based developer workstation provided by Microsoft Azure | +| **DevCenter** | Azure service for managing developer environments at scale | +| **Landing Zone** | A pre-configured Azure environment with governance, security, and networking | +| **Accelerator** | Pre-built infrastructure-as-code templates for rapid deployment | +| **Catalog** | Git repository containing Dev Box image definitions or environment templates | +| **Pool** | Collection of Dev Boxes with shared configuration (VM size, image, network) | +| **RBAC** | Role-Based Access Control - Azure's authorization system | +| **Managed Identity** | Azure AD identity automatically managed for Azure resources | +| **azd** | Azure Developer CLI - Command-line tool for Azure development workflows | + +--- + +*Document generated as part of TOGAF Architecture Documentation for DevExp-DevBox Landing Zone Accelerator* From c6e8a41c86ecb19163d5f240a7a747d747ddea55 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 15:53:43 -0500 Subject: [PATCH 25/49] Add comprehensive Data Architecture documentation for DevExp-DevBox Landing Zone Accelerator --- docs/architecture/02-data-architecture.md | 702 ++++++++++++++++++++++ 1 file changed, 702 insertions(+) create mode 100644 docs/architecture/02-data-architecture.md diff --git a/docs/architecture/02-data-architecture.md b/docs/architecture/02-data-architecture.md new file mode 100644 index 00000000..35412276 --- /dev/null +++ b/docs/architecture/02-data-architecture.md @@ -0,0 +1,702 @@ +# Data Architecture + +> **TOGAF Layer**: Data Architecture +> **Version**: 1.0.0 +> **Last Updated**: January 22, 2026 +> **Author**: DevExp Team + +--- + +## Table of Contents + +- [Data Overview](#data-overview) +- [Configuration Data Model](#configuration-data-model) +- [Secrets Management](#secrets-management) +- [Telemetry & Diagnostics](#telemetry--diagnostics) +- [Data Flow Diagrams](#data-flow-diagrams) +- [Data Governance](#data-governance) +- [Schema Documentation](#schema-documentation) +- [References](#references) +- [Glossary](#glossary) + +--- + +## Data Overview + +The DevExp-DevBox Landing Zone Accelerator manages several categories of data that flow through the system during deployment and runtime operations. Understanding these data types is essential for security, compliance, and operational management. + +### Data Categories + +```mermaid +graph TB + subgraph "Configuration Data" + CD1[Resource Organization
azureResources.yaml] + CD2[Security Settings
security.yaml] + CD3[Workload Config
devcenter.yaml] + end + + subgraph "Secrets & Credentials" + SC1[GitHub PAT
Key Vault Secret] + SC2[Azure AD Tokens
Managed Identity] + SC3[Service Principal
OIDC Federation] + end + + subgraph "Telemetry Data" + TD1[Resource Logs
Log Analytics] + TD2[Metrics
Azure Monitor] + TD3[Diagnostic Data
Azure Diagnostics] + end + + subgraph "State Data" + ST1[Deployment State
azd Environment] + ST2[Resource State
Azure RM] + ST3[RBAC Assignments
Azure AD] + end + + style CD1 fill:#E3F2FD + style CD2 fill:#E3F2FD + style CD3 fill:#E3F2FD + style SC1 fill:#FFEBEE + style SC2 fill:#FFEBEE + style SC3 fill:#FFEBEE + style TD1 fill:#E8F5E9 + style TD2 fill:#E8F5E9 + style TD3 fill:#E8F5E9 + style ST1 fill:#FFF3E0 + style ST2 fill:#FFF3E0 + style ST3 fill:#FFF3E0 +``` + +### Data Classification + +| Data Type | Classification | Sensitivity | Storage Location | Retention | +|-----------|---------------|-------------|------------------|-----------| +| Resource Organization Config | Internal | Low | Git Repository | Version controlled | +| Security Configuration | Confidential | Medium | Git Repository | Version controlled | +| DevCenter Configuration | Internal | Low | Git Repository | Version controlled | +| GitHub PAT Token | Secret | Critical | Azure Key Vault | 7-90 days (soft delete) | +| Managed Identity Tokens | Secret | Critical | Azure AD | Session-based | +| Deployment Logs | Internal | Medium | Log Analytics | 30-90 days | +| Resource Metrics | Internal | Low | Azure Monitor | 93 days | +| Deployment State | Internal | Medium | azd Environment | Until deleted | + +--- + +## Configuration Data Model + +### Overview + +The accelerator uses YAML-based configuration files with JSON Schema validation to define infrastructure settings. Configuration is loaded at deployment time using Bicep's `loadYamlContent()` function. + +### Configuration File Structure + +``` +infra/settings/ +β”œβ”€β”€ resourceOrganization/ +β”‚ β”œβ”€β”€ azureResources.yaml # Landing zone resource groups +β”‚ └── azureResources.schema.json +β”œβ”€β”€ security/ +β”‚ β”œβ”€β”€ security.yaml # Key Vault configuration +β”‚ └── security.schema.json +└── workload/ + β”œβ”€β”€ devcenter.yaml # DevCenter & projects + └── devcenter.schema.json +``` + +### Data Entity Relationship Diagram + +```mermaid +erDiagram + LANDING_ZONES ||--o{ RESOURCE_GROUPS : contains + RESOURCE_GROUPS ||--o{ RESOURCES : hosts + + DEVCENTER ||--o{ PROJECTS : manages + DEVCENTER ||--o{ CATALOGS : syncs + DEVCENTER ||--o{ ENVIRONMENT_TYPES : defines + DEVCENTER ||--|| IDENTITY : has + + PROJECTS ||--o{ POOLS : contains + PROJECTS ||--o{ PROJECT_CATALOGS : syncs + PROJECTS ||--o{ PROJECT_ENV_TYPES : enables + PROJECTS ||--|| NETWORK : uses + PROJECTS ||--|| PROJECT_IDENTITY : has + + IDENTITY ||--o{ ROLE_ASSIGNMENTS : grants + PROJECT_IDENTITY ||--o{ ROLE_ASSIGNMENTS : grants + + KEY_VAULT ||--o{ SECRETS : stores + SECRETS ||--|| CATALOGS : authenticates + SECRETS ||--|| PROJECT_CATALOGS : authenticates + + NETWORK ||--o{ SUBNETS : contains + NETWORK ||--|| NETWORK_CONNECTION : creates + NETWORK_CONNECTION ||--|| DEVCENTER : attaches + + LANDING_ZONES { + string security_name + string monitoring_name + string workload_name + object tags + } + + DEVCENTER { + string name + string catalogItemSyncEnableStatus + string microsoftHostedNetworkEnableStatus + string installAzureMonitorAgentEnableStatus + } + + PROJECTS { + string name + string description + object network + object identity + array pools + array catalogs + array environmentTypes + } + + KEY_VAULT { + string name + boolean enablePurgeProtection + boolean enableSoftDelete + int softDeleteRetentionInDays + boolean enableRbacAuthorization + } + + POOLS { + string name + string imageDefinitionName + string vmSku + } +``` + +### Resource Organization Configuration + +**File**: `infra/settings/resourceOrganization/azureResources.yaml` + +| Property | Type | Description | Example | +|----------|------|-------------|---------| +| `workload.name` | string | Workload resource group name | `devexp-workload` | +| `workload.create` | boolean | Create new or use existing | `true` | +| `workload.tags` | object | Azure resource tags | See tags schema | +| `security.name` | string | Security resource group name | `devexp-security` | +| `security.create` | boolean | Create new or use existing | `true` | +| `monitoring.name` | string | Monitoring resource group name | `devexp-monitoring` | +| `monitoring.create` | boolean | Create new or use existing | `true` | + +**Tags Schema**: + +```yaml +tags: + environment: dev|test|staging|prod + division: string # Business division + team: string # Team name + project: string # Project identifier + costCenter: string # Cost allocation + owner: string # Resource owner + landingZone: string # Landing zone type + resources: string # Resource type +``` + +### Security Configuration + +**File**: `infra/settings/security/security.yaml` + +| Property | Type | Description | Constraints | +|----------|------|-------------|-------------| +| `create` | boolean | Create Key Vault | Required | +| `keyVault.name` | string | Key Vault name prefix | 3-24 chars, alphanumeric | +| `keyVault.description` | string | Purpose description | Optional | +| `keyVault.secretName` | string | Secret name for PAT | Default: `gha-token` | +| `keyVault.enablePurgeProtection` | boolean | Prevent permanent deletion | Recommended: `true` | +| `keyVault.enableSoftDelete` | boolean | Enable recovery period | Recommended: `true` | +| `keyVault.softDeleteRetentionInDays` | integer | Soft delete retention | 7-90 days | +| `keyVault.enableRbacAuthorization` | boolean | Use Azure RBAC | Recommended: `true` | + +### DevCenter Configuration + +**File**: `infra/settings/workload/devcenter.yaml` + +#### Core DevCenter Properties + +| Property | Type | Description | +|----------|------|-------------| +| `name` | string | DevCenter resource name | +| `catalogItemSyncEnableStatus` | Enabled\|Disabled | Catalog sync feature | +| `microsoftHostedNetworkEnableStatus` | Enabled\|Disabled | Microsoft-hosted networking | +| `installAzureMonitorAgentEnableStatus` | Enabled\|Disabled | Azure Monitor agent | +| `identity.type` | SystemAssigned\|UserAssigned | Managed identity type | + +#### Identity & Role Assignments + +```yaml +identity: + type: "SystemAssigned" + roleAssignments: + devCenter: + - id: "b24988ac-6180-42a0-ab88-20f7382dd24c" # Contributor + name: "Contributor" + scope: "Subscription" + - id: "18d7d88d-d35e-4fb5-a5c3-7773c20a72d9" # User Access Admin + name: "User Access Administrator" + scope: "Subscription" + - id: "4633458b-17de-408a-b874-0445c86b69e6" # Key Vault Secrets User + name: "Key Vault Secrets User" + scope: "ResourceGroup" + orgRoleTypes: + - type: DevManager + azureADGroupId: "" + azureADGroupName: "Platform Engineering Team" + azureRBACRoles: + - name: "DevCenter Project Admin" + id: "331c37c6-af14-46d9-b9f4-e1909e1b95a0" + scope: ResourceGroup +``` + +#### Project Configuration + +```yaml +projects: + - name: "eShop" + description: "eShop project" + network: + name: eShop + create: true + resourceGroupName: "eShop-connectivity-RG" + virtualNetworkType: Managed|Unmanaged + addressPrefixes: ["10.0.0.0/16"] + subnets: + - name: eShop-subnet + properties: + addressPrefix: "10.0.1.0/24" + pools: + - name: "backend-engineer" + imageDefinitionName: "eShop-backend-engineer" + vmSku: "general_i_32c128gb512ssd_v2" + - name: "frontend-engineer" + imageDefinitionName: "eShop-frontend-engineer" + vmSku: "general_i_16c64gb256ssd_v2" + catalogs: + - name: "environments" + type: environmentDefinition + sourceControl: gitHub + visibility: private + uri: "https://github.com/org/repo.git" + branch: "main" + path: "/.devcenter/environments" +``` + +--- + +## Secrets Management + +### Secret Types + +| Secret | Purpose | Storage | Rotation | +|--------|---------|---------|----------| +| **GitHub PAT** | Catalog authentication for private repos | Key Vault | Manual (recommended: 90 days) | +| **Azure DevOps PAT** | ADO catalog authentication | Key Vault | Manual (recommended: 90 days) | +| **Service Principal** | CI/CD deployment | GitHub Secrets / Azure DevOps | OIDC (no rotation needed) | + +### Key Vault Architecture + +```mermaid +graph TB + subgraph "Azure Key Vault" + KV[contoso-*****-kv] + SEC1[gha-token
GitHub PAT] + end + + subgraph "Access Patterns" + DC[DevCenter
Managed Identity] + PROJ[Project
Managed Identity] + CICD[CI/CD Pipeline
OIDC] + end + + subgraph "Consumers" + CAT1[DevCenter
Catalogs] + CAT2[Project
Catalogs] + end + + DC -->|Key Vault Secrets User| KV + PROJ -->|Key Vault Secrets User| KV + CICD -->|Key Vault Secrets Officer| KV + + KV --> SEC1 + SEC1 -->|secretIdentifier| CAT1 + SEC1 -->|secretIdentifier| CAT2 + + style KV fill:#0078D4,color:#fff + style SEC1 fill:#D32F2F,color:#fff +``` + +### Secret Lifecycle + +```mermaid +sequenceDiagram + participant Admin as Administrator + participant GH as GitHub + participant CICD as CI/CD Pipeline + participant KV as Key Vault + participant DC as DevCenter + participant Cat as Catalog + + Admin->>GH: Create PAT with repo scope + Admin->>CICD: Store PAT as pipeline secret + CICD->>KV: azd provision (store secret) + KV-->>CICD: Secret URI returned + CICD->>DC: Deploy with secretIdentifier + DC->>Cat: Configure catalog + + loop Catalog Sync + Cat->>KV: Request secret (Managed Identity) + KV-->>Cat: Return PAT + Cat->>GH: Authenticate & sync + GH-->>Cat: Repository content + end +``` + +### Secret Access Patterns + +| Principal | Role | Scope | Purpose | +|-----------|------|-------|---------| +| DevCenter Managed Identity | Key Vault Secrets User | Security RG | Read PAT for catalog sync | +| Project Managed Identity | Key Vault Secrets User | Security RG | Read PAT for project catalogs | +| DevCenter Managed Identity | Key Vault Secrets Officer | Security RG | Manage secrets if needed | +| CI/CD Service Principal | Deployer (custom) | Key Vault | Initial secret provisioning | + +--- + +## Telemetry & Diagnostics + +### Log Analytics Data Collection + +```mermaid +graph LR + subgraph "Data Sources" + DC[DevCenter] + KV[Key Vault] + VNET[Virtual Network] + LA[Log Analytics
Workspace] + end + + subgraph "Log Categories" + LOGS[All Logs
categoryGroup: allLogs] + MET[All Metrics
category: AllMetrics] + end + + subgraph "Analytics" + QRY[KQL Queries] + WBK[Workbooks] + ALR[Alerts] + end + + DC -->|Diagnostic Settings| LOGS + KV -->|Diagnostic Settings| LOGS + VNET -->|Diagnostic Settings| LOGS + + DC -->|Diagnostic Settings| MET + KV -->|Diagnostic Settings| MET + VNET -->|Diagnostic Settings| MET + + LOGS --> LA + MET --> LA + + LA --> QRY + LA --> WBK + LA --> ALR + + style LA fill:#68217A,color:#fff +``` + +### Diagnostic Settings Configuration + +| Resource | Log Categories | Metrics | Destination | +|----------|---------------|---------|-------------| +| Log Analytics Workspace | allLogs | AllMetrics | Self (workspace) | +| Key Vault | allLogs | AllMetrics | Log Analytics | +| DevCenter | allLogs | AllMetrics | Log Analytics | +| Virtual Network | allLogs | AllMetrics | Log Analytics | + +### Telemetry Data Schema + +**DevCenter Logs**: + +``` +AzureDiagnostics +| where ResourceProvider == "MICROSOFT.DEVCENTER" +| project TimeGenerated, OperationName, ResultType, CallerIpAddress +``` + +**Key Vault Logs**: + +``` +AzureDiagnostics +| where ResourceProvider == "MICROSOFT.KEYVAULT" +| project TimeGenerated, OperationName, ResultType, identity_claim_upn_s +``` + +--- + +## Data Flow Diagrams + +### Configuration Loading Flow + +```mermaid +flowchart TB + subgraph "Source Control" + YAML1[azureResources.yaml] + YAML2[security.yaml] + YAML3[devcenter.yaml] + end + + subgraph "Bicep Compilation" + MAIN[main.bicep] + LOAD1[loadYamlContent
resourceOrganization] + LOAD2[loadYamlContent
security] + LOAD3[loadYamlContent
workload] + end + + subgraph "Azure Resources" + RG1[Security RG] + RG2[Monitoring RG] + RG3[Workload RG] + end + + YAML1 --> LOAD1 + YAML2 --> LOAD2 + YAML3 --> LOAD3 + + MAIN --> LOAD1 + MAIN --> LOAD2 + MAIN --> LOAD3 + + LOAD1 -->|createResourceGroupName| RG1 + LOAD1 -->|createResourceGroupName| RG2 + LOAD1 -->|createResourceGroupName| RG3 + + LOAD2 -->|keyVault config| RG1 + LOAD3 -->|devCenter config| RG3 + + style MAIN fill:#FF6B35,color:#fff +``` + +### Secrets Flow Diagram + +```mermaid +flowchart TB + subgraph "Secret Injection" + ENV[Environment Variable
KEY_VAULT_SECRET] + AZD[azd provision] + PARAM[@secure param
secretValue] + end + + subgraph "Secret Storage" + SEC[security.bicep] + SECMOD[secret.bicep] + KV[(Key Vault
gha-token)] + end + + subgraph "Secret Consumption" + URI[secretIdentifier
URI] + CAT[catalog.bicep] + PCAT[projectCatalog.bicep] + end + + ENV --> AZD + AZD --> PARAM + PARAM --> SEC + SEC --> SECMOD + SECMOD --> KV + + KV -->|properties.secretUri| URI + URI --> CAT + URI --> PCAT + + style KV fill:#D32F2F,color:#fff + style ENV fill:#FFC107,color:#000 +``` + +### Deployment Data Flow + +```mermaid +sequenceDiagram + participant Git as Git Repository + participant AZD as Azure Developer CLI + participant ARM as Azure Resource Manager + participant RG as Resource Groups + participant Res as Azure Resources + participant LA as Log Analytics + + Git->>AZD: Clone & load YAML configs + AZD->>AZD: Compile Bicep templates + AZD->>ARM: Submit deployment + ARM->>RG: Create resource groups + + par Parallel Deployment + ARM->>Res: Deploy Log Analytics + ARM->>Res: Deploy Key Vault + ARM->>Res: Deploy DevCenter + end + + Res->>LA: Configure diagnostics + Res-->>AZD: Return outputs + AZD-->>Git: Store in azd environment +``` + +--- + +## Data Governance + +### Data Classification Matrix + +| Data Element | Classification | Owner | Access Control | Encryption | +|--------------|---------------|-------|----------------|------------| +| YAML Configuration | Internal | Platform Team | Git branch protection | At rest (Git LFS optional) | +| JSON Schemas | Public | Platform Team | Read-only | None required | +| PAT Tokens | Secret | Security Team | Key Vault RBAC | At rest + in transit | +| Deployment Logs | Confidential | Operations | Log Analytics RBAC | At rest | +| Resource Metrics | Internal | Operations | Azure Monitor RBAC | At rest | +| Bicep Templates | Internal | Platform Team | Git branch protection | At rest | + +### Data Retention Policies + +| Data Type | Retention Period | Justification | Archive Location | +|-----------|------------------|---------------|------------------| +| Deployment Logs | 90 days | Compliance/troubleshooting | Log Analytics | +| Key Vault Soft Delete | 7-90 days | Recovery window | Key Vault | +| Resource Metrics | 93 days | Azure default | Azure Monitor | +| Git History | Indefinite | Version control | Git repository | +| azd Environment State | Until deleted | Active deployments | Local/.azure | + +### Compliance Considerations + +| Requirement | Implementation | Evidence | +|-------------|----------------|----------| +| **Data Encryption at Rest** | Azure Storage encryption, Key Vault encryption | Azure Security Center | +| **Data Encryption in Transit** | TLS 1.2+ for all Azure services | Network policies | +| **Access Logging** | Key Vault audit logs, Azure Activity Log | Log Analytics queries | +| **Data Residency** | Region-specific deployment | Bicep location parameter | +| **Right to Erasure** | Key Vault purge, resource deletion | Deletion scripts | + +--- + +## Schema Documentation + +### JSON Schema References + +#### Security Schema (`security.schema.json`) + +```json +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "Azure Key Vault Security Configuration", + "type": "object", + "required": ["create", "keyVault"], + "properties": { + "create": { "type": "boolean" }, + "keyVault": { + "type": "object", + "required": ["name", "tags"], + "properties": { + "name": { + "type": "string", + "pattern": "^[a-zA-Z0-9-]{3,24}$", + "minLength": 3, + "maxLength": 24 + }, + "enablePurgeProtection": { "type": "boolean" }, + "enableSoftDelete": { "type": "boolean" }, + "softDeleteRetentionInDays": { + "type": "integer", + "minimum": 7, + "maximum": 90 + }, + "enableRbacAuthorization": { "type": "boolean" } + } + } + } +} +``` + +#### DevCenter Schema (`devcenter.schema.json`) - Key Definitions + +```json +{ + "definitions": { + "roleAssignment": { + "type": "object", + "properties": { + "id": { "type": "string", "pattern": "^[a-fA-F0-9-]{36}$" }, + "name": { "type": "string" }, + "scope": { "enum": ["Subscription", "ResourceGroup", "Project"] } + } + }, + "catalog": { + "type": "object", + "required": ["name", "type", "uri"], + "properties": { + "name": { "type": "string" }, + "type": { "enum": ["gitHub", "adoGit", "environmentDefinition", "imageDefinition"] }, + "visibility": { "enum": ["public", "private"] }, + "uri": { "type": "string", "format": "uri" }, + "branch": { "type": "string" }, + "path": { "type": "string" } + } + }, + "pool": { + "type": "object", + "required": ["name", "imageDefinitionName", "vmSku"], + "properties": { + "name": { "type": "string" }, + "imageDefinitionName": { "type": "string" }, + "vmSku": { "type": "string" } + } + } + } +} +``` + +### Schema Validation + +Schemas are validated at authoring time using the `yaml-language-server` directive: + +```yaml +# yaml-language-server: $schema=./security.schema.json +``` + +--- + +## References + +### Internal Documents + +- [Business Architecture](01-business-architecture.md) - Business context and stakeholders +- [Application Architecture](03-application-architecture.md) - Module design and Bicep structure +- [Technology Architecture](04-technology-architecture.md) - Azure services and infrastructure +- [Security Architecture](05-security-architecture.md) - Security controls and secrets management + +### External References + +- [Azure Key Vault Best Practices](https://learn.microsoft.com/en-us/azure/key-vault/general/best-practices) +- [Log Analytics Workspace Design](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/workspace-design) +- [Bicep loadYamlContent Function](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/bicep-functions-files#loadyamlcontent) +- [JSON Schema Specification](https://json-schema.org/specification.html) + +--- + +## Glossary + +| Term | Definition | +|------|------------| +| **loadYamlContent()** | Bicep function that loads YAML files as objects at compile time | +| **Secret Identifier** | URI to a specific version of a secret in Azure Key Vault | +| **Diagnostic Settings** | Azure configuration for routing logs and metrics to destinations | +| **Soft Delete** | Key Vault feature allowing recovery of deleted secrets within retention period | +| **Purge Protection** | Key Vault feature preventing permanent deletion during soft delete period | +| **RBAC Authorization** | Key Vault access control using Azure Role-Based Access Control instead of access policies | + +--- + +*Document generated as part of TOGAF Architecture Documentation for DevExp-DevBox Landing Zone Accelerator* From 48015f7f6d887f86b607d0ff766f583e58c25474 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 15:56:14 -0500 Subject: [PATCH 26/49] Add Application Architecture documentation for DevExp-DevBox Landing Zone Accelerator --- .../03-application-architecture.md | 1122 +++++++++++++++++ 1 file changed, 1122 insertions(+) create mode 100644 docs/architecture/03-application-architecture.md diff --git a/docs/architecture/03-application-architecture.md b/docs/architecture/03-application-architecture.md new file mode 100644 index 00000000..344ef10d --- /dev/null +++ b/docs/architecture/03-application-architecture.md @@ -0,0 +1,1122 @@ +# Application Architecture + +> **TOGAF Layer**: Application Architecture +> **Version**: 1.0.0 +> **Last Updated**: January 22, 2026 +> **Author**: DevExp Team + +--- + +## Table of Contents + +- [Architecture Overview](#architecture-overview) +- [Module Catalog](#module-catalog) +- [Module Dependencies](#module-dependencies) +- [Deployment Orchestration](#deployment-orchestration) +- [Interface Contracts](#interface-contracts) +- [Design Patterns](#design-patterns) +- [Extension Points](#extension-points) +- [References](#references) +- [Glossary](#glossary) + +--- + +## Architecture Overview + +The DevExp-DevBox Landing Zone Accelerator implements a **modular Infrastructure-as-Code (IaC)** architecture using Azure Bicep. The solution follows the **Landing Zone Accelerator** pattern with four distinct zones, each responsible for specific infrastructure concerns. + +### Landing Zone Pattern + +```mermaid +graph TB + subgraph "Subscription Scope" + MAIN[main.bicep
Orchestrator] + end + + subgraph "Security Landing Zone" + SECRG[Security RG] + SEC[security.bicep] + KV[keyVault.bicep] + SECRET[secret.bicep] + end + + subgraph "Monitoring Landing Zone" + MONRG[Monitoring RG] + LA[logAnalytics.bicep] + end + + subgraph "Workload Landing Zone" + WRKRG[Workload RG] + WRK[workload.bicep] + + subgraph "Core" + DC[devCenter.bicep] + CAT[catalog.bicep] + ENV[environmentType.bicep] + end + + subgraph "Project" + PROJ[project.bicep] + PCAT[projectCatalog.bicep] + PENV[projectEnvironmentType.bicep] + POOL[projectPool.bicep] + end + end + + subgraph "Connectivity Landing Zone" + CONRG[Connectivity RG] + CON[connectivity.bicep] + VNET[vnet.bicep] + NC[networkConnection.bicep] + end + + MAIN --> SECRG + MAIN --> MONRG + MAIN --> WRKRG + + SECRG --> SEC + SEC --> KV + SEC --> SECRET + + MONRG --> LA + + WRKRG --> WRK + WRK --> DC + DC --> CAT + DC --> ENV + WRK --> PROJ + PROJ --> PCAT + PROJ --> PENV + PROJ --> POOL + PROJ --> CON + CON --> CONRG + CON --> VNET + VNET --> NC + + style MAIN fill:#1976D2,color:#fff + style SEC fill:#D32F2F,color:#fff + style LA fill:#388E3C,color:#fff + style WRK fill:#F57C00,color:#fff + style CON fill:#7B1FA2,color:#fff +``` + +### Deployment Scopes + +| Zone | Bicep Scope | Resource Group | Purpose | +|------|-------------|----------------|---------| +| **Orchestrator** | `subscription` | Creates RGs | Entry point, resource group creation | +| **Security** | `resourceGroup` | devexp-security-* | Key Vault, secrets management | +| **Monitoring** | `resourceGroup` | devexp-monitoring-* | Log Analytics, diagnostics | +| **Workload** | `resourceGroup` | devexp-workload-* | DevCenter, projects, pools | +| **Connectivity** | `resourceGroup` | *-connectivity-RG | Virtual networks, network connections | + +--- + +## Module Catalog + +### Entry Point Module + +#### Module: main.bicep + +- **Path**: `infra/main.bicep` +- **Scope**: `subscription` +- **Purpose**: Subscription-level orchestrator that creates resource groups and invokes landing zone modules + +**Inputs**: + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `location` | string | Yes | Azure region (validated against allowed list) | +| `secretValue` | secureString | Yes | GitHub/ADO PAT for catalog authentication | +| `environmentName` | string | Yes | Environment identifier (2-10 chars) | + +**Outputs**: + +| Output | Type | Description | +|--------|------|-------------| +| `SECURITY_AZURE_RESOURCE_GROUP_NAME` | string | Security RG name | +| `MONITORING_AZURE_RESOURCE_GROUP_NAME` | string | Monitoring RG name | +| `WORKLOAD_AZURE_RESOURCE_GROUP_NAME` | string | Workload RG name | +| `AZURE_LOG_ANALYTICS_WORKSPACE_ID` | string | Log Analytics resource ID | +| `AZURE_LOG_ANALYTICS_WORKSPACE_NAME` | string | Log Analytics workspace name | +| `AZURE_KEY_VAULT_NAME` | string | Key Vault name | +| `AZURE_KEY_VAULT_SECRET_IDENTIFIER` | string | Secret URI | +| `AZURE_KEY_VAULT_ENDPOINT` | string | Key Vault URI | +| `AZURE_DEV_CENTER_NAME` | string | DevCenter name | +| `AZURE_DEV_CENTER_PROJECTS` | array | List of project names | + +**Dependencies**: None (entry point) + +**Dependents**: All other modules + +--- + +### Management Modules + +#### Module: logAnalytics.bicep + +- **Path**: `src/management/logAnalytics.bicep` +- **Scope**: `resourceGroup` +- **Purpose**: Deploys Log Analytics workspace for centralized monitoring + +**Inputs**: + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `name` | string | Yes | - | Workspace name prefix | +| `location` | string | No | RG location | Azure region | +| `tags` | object | No | `{}` | Resource tags | +| `sku` | string | No | `PerGB2018` | Pricing tier | + +**Outputs**: + +| Output | Type | Description | +|--------|------|-------------| +| `AZURE_LOG_ANALYTICS_WORKSPACE_ID` | string | Workspace resource ID | +| `AZURE_LOG_ANALYTICS_WORKSPACE_NAME` | string | Workspace name (with unique suffix) | + +**Dependencies**: None + +**Dependents**: security.bicep, workload.bicep, connectivity.bicep (all diagnostic settings) + +--- + +### Security Modules + +#### Module: security.bicep + +- **Path**: `src/security/security.bicep` +- **Scope**: `resourceGroup` +- **Purpose**: Orchestrates security resources deployment (Key Vault and secrets) + +**Inputs**: + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `tags` | object | Yes | Resource tags | +| `secretValue` | secureString | Yes | PAT token value | +| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | + +**Outputs**: + +| Output | Type | Description | +|--------|------|-------------| +| `AZURE_KEY_VAULT_NAME` | string | Key Vault name | +| `AZURE_KEY_VAULT_SECRET_IDENTIFIER` | string | Secret URI for catalog auth | +| `AZURE_KEY_VAULT_ENDPOINT` | string | Key Vault vault URI | + +**Dependencies**: logAnalytics.bicep + +**Dependents**: workload.bicep + +--- + +#### Module: keyVault.bicep + +- **Path**: `src/security/keyVault.bicep` +- **Scope**: `resourceGroup` +- **Purpose**: Deploys Azure Key Vault with security configurations + +**Inputs**: + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `keyvaultSettings` | object | Yes | Configuration from security.yaml | +| `location` | string | No | Azure region | +| `tags` | object | Yes | Resource tags | +| `unique` | string | No | Unique suffix for naming | + +**Outputs**: + +| Output | Type | Description | +|--------|------|-------------| +| `AZURE_KEY_VAULT_NAME` | string | Full Key Vault name | +| `AZURE_KEY_VAULT_ENDPOINT` | string | Key Vault URI | + +**Dependencies**: None + +**Dependents**: secret.bicep + +--- + +#### Module: secret.bicep + +- **Path**: `src/security/secret.bicep` +- **Scope**: `resourceGroup` +- **Purpose**: Creates secrets in Key Vault and configures diagnostics + +**Inputs**: + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `name` | string | Yes | Secret name | +| `secretValue` | secureString | Yes | Secret value | +| `keyVaultName` | string | Yes | Parent Key Vault name | +| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | + +**Outputs**: + +| Output | Type | Description | +|--------|------|-------------| +| `AZURE_KEY_VAULT_SECRET_IDENTIFIER` | string | Secret URI | + +**Dependencies**: keyVault.bicep, logAnalytics.bicep + +**Dependents**: catalog.bicep, projectCatalog.bicep + +--- + +### Workload Modules + +#### Module: workload.bicep + +- **Path**: `src/workload/workload.bicep` +- **Scope**: `resourceGroup` +- **Purpose**: Orchestrates DevCenter and project deployments + +**Inputs**: + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | +| `secretIdentifier` | secureString | Yes | Key Vault secret URI | +| `securityResourceGroupName` | string | Yes | Security RG for RBAC | +| `location` | string | No | Azure region | + +**Outputs**: + +| Output | Type | Description | +|--------|------|-------------| +| `AZURE_DEV_CENTER_NAME` | string | DevCenter name | +| `AZURE_DEV_CENTER_PROJECTS` | array | Project names array | + +**Dependencies**: security.bicep, logAnalytics.bicep + +**Dependents**: None (terminal module) + +--- + +#### Module: devCenter.bicep + +- **Path**: `src/workload/core/devCenter.bicep` +- **Scope**: `resourceGroup` +- **Purpose**: Deploys Azure DevCenter with identity and role assignments + +**Inputs**: + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `config` | DevCenterConfig | Yes | DevCenter configuration object | +| `catalogs` | array | Yes | Catalog configurations | +| `environmentTypes` | array | Yes | Environment type definitions | +| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | +| `secretIdentifier` | secureString | Yes | Secret URI for catalogs | +| `securityResourceGroupName` | string | Yes | Security RG name | +| `location` | string | No | Azure region | + +**Outputs**: + +| Output | Type | Description | +|--------|------|-------------| +| `AZURE_DEV_CENTER_NAME` | string | DevCenter name | + +**Dependencies**: logAnalytics.bicep, secret.bicep + +**Dependents**: project.bicep, catalog.bicep, environmentType.bicep + +--- + +#### Module: catalog.bicep + +- **Path**: `src/workload/core/catalog.bicep` +- **Scope**: `resourceGroup` +- **Purpose**: Configures DevCenter catalogs for image/environment definitions + +**Inputs**: + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `devCenterName` | string | Yes | Parent DevCenter name | +| `catalogConfig` | Catalog | Yes | Catalog configuration | +| `secretIdentifier` | secureString | Yes | Secret URI for private repos | + +**Type Definition - Catalog**: + +```bicep +type Catalog = { + name: string + type: 'gitHub' | 'adoGit' + visibility: 'public' | 'private' + uri: string + branch: string + path: string +} +``` + +**Outputs**: + +| Output | Type | Description | +|--------|------|-------------| +| `AZURE_DEV_CENTER_CATALOG_NAME` | string | Catalog name | +| `AZURE_DEV_CENTER_CATALOG_ID` | string | Catalog resource ID | +| `AZURE_DEV_CENTER_CATALOG_TYPE` | string | Catalog type | + +**Dependencies**: devCenter.bicep, secret.bicep + +**Dependents**: None + +--- + +#### Module: environmentType.bicep + +- **Path**: `src/workload/core/environmentType.bicep` +- **Scope**: `resourceGroup` +- **Purpose**: Defines environment types (dev, staging, UAT) in DevCenter + +**Inputs**: + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `devCenterName` | string | Yes | Parent DevCenter name | +| `environmentConfig` | EnvironmentType | Yes | Environment type config | + +**Outputs**: + +| Output | Type | Description | +|--------|------|-------------| +| `environmentTypeName` | string | Environment type name | +| `environmentTypeId` | string | Environment type resource ID | + +**Dependencies**: devCenter.bicep + +**Dependents**: projectEnvironmentType.bicep + +--- + +#### Module: project.bicep + +- **Path**: `src/workload/project/project.bicep` +- **Scope**: `resourceGroup` +- **Purpose**: Deploys DevCenter projects with pools, catalogs, and networking + +**Inputs**: + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `devCenterName` | string | Yes | Parent DevCenter name | +| `name` | string | Yes | Project name | +| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | +| `projectDescription` | string | Yes | Project description | +| `catalogs` | object[] | Yes | Project catalog configurations | +| `projectEnvironmentTypes` | array | Yes | Environment types for project | +| `projectPools` | array | Yes | Pool configurations | +| `projectNetwork` | object | Yes | Network configuration | +| `secretIdentifier` | secureString | Yes | Secret URI for catalogs | +| `securityResourceGroupName` | string | Yes | Security RG name | +| `identity` | Identity | Yes | Managed identity config | +| `tags` | object | No | Resource tags | +| `location` | string | No | Azure region | + +**Outputs**: + +| Output | Type | Description | +|--------|------|-------------| +| `AZURE_PROJECT_NAME` | string | Project name | +| `AZURE_PROJECT_ID` | string | Project resource ID | + +**Dependencies**: devCenter.bicep + +**Dependents**: projectCatalog.bicep, projectPool.bicep, projectEnvironmentType.bicep, connectivity.bicep + +--- + +#### Module: projectPool.bicep + +- **Path**: `src/workload/project/projectPool.bicep` +- **Scope**: `resourceGroup` +- **Purpose**: Deploys Dev Box pools with specific VM configurations + +**Inputs**: + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `name` | string | Yes | Pool name | +| `location` | string | No | Azure region | +| `catalogs` | Catalog[] | Yes | Catalog references | +| `imageDefinitionName` | string | Yes | Image definition name | +| `networkConnectionName` | string | Yes | Network connection name | +| `vmSku` | string | Yes | VM SKU (e.g., `general_i_32c128gb512ssd_v2`) | +| `networkType` | string | Yes | `Managed` or `Unmanaged` | +| `projectName` | string | Yes | Parent project name | + +**Dependencies**: project.bicep, connectivity.bicep, projectCatalog.bicep + +**Dependents**: None + +--- + +### Connectivity Modules + +#### Module: connectivity.bicep + +- **Path**: `src/connectivity/connectivity.bicep` +- **Scope**: `resourceGroup` +- **Purpose**: Orchestrates network infrastructure for Dev Box connectivity + +**Inputs**: + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `devCenterName` | string | Yes | DevCenter name | +| `projectNetwork` | object | Yes | Network configuration | +| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | +| `location` | string | Yes | Azure region | + +**Outputs**: + +| Output | Type | Description | +|--------|------|-------------| +| `networkConnectionName` | string | Network connection name | +| `networkType` | string | `Managed` or `Unmanaged` | + +**Dependencies**: devCenter.bicep, logAnalytics.bicep + +**Dependents**: projectPool.bicep + +--- + +#### Module: vnet.bicep + +- **Path**: `src/connectivity/vnet.bicep` +- **Scope**: `resourceGroup` +- **Purpose**: Deploys virtual networks and subnets + +**Inputs**: + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | +| `location` | string | Yes | Azure region | +| `tags` | object | No | Resource tags | +| `settings` | object | Yes | Network settings from YAML | + +**Outputs**: + +| Output | Type | Description | +|--------|------|-------------| +| `AZURE_VIRTUAL_NETWORK` | object | VNet details (name, RG, subnets) | + +**Dependencies**: logAnalytics.bicep + +**Dependents**: networkConnection.bicep + +--- + +#### Module: networkConnection.bicep + +- **Path**: `src/connectivity/networkConnection.bicep` +- **Scope**: `resourceGroup` +- **Purpose**: Creates DevCenter network connections for Dev Box + +**Inputs**: + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `name` | string | Yes | Connection name | +| `devCenterName` | string | Yes | DevCenter name | +| `subnetId` | string | Yes | Subnet resource ID | +| `location` | string | No | Azure region | +| `tags` | object | No | Resource tags | + +**Outputs**: + +| Output | Type | Description | +|--------|------|-------------| +| `vnetAttachmentName` | string | Attached network name | +| `networkConnectionId` | string | Network connection ID | +| `attachedNetworkId` | string | Attached network resource ID | +| `networkConnectionName` | string | Network connection name | + +**Dependencies**: vnet.bicep, devCenter.bicep + +**Dependents**: projectPool.bicep + +--- + +### Identity Modules + +#### Module: devCenterRoleAssignment.bicep + +- **Path**: `src/identity/devCenterRoleAssignment.bicep` +- **Scope**: `subscription` +- **Purpose**: Assigns RBAC roles to DevCenter managed identity at subscription scope + +**Inputs**: + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `id` | string | Yes | Role definition GUID | +| `principalId` | string | Yes | DevCenter managed identity | +| `principalType` | string | No | Default: `ServicePrincipal` | +| `scope` | string | Yes | `Subscription` or `ResourceGroup` | + +**Outputs**: + +| Output | Type | Description | +|--------|------|-------------| +| `roleAssignmentId` | string | Role assignment ID | +| `scope` | string | Assignment scope | + +--- + +#### Module: projectIdentityRoleAssignment.bicep + +- **Path**: `src/identity/projectIdentityRoleAssignment.bicep` +- **Scope**: `resourceGroup` +- **Purpose**: Assigns RBAC roles to project identities and Azure AD groups + +**Inputs**: + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `projectName` | string | Yes | Project name | +| `principalId` | string | Yes | Principal object ID | +| `roles` | array | Yes | Role definitions to assign | +| `principalType` | string | Yes | `User`, `Group`, or `ServicePrincipal` | + +**Outputs**: + +| Output | Type | Description | +|--------|------|-------------| +| `roleAssignmentIds` | array | Created role assignment details | +| `projectId` | string | Project resource ID | + +--- + +#### Module: orgRoleAssignment.bicep + +- **Path**: `src/identity/orgRoleAssignment.bicep` +- **Scope**: `resourceGroup` +- **Purpose**: Assigns RBAC roles to organizational Azure AD groups + +**Inputs**: + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `principalId` | string | Yes | Azure AD group object ID | +| `roles` | array | Yes | Role definitions to assign | +| `principalType` | string | No | Default: `Group` | + +--- + +## Module Dependencies + +### Dependency Graph + +```mermaid +graph TB + subgraph "Entry Point" + MAIN[main.bicep] + end + + subgraph "Tier 1 - Foundation" + LA[logAnalytics.bicep] + end + + subgraph "Tier 2 - Security" + SEC[security.bicep] + KV[keyVault.bicep] + SECRET[secret.bicep] + end + + subgraph "Tier 3 - Workload Core" + WRK[workload.bicep] + DC[devCenter.bicep] + CAT[catalog.bicep] + ENV[environmentType.bicep] + end + + subgraph "Tier 4 - Project Resources" + PROJ[project.bicep] + PCAT[projectCatalog.bicep] + PENV[projectEnvironmentType.bicep] + end + + subgraph "Tier 5 - Connectivity & Pools" + CON[connectivity.bicep] + VNET[vnet.bicep] + NC[networkConnection.bicep] + POOL[projectPool.bicep] + end + + subgraph "Cross-Cutting - Identity" + DCRA[devCenterRoleAssignment.bicep] + PIRA[projectIdentityRoleAssignment.bicep] + ORA[orgRoleAssignment.bicep] + end + + MAIN --> LA + MAIN --> SEC + MAIN --> WRK + + SEC --> KV + SEC --> SECRET + SECRET -.->|logAnalyticsId| LA + + WRK --> DC + WRK --> PROJ + + DC --> CAT + DC --> ENV + DC --> DCRA + DC --> ORA + DC -.->|logAnalyticsId| LA + DC -.->|secretIdentifier| SECRET + + PROJ --> PCAT + PROJ --> PENV + PROJ --> CON + PROJ --> POOL + PROJ --> PIRA + + CON --> VNET + VNET --> NC + NC -.->|devCenterName| DC + + POOL -.->|networkConnectionName| CON + POOL -.->|catalogs| PCAT + + PCAT -.->|secretIdentifier| SECRET + + style MAIN fill:#1976D2,color:#fff + style LA fill:#388E3C,color:#fff + style SEC fill:#D32F2F,color:#fff + style DC fill:#F57C00,color:#fff +``` + +### Dependency Matrix + +| Module | Depends On | Required By | +|--------|-----------|-------------| +| main.bicep | - | All modules | +| logAnalytics.bicep | main.bicep | security, devCenter, vnet, secret | +| security.bicep | main.bicep, logAnalytics | workload | +| keyVault.bicep | security | secret | +| secret.bicep | keyVault, logAnalytics | catalog, projectCatalog | +| workload.bicep | main.bicep, security, logAnalytics | - | +| devCenter.bicep | workload, logAnalytics, secret | project, catalog, environmentType | +| catalog.bicep | devCenter, secret | - | +| environmentType.bicep | devCenter | projectEnvironmentType | +| project.bicep | devCenter | projectCatalog, projectPool, projectEnvironmentType | +| projectPool.bicep | project, connectivity, projectCatalog | - | +| connectivity.bicep | devCenter, logAnalytics | projectPool | +| vnet.bicep | logAnalytics | networkConnection | +| networkConnection.bicep | vnet, devCenter | connectivity | + +--- + +## Deployment Orchestration + +### Deployment Sequence Diagram + +```mermaid +sequenceDiagram + participant AZD as Azure Developer CLI + participant ARM as Azure Resource Manager + participant RG as Resource Groups + participant MON as Monitoring Zone + participant SEC as Security Zone + participant WRK as Workload Zone + participant CON as Connectivity Zone + + AZD->>ARM: Deploy main.bicep (subscription scope) + + ARM->>RG: Create Security RG + ARM->>RG: Create Monitoring RG + ARM->>RG: Create Workload RG + + ARM->>MON: Deploy logAnalytics.bicep + MON-->>ARM: Return workspaceId + + ARM->>SEC: Deploy security.bicep + SEC->>SEC: Deploy keyVault.bicep + SEC->>SEC: Deploy secret.bicep + SEC-->>ARM: Return secretIdentifier + + ARM->>WRK: Deploy workload.bicep + WRK->>WRK: Deploy devCenter.bicep + + par RBAC Assignments + WRK->>WRK: devCenterRoleAssignment (subscription) + WRK->>WRK: devCenterRoleAssignmentRG (security RG) + WRK->>WRK: orgRoleAssignment + end + + par DevCenter Resources + WRK->>WRK: Deploy catalog.bicep + WRK->>WRK: Deploy environmentType.bicep + end + + loop For Each Project + WRK->>WRK: Deploy project.bicep + + par Project Resources + WRK->>WRK: projectCatalog.bicep + WRK->>WRK: projectEnvironmentType.bicep + WRK->>WRK: projectIdentityRoleAssignment + end + + WRK->>CON: Deploy connectivity.bicep + CON->>CON: Create connectivity RG + CON->>CON: Deploy vnet.bicep + CON->>CON: Deploy networkConnection.bicep + CON-->>WRK: Return networkConnectionName + + WRK->>WRK: Deploy projectPool.bicep + end + + ARM-->>AZD: Deployment Complete + Outputs +``` + +### Deployment Configuration + +**azure.yaml** (azd configuration): + +```yaml +name: ContosoDevExp + +hooks: + preprovision: + shell: sh + continueOnError: false + interactive: true + run: | + ./setup.sh -e ${AZURE_ENV_NAME} -s ${SOURCE_CONTROL_PLATFORM} +``` + +### Environment Variables + +| Variable | Purpose | Source | +|----------|---------|--------| +| `AZURE_ENV_NAME` | Environment name | User input / CI/CD | +| `AZURE_LOCATION` | Azure region | User input / CI/CD | +| `KEY_VAULT_SECRET` | PAT token value | GitHub Secret / ADO Variable | +| `SOURCE_CONTROL_PLATFORM` | `github` or `adogit` | User selection | +| `AZURE_SUBSCRIPTION_ID` | Target subscription | Azure login | + +--- + +## Interface Contracts + +### Module Parameter Standards + +All modules follow consistent parameter patterns: + +```bicep +// Required parameters +@description('Clear description of purpose') +param requiredParam string + +// Secure parameters +@description('Sensitive data - stored securely') +@secure() +param secretParam string + +// Optional with defaults +@description('Optional parameter with sensible default') +param optionalParam string = 'default' + +// Validated parameters +@description('Parameter with validation') +@allowed(['option1', 'option2']) +param validatedParam string + +// Length-validated strings +@minLength(3) +@maxLength(24) +param constrainedParam string +``` + +### Output Standards + +```bicep +// All outputs use SCREAMING_SNAKE_CASE for azd integration +@description('Clear description of output value') +output AZURE_RESOURCE_NAME string = resource.name + +@description('Resource ID for downstream modules') +output AZURE_RESOURCE_ID string = resource.id +``` + +### Type Definitions + +The accelerator uses custom Bicep types for validation: + +```bicep +// Status type for feature toggles +type Status = 'Enabled' | 'Disabled' + +// Identity configuration +type Identity = { + type: 'SystemAssigned' | 'UserAssigned' + roleAssignments: RoleAssignment +} + +// RBAC role definition +type AzureRBACRole = { + id: string + name: string + scope: 'Subscription' | 'ResourceGroup' | 'Project' +} + +// Catalog configuration +type Catalog = { + name: string + type: 'gitHub' | 'adoGit' | 'environmentDefinition' | 'imageDefinition' + visibility: 'public' | 'private' + uri: string + branch: string + path: string +} +``` + +--- + +## Design Patterns + +### Pattern 1: Modular Landing Zone Design + +**Description**: Each landing zone (Security, Monitoring, Workload, Connectivity) is implemented as independent, reusable modules. + +**Benefits**: + +- Clear separation of concerns +- Independent scaling and updates +- Easier testing and validation +- Team ownership boundaries + +**Implementation**: + +``` +src/ +β”œβ”€β”€ security/ β†’ Security Landing Zone +β”œβ”€β”€ management/ β†’ Monitoring Landing Zone +β”œβ”€β”€ workload/ β†’ Workload Landing Zone +└── connectivity/ β†’ Connectivity Landing Zone +``` + +--- + +### Pattern 2: Declarative Configuration + +**Description**: Infrastructure configuration is externalized to YAML files with JSON Schema validation. + +**Benefits**: + +- Configuration-as-code +- IDE autocomplete and validation +- Environment-specific overrides +- Non-developer friendly editing + +**Implementation**: + +```yaml +# yaml-language-server: $schema=./security.schema.json +create: true +keyVault: + name: contoso + enablePurgeProtection: true +``` + +--- + +### Pattern 3: RBAC Separation + +**Description**: Role assignments are implemented in dedicated identity modules with scope-specific deployments. + +**Benefits**: + +- Least privilege enforcement +- Clear audit trail +- Reusable role assignment logic +- Scope-appropriate permissions + +**Implementation**: + +``` +src/identity/ +β”œβ”€β”€ devCenterRoleAssignment.bicep β†’ Subscription scope +β”œβ”€β”€ devCenterRoleAssignmentRG.bicep β†’ Resource group scope +β”œβ”€β”€ projectIdentityRoleAssignment.bicep β†’ Project scope +└── orgRoleAssignment.bicep β†’ Organization groups +``` + +--- + +### Pattern 4: Conditional Resource Creation + +**Description**: Resources can be conditionally created or referenced as existing based on configuration. + +**Benefits**: + +- Support for brownfield deployments +- Resource reuse across environments +- Flexible deployment scenarios + +**Implementation**: + +```bicep +// Create new or reference existing Key Vault +resource keyVault 'Microsoft.KeyVault/vaults@...' = if (settings.create) { ... } +resource existingKeyVault 'Microsoft.KeyVault/vaults@...' existing = if (!settings.create) { ... } + +// Output appropriate reference +output name string = settings.create ? keyVault.name : existingKeyVault.name +``` + +--- + +### Pattern 5: Diagnostic Settings Integration + +**Description**: Every resource that supports diagnostics is configured to send logs/metrics to Log Analytics. + +**Benefits**: + +- Centralized observability +- Consistent logging across resources +- Compliance and audit support + +**Implementation**: + +```bicep +resource diagnosticSettings 'Microsoft.Insights/diagnosticSettings@...' = { + scope: targetResource + properties: { + workspaceId: logAnalyticsId + logs: [{ categoryGroup: 'allLogs', enabled: true }] + metrics: [{ category: 'AllMetrics', enabled: true }] + } +} +``` + +--- + +## Extension Points + +### Adding a New Project + +1. Edit `infra/settings/workload/devcenter.yaml`: + +```yaml +projects: + - name: "newProject" + description: "New project description" + network: + name: newProject + create: true + resourceGroupName: "newProject-connectivity-RG" + virtualNetworkType: Managed + addressPrefixes: ["10.1.0.0/16"] + subnets: + - name: newProject-subnet + properties: + addressPrefix: "10.1.1.0/24" + pools: + - name: "developer" + imageDefinitionName: "newProject-developer" + vmSku: "general_i_16c64gb256ssd_v2" + catalogs: + - name: "images" + type: imageDefinition + sourceControl: gitHub + visibility: private + uri: "https://github.com/org/newProject.git" + branch: "main" + path: "/.devcenter/imageDefinitions" +``` + +1. Run `azd provision` to deploy the new project. + +--- + +### Adding a New Dev Box Pool + +1. Add pool configuration to the project's `pools` array: + +```yaml +pools: + - name: "data-engineer" + imageDefinitionName: "project-data-engineer" + vmSku: "general_i_32c128gb1024ssd_v2" +``` + +1. Ensure the image definition exists in the referenced catalog. + +--- + +### Adding a New Catalog + +1. Add catalog to DevCenter or project level: + +```yaml +catalogs: + - name: "customEnvironments" + type: environmentDefinition + sourceControl: adoGit + visibility: private + uri: "https://dev.azure.com/org/project/_git/repo" + branch: "main" + path: "/environments" +``` + +--- + +### Adding a New Landing Zone + +1. Create new module directory: `src/newzone/` +2. Create orchestrator module: `src/newzone/newzone.bicep` +3. Add resource group configuration to `azureResources.yaml` +4. Reference from `main.bicep`: + +```bicep +module newzone '../src/newzone/newzone.bicep' = { + scope: resourceGroup(newzoneRgName) + params: { ... } +} +``` + +--- + +## References + +### Internal Documents + +- [Business Architecture](01-business-architecture.md) - Business context and stakeholders +- [Data Architecture](02-data-architecture.md) - Configuration schemas and data flows +- [Technology Architecture](04-technology-architecture.md) - Azure services and infrastructure +- [Security Architecture](05-security-architecture.md) - Security controls and RBAC + +### External References + +- [Azure Bicep Documentation](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/) +- [Azure Developer CLI](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/) +- [Azure Landing Zones](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/landing-zone/) +- [DevCenter API Reference](https://learn.microsoft.com/en-us/rest/api/devcenter/) + +--- + +## Glossary + +| Term | Definition | +|------|------------| +| **Bicep** | Domain-specific language for Azure Resource Manager templates | +| **Module** | Reusable Bicep file that encapsulates resource definitions | +| **Scope** | Deployment target level (subscription, resourceGroup, etc.) | +| **Landing Zone** | Pre-configured environment segment with specific purpose | +| **Orchestrator** | Main entry point module that coordinates other modules | +| **loadYamlContent()** | Bicep function to load YAML configuration at compile time | +| **azd** | Azure Developer CLI for streamlined Azure deployments | + +--- + +*Document generated as part of TOGAF Architecture Documentation for DevExp-DevBox Landing Zone Accelerator* From 196f47fd1deb13eda3bf62e28be5a66701b2c3d7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 15:58:03 -0500 Subject: [PATCH 27/49] Add comprehensive Technology Architecture documentation for DevExp-DevBox Landing Zone Accelerator --- .../04-technology-architecture.md | 772 ++++++++++++++++++ 1 file changed, 772 insertions(+) create mode 100644 docs/architecture/04-technology-architecture.md diff --git a/docs/architecture/04-technology-architecture.md b/docs/architecture/04-technology-architecture.md new file mode 100644 index 00000000..0fd076cd --- /dev/null +++ b/docs/architecture/04-technology-architecture.md @@ -0,0 +1,772 @@ +# Technology Architecture + +> **TOGAF Layer**: Technology Architecture +> **Version**: 1.0.0 +> **Last Updated**: January 22, 2026 +> **Author**: DevExp Team + +--- + +## Table of Contents + +- [Infrastructure Overview](#infrastructure-overview) +- [Landing Zone Design](#landing-zone-design) +- [Network Architecture](#network-architecture) +- [Identity & Access](#identity--access) +- [Security Architecture](#security-architecture) +- [Monitoring & Observability](#monitoring--observability) +- [CI/CD Infrastructure](#cicd-infrastructure) +- [Deployment Tools](#deployment-tools) +- [DevOps Practices](#devops-practices) +- [References](#references) +- [Glossary](#glossary) + +--- + +## Infrastructure Overview + +The DevExp-DevBox Landing Zone Accelerator deploys a comprehensive Azure infrastructure to support Microsoft Dev Box environments at enterprise scale. The solution leverages Platform-as-a-Service (PaaS) offerings for reduced operational overhead and built-in security. + +### Azure Resource Topology + +```mermaid +graph TB + subgraph "Azure Subscription" + subgraph "Security Landing Zone" + SECRG[devexp-security-*-RG] + KV[Azure Key Vault] + end + + subgraph "Monitoring Landing Zone" + MONRG[devexp-monitoring-*-RG] + LA[Log Analytics Workspace] + end + + subgraph "Workload Landing Zone" + WRKRG[devexp-workload-*-RG] + DC[Azure DevCenter] + PROJ[DevCenter Projects] + POOL[Dev Box Pools] + ENVT[Environment Types] + CAT[Catalogs] + end + + subgraph "Connectivity Landing Zone" + CONRG[*-connectivity-RG] + VNET[Virtual Networks] + SUB[Subnets] + NC[Network Connections] + end + end + + KV -->|Diagnostic Logs| LA + DC -->|Diagnostic Logs| LA + VNET -->|Diagnostic Logs| LA + + DC --> PROJ + PROJ --> POOL + DC --> CAT + DC --> ENVT + + PROJ --> NC + NC --> SUB + SUB --> VNET + + style KV fill:#D32F2F,color:#fff + style LA fill:#388E3C,color:#fff + style DC fill:#1976D2,color:#fff + style VNET fill:#7B1FA2,color:#fff +``` + +### Azure Services Deployed + +| Service | Resource Type | Landing Zone | Purpose | +|---------|--------------|--------------|---------| +| **Azure DevCenter** | Microsoft.DevCenter/devcenters | Workload | Central management for Dev Box environments | +| **DevCenter Projects** | Microsoft.DevCenter/projects | Workload | Team-level Dev Box organization | +| **Dev Box Pools** | Microsoft.DevCenter/projects/pools | Workload | VM configuration templates | +| **Catalogs** | Microsoft.DevCenter/devcenters/catalogs | Workload | Image/environment definitions | +| **Environment Types** | Microsoft.DevCenter/devcenters/environmentTypes | Workload | Deployment environment stages | +| **Azure Key Vault** | Microsoft.KeyVault/vaults | Security | Secrets and credential management | +| **Log Analytics** | Microsoft.OperationalInsights/workspaces | Monitoring | Centralized logging and analytics | +| **Virtual Networks** | Microsoft.Network/virtualNetworks | Connectivity | Network infrastructure | +| **Network Connections** | Microsoft.DevCenter/networkConnections | Connectivity | Dev Box network attachment | +| **Role Assignments** | Microsoft.Authorization/roleAssignments | Cross-cutting | RBAC permissions | + +### Resource Naming Convention + +``` +{landingZone}-{environmentName}-{location}-{resourceType} +``` + +| Component | Example | Description | +|-----------|---------|-------------| +| Landing Zone | `devexp-security` | Functional area identifier | +| Environment | `prod` | Deployment environment | +| Location | `eastus2` | Azure region | +| Resource Type | `RG` | Resource type suffix | + +**Example**: `devexp-security-prod-eastus2-RG` + +### API Versions + +| Resource | API Version | Notes | +|----------|-------------|-------| +| Resource Groups | 2025-04-01 | Latest stable | +| DevCenter | 2025-10-01-preview | Preview for latest features | +| Key Vault | 2025-05-01 | Latest stable | +| Log Analytics | 2025-07-01 | Latest stable | +| Virtual Networks | 2025-01-01 | Latest stable | +| Network Connections | 2025-10-01-preview | Aligned with DevCenter | +| Role Assignments | 2022-04-01 | Stable RBAC API | +| Diagnostic Settings | 2021-05-01-preview | Stable diagnostics API | + +--- + +## Landing Zone Design + +### Four-Zone Architecture + +```mermaid +graph LR + subgraph "Landing Zone Architecture" + direction TB + + subgraph "Zone 1: Security" + SEC[Security Zone] + SEC1[Key Vault] + SEC2[Secrets] + SEC3[Access Policies] + end + + subgraph "Zone 2: Monitoring" + MON[Monitoring Zone] + MON1[Log Analytics] + MON2[Solutions] + MON3[Diagnostics] + end + + subgraph "Zone 3: Workload" + WRK[Workload Zone] + WRK1[DevCenter] + WRK2[Projects] + WRK3[Pools] + end + + subgraph "Zone 4: Connectivity" + CON[Connectivity Zone] + CON1[VNets] + CON2[Subnets] + CON3[Network Connections] + end + end + + SEC --> SEC1 --> SEC2 --> SEC3 + MON --> MON1 --> MON2 --> MON3 + WRK --> WRK1 --> WRK2 --> WRK3 + CON --> CON1 --> CON2 --> CON3 + + SEC -.->|Logs| MON + WRK -.->|Logs| MON + CON -.->|Logs| MON + WRK -.->|Secrets| SEC + WRK -.->|Network| CON +``` + +### Resource Group Isolation + +| Landing Zone | Resource Group Pattern | Isolation Benefit | +|--------------|----------------------|-------------------| +| **Security** | devexp-security-{env}-{loc}-RG | Secrets isolated from workloads | +| **Monitoring** | devexp-monitoring-{env}-{loc}-RG | Centralized but segregated logging | +| **Workload** | devexp-workload-{env}-{loc}-RG | Application resources separated | +| **Connectivity** | {project}-connectivity-RG | Per-project network isolation | + +### Tagging Strategy + +All resources are tagged for governance and cost management: + +```yaml +tags: + environment: dev|test|staging|prod + division: Platforms + team: DevExP + project: Contoso-DevExp-DevBox + costCenter: IT + owner: Contoso + landingZone: Security|Monitoring|Workload|Connectivity + resources: ResourceType +``` + +--- + +## Network Architecture + +### Network Architecture Diagram + +```mermaid +graph TB + subgraph "Azure Region" + subgraph "Project VNet (10.0.0.0/16)" + SUB1[Dev Box Subnet
10.0.1.0/24] + end + + subgraph "DevCenter" + DC[Azure DevCenter] + NC[Network Connection
AzureADJoin] + end + + subgraph "Managed Network Option" + MN[Microsoft Hosted
Network] + end + end + + subgraph "Identity" + AAD[Azure AD] + end + + subgraph "Internet" + GH[GitHub/ADO] + DEV[Developer Clients] + end + + DC -->|Attached Network| NC + NC -->|domainJoinType| AAD + NC -->|subnetId| SUB1 + + DC -.->|Alternative| MN + + DEV -->|RDP/Web| DC + DC -->|Catalog Sync| GH + + style DC fill:#1976D2,color:#fff + style NC fill:#7B1FA2,color:#fff + style AAD fill:#0078D4,color:#fff +``` + +### Network Configuration Options + +| Option | Type | Use Case | Configuration | +|--------|------|----------|---------------| +| **Microsoft Hosted** | Managed | Simple deployments, no custom networking | `virtualNetworkType: Managed` | +| **Customer Managed** | Unmanaged | Hybrid connectivity, custom DNS, firewall | `virtualNetworkType: Unmanaged` | + +### VNet Configuration + +```yaml +network: + name: eShop + create: true + resourceGroupName: "eShop-connectivity-RG" + virtualNetworkType: Managed # or Unmanaged + addressPrefixes: + - 10.0.0.0/16 + subnets: + - name: eShop-subnet + properties: + addressPrefix: 10.0.1.0/24 +``` + +### Network Connection Properties + +| Property | Value | Description | +|----------|-------|-------------| +| `domainJoinType` | AzureADJoin | Azure AD-only join (no hybrid) | +| `subnetId` | Resource ID | Target subnet for Dev Boxes | +| `networkingResourceGroupName` | Auto | Microsoft-managed NIC resources | + +### Network Security Considerations + +- **NSGs**: Not explicitly deployed; rely on Azure DevCenter defaults +- **Private Endpoints**: Can be added for enhanced security +- **DNS**: Azure-provided or custom (for hybrid scenarios) +- **Firewall**: Optional Azure Firewall integration for egress control + +--- + +## Identity & Access + +### Identity & RBAC Model + +```mermaid +graph TB + subgraph "Azure AD" + SP[DevCenter
Managed Identity] + PROJ_SP[Project
Managed Identity] + GROUP1[Platform Engineering
Team Group] + GROUP2[eShop Developers
Group] + end + + subgraph "Subscription Scope" + ROLE1[Contributor] + ROLE2[User Access
Administrator] + end + + subgraph "Resource Group Scope" + ROLE3[Key Vault
Secrets User] + ROLE4[Key Vault
Secrets Officer] + ROLE5[DevCenter
Project Admin] + end + + subgraph "Project Scope" + ROLE6[Contributor] + ROLE7[Dev Box User] + ROLE8[Deployment
Environment User] + end + + SP -->|Subscription| ROLE1 + SP -->|Subscription| ROLE2 + SP -->|Security RG| ROLE3 + SP -->|Security RG| ROLE4 + + PROJ_SP -->|Workload RG| ROLE6 + PROJ_SP -->|Security RG| ROLE3 + + GROUP1 -->|Workload RG| ROLE5 + GROUP2 -->|Project| ROLE6 + GROUP2 -->|Project| ROLE7 + GROUP2 -->|Project| ROLE8 + GROUP2 -->|Security RG| ROLE3 + + style SP fill:#0078D4,color:#fff + style PROJ_SP fill:#0078D4,color:#fff + style GROUP1 fill:#FF9800,color:#fff + style GROUP2 fill:#4CAF50,color:#fff +``` + +### Managed Identities + +| Identity | Type | Purpose | Scope | +|----------|------|---------|-------| +| **DevCenter Identity** | SystemAssigned | DevCenter operations, catalog sync | Subscription + Security RG | +| **Project Identity** | SystemAssigned | Project-level operations | Project + Security RG | + +### Role Assignments Summary + +#### DevCenter Identity Roles + +| Role | Role ID | Scope | Purpose | +|------|---------|-------|---------| +| Contributor | b24988ac-6180-42a0-ab88-20f7382dd24c | Subscription | Manage Azure resources | +| User Access Administrator | 18d7d88d-d35e-4fb5-a5c3-7773c20a72d9 | Subscription | Assign RBAC roles | +| Key Vault Secrets User | 4633458b-17de-408a-b874-0445c86b69e6 | Security RG | Read secrets for catalogs | +| Key Vault Secrets Officer | b86a8fe4-44ce-4948-aee5-eccb2c155cd7 | Security RG | Manage secrets | + +#### Organization Group Roles + +| Group | Role | Scope | Purpose | +|-------|------|-------|---------| +| Platform Engineering Team | DevCenter Project Admin | Workload RG | Manage DevCenter settings | + +#### Project User Roles + +| Group | Role | Scope | Purpose | +|-------|------|-------|---------| +| {Project} Developers | Contributor | Project | Manage project resources | +| {Project} Developers | Dev Box User | Project | Use Dev Boxes | +| {Project} Developers | Deployment Environment User | Project | Deploy environments | +| {Project} Developers | Key Vault Secrets User | Security RG | Access secrets | + +--- + +## Security Architecture + +### Key Vault Configuration + +```mermaid +graph TB + subgraph "Key Vault Security" + KV[Azure Key Vault] + + subgraph "Security Features" + PP[Purge Protection
Enabled] + SD[Soft Delete
7 days] + RBAC[RBAC Authorization
Enabled] + end + + subgraph "Access" + MI[Managed Identities
RBAC-based] + DEPLOY[Deployer
Access Policy] + end + + subgraph "Secrets" + PAT[gha-token
GitHub PAT] + end + end + + KV --> PP + KV --> SD + KV --> RBAC + + MI -->|Secrets User| KV + DEPLOY -->|Initial Setup| KV + + KV --> PAT + + style KV fill:#D32F2F,color:#fff + style PP fill:#4CAF50,color:#fff + style SD fill:#4CAF50,color:#fff + style RBAC fill:#4CAF50,color:#fff +``` + +### Security Configuration + +| Setting | Value | Security Impact | +|---------|-------|-----------------| +| `enablePurgeProtection` | true | Prevents permanent secret deletion | +| `enableSoftDelete` | true | Enables secret recovery | +| `softDeleteRetentionInDays` | 7 | Recovery window | +| `enableRbacAuthorization` | true | RBAC instead of access policies | +| SKU | Standard | Cost-effective for most scenarios | + +### Network Security + +- **Service Tags**: Azure DevCenter uses service tags for outbound rules +- **Private Link**: Optional for Key Vault and storage +- **Azure AD Join**: No on-premises domain dependency + +--- + +## Monitoring & Observability + +### Log Analytics Integration + +```mermaid +graph LR + subgraph "Data Sources" + DC[DevCenter] + KV[Key Vault] + VNET[Virtual Network] + LA_SELF[Log Analytics] + end + + subgraph "Log Analytics Workspace" + LA[Log Analytics] + SOL[Azure Activity
Solution] + end + + subgraph "Consumption" + QUERY[KQL Queries] + ALERT[Alerts] + WORKBOOK[Workbooks] + EXPORT[Data Export] + end + + DC -->|Diagnostic Settings| LA + KV -->|Diagnostic Settings| LA + VNET -->|Diagnostic Settings| LA + LA_SELF -->|Self Diagnostics| LA + + LA --> SOL + LA --> QUERY + LA --> ALERT + LA --> WORKBOOK + LA --> EXPORT + + style LA fill:#68217A,color:#fff +``` + +### Diagnostic Settings Configuration + +All resources are configured with diagnostic settings: + +```bicep +resource diagnosticSettings 'Microsoft.Insights/diagnosticSettings@...' = { + name: '${resourceName}-diagnostics' + scope: targetResource + properties: { + logAnalyticsDestinationType: 'AzureDiagnostics' + logs: [ + { + categoryGroup: 'allLogs' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + workspaceId: logAnalyticsWorkspaceId + } +} +``` + +### Log Categories + +| Resource | Log Category | Contents | +|----------|--------------|----------| +| Key Vault | AuditEvent | Secret access, management operations | +| DevCenter | DataPlaneRequests | API operations | +| DevCenter | DevBoxProvisioning | Dev Box lifecycle | +| Virtual Network | VMProtectionAlerts | Network protection alerts | + +### Monitoring Queries + +**Key Vault Access Audit**: + +```kusto +AzureDiagnostics +| where ResourceProvider == "MICROSOFT.KEYVAULT" +| where OperationName == "SecretGet" +| project TimeGenerated, CallerIPAddress, identity_claim_upn_s, ResultType +``` + +**DevCenter Operations**: + +```kusto +AzureDiagnostics +| where ResourceProvider == "MICROSOFT.DEVCENTER" +| summarize count() by OperationName, ResultType +``` + +--- + +## CI/CD Infrastructure + +### CI/CD Pipeline Flow + +```mermaid +graph LR + subgraph "Source Control" + GH[GitHub Repository] + ADO_REPO[Azure DevOps Repo] + end + + subgraph "CI Pipeline" + CI_TRIGGER[Push/PR Trigger] + VERSION[Generate Version] + BUILD[Build Bicep] + ARTIFACT[Upload Artifacts] + end + + subgraph "CD Pipeline" + MANUAL[Manual Trigger] + AUTH[OIDC Authentication] + PROVISION[azd provision] + end + + subgraph "Azure" + ARM[Azure Resource Manager] + RES[Azure Resources] + end + + GH --> CI_TRIGGER + ADO_REPO --> CI_TRIGGER + + CI_TRIGGER --> VERSION + VERSION --> BUILD + BUILD --> ARTIFACT + + MANUAL --> AUTH + AUTH --> PROVISION + PROVISION --> ARM + ARM --> RES + + style GH fill:#333,color:#fff + style ARM fill:#0078D4,color:#fff +``` + +### GitHub Actions Workflows + +#### CI Workflow (`ci.yml`) + +| Job | Steps | Trigger | +|-----|-------|---------| +| `generate-tag-version` | Checkout, Generate Release | Push to feature/*, PR to main | +| `build` | Checkout, Build Bicep, Upload Artifacts | After version generation | + +#### Deploy Workflow (`deploy.yml`) + +| Job | Steps | Trigger | +|-----|-------|---------| +| `build-and-deploy-to-azure` | Checkout, Install azd, Build, Login (OIDC), Provision | Manual (workflow_dispatch) | + +### Azure DevOps Pipeline (`azure-dev.yml`) + +| Task | Description | +|------|-------------| +| Install azd | Installs Azure Developer CLI | +| Configure AZD Auth | Sets `auth.useAzCliAuth` | +| Provision Infrastructure | Runs `azd provision` | + +### Authentication Methods + +| Platform | Method | Details | +|----------|--------|---------| +| **GitHub Actions** | OIDC Federation | Secretless, federated credentials | +| **Azure DevOps** | Service Connection | Azure CLI service principal | + +### CI/CD Environment Variables + +| Variable | Source | Purpose | +|----------|--------|---------| +| `AZURE_CLIENT_ID` | GitHub/ADO Variable | Service principal client ID | +| `AZURE_TENANT_ID` | GitHub/ADO Variable | Azure AD tenant ID | +| `AZURE_SUBSCRIPTION_ID` | GitHub/ADO Variable | Target subscription | +| `AZURE_ENV_NAME` | Workflow Input | Environment name | +| `AZURE_LOCATION` | Workflow Input | Azure region | +| `KEY_VAULT_SECRET` | GitHub Secret | PAT token value | +| `SOURCE_CONTROL_PLATFORM` | Environment | `github` or `adogit` | + +--- + +## Deployment Tools + +### Azure Developer CLI (azd) + +The primary deployment tool is Azure Developer CLI (`azd`), configured via `azure.yaml`: + +```yaml +name: ContosoDevExp + +hooks: + preprovision: + shell: sh + continueOnError: false + interactive: true + run: | + ./setup.sh -e ${AZURE_ENV_NAME} -s ${SOURCE_CONTROL_PLATFORM} +``` + +### azd Commands + +| Command | Purpose | +|---------|---------| +| `azd init` | Initialize azd environment | +| `azd auth login` | Authenticate to Azure | +| `azd provision` | Deploy infrastructure | +| `azd env new` | Create new environment | +| `azd env set` | Set environment variables | + +### Setup Scripts + +#### setUp.sh (Bash) + +| Function | Purpose | +|----------|---------| +| `test_azure_authentication` | Verify Azure CLI login | +| `test_github_authentication` | Verify GitHub CLI login | +| `get_secure_github_token` | Retrieve GitHub PAT | +| `initialize_azd_environment` | Configure azd environment | +| `start_azure_provisioning` | Run azd provision | + +#### setUp.ps1 (PowerShell) + +Equivalent functionality for Windows environments. + +### Script Flow + +```mermaid +sequenceDiagram + participant User + participant Script as setUp.sh/ps1 + participant AZ as Azure CLI + participant GH as GitHub CLI + participant AZD as Azure Developer CLI + + User->>Script: Run with -e envName -s github + Script->>AZ: Test authentication + AZ-->>Script: Authenticated + Script->>GH: Test authentication + GH-->>Script: Authenticated + Script->>GH: Get PAT token + GH-->>Script: Token retrieved + Script->>AZD: Initialize environment + AZD-->>Script: Environment ready + Script->>AZD: Set KEY_VAULT_SECRET + Script->>AZD: azd provision + AZD->>AZ: Deploy resources + AZ-->>Script: Deployment complete +``` + +--- + +## DevOps Practices + +### Release Strategy + +```mermaid +gitGraph + commit id: "Initial" + branch feature/new-pool + commit id: "Add pool config" + commit id: "Update YAML" + checkout main + merge feature/new-pool id: "PR Merge" + commit id: "Release v1.1.0" tag: "v1.1.0" +``` + +### Branching Model + +| Branch Pattern | Purpose | Protection | +|----------------|---------|------------| +| `main` | Production-ready code | Required reviews, CI pass | +| `feature/*` | New features | CI validation | +| `fix/*` | Bug fixes | CI validation | +| `docs/*` | Documentation updates | Optional CI | + +### Semantic Versioning + +The CI pipeline generates semantic versions based on commit messages: + +| Commit Prefix | Version Bump | Example | +|---------------|--------------|---------| +| `feat:` | Minor | 1.0.0 β†’ 1.1.0 | +| `fix:` | Patch | 1.0.0 β†’ 1.0.1 | +| `BREAKING CHANGE:` | Major | 1.0.0 β†’ 2.0.0 | + +### Artifact Management + +| Artifact | Retention | Contents | +|----------|-----------|----------| +| Bicep ARM Templates | 7 days | Compiled JSON templates | +| Release Assets | Permanent | Tagged releases | + +### Quality Gates + +| Gate | Trigger | Criteria | +|------|---------|----------| +| Bicep Build | PR/Push | Successful compilation | +| Artifact Upload | Build Success | Non-empty artifacts | +| Deploy Approval | Manual | Environment owner approval | + +--- + +## References + +### Internal Documents + +- [Business Architecture](01-business-architecture.md) - Business context and stakeholders +- [Data Architecture](02-data-architecture.md) - Configuration schemas and data flows +- [Application Architecture](03-application-architecture.md) - Module design and Bicep structure +- [Security Architecture](05-security-architecture.md) - Security controls and compliance + +### External References + +- [Microsoft Dev Box Documentation](https://learn.microsoft.com/en-us/azure/dev-box/) +- [Azure DevCenter API Reference](https://learn.microsoft.com/en-us/rest/api/devcenter/) +- [Azure Developer CLI Documentation](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/) +- [Azure Landing Zones](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/landing-zone/) +- [GitHub Actions for Azure](https://learn.microsoft.com/en-us/azure/developer/github/github-actions) +- [Azure DevOps Pipelines](https://learn.microsoft.com/en-us/azure/devops/pipelines/) + +--- + +## Glossary + +| Term | Definition | +|------|------------| +| **Landing Zone** | Pre-configured Azure environment segment for specific workloads | +| **DevCenter** | Azure service for managing developer environments at scale | +| **Dev Box** | Cloud-based developer workstation | +| **Network Connection** | Link between DevCenter and VNet subnet | +| **OIDC Federation** | OpenID Connect-based authentication without stored secrets | +| **azd** | Azure Developer CLI - streamlined Azure development tool | +| **ARM** | Azure Resource Manager - Azure's deployment engine | +| **Diagnostic Settings** | Azure configuration for log/metric routing | + +--- + +*Document generated as part of TOGAF Architecture Documentation for DevExp-DevBox Landing Zone Accelerator* From 3e488628587c3d63fa5303dba308e698f99a6e2f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 16:00:00 -0500 Subject: [PATCH 28/49] Add comprehensive Security Architecture documentation for DevExp-DevBox Landing Zone Accelerator --- docs/architecture/05-security-architecture.md | 979 ++++++++++++++++++ 1 file changed, 979 insertions(+) create mode 100644 docs/architecture/05-security-architecture.md diff --git a/docs/architecture/05-security-architecture.md b/docs/architecture/05-security-architecture.md new file mode 100644 index 00000000..baf30de2 --- /dev/null +++ b/docs/architecture/05-security-architecture.md @@ -0,0 +1,979 @@ +# Security Architecture + +> **TOGAF Layer**: Security Architecture +> **Version**: 1.0.0 +> **Last Updated**: January 22, 2026 +> **Author**: DevExp Team + +--- + +## Table of Contents + +- [Security Overview](#security-overview) +- [Threat Model](#threat-model) +- [Identity & Access Management](#identity--access-management) +- [Authorization & RBAC](#authorization--rbac) +- [Secrets Management](#secrets-management) +- [Network Security](#network-security) +- [Data Protection](#data-protection) +- [Security Monitoring & Logging](#security-monitoring--logging) +- [Compliance & Governance](#compliance--governance) +- [Security Controls Matrix](#security-controls-matrix) +- [Incident Response](#incident-response) +- [Security Hardening](#security-hardening) +- [Supply Chain Security](#supply-chain-security) +- [CI/CD Security](#cicd-security) +- [Security Recommendations](#security-recommendations) +- [References](#references) +- [Glossary](#glossary) + +--- + +## Security Overview + +The DevExp-DevBox Landing Zone Accelerator implements a **defense-in-depth** security strategy aligned with **Zero Trust** principles. Security controls are embedded at every layer: identity, network, data, and application. + +### Security Architecture Overview + +```mermaid +graph TB + subgraph "Security Perimeter" + subgraph "Identity Layer" + AAD[Azure AD] + MI[Managed Identities] + RBAC[RBAC Roles] + end + + subgraph "Network Layer" + VNET[Virtual Networks] + NSG[Network Security] + PE[Private Endpoints
Optional] + end + + subgraph "Data Layer" + KV[Key Vault] + ENC[Encryption] + SEC[Secrets] + end + + subgraph "Application Layer" + DC[DevCenter] + PROJ[Projects] + CAT[Catalogs] + end + + subgraph "Monitoring Layer" + LA[Log Analytics] + AUDIT[Audit Logs] + ALERT[Security Alerts] + end + end + + AAD --> MI + MI --> RBAC + RBAC --> DC + RBAC --> KV + + VNET --> DC + VNET --> PE + PE --> KV + + KV --> SEC + SEC --> CAT + + DC --> PROJ + + DC -->|Logs| LA + KV -->|Logs| LA + LA --> AUDIT + LA --> ALERT + + style AAD fill:#0078D4,color:#fff + style KV fill:#D32F2F,color:#fff + style LA fill:#388E3C,color:#fff +``` + +### Security Principles + +| Principle | Implementation | +|-----------|----------------| +| **Zero Trust** | No implicit trust; verify explicitly via Azure AD and RBAC | +| **Least Privilege** | Role assignments with minimum necessary permissions | +| **Defense in Depth** | Multiple security layers (identity, network, data, monitoring) | +| **Assume Breach** | Comprehensive logging and monitoring for detection | +| **Secure by Default** | Hardened configurations (purge protection, RBAC authorization) | + +### Security Posture Summary + +| Area | Status | Key Controls | +|------|--------|--------------| +| **Identity** | βœ… Strong | Managed identities, Azure AD integration, RBAC | +| **Secrets** | βœ… Strong | Key Vault with purge protection, RBAC authorization | +| **Network** | ⚠️ Moderate | VNet isolation available, private endpoints optional | +| **Monitoring** | βœ… Strong | Centralized logging, diagnostic settings | +| **CI/CD** | βœ… Strong | OIDC federation, no stored secrets | + +--- + +## Threat Model + +### STRIDE Analysis + +```mermaid +graph TB + subgraph "STRIDE Threat Categories" + S[Spoofing
Identity] + T[Tampering
Data] + R[Repudiation
Actions] + I[Information Disclosure
Data Leakage] + D[Denial of Service
Availability] + E[Elevation of Privilege
Authorization] + end + + subgraph "Mitigations" + M1[Azure AD + MFA] + M2[RBAC + Audit Logs] + M3[Key Vault Logging] + M4[Encryption + RBAC] + M5[Azure DDoS + Throttling] + M6[Least Privilege RBAC] + end + + S --> M1 + T --> M2 + R --> M3 + I --> M4 + D --> M5 + E --> M6 + + style S fill:#FF5722,color:#fff + style T fill:#FF5722,color:#fff + style R fill:#FF5722,color:#fff + style I fill:#FF5722,color:#fff + style D fill:#FF5722,color:#fff + style E fill:#FF5722,color:#fff +``` + +### Threat Assessment + +#### Threat: Unauthorized Secret Access + +- **STRIDE Category**: Information Disclosure +- **Attack Vector**: Compromised identity attempts to read GitHub PAT from Key Vault +- **Affected Assets**: Key Vault secrets, Git repositories +- **Mitigations**: + - RBAC-based Key Vault authorization + - Managed identities (no stored credentials) + - Key Vault audit logging + - Principle of least privilege +- **Residual Risk**: Low + +--- + +#### Threat: Catalog Tampering + +- **STRIDE Category**: Tampering +- **Attack Vector**: Attacker modifies Dev Box image definitions in catalog repository +- **Affected Assets**: Dev Box images, developer workstations +- **Mitigations**: + - Git branch protection rules + - PAT authentication for private repositories + - Catalog sync audit logs +- **Residual Risk**: Medium (depends on source control security) + +--- + +#### Threat: Privilege Escalation via DevCenter + +- **STRIDE Category**: Elevation of Privilege +- **Attack Vector**: User with Dev Box User role attempts to gain DevCenter Admin access +- **Affected Assets**: DevCenter, all projects +- **Mitigations**: + - Scoped role assignments (Project vs DevCenter) + - Azure AD group-based access + - Role assignment audit logs +- **Residual Risk**: Low + +--- + +#### Threat: Network-based Attacks on Dev Boxes + +- **STRIDE Category**: Denial of Service / Information Disclosure +- **Attack Vector**: External attacker targets Dev Box network +- **Affected Assets**: Virtual networks, Dev Boxes +- **Mitigations**: + - Microsoft-hosted networking (default) + - Azure DDoS protection + - Optional NSGs and private endpoints +- **Residual Risk**: Low (Microsoft-hosted) / Medium (customer-managed) + +--- + +#### Threat: CI/CD Pipeline Compromise + +- **STRIDE Category**: Spoofing / Tampering +- **Attack Vector**: Attacker injects malicious code via compromised pipeline +- **Affected Assets**: Infrastructure deployment, Azure resources +- **Mitigations**: + - OIDC federation (no stored secrets) + - Branch protection rules + - Manual deployment approval + - Artifact integrity verification +- **Residual Risk**: Low + +--- + +### Risk Assessment Matrix + +| Threat | Likelihood | Impact | Risk Score | Mitigation Status | +|--------|------------|--------|------------|-------------------| +| Unauthorized Secret Access | Low | High | Medium | βœ… Mitigated | +| Catalog Tampering | Medium | High | High | ⚠️ Partial | +| Privilege Escalation | Low | Critical | Medium | βœ… Mitigated | +| Network Attacks | Low | Medium | Low | βœ… Mitigated | +| CI/CD Compromise | Low | Critical | Medium | βœ… Mitigated | + +--- + +## Identity & Access Management + +### Identity Architecture + +```mermaid +graph TB + subgraph "Azure AD" + TENANT[Azure AD Tenant] + + subgraph "Users & Groups" + PE_GROUP[Platform Engineering
Team] + DEV_GROUP[Project Developers] + ADMIN[Global Admins] + end + + subgraph "Service Principals" + CICD_SP[CI/CD Service
Principal] + end + + subgraph "Managed Identities" + DC_MI[DevCenter
Managed Identity] + PROJ_MI[Project
Managed Identity] + end + end + + TENANT --> PE_GROUP + TENANT --> DEV_GROUP + TENANT --> ADMIN + TENANT --> CICD_SP + TENANT --> DC_MI + TENANT --> PROJ_MI + + style TENANT fill:#0078D4,color:#fff + style DC_MI fill:#4CAF50,color:#fff + style PROJ_MI fill:#4CAF50,color:#fff +``` + +### Identity Types + +| Identity Type | Use Case | Lifecycle | Credential Management | +|---------------|----------|-----------|----------------------| +| **Azure AD Users** | Human access to Dev Boxes | HR-managed | Password + MFA | +| **Azure AD Groups** | Role assignment targets | Team-managed | N/A | +| **Managed Identities** | Service-to-service auth | Resource lifecycle | Azure-managed (no credentials) | +| **Service Principals** | CI/CD automation | App registration | OIDC federation | + +### Managed Identity Configuration + +```yaml +# DevCenter identity (from devcenter.yaml) +identity: + type: "SystemAssigned" +``` + +**Benefits**: +- No credential storage required +- Automatic credential rotation +- Azure-managed lifecycle +- Audit trail via Azure AD + +### Authentication Flows + +```mermaid +sequenceDiagram + participant Dev as Developer + participant AAD as Azure AD + participant DC as DevCenter + participant KV as Key Vault + + Dev->>AAD: Authenticate (MFA) + AAD-->>Dev: Access Token + Dev->>DC: Request Dev Box + DC->>AAD: Validate Token + AAD-->>DC: Token Valid + DC->>DC: Check RBAC + DC-->>Dev: Dev Box Provisioned + + Note over DC,KV: Catalog Sync (Managed Identity) + DC->>AAD: Request Token (MI) + AAD-->>DC: MI Token + DC->>KV: Get Secret (MI Token) + KV->>AAD: Validate MI + AAD-->>KV: Authorized + KV-->>DC: Secret Value +``` + +--- + +## Authorization & RBAC + +### RBAC Hierarchy + +```mermaid +graph TB + subgraph "Scope Hierarchy" + SUB[Subscription] + RG_SEC[Security RG] + RG_WRK[Workload RG] + DC[DevCenter] + PROJ[Project] + POOL[Pool] + end + + SUB --> RG_SEC + SUB --> RG_WRK + RG_WRK --> DC + DC --> PROJ + PROJ --> POOL + + subgraph "Role Inheritance" + R1[Contributor
@ Subscription] + R2[Key Vault Secrets User
@ Security RG] + R3[DevCenter Project Admin
@ Workload RG] + R4[Dev Box User
@ Project] + end + + R1 -.->|Inherits down| RG_WRK + R2 -.->|Scoped| RG_SEC + R3 -.->|Scoped| DC + R4 -.->|Scoped| PROJ +``` + +### Role Assignments Table + +| Principal | Role | Role ID | Scope | Purpose | +|-----------|------|---------|-------|---------| +| DevCenter MI | Contributor | b24988ac-6180-42a0-ab88-20f7382dd24c | Subscription | Resource management | +| DevCenter MI | User Access Administrator | 18d7d88d-d35e-4fb5-a5c3-7773c20a72d9 | Subscription | RBAC assignments | +| DevCenter MI | Key Vault Secrets User | 4633458b-17de-408a-b874-0445c86b69e6 | Security RG | Read catalog secrets | +| DevCenter MI | Key Vault Secrets Officer | b86a8fe4-44ce-4948-aee5-eccb2c155cd7 | Security RG | Manage secrets | +| Platform Engineering Team | DevCenter Project Admin | 331c37c6-af14-46d9-b9f4-e1909e1b95a0 | Workload RG | Manage DevCenter | +| Project Developers | Contributor | b24988ac-6180-42a0-ab88-20f7382dd24c | Project | Project resources | +| Project Developers | Dev Box User | 45d50f46-0b78-4001-a660-4198cbe8cd05 | Project | Use Dev Boxes | +| Project Developers | Deployment Environment User | 18e40d4e-8d2e-438d-97e1-9528336e149c | Project | Deploy environments | +| Project Developers | Key Vault Secrets User | 4633458b-17de-408a-b874-0445c86b69e6 | Security RG | Access secrets | + +### Scope Isolation + +| Scope Level | Isolation Benefit | Access Control | +|-------------|-------------------|----------------| +| Subscription | Tenant boundary | Subscription owners | +| Resource Group | Workload separation | RG-level RBAC | +| DevCenter | Platform management | DevCenter admins | +| Project | Team isolation | Project-level roles | + +--- + +## Secrets Management + +### Key Vault Architecture + +```mermaid +graph TB + subgraph "Azure Key Vault" + KV[contoso-*****-kv] + + subgraph "Security Settings" + PP[Purge Protection βœ“] + SD[Soft Delete βœ“] + RBAC_AUTH[RBAC Authorization βœ“] + end + + subgraph "Secrets" + PAT[gha-token
GitHub PAT] + end + + subgraph "Access Control" + DEPLOYER[Deployer Access
Policy] + MI_ACCESS[Managed Identity
RBAC] + end + end + + KV --> PP + KV --> SD + KV --> RBAC_AUTH + KV --> PAT + + DEPLOYER -->|Initial Setup| KV + MI_ACCESS -->|Runtime Access| KV + + style KV fill:#0078D4,color:#fff + style PP fill:#4CAF50,color:#fff + style SD fill:#4CAF50,color:#fff + style RBAC_AUTH fill:#4CAF50,color:#fff +``` + +### Secrets Access Flow + +```mermaid +sequenceDiagram + participant DC as DevCenter + participant AAD as Azure AD + participant KV as Key Vault + participant GH as GitHub + + DC->>AAD: Request token for Key Vault + Note over DC,AAD: Using Managed Identity + AAD-->>DC: Access token + + DC->>KV: GET secret (with token) + KV->>AAD: Validate token & RBAC + AAD-->>KV: Authorized (Secrets User role) + KV-->>DC: Secret value (GitHub PAT) + + DC->>GH: Clone catalog (with PAT) + GH-->>DC: Repository content +``` + +### Key Vault Access Matrix + +| Identity | Permission | Justification | +|----------|------------|---------------| +| DevCenter Managed Identity | secrets/get, secrets/list | Catalog authentication | +| Project Managed Identity | secrets/get, secrets/list | Project catalog authentication | +| CI/CD Service Principal | secrets/set | Initial secret provisioning | +| Deployer (azd) | secrets/* | Deployment operations | + +### Secret Types + +| Secret | Name | Purpose | Rotation | +|--------|------|---------|----------| +| GitHub PAT | gha-token | Private catalog authentication | Manual (90 days recommended) | + +### Security Configuration + +| Setting | Value | Impact | +|---------|-------|--------| +| `enablePurgeProtection` | `true` | Prevents permanent deletion | +| `enableSoftDelete` | `true` | 7-day recovery window | +| `softDeleteRetentionInDays` | `7` | Minimum retention | +| `enableRbacAuthorization` | `true` | RBAC instead of access policies | + +--- + +## Network Security + +### Network Security Topology + +```mermaid +graph TB + subgraph "Internet" + DEV[Developer] + GH[GitHub] + end + + subgraph "Azure" + subgraph "DevCenter Network" + DC[DevCenter] + NC[Network Connection] + end + + subgraph "Project Network" + VNET[VNet 10.0.0.0/16] + SUBNET[Subnet 10.0.1.0/24] + DEVBOX[Dev Boxes] + end + + subgraph "Security Services" + AAD[Azure AD] + KV[Key Vault] + end + end + + DEV -->|HTTPS/RDP| DC + DC --> NC + NC --> SUBNET + SUBNET --> DEVBOX + + DC -->|HTTPS| GH + DC -->|Managed Identity| AAD + DC -->|Secret Access| KV + + style VNET fill:#7B1FA2,color:#fff + style KV fill:#D32F2F,color:#fff +``` + +### Network Configuration Options + +| Configuration | Type | Security Level | Use Case | +|---------------|------|----------------|----------| +| Microsoft Hosted | Managed | Standard | Simple deployments | +| Customer VNet | Unmanaged | Enhanced | Custom networking, firewall | + +### Network Segmentation + +| Segment | CIDR | Resources | +|---------|------|-----------| +| Project VNet | 10.0.0.0/16 | All project resources | +| Dev Box Subnet | 10.0.1.0/24 | Dev Box VMs | + +### Security Recommendations + +1. **Private Endpoints** (Optional): Add private endpoints for Key Vault +2. **NSG Rules**: Restrict inbound traffic to required ports +3. **Azure Firewall**: Add for egress control in enterprise scenarios +4. **Azure Bastion**: Use for secure Dev Box access + +--- + +## Data Protection + +### Encryption Matrix + +| Data State | Encryption Method | Key Management | +|------------|-------------------|----------------| +| At Rest (Key Vault) | AES-256 | Platform-managed | +| At Rest (Log Analytics) | AES-256 | Platform-managed | +| At Rest (Dev Box Disks) | AES-256 | Platform-managed | +| In Transit | TLS 1.2+ | Azure-managed certificates | + +### Data Classification + +| Data Type | Classification | Protection | +|-----------|---------------|------------| +| GitHub PAT | Secret | Key Vault encryption + RBAC | +| Configuration YAML | Internal | Git encryption | +| Audit Logs | Confidential | Log Analytics encryption | +| Dev Box Content | Variable | Disk encryption | + +### Sensitive Data Handling + +- **Secrets**: Never logged, stored only in Key Vault +- **PAT Tokens**: Retrieved at runtime, not embedded in templates +- **User Data**: Managed on Dev Box disks with encryption + +--- + +## Security Monitoring & Logging + +### Security Logging Architecture + +```mermaid +graph LR + subgraph "Log Sources" + KV_LOG[Key Vault
AuditEvent] + DC_LOG[DevCenter
Operations] + AAD_LOG[Azure AD
Sign-ins] + ACT_LOG[Activity Log
ARM Operations] + end + + subgraph "Log Analytics" + LA[Log Analytics
Workspace] + end + + subgraph "Analysis" + QUERY[Security Queries] + ALERT[Alert Rules] + WORKBOOK[Security Workbooks] + end + + KV_LOG --> LA + DC_LOG --> LA + AAD_LOG --> LA + ACT_LOG --> LA + + LA --> QUERY + LA --> ALERT + LA --> WORKBOOK + + style LA fill:#68217A,color:#fff +``` + +### Security-Relevant Logs + +| Log Source | Category | Security Events | +|------------|----------|-----------------| +| Key Vault | AuditEvent | Secret access, management operations | +| DevCenter | DataPlaneRequests | API operations | +| Azure AD | SignInLogs | Authentication attempts | +| Activity Log | Administrative | Resource modifications | + +### Security Queries + +**Unauthorized Secret Access Attempts**: +```kusto +AzureDiagnostics +| where ResourceProvider == "MICROSOFT.KEYVAULT" +| where ResultType != "Success" +| project TimeGenerated, OperationName, ResultType, CallerIPAddress +| order by TimeGenerated desc +``` + +**Privilege Escalation Detection**: +```kusto +AzureActivity +| where OperationNameValue contains "roleAssignments/write" +| project TimeGenerated, Caller, ResourceGroup, Properties +``` + +**Suspicious DevCenter Operations**: +```kusto +AzureDiagnostics +| where ResourceProvider == "MICROSOFT.DEVCENTER" +| where ResultType != "Success" +| summarize FailedOperations = count() by OperationName, bin(TimeGenerated, 1h) +| where FailedOperations > 10 +``` + +### Alert Rules (Recommended) + +| Alert | Condition | Severity | +|-------|-----------|----------| +| Key Vault Access Denied | ResultType == "Forbidden" | High | +| Mass Secret Reads | Secret reads > 100/hour | Medium | +| Role Assignment Change | roleAssignments/write | High | +| DevCenter Config Change | DevCenter update operations | Medium | + +--- + +## Compliance & Governance + +### Compliance Mapping + +| Framework | Control | Implementation | Evidence | +|-----------|---------|----------------|----------| +| **NIST 800-53** | AC-2 (Account Management) | Azure AD groups + RBAC | Role assignment audit | +| **NIST 800-53** | AC-6 (Least Privilege) | Scoped role assignments | RBAC configuration | +| **NIST 800-53** | AU-2 (Audit Events) | Diagnostic settings | Log Analytics | +| **NIST 800-53** | SC-12 (Key Management) | Key Vault | Key Vault audit logs | +| **CIS Azure** | 4.1.1 | RBAC authorization for Key Vault | enableRbacAuthorization: true | +| **CIS Azure** | 4.1.3 | Key Vault soft delete | enableSoftDelete: true | +| **CIS Azure** | 4.1.4 | Key Vault purge protection | enablePurgeProtection: true | + +### Tagging for Compliance + +```yaml +tags: + environment: dev|test|staging|prod # Environment classification + owner: Contoso # Resource accountability + costCenter: IT # Financial tracking + project: DevExp-DevBox # Project association +``` + +### Resource Locks (Recommended) + +| Resource | Lock Type | Purpose | +|----------|-----------|---------| +| Key Vault | CanNotDelete | Prevent accidental deletion | +| Log Analytics | CanNotDelete | Preserve audit logs | +| DevCenter | CanNotDelete | Protect platform | + +--- + +## Security Controls Matrix + +### Control Inventory + +| Control ID | Control Name | Category | Framework | Status | Implementation | +|------------|--------------|----------|-----------|--------|----------------| +| SC-001 | Azure AD Authentication | Identity | NIST AC-14 | βœ… Implemented | All services use Azure AD | +| SC-002 | Managed Identities | Identity | NIST IA-2 | βœ… Implemented | DevCenter + Projects | +| SC-003 | RBAC Authorization | Authorization | NIST AC-3 | βœ… Implemented | All resource access | +| SC-004 | Key Vault Secrets | Data Protection | NIST SC-12 | βœ… Implemented | PAT storage | +| SC-005 | Purge Protection | Data Protection | CIS 4.1.4 | βœ… Implemented | Key Vault config | +| SC-006 | Soft Delete | Data Protection | CIS 4.1.3 | βœ… Implemented | 7-day retention | +| SC-007 | Diagnostic Logging | Monitoring | NIST AU-2 | βœ… Implemented | All resources | +| SC-008 | Network Isolation | Network | NIST SC-7 | ⚠️ Partial | VNet available | +| SC-009 | Encryption at Rest | Data Protection | NIST SC-28 | βœ… Implemented | Platform encryption | +| SC-010 | Encryption in Transit | Data Protection | NIST SC-8 | βœ… Implemented | TLS 1.2+ | + +### Control: Azure AD Authentication + +- **Category**: Identity +- **Framework Mapping**: NIST 800-53 AC-14, Azure Security Benchmark IM-1 +- **Implementation**: Azure AD tenant integration, managed identity authentication +- **Status**: Implemented +- **Evidence**: All Azure resources require Azure AD authentication + +### Control: Key Vault RBAC Authorization + +- **Category**: Data Protection +- **Framework Mapping**: CIS Azure 4.1.1, NIST 800-53 AC-3 +- **Implementation**: `enableRbacAuthorization: true` in Key Vault config +- **Status**: Implemented +- **Evidence**: security.yaml configuration + +### Control: Purge Protection + +- **Category**: Data Protection +- **Framework Mapping**: CIS Azure 4.1.4, NIST 800-53 SC-12 +- **Implementation**: `enablePurgeProtection: true` in Key Vault config +- **Status**: Implemented +- **Evidence**: security.yaml configuration + +--- + +## Incident Response + +### Detection Capabilities + +| Detection Type | Mechanism | Response | +|----------------|-----------|----------| +| Secret Access Anomaly | Log Analytics query | Alert β†’ Investigate | +| Role Assignment Change | Activity Log alert | Alert β†’ Review | +| DevCenter Config Change | Diagnostic logs | Alert β†’ Verify | +| Authentication Failure | Azure AD logs | Alert β†’ Lock account | + +### Response Procedures + +#### Secret Compromise Response + +1. **Detect**: Alert triggered for unauthorized Key Vault access +2. **Contain**: Disable affected managed identity / rotate secret +3. **Eradicate**: Rotate GitHub PAT, update Key Vault +4. **Recover**: Re-sync catalogs with new credentials +5. **Lessons Learned**: Review access policies, enhance monitoring + +#### Escalation Path + +| Severity | Initial Response | Escalation | +|----------|-----------------|------------| +| Low | Security Team | N/A | +| Medium | Security Team | Platform Team | +| High | Platform + Security | CISO | +| Critical | All Teams | Incident Commander | + +--- + +## Security Hardening + +### Key Vault Hardening + +| Setting | Hardened Value | Default | Impact | +|---------|----------------|---------|--------| +| Purge Protection | Enabled | Disabled | Prevents permanent deletion | +| Soft Delete | Enabled | Enabled | Allows recovery | +| Retention Days | 7-90 | 90 | Balance recovery vs. compliance | +| RBAC Authorization | Enabled | Disabled | Modern access control | +| Network Rules | Optional | None | Network-level restriction | + +### DevCenter Security Settings + +| Setting | Value | Security Impact | +|---------|-------|-----------------| +| `catalogItemSyncEnableStatus` | Enabled | Allows catalog sync | +| `microsoftHostedNetworkEnableStatus` | Enabled | Uses Azure-managed networking | +| `installAzureMonitorAgentEnableStatus` | Enabled | Enables monitoring | + +### Secure Defaults + +The accelerator implements secure defaults: + +- βœ… RBAC authorization for Key Vault (not access policies) +- βœ… Purge protection enabled +- βœ… Soft delete enabled +- βœ… Managed identities (no stored credentials) +- βœ… Diagnostic settings on all resources +- βœ… OIDC federation for CI/CD (no secrets in pipelines) + +--- + +## Supply Chain Security + +### Catalog Security + +```mermaid +graph LR + subgraph "Source Control" + GH[GitHub Repository] + ADO[Azure DevOps] + end + + subgraph "Authentication" + PAT[PAT Token] + KV[Key Vault] + end + + subgraph "DevCenter" + CAT[Catalog Sync] + IMG[Image Definitions] + end + + GH -->|Private Repo| PAT + ADO -->|Private Repo| PAT + PAT -->|Stored| KV + KV -->|Retrieved| CAT + CAT --> IMG + + style KV fill:#D32F2F,color:#fff +``` + +### Image Provenance + +| Control | Implementation | Status | +|---------|----------------|--------| +| Source Verification | PAT authentication | βœ… | +| Branch Protection | Git settings (external) | ⚠️ Manual | +| Catalog Sync Logs | DevCenter diagnostics | βœ… | + +### Dependency Management + +| Component | Version Control | Security Updates | +|-----------|-----------------|------------------| +| Bicep Templates | Git versioned | PR review required | +| YAML Configs | Git versioned | Schema validation | +| CI/CD Actions | Pinned versions | Dependabot alerts | + +--- + +## CI/CD Security + +### Pipeline Security Architecture + +```mermaid +graph TB + subgraph "GitHub Actions" + TRIGGER[Push/PR Trigger] + OIDC[OIDC Token Request] + BUILD[Build Bicep] + DEPLOY[azd provision] + end + + subgraph "Azure AD" + FED[Federated Credential] + TOKEN[Access Token] + end + + subgraph "Azure" + ARM[Resource Manager] + end + + TRIGGER --> OIDC + OIDC --> FED + FED --> TOKEN + TOKEN --> BUILD + BUILD --> DEPLOY + DEPLOY --> ARM + + style OIDC fill:#4CAF50,color:#fff + style FED fill:#0078D4,color:#fff +``` + +### OIDC Federation (No Stored Secrets) + +```yaml +# GitHub Actions workflow +- name: Log in with Azure (Federated Credentials) + run: | + azd auth login \ + --client-id "${{ vars.AZURE_CLIENT_ID }}" \ + --federated-credential-provider "github" \ + --tenant-id "${{ vars.AZURE_TENANT_ID }}" +``` + +**Benefits**: +- No long-lived secrets in repository +- Automatic token rotation +- Auditable via Azure AD logs + +### Pipeline Security Controls + +| Control | Implementation | Status | +|---------|----------------|--------| +| OIDC Authentication | Federated credentials | βœ… | +| Branch Protection | Main branch rules | ⚠️ External | +| Artifact Integrity | GitHub artifact storage | βœ… | +| Manual Approval | workflow_dispatch | βœ… | +| Environment Secrets | KEY_VAULT_SECRET only | βœ… | + +### Security Best Practices + +1. **No Hardcoded Secrets**: Use GitHub Secrets for sensitive values +2. **OIDC over Service Principals**: Eliminates secret management +3. **Pinned Action Versions**: Prevent supply chain attacks +4. **Branch Protection**: Require PR reviews for main + +--- + +## Security Recommendations + +### Current Gaps + +| Gap | Risk Level | Recommendation | Priority | +|-----|------------|----------------|----------| +| No Private Endpoints | Medium | Add PE for Key Vault | Medium | +| No NSG Rules | Low | Add explicit deny rules | Low | +| Manual PAT Rotation | Medium | Implement automated rotation | Medium | +| No Azure Policy | Medium | Add compliance policies | High | + +### Security Roadmap + +```mermaid +gantt + title Security Enhancement Roadmap + dateFormat YYYY-MM-DD + section Phase 1 + Azure Policy Integration :2026-02-01, 30d + Private Endpoints :2026-02-15, 30d + section Phase 2 + Automated Secret Rotation :2026-03-01, 45d + Advanced Monitoring :2026-03-15, 30d + section Phase 3 + Penetration Testing :2026-04-01, 15d + Security Review :2026-04-15, 15d +``` + +### Recommended Enhancements + +1. **Azure Policy**: Enforce Key Vault soft delete, require tags +2. **Private Endpoints**: Key Vault private endpoint for enhanced network security +3. **Secret Rotation**: Azure Automation for PAT rotation +4. **Microsoft Defender**: Enable Defender for Key Vault +5. **Resource Locks**: Prevent accidental deletion + +--- + +## References + +### Internal Documents + +- [Business Architecture](01-business-architecture.md) - Business context and stakeholders +- [Data Architecture](02-data-architecture.md) - Configuration schemas and data flows +- [Application Architecture](03-application-architecture.md) - Module design and Bicep structure +- [Technology Architecture](04-technology-architecture.md) - Azure services and infrastructure + +### External References + +- [Azure Security Baseline](https://learn.microsoft.com/en-us/security/benchmark/azure/) +- [Key Vault Security Best Practices](https://learn.microsoft.com/en-us/azure/key-vault/general/best-practices) +- [Azure RBAC Documentation](https://learn.microsoft.com/en-us/azure/role-based-access-control/) +- [Microsoft Cloud Security Benchmark](https://learn.microsoft.com/en-us/security/benchmark/azure/introduction) +- [NIST 800-53 Controls](https://csrc.nist.gov/publications/detail/sp/800-53/rev-5/final) +- [CIS Azure Benchmark](https://www.cisecurity.org/benchmark/azure) + +--- + +## Glossary + +| Term | Definition | +|------|------------| +| **Zero Trust** | Security model assuming no implicit trust | +| **RBAC** | Role-Based Access Control | +| **Managed Identity** | Azure-managed service identity | +| **OIDC Federation** | OpenID Connect-based secretless authentication | +| **Purge Protection** | Key Vault feature preventing permanent deletion | +| **Soft Delete** | Key Vault feature allowing secret recovery | +| **STRIDE** | Threat modeling framework (Spoofing, Tampering, Repudiation, Information Disclosure, DoS, Elevation) | +| **Defense in Depth** | Multiple layers of security controls | + +--- + +*Document generated as part of TOGAF Architecture Documentation for DevExp-DevBox Landing Zone Accelerator* From 98fe3b03c8e6db8716fdc214d06235431f6fe202 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 16:03:46 -0500 Subject: [PATCH 29/49] Refactor architecture documentation to enhance readability and consistency with emoji indicators --- docs/architecture/01-business-architecture.md | 60 ++++++++++++------- docs/architecture/02-data-architecture.md | 54 +++++++++++------ .../03-application-architecture.md | 54 +++++++++++------ 3 files changed, 109 insertions(+), 59 deletions(-) diff --git a/docs/architecture/01-business-architecture.md b/docs/architecture/01-business-architecture.md index a38316ab..f88790ef 100644 --- a/docs/architecture/01-business-architecture.md +++ b/docs/architecture/01-business-architecture.md @@ -1,4 +1,4 @@ -# Business Architecture +# πŸ“Š Business Architecture > **TOGAF Layer**: Business Architecture > **Version**: 1.0.0 @@ -7,21 +7,21 @@ --- -## Table of Contents +## πŸ“‘ Table of Contents -- [Executive Summary](#executive-summary) -- [Business Context](#business-context) -- [Stakeholder Analysis](#stakeholder-analysis) -- [Business Capabilities](#business-capabilities) -- [Value Streams](#value-streams) -- [Business Requirements](#business-requirements) -- [Success Metrics](#success-metrics) -- [References](#references) -- [Glossary](#glossary) +- [πŸ“‹ Executive Summary](#-executive-summary) +- [🎯 Business Context](#-business-context) +- [πŸ‘₯ Stakeholder Analysis](#-stakeholder-analysis) +- [πŸ—οΈ Business Capabilities](#️-business-capabilities) +- [πŸ”„ Value Streams](#-value-streams) +- [πŸ“ Business Requirements](#-business-requirements) +- [πŸ“ˆ Success Metrics](#-success-metrics) +- [πŸ“š References](#-references) +- [πŸ“– Glossary](#-glossary) --- -## Executive Summary +## πŸ“‹ Executive Summary The **DevExp-DevBox Landing Zone Accelerator** is an enterprise-grade infrastructure-as-code solution that streamlines the deployment and management of Microsoft Dev Box environments on Azure. This accelerator enables organizations to rapidly provision secure, compliant, and scalable developer workstations while maintaining governance controls and operational excellence. @@ -35,9 +35,11 @@ The **DevExp-DevBox Landing Zone Accelerator** is an enterprise-grade infrastruc | **Cost Optimization** | Right-sized VM SKUs per role and centralized resource management | | **Operational Efficiency** | Automated provisioning via Azure Developer CLI (azd) with CI/CD integration | +[↑ Back to Top](#-business-architecture) + --- -## Business Context +## 🎯 Business Context ### Problem Statement @@ -83,9 +85,11 @@ mindmap | **Talent Retention** | Modern developer experience | Medium | | **Compliance** | Meet regulatory requirements | High | +[↑ Back to Top](#-business-architecture) + --- -## Stakeholder Analysis +## πŸ‘₯ Stakeholder Analysis ### Stakeholder Map @@ -152,11 +156,13 @@ graph TB | Cost Management | R | I | I | C | **A** | | Incident Response | C | I | C | **R/A** | I | -*R = Responsible, A = Accountable, C = Consulted, I = Informed* +> **Legend**: R = Responsible, A = Accountable, C = Consulted, I = Informed + +[↑ Back to Top](#-business-architecture) --- -## Business Capabilities +## πŸ—οΈ Business Capabilities ### Business Capability Model @@ -243,9 +249,11 @@ graph TB | **Pool Management** | Workload | Dev Box Pools | Role-specific workstation configurations | | **Catalog Management** | Workload | Git Catalogs | Configuration-as-code for Dev Box definitions | +[↑ Back to Top](#-business-architecture) + --- -## Value Streams +## πŸ”„ Value Streams ### Developer Onboarding Value Stream @@ -317,9 +325,11 @@ stateDiagram-v2 Suspended --> InUse: Developer Resume ``` +[↑ Back to Top](#-business-architecture) + --- -## Business Requirements +## πŸ“ Business Requirements ### Functional Requirements @@ -349,9 +359,11 @@ stateDiagram-v2 | **NFR-007** | Disaster recovery | Reliability | RPO < 24 hours | Bicep redeployment | | **NFR-008** | Cost visibility | Manageability | Per-project breakdown | Azure Cost Management | +[↑ Back to Top](#-business-architecture) + --- -## Success Metrics +## πŸ“ˆ Success Metrics ### Key Performance Indicators (KPIs) @@ -404,9 +416,11 @@ graph TB | **Cost** | Infrastructure cost predictability | Β±10% budget variance | | **Speed** | Time to market for new projects | 2 weeks faster | +[↑ Back to Top](#-business-architecture) + --- -## References +## πŸ“š References ### Internal Documents @@ -422,9 +436,11 @@ graph TB - [Azure DevCenter Documentation](https://learn.microsoft.com/en-us/azure/dev-box/concept-dev-box-concepts) - [TOGAF Architecture Framework](https://www.opengroup.org/togaf) +[↑ Back to Top](#-business-architecture) + --- -## Glossary +## πŸ“– Glossary | Term | Definition | |------|------------| @@ -438,6 +454,8 @@ graph TB | **Managed Identity** | Azure AD identity automatically managed for Azure resources | | **azd** | Azure Developer CLI - Command-line tool for Azure development workflows | +[↑ Back to Top](#-business-architecture) + --- *Document generated as part of TOGAF Architecture Documentation for DevExp-DevBox Landing Zone Accelerator* diff --git a/docs/architecture/02-data-architecture.md b/docs/architecture/02-data-architecture.md index 35412276..7db79e61 100644 --- a/docs/architecture/02-data-architecture.md +++ b/docs/architecture/02-data-architecture.md @@ -1,4 +1,4 @@ -# Data Architecture +# πŸ—„οΈ Data Architecture > **TOGAF Layer**: Data Architecture > **Version**: 1.0.0 @@ -7,21 +7,21 @@ --- -## Table of Contents +## πŸ“‘ Table of Contents -- [Data Overview](#data-overview) -- [Configuration Data Model](#configuration-data-model) -- [Secrets Management](#secrets-management) -- [Telemetry & Diagnostics](#telemetry--diagnostics) -- [Data Flow Diagrams](#data-flow-diagrams) -- [Data Governance](#data-governance) -- [Schema Documentation](#schema-documentation) -- [References](#references) -- [Glossary](#glossary) +- [πŸ“Š Data Overview](#-data-overview) +- [βš™οΈ Configuration Data Model](#️-configuration-data-model) +- [πŸ” Secrets Management](#-secrets-management) +- [πŸ“‘ Telemetry & Diagnostics](#-telemetry--diagnostics) +- [πŸ”€ Data Flow Diagrams](#-data-flow-diagrams) +- [πŸ›οΈ Data Governance](#️-data-governance) +- [πŸ“‹ Schema Documentation](#-schema-documentation) +- [πŸ“š References](#-references) +- [πŸ“– Glossary](#-glossary) --- -## Data Overview +## πŸ“Š Data Overview The DevExp-DevBox Landing Zone Accelerator manages several categories of data that flow through the system during deployment and runtime operations. Understanding these data types is essential for security, compliance, and operational management. @@ -80,9 +80,11 @@ graph TB | Resource Metrics | Internal | Low | Azure Monitor | 93 days | | Deployment State | Internal | Medium | azd Environment | Until deleted | +[↑ Back to Top](#️-data-architecture) + --- -## Configuration Data Model +## βš™οΈ Configuration Data Model ### Overview @@ -287,9 +289,11 @@ projects: path: "/.devcenter/environments" ``` +[↑ Back to Top](#️-data-architecture) + --- -## Secrets Management +## πŸ” Secrets Management ### Secret Types @@ -366,9 +370,11 @@ sequenceDiagram | DevCenter Managed Identity | Key Vault Secrets Officer | Security RG | Manage secrets if needed | | CI/CD Service Principal | Deployer (custom) | Key Vault | Initial secret provisioning | +[↑ Back to Top](#️-data-architecture) + --- -## Telemetry & Diagnostics +## πŸ“‘ Telemetry & Diagnostics ### Log Analytics Data Collection @@ -437,9 +443,11 @@ AzureDiagnostics | project TimeGenerated, OperationName, ResultType, identity_claim_upn_s ``` +[↑ Back to Top](#️-data-architecture) + --- -## Data Flow Diagrams +## πŸ”€ Data Flow Diagrams ### Configuration Loading Flow @@ -580,9 +588,11 @@ sequenceDiagram | **Data Residency** | Region-specific deployment | Bicep location parameter | | **Right to Erasure** | Key Vault purge, resource deletion | Deletion scripts | +[↑ Back to Top](#️-data-architecture) + --- -## Schema Documentation +## πŸ“‹ Schema Documentation ### JSON Schema References @@ -666,9 +676,11 @@ Schemas are validated at authoring time using the `yaml-language-server` directi # yaml-language-server: $schema=./security.schema.json ``` +[↑ Back to Top](#️-data-architecture) + --- -## References +## πŸ“š References ### Internal Documents @@ -684,9 +696,11 @@ Schemas are validated at authoring time using the `yaml-language-server` directi - [Bicep loadYamlContent Function](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/bicep-functions-files#loadyamlcontent) - [JSON Schema Specification](https://json-schema.org/specification.html) +[↑ Back to Top](#️-data-architecture) + --- -## Glossary +## πŸ“– Glossary | Term | Definition | |------|------------| @@ -697,6 +711,8 @@ Schemas are validated at authoring time using the `yaml-language-server` directi | **Purge Protection** | Key Vault feature preventing permanent deletion during soft delete period | | **RBAC Authorization** | Key Vault access control using Azure Role-Based Access Control instead of access policies | +[↑ Back to Top](#️-data-architecture) + --- *Document generated as part of TOGAF Architecture Documentation for DevExp-DevBox Landing Zone Accelerator* diff --git a/docs/architecture/03-application-architecture.md b/docs/architecture/03-application-architecture.md index 344ef10d..393fd904 100644 --- a/docs/architecture/03-application-architecture.md +++ b/docs/architecture/03-application-architecture.md @@ -1,4 +1,4 @@ -# Application Architecture +# πŸ›οΈ Application Architecture > **TOGAF Layer**: Application Architecture > **Version**: 1.0.0 @@ -7,21 +7,21 @@ --- -## Table of Contents +## πŸ“‘ Table of Contents -- [Architecture Overview](#architecture-overview) -- [Module Catalog](#module-catalog) -- [Module Dependencies](#module-dependencies) -- [Deployment Orchestration](#deployment-orchestration) -- [Interface Contracts](#interface-contracts) -- [Design Patterns](#design-patterns) -- [Extension Points](#extension-points) -- [References](#references) -- [Glossary](#glossary) +- [πŸ” Architecture Overview](#-architecture-overview) +- [πŸ“¦ Module Catalog](#-module-catalog) +- [πŸ”— Module Dependencies](#-module-dependencies) +- [πŸš€ Deployment Orchestration](#-deployment-orchestration) +- [πŸ“ Interface Contracts](#-interface-contracts) +- [🎨 Design Patterns](#-design-patterns) +- [πŸ”Œ Extension Points](#-extension-points) +- [πŸ“š References](#-references) +- [πŸ“– Glossary](#-glossary) --- -## Architecture Overview +## πŸ” Architecture Overview The DevExp-DevBox Landing Zone Accelerator implements a **modular Infrastructure-as-Code (IaC)** architecture using Azure Bicep. The solution follows the **Landing Zone Accelerator** pattern with four distinct zones, each responsible for specific infrastructure concerns. @@ -110,9 +110,11 @@ graph TB | **Workload** | `resourceGroup` | devexp-workload-* | DevCenter, projects, pools | | **Connectivity** | `resourceGroup` | *-connectivity-RG | Virtual networks, network connections | +[↑ Back to Top](#️-application-architecture) + --- -## Module Catalog +## πŸ“¦ Module Catalog ### Entry Point Module @@ -713,9 +715,11 @@ graph TB | vnet.bicep | logAnalytics | networkConnection | | networkConnection.bicep | vnet, devCenter | connectivity | +[↑ Back to Top](#️-application-architecture) + --- -## Deployment Orchestration +## πŸš€ Deployment Orchestration ### Deployment Sequence Diagram @@ -804,9 +808,11 @@ hooks: | `SOURCE_CONTROL_PLATFORM` | `github` or `adogit` | User selection | | `AZURE_SUBSCRIPTION_ID` | Target subscription | Azure login | +[↑ Back to Top](#️-application-architecture) + --- -## Interface Contracts +## πŸ“ Interface Contracts ### Module Parameter Standards @@ -880,9 +886,11 @@ type Catalog = { } ``` +[↑ Back to Top](#️-application-architecture) + --- -## Design Patterns +## 🎨 Design Patterns ### Pattern 1: Modular Landing Zone Design @@ -999,9 +1007,11 @@ resource diagnosticSettings 'Microsoft.Insights/diagnosticSettings@...' = { } ``` +[↑ Back to Top](#️-application-architecture) + --- -## Extension Points +## πŸ”Œ Extension Points ### Adding a New Project @@ -1085,9 +1095,11 @@ module newzone '../src/newzone/newzone.bicep' = { } ``` +[↑ Back to Top](#️-application-architecture) + --- -## References +## πŸ“š References ### Internal Documents @@ -1103,9 +1115,11 @@ module newzone '../src/newzone/newzone.bicep' = { - [Azure Landing Zones](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/landing-zone/) - [DevCenter API Reference](https://learn.microsoft.com/en-us/rest/api/devcenter/) +[↑ Back to Top](#️-application-architecture) + --- -## Glossary +## πŸ“– Glossary | Term | Definition | |------|------------| @@ -1117,6 +1131,8 @@ module newzone '../src/newzone/newzone.bicep' = { | **loadYamlContent()** | Bicep function to load YAML configuration at compile time | | **azd** | Azure Developer CLI for streamlined Azure deployments | +[↑ Back to Top](#️-application-architecture) + --- *Document generated as part of TOGAF Architecture Documentation for DevExp-DevBox Landing Zone Accelerator* From 6dda419462f533635488c04c4bd04ab5c5fc5fe3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 16:04:19 -0500 Subject: [PATCH 30/49] Refactor Technology Architecture documentation for improved readability with emoji indicators --- .../04-technology-architecture.md | 70 ++++++++++++------- docs/architecture/05-security-architecture.md | 42 +++++------ 2 files changed, 67 insertions(+), 45 deletions(-) diff --git a/docs/architecture/04-technology-architecture.md b/docs/architecture/04-technology-architecture.md index 0fd076cd..b4272d8f 100644 --- a/docs/architecture/04-technology-architecture.md +++ b/docs/architecture/04-technology-architecture.md @@ -1,4 +1,4 @@ -# Technology Architecture +# βš™οΈ Technology Architecture > **TOGAF Layer**: Technology Architecture > **Version**: 1.0.0 @@ -7,23 +7,23 @@ --- -## Table of Contents +## πŸ“‘ Table of Contents -- [Infrastructure Overview](#infrastructure-overview) -- [Landing Zone Design](#landing-zone-design) -- [Network Architecture](#network-architecture) -- [Identity & Access](#identity--access) -- [Security Architecture](#security-architecture) -- [Monitoring & Observability](#monitoring--observability) -- [CI/CD Infrastructure](#cicd-infrastructure) -- [Deployment Tools](#deployment-tools) -- [DevOps Practices](#devops-practices) -- [References](#references) -- [Glossary](#glossary) +- [πŸ—οΈ Infrastructure Overview](#️-infrastructure-overview) +- [πŸ›οΈ Landing Zone Design](#️-landing-zone-design) +- [🌐 Network Architecture](#-network-architecture) +- [πŸ”‘ Identity & Access](#-identity--access) +- [πŸ”’ Security Architecture](#-security-architecture) +- [πŸ“Š Monitoring & Observability](#-monitoring--observability) +- [πŸ”„ CI/CD Infrastructure](#-cicd-infrastructure) +- [πŸ› οΈ Deployment Tools](#️-deployment-tools) +- [πŸ“‹ DevOps Practices](#-devops-practices) +- [πŸ“š References](#-references) +- [πŸ“– Glossary](#-glossary) --- -## Infrastructure Overview +## πŸ—οΈ Infrastructure Overview The DevExp-DevBox Landing Zone Accelerator deploys a comprehensive Azure infrastructure to support Microsoft Dev Box environments at enterprise scale. The solution leverages Platform-as-a-Service (PaaS) offerings for reduced operational overhead and built-in security. @@ -121,9 +121,11 @@ graph TB | Role Assignments | 2022-04-01 | Stable RBAC API | | Diagnostic Settings | 2021-05-01-preview | Stable diagnostics API | +[↑ Back to Top](#️-technology-architecture) + --- -## Landing Zone Design +## πŸ›οΈ Landing Zone Design ### Four-Zone Architecture @@ -198,9 +200,11 @@ tags: resources: ResourceType ``` +[↑ Back to Top](#️-technology-architecture) + --- -## Network Architecture +## 🌐 Network Architecture ### Network Architecture Diagram @@ -282,9 +286,11 @@ network: - **DNS**: Azure-provided or custom (for hybrid scenarios) - **Firewall**: Optional Azure Firewall integration for egress control +[↑ Back to Top](#️-technology-architecture) + --- -## Identity & Access +## πŸ”‘ Identity & Access ### Identity & RBAC Model @@ -367,9 +373,11 @@ graph TB | {Project} Developers | Deployment Environment User | Project | Deploy environments | | {Project} Developers | Key Vault Secrets User | Security RG | Access secrets | +[↑ Back to Top](#️-technology-architecture) + --- -## Security Architecture +## πŸ”’ Security Architecture ### Key Vault Configuration @@ -425,9 +433,11 @@ graph TB - **Private Link**: Optional for Key Vault and storage - **Azure AD Join**: No on-premises domain dependency +[↑ Back to Top](#️-technology-architecture) + --- -## Monitoring & Observability +## πŸ“Š Monitoring & Observability ### Log Analytics Integration @@ -521,9 +531,11 @@ AzureDiagnostics | summarize count() by OperationName, ResultType ``` +[↑ Back to Top](#️-technology-architecture) + --- -## CI/CD Infrastructure +## πŸ”„ CI/CD Infrastructure ### CI/CD Pipeline Flow @@ -610,9 +622,11 @@ graph LR | `KEY_VAULT_SECRET` | GitHub Secret | PAT token value | | `SOURCE_CONTROL_PLATFORM` | Environment | `github` or `adogit` | +[↑ Back to Top](#️-technology-architecture) + --- -## Deployment Tools +## πŸ› οΈ Deployment Tools ### Azure Developer CLI (azd) @@ -681,9 +695,11 @@ sequenceDiagram AZ-->>Script: Deployment complete ``` +[↑ Back to Top](#️-technology-architecture) + --- -## DevOps Practices +## πŸ“‹ DevOps Practices ### Release Strategy @@ -732,9 +748,11 @@ The CI pipeline generates semantic versions based on commit messages: | Artifact Upload | Build Success | Non-empty artifacts | | Deploy Approval | Manual | Environment owner approval | +[↑ Back to Top](#️-technology-architecture) + --- -## References +## πŸ“š References ### Internal Documents @@ -752,9 +770,11 @@ The CI pipeline generates semantic versions based on commit messages: - [GitHub Actions for Azure](https://learn.microsoft.com/en-us/azure/developer/github/github-actions) - [Azure DevOps Pipelines](https://learn.microsoft.com/en-us/azure/devops/pipelines/) +[↑ Back to Top](#️-technology-architecture) + --- -## Glossary +## πŸ“– Glossary | Term | Definition | |------|------------| @@ -767,6 +787,8 @@ The CI pipeline generates semantic versions based on commit messages: | **ARM** | Azure Resource Manager - Azure's deployment engine | | **Diagnostic Settings** | Azure configuration for log/metric routing | +[↑ Back to Top](#️-technology-architecture) + --- *Document generated as part of TOGAF Architecture Documentation for DevExp-DevBox Landing Zone Accelerator* diff --git a/docs/architecture/05-security-architecture.md b/docs/architecture/05-security-architecture.md index baf30de2..bd016f4b 100644 --- a/docs/architecture/05-security-architecture.md +++ b/docs/architecture/05-security-architecture.md @@ -1,4 +1,4 @@ -# Security Architecture +# πŸ” Security Architecture > **TOGAF Layer**: Security Architecture > **Version**: 1.0.0 @@ -7,29 +7,29 @@ --- -## Table of Contents - -- [Security Overview](#security-overview) -- [Threat Model](#threat-model) -- [Identity & Access Management](#identity--access-management) -- [Authorization & RBAC](#authorization--rbac) -- [Secrets Management](#secrets-management) -- [Network Security](#network-security) -- [Data Protection](#data-protection) -- [Security Monitoring & Logging](#security-monitoring--logging) -- [Compliance & Governance](#compliance--governance) -- [Security Controls Matrix](#security-controls-matrix) -- [Incident Response](#incident-response) -- [Security Hardening](#security-hardening) -- [Supply Chain Security](#supply-chain-security) -- [CI/CD Security](#cicd-security) -- [Security Recommendations](#security-recommendations) -- [References](#references) -- [Glossary](#glossary) +## πŸ“‘ Table of Contents + +- [πŸ›‘οΈ Security Overview](#️-security-overview) +- [⚠️ Threat Model](#️-threat-model) +- [πŸ”‘ Identity & Access Management](#-identity--access-management) +- [βœ… Authorization & RBAC](#-authorization--rbac) +- [πŸ”’ Secrets Management](#-secrets-management) +- [🌐 Network Security](#-network-security) +- [πŸ“€ Data Protection](#-data-protection) +- [πŸ“Š Security Monitoring & Logging](#-security-monitoring--logging) +- [πŸ“‹ Compliance & Governance](#-compliance--governance) +- [🎯 Security Controls Matrix](#-security-controls-matrix) +- [🚨 Incident Response](#-incident-response) +- [πŸ› οΈ Security Hardening](#️-security-hardening) +- [πŸ“¦ Supply Chain Security](#-supply-chain-security) +- [πŸ”„ CI/CD Security](#-cicd-security) +- [πŸ’‘ Security Recommendations](#-security-recommendations) +- [πŸ“š References](#-references) +- [πŸ“– Glossary](#-glossary) --- -## Security Overview +## πŸ›‘οΈ Security Overview The DevExp-DevBox Landing Zone Accelerator implements a **defense-in-depth** security strategy aligned with **Zero Trust** principles. Security controls are embedded at every layer: identity, network, data, and application. From 97fcdf48809df0ae9a12ebbe08d30e0af69244fa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 16:04:26 -0500 Subject: [PATCH 31/49] Refactor Security Architecture documentation for improved clarity and consistency --- docs/architecture/05-security-architecture.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/architecture/05-security-architecture.md b/docs/architecture/05-security-architecture.md index bd016f4b..c6a5bd69 100644 --- a/docs/architecture/05-security-architecture.md +++ b/docs/architecture/05-security-architecture.md @@ -161,7 +161,7 @@ graph TB - **STRIDE Category**: Information Disclosure - **Attack Vector**: Compromised identity attempts to read GitHub PAT from Key Vault - **Affected Assets**: Key Vault secrets, Git repositories -- **Mitigations**: +- **Mitigations**: - RBAC-based Key Vault authorization - Managed identities (no stored credentials) - Key Vault audit logging @@ -290,6 +290,7 @@ identity: ``` **Benefits**: + - No credential storage required - Automatic credential rotation - Azure-managed lifecycle @@ -609,6 +610,7 @@ graph LR ### Security Queries **Unauthorized Secret Access Attempts**: + ```kusto AzureDiagnostics | where ResourceProvider == "MICROSOFT.KEYVAULT" @@ -618,6 +620,7 @@ AzureDiagnostics ``` **Privilege Escalation Detection**: + ```kusto AzureActivity | where OperationNameValue contains "roleAssignments/write" @@ -625,6 +628,7 @@ AzureActivity ``` **Suspicious DevCenter Operations**: + ```kusto AzureDiagnostics | where ResourceProvider == "MICROSOFT.DEVCENTER" @@ -880,6 +884,7 @@ graph TB ``` **Benefits**: + - No long-lived secrets in repository - Automatic token rotation - Auditable via Azure AD logs From 594e43aee03a45fe30a65cb6e4894dc876e959f9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 16:05:01 -0500 Subject: [PATCH 32/49] Refactor Security Architecture documentation to enhance readability with emoji indicators and back-to-top links --- docs/architecture/05-security-architecture.md | 62 ++++++++++++++----- 1 file changed, 47 insertions(+), 15 deletions(-) diff --git a/docs/architecture/05-security-architecture.md b/docs/architecture/05-security-architecture.md index c6a5bd69..80281a1c 100644 --- a/docs/architecture/05-security-architecture.md +++ b/docs/architecture/05-security-architecture.md @@ -113,9 +113,11 @@ graph TB | **Monitoring** | βœ… Strong | Centralized logging, diagnostic settings | | **CI/CD** | βœ… Strong | OIDC federation, no stored secrets | +[↑ Back to Top](#-security-architecture) + --- -## Threat Model +## ⚠️ Threat Model ### STRIDE Analysis @@ -233,9 +235,11 @@ graph TB | Network Attacks | Low | Medium | Low | βœ… Mitigated | | CI/CD Compromise | Low | Critical | Medium | βœ… Mitigated | +[↑ Back to Top](#-security-architecture) + --- -## Identity & Access Management +## πŸ”‘ Identity & Access Management ### Identity Architecture @@ -322,9 +326,11 @@ sequenceDiagram KV-->>DC: Secret Value ``` +[↑ Back to Top](#-security-architecture) + --- -## Authorization & RBAC +## βœ… Authorization & RBAC ### RBAC Hierarchy @@ -381,9 +387,11 @@ graph TB | DevCenter | Platform management | DevCenter admins | | Project | Team isolation | Project-level roles | +[↑ Back to Top](#-security-architecture) + --- -## Secrets Management +## πŸ”’ Secrets Management ### Key Vault Architecture @@ -468,9 +476,11 @@ sequenceDiagram | `softDeleteRetentionInDays` | `7` | Minimum retention | | `enableRbacAuthorization` | `true` | RBAC instead of access policies | +[↑ Back to Top](#-security-architecture) + --- -## Network Security +## 🌐 Network Security ### Network Security Topology @@ -533,9 +543,11 @@ graph TB 3. **Azure Firewall**: Add for egress control in enterprise scenarios 4. **Azure Bastion**: Use for secure Dev Box access +[↑ Back to Top](#-security-architecture) + --- -## Data Protection +## πŸ“€ Data Protection ### Encryption Matrix @@ -561,9 +573,11 @@ graph TB - **PAT Tokens**: Retrieved at runtime, not embedded in templates - **User Data**: Managed on Dev Box disks with encryption +[↑ Back to Top](#-security-architecture) + --- -## Security Monitoring & Logging +## πŸ“Š Security Monitoring & Logging ### Security Logging Architecture @@ -646,9 +660,11 @@ AzureDiagnostics | Role Assignment Change | roleAssignments/write | High | | DevCenter Config Change | DevCenter update operations | Medium | +[↑ Back to Top](#-security-architecture) + --- -## Compliance & Governance +## πŸ“‹ Compliance & Governance ### Compliance Mapping @@ -680,9 +696,11 @@ tags: | Log Analytics | CanNotDelete | Preserve audit logs | | DevCenter | CanNotDelete | Protect platform | +[↑ Back to Top](#-security-architecture) + --- -## Security Controls Matrix +## 🎯 Security Controls Matrix ### Control Inventory @@ -755,9 +773,11 @@ tags: | High | Platform + Security | CISO | | Critical | All Teams | Incident Commander | +[↑ Back to Top](#-security-architecture) + --- -## Security Hardening +## πŸ› οΈ Security Hardening ### Key Vault Hardening @@ -788,9 +808,11 @@ The accelerator implements secure defaults: - βœ… Diagnostic settings on all resources - βœ… OIDC federation for CI/CD (no secrets in pipelines) +[↑ Back to Top](#-security-architecture) + --- -## Supply Chain Security +## πŸ“¦ Supply Chain Security ### Catalog Security @@ -836,9 +858,11 @@ graph LR | YAML Configs | Git versioned | Schema validation | | CI/CD Actions | Pinned versions | Dependabot alerts | +[↑ Back to Top](#-security-architecture) + --- -## CI/CD Security +## πŸ”„ CI/CD Security ### Pipeline Security Architecture @@ -906,9 +930,11 @@ graph TB 3. **Pinned Action Versions**: Prevent supply chain attacks 4. **Branch Protection**: Require PR reviews for main +[↑ Back to Top](#-security-architecture) + --- -## Security Recommendations +## πŸ’‘ Security Recommendations ### Current Gaps @@ -944,9 +970,11 @@ gantt 4. **Microsoft Defender**: Enable Defender for Key Vault 5. **Resource Locks**: Prevent accidental deletion +[↑ Back to Top](#-security-architecture) + --- -## References +## πŸ“š References ### Internal Documents @@ -964,9 +992,11 @@ gantt - [NIST 800-53 Controls](https://csrc.nist.gov/publications/detail/sp/800-53/rev-5/final) - [CIS Azure Benchmark](https://www.cisecurity.org/benchmark/azure) +[↑ Back to Top](#-security-architecture) + --- -## Glossary +## πŸ“– Glossary | Term | Definition | |------|------------| @@ -979,6 +1009,8 @@ gantt | **STRIDE** | Threat modeling framework (Spoofing, Tampering, Repudiation, Information Disclosure, DoS, Elevation) | | **Defense in Depth** | Multiple layers of security controls | +[↑ Back to Top](#-security-architecture) + --- *Document generated as part of TOGAF Architecture Documentation for DevExp-DevBox Landing Zone Accelerator* From f5e72015a47b227634caf407682f17545f7beb16 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 16:05:40 -0500 Subject: [PATCH 33/49] Refactor architecture documentation for improved clarity and consistency with emoji indicators --- docs/architecture/01-business-architecture.md | 6 ++++-- docs/architecture/02-data-architecture.md | 4 +++- docs/architecture/03-application-architecture.md | 2 +- docs/architecture/04-technology-architecture.md | 2 +- docs/architecture/05-security-architecture.md | 8 ++++++-- 5 files changed, 15 insertions(+), 7 deletions(-) diff --git a/docs/architecture/01-business-architecture.md b/docs/architecture/01-business-architecture.md index f88790ef..3fc5c8d1 100644 --- a/docs/architecture/01-business-architecture.md +++ b/docs/architecture/01-business-architecture.md @@ -25,10 +25,12 @@ The **DevExp-DevBox Landing Zone Accelerator** is an enterprise-grade infrastructure-as-code solution that streamlines the deployment and management of Microsoft Dev Box environments on Azure. This accelerator enables organizations to rapidly provision secure, compliant, and scalable developer workstations while maintaining governance controls and operational excellence. +> πŸ’‘ **Key Benefit**: Reduce developer onboarding time from days to minutes with pre-configured, secure environments. + ### Key Business Value Propositions | Value Area | Description | -|------------|-------------| +|:-----------|:------------| | **Accelerated Developer Onboarding** | Reduce new developer setup time from days to minutes through pre-configured Dev Box environments | | **Standardized Development Environments** | Ensure consistency across teams with role-specific configurations (backend, frontend engineers) | | **Security & Compliance** | Built-in security controls with Key Vault integration, RBAC, and Azure AD authentication | @@ -77,7 +79,7 @@ mindmap ### Business Drivers | Driver | Description | Priority | -|--------|-------------|----------| +|:-------|:------------|:--------:| | **Developer Productivity** | Eliminate environment setup overhead | High | | **Security Posture** | Centralized security controls and monitoring | High | | **Operational Excellence** | Automated, repeatable deployments | High | diff --git a/docs/architecture/02-data-architecture.md b/docs/architecture/02-data-architecture.md index 7db79e61..4f438076 100644 --- a/docs/architecture/02-data-architecture.md +++ b/docs/architecture/02-data-architecture.md @@ -70,7 +70,7 @@ graph TB ### Data Classification | Data Type | Classification | Sensitivity | Storage Location | Retention | -|-----------|---------------|-------------|------------------|-----------| +|:----------|:--------------:|:-----------:|:-----------------|:----------| | Resource Organization Config | Internal | Low | Git Repository | Version controlled | | Security Configuration | Confidential | Medium | Git Repository | Version controlled | | DevCenter Configuration | Internal | Low | Git Repository | Version controlled | @@ -295,6 +295,8 @@ projects: ## πŸ” Secrets Management +> πŸ”’ **Important**: All secrets are stored in Azure Key Vault with RBAC authorization. Never commit secrets to source control. + ### Secret Types | Secret | Purpose | Storage | Rotation | diff --git a/docs/architecture/03-application-architecture.md b/docs/architecture/03-application-architecture.md index 393fd904..50055ced 100644 --- a/docs/architecture/03-application-architecture.md +++ b/docs/architecture/03-application-architecture.md @@ -103,7 +103,7 @@ graph TB ### Deployment Scopes | Zone | Bicep Scope | Resource Group | Purpose | -|------|-------------|----------------|---------| +|:-----|:-----------:|:---------------|:--------| | **Orchestrator** | `subscription` | Creates RGs | Entry point, resource group creation | | **Security** | `resourceGroup` | devexp-security-* | Key Vault, secrets management | | **Monitoring** | `resourceGroup` | devexp-monitoring-* | Log Analytics, diagnostics | diff --git a/docs/architecture/04-technology-architecture.md b/docs/architecture/04-technology-architecture.md index b4272d8f..98d0ae3a 100644 --- a/docs/architecture/04-technology-architecture.md +++ b/docs/architecture/04-technology-architecture.md @@ -81,7 +81,7 @@ graph TB ### Azure Services Deployed | Service | Resource Type | Landing Zone | Purpose | -|---------|--------------|--------------|---------| +|:--------|:--------------|:------------:|:--------| | **Azure DevCenter** | Microsoft.DevCenter/devcenters | Workload | Central management for Dev Box environments | | **DevCenter Projects** | Microsoft.DevCenter/projects | Workload | Team-level Dev Box organization | | **Dev Box Pools** | Microsoft.DevCenter/projects/pools | Workload | VM configuration templates | diff --git a/docs/architecture/05-security-architecture.md b/docs/architecture/05-security-architecture.md index 80281a1c..9e775da2 100644 --- a/docs/architecture/05-security-architecture.md +++ b/docs/architecture/05-security-architecture.md @@ -105,8 +105,10 @@ graph TB ### Security Posture Summary +> πŸ›‘οΈ **Security Status Overview**: The accelerator implements strong security controls across identity, secrets, and monitoring. Network security is moderate with optional enhancements available. + | Area | Status | Key Controls | -|------|--------|--------------| +|:-----|:------:|:-------------| | **Identity** | βœ… Strong | Managed identities, Azure AD integration, RBAC | | **Secrets** | βœ… Strong | Key Vault with purge protection, RBAC authorization | | **Network** | ⚠️ Moderate | VNet isolation available, private endpoints optional | @@ -227,8 +229,10 @@ graph TB ### Risk Assessment Matrix +> ⚠️ **Note**: Catalog tampering risk depends on external source control security configuration. + | Threat | Likelihood | Impact | Risk Score | Mitigation Status | -|--------|------------|--------|------------|-------------------| +|:-------|:----------:|:------:|:----------:|:-----------------:| | Unauthorized Secret Access | Low | High | Medium | βœ… Mitigated | | Catalog Tampering | Medium | High | High | ⚠️ Partial | | Privilege Escalation | Low | Critical | Medium | βœ… Mitigated | From b8660de8e31f7b2d2f6719357519b38d7304ac3a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 16:06:14 -0500 Subject: [PATCH 34/49] Refactor architecture documentation tables for improved formatting and consistency --- docs/architecture/01-business-architecture.md | 4 ++-- docs/architecture/02-data-architecture.md | 2 +- docs/architecture/04-technology-architecture.md | 6 ++++-- docs/architecture/05-security-architecture.md | 2 ++ 4 files changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/architecture/01-business-architecture.md b/docs/architecture/01-business-architecture.md index 3fc5c8d1..a304ee9e 100644 --- a/docs/architecture/01-business-architecture.md +++ b/docs/architecture/01-business-architecture.md @@ -336,7 +336,7 @@ stateDiagram-v2 ### Functional Requirements | ID | Requirement | Priority | Landing Zone | -|----|-------------|----------|--------------| +|:---|:------------|:--------:|:-------------| | **FR-001** | Deploy Azure DevCenter with project organization | Must Have | Workload | | **FR-002** | Provision Dev Box pools with role-specific configurations | Must Have | Workload | | **FR-003** | Integrate Git catalogs for image definitions | Must Have | Workload | @@ -351,7 +351,7 @@ stateDiagram-v2 ### Non-Functional Requirements | ID | Requirement | Category | Target | Measurement | -|----|-------------|----------|--------|-------------| +|:---|:------------|:---------|:-------|:------------| | **NFR-001** | Infrastructure deployment time | Performance | < 30 minutes | azd provision duration | | **NFR-002** | Dev Box startup time | Performance | < 15 minutes | DevCenter metrics | | **NFR-003** | System availability | Reliability | 99.9% | Azure Monitor | diff --git a/docs/architecture/02-data-architecture.md b/docs/architecture/02-data-architecture.md index 4f438076..2e5d741c 100644 --- a/docs/architecture/02-data-architecture.md +++ b/docs/architecture/02-data-architecture.md @@ -206,7 +206,7 @@ tags: **File**: `infra/settings/security/security.yaml` | Property | Type | Description | Constraints | -|----------|------|-------------|-------------| +|:---------|:-----|:------------|:------------| | `create` | boolean | Create Key Vault | Required | | `keyVault.name` | string | Key Vault name prefix | 3-24 chars, alphanumeric | | `keyVault.description` | string | Purpose description | Optional | diff --git a/docs/architecture/04-technology-architecture.md b/docs/architecture/04-technology-architecture.md index 98d0ae3a..4efcd24a 100644 --- a/docs/architecture/04-technology-architecture.md +++ b/docs/architecture/04-technology-architecture.md @@ -111,7 +111,7 @@ graph TB ### API Versions | Resource | API Version | Notes | -|----------|-------------|-------| +|:---------|:-----------:|:------| | Resource Groups | 2025-04-01 | Latest stable | | DevCenter | 2025-10-01-preview | Preview for latest features | | Key Vault | 2025-05-01 | Latest stable | @@ -251,7 +251,7 @@ graph TB ### Network Configuration Options | Option | Type | Use Case | Configuration | -|--------|------|----------|---------------| +|:-------|:----:|:---------|:--------------| | **Microsoft Hosted** | Managed | Simple deployments, no custom networking | `virtualNetworkType: Managed` | | **Customer Managed** | Unmanaged | Hybrid connectivity, custom DNS, firewall | `virtualNetworkType: Unmanaged` | @@ -630,6 +630,8 @@ graph LR ### Azure Developer CLI (azd) +> πŸ› οΈ **Prerequisite**: Ensure Azure Developer CLI (`azd`) is installed. See [installation guide](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd). + The primary deployment tool is Azure Developer CLI (`azd`), configured via `azure.yaml`: ```yaml diff --git a/docs/architecture/05-security-architecture.md b/docs/architecture/05-security-architecture.md index 9e775da2..de36431a 100644 --- a/docs/architecture/05-security-architecture.md +++ b/docs/architecture/05-security-architecture.md @@ -176,6 +176,8 @@ graph TB #### Threat: Catalog Tampering +> ⚠️ **Warning**: This threat depends on external source control security. Ensure proper branch protection rules are configured. + - **STRIDE Category**: Tampering - **Attack Vector**: Attacker modifies Dev Box image definitions in catalog repository - **Affected Assets**: Dev Box images, developer workstations From f9c96158fed844b8c73b34f143ad1885f2eb3a70 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 16:08:58 -0500 Subject: [PATCH 35/49] Refactor architecture documentation for improved clarity, navigation, and consistency with added target audience and reading time indicators --- docs/architecture/01-business-architecture.md | 55 ++++++++++++++++++- docs/architecture/02-data-architecture.md | 55 ++++++++++++++++++- .../03-application-architecture.md | 52 ++++++++++++++++++ .../04-technology-architecture.md | 55 ++++++++++++++++++- 4 files changed, 214 insertions(+), 3 deletions(-) diff --git a/docs/architecture/01-business-architecture.md b/docs/architecture/01-business-architecture.md index a304ee9e..9fa10035 100644 --- a/docs/architecture/01-business-architecture.md +++ b/docs/architecture/01-business-architecture.md @@ -1,5 +1,32 @@ +--- +title: "Business Architecture" +description: "TOGAF Business Architecture documentation for the DevExp-DevBox Landing Zone Accelerator, covering stakeholder analysis, business capabilities, value streams, and success metrics." +author: "DevExp Team" +date: "2026-01-22" +version: "1.0.0" +tags: + - TOGAF + - Business Architecture + - DevExp + - Dev Box + - Azure +--- + # πŸ“Š Business Architecture +> [!NOTE] +> **Target Audience**: Business Decision Makers, Enterprise Architects, Project Managers +> **Reading Time**: ~15 minutes + +
+πŸ“ Document Navigation + +| Previous | Index | Next | +|:---------|:-----:|-----:| +| β€” | [Architecture Index](README.md) | [Data Architecture β†’](02-data-architecture.md) | + +
+ > **TOGAF Layer**: Business Architecture > **Version**: 1.0.0 > **Last Updated**: January 22, 2026 @@ -25,7 +52,8 @@ The **DevExp-DevBox Landing Zone Accelerator** is an enterprise-grade infrastructure-as-code solution that streamlines the deployment and management of Microsoft Dev Box environments on Azure. This accelerator enables organizations to rapidly provision secure, compliant, and scalable developer workstations while maintaining governance controls and operational excellence. -> πŸ’‘ **Key Benefit**: Reduce developer onboarding time from days to minutes with pre-configured, secure environments. +> [!TIP] +> **Key Benefit**: Reduce developer onboarding time from days to minutes with pre-configured, secure environments. ### Key Business Value Propositions @@ -460,4 +488,29 @@ graph TB --- +## πŸ“Ž Related Documents + +
+TOGAF Architecture Series + +| Document | Description | +|:---------|:------------| +| πŸ“Š **Business Architecture** | *You are here* | +| [πŸ—„οΈ Data Architecture](02-data-architecture.md) | Configuration schemas, secrets management, data flows | +| [πŸ›οΈ Application Architecture](03-application-architecture.md) | Bicep module design, dependencies, patterns | +| [βš™οΈ Technology Architecture](04-technology-architecture.md) | Azure services, CI/CD, deployment tools | +| [πŸ” Security Architecture](05-security-architecture.md) | Threat model, RBAC, compliance controls | + +
+ +--- + +
+ +**[← Previous: Index](README.md)** | **[Next: Data Architecture β†’](02-data-architecture.md)** + +--- + *Document generated as part of TOGAF Architecture Documentation for DevExp-DevBox Landing Zone Accelerator* + +
diff --git a/docs/architecture/02-data-architecture.md b/docs/architecture/02-data-architecture.md index 2e5d741c..6e48e5fd 100644 --- a/docs/architecture/02-data-architecture.md +++ b/docs/architecture/02-data-architecture.md @@ -1,5 +1,32 @@ +--- +title: "Data Architecture" +description: "TOGAF Data Architecture documentation for the DevExp-DevBox Landing Zone Accelerator, covering configuration data models, secrets management, telemetry, and data governance." +author: "DevExp Team" +date: "2026-01-22" +version: "1.0.0" +tags: + - TOGAF + - Data Architecture + - DevExp + - Key Vault + - Azure +--- + # πŸ—„οΈ Data Architecture +> [!NOTE] +> **Target Audience**: Data Architects, Platform Engineers, Security Teams +> **Reading Time**: ~20 minutes + +
+πŸ“ Document Navigation + +| Previous | Index | Next | +|:---------|:-----:|-----:| +| [← Business Architecture](01-business-architecture.md) | [Architecture Index](README.md) | [Application Architecture β†’](03-application-architecture.md) | + +
+ > **TOGAF Layer**: Data Architecture > **Version**: 1.0.0 > **Last Updated**: January 22, 2026 @@ -295,7 +322,8 @@ projects: ## πŸ” Secrets Management -> πŸ”’ **Important**: All secrets are stored in Azure Key Vault with RBAC authorization. Never commit secrets to source control. +> [!IMPORTANT] +> All secrets are stored in Azure Key Vault with RBAC authorization. Never commit secrets to source control. ### Secret Types @@ -717,4 +745,29 @@ Schemas are validated at authoring time using the `yaml-language-server` directi --- +## πŸ“Ž Related Documents + +
+TOGAF Architecture Series + +| Document | Description | +|:---------|:------------| +| [πŸ“Š Business Architecture](01-business-architecture.md) | Stakeholder analysis, capabilities, value streams | +| πŸ—„οΈ **Data Architecture** | *You are here* | +| [πŸ›οΈ Application Architecture](03-application-architecture.md) | Bicep module design, dependencies, patterns | +| [βš™οΈ Technology Architecture](04-technology-architecture.md) | Azure services, CI/CD, deployment tools | +| [πŸ” Security Architecture](05-security-architecture.md) | Threat model, RBAC, compliance controls | + +
+ +--- + +
+ +**[← Previous: Business Architecture](01-business-architecture.md)** | **[Next: Application Architecture β†’](03-application-architecture.md)** + +--- + *Document generated as part of TOGAF Architecture Documentation for DevExp-DevBox Landing Zone Accelerator* + +
diff --git a/docs/architecture/03-application-architecture.md b/docs/architecture/03-application-architecture.md index 50055ced..a52bfa8e 100644 --- a/docs/architecture/03-application-architecture.md +++ b/docs/architecture/03-application-architecture.md @@ -1,5 +1,32 @@ +--- +title: "Application Architecture" +description: "TOGAF Application Architecture documentation for the DevExp-DevBox Landing Zone Accelerator, covering Bicep module catalog, dependencies, deployment orchestration, and design patterns." +author: "DevExp Team" +date: "2026-01-22" +version: "1.0.0" +tags: + - TOGAF + - Application Architecture + - DevExp + - Bicep + - Infrastructure as Code +--- + # πŸ›οΈ Application Architecture +> [!NOTE] +> **Target Audience**: Platform Engineers, DevOps Engineers, Infrastructure Architects +> **Reading Time**: ~25 minutes + +
+πŸ“ Document Navigation + +| Previous | Index | Next | +|:---------|:-----:|-----:| +| [← Data Architecture](02-data-architecture.md) | [Architecture Index](README.md) | [Technology Architecture β†’](04-technology-architecture.md) | + +
+ > **TOGAF Layer**: Application Architecture > **Version**: 1.0.0 > **Last Updated**: January 22, 2026 @@ -1135,4 +1162,29 @@ module newzone '../src/newzone/newzone.bicep' = { --- +## πŸ“Ž Related Documents + +
+TOGAF Architecture Series + +| Document | Description | +|:---------|:------------| +| [πŸ“Š Business Architecture](01-business-architecture.md) | Stakeholder analysis, capabilities, value streams | +| [πŸ—„οΈ Data Architecture](02-data-architecture.md) | Configuration schemas, secrets management, data flows | +| πŸ›οΈ **Application Architecture** | *You are here* | +| [βš™οΈ Technology Architecture](04-technology-architecture.md) | Azure services, CI/CD, deployment tools | +| [πŸ” Security Architecture](05-security-architecture.md) | Threat model, RBAC, compliance controls | + +
+ +--- + +
+ +**[← Previous: Data Architecture](02-data-architecture.md)** | **[Next: Technology Architecture β†’](04-technology-architecture.md)** + +--- + *Document generated as part of TOGAF Architecture Documentation for DevExp-DevBox Landing Zone Accelerator* + +
diff --git a/docs/architecture/04-technology-architecture.md b/docs/architecture/04-technology-architecture.md index 4efcd24a..6e4a52a0 100644 --- a/docs/architecture/04-technology-architecture.md +++ b/docs/architecture/04-technology-architecture.md @@ -1,5 +1,32 @@ +--- +title: "Technology Architecture" +description: "TOGAF Technology Architecture documentation for the DevExp-DevBox Landing Zone Accelerator, covering Azure infrastructure, landing zones, networking, CI/CD, and deployment tools." +author: "DevExp Team" +date: "2026-01-22" +version: "1.0.0" +tags: + - TOGAF + - Technology Architecture + - DevExp + - Azure + - DevOps +--- + # βš™οΈ Technology Architecture +> [!NOTE] +> **Target Audience**: Cloud Architects, DevOps Engineers, Infrastructure Teams +> **Reading Time**: ~20 minutes + +
+πŸ“ Document Navigation + +| Previous | Index | Next | +|:---------|:-----:|-----:| +| [← Application Architecture](03-application-architecture.md) | [Architecture Index](README.md) | [Security Architecture β†’](05-security-architecture.md) | + +
+ > **TOGAF Layer**: Technology Architecture > **Version**: 1.0.0 > **Last Updated**: January 22, 2026 @@ -630,7 +657,8 @@ graph LR ### Azure Developer CLI (azd) -> πŸ› οΈ **Prerequisite**: Ensure Azure Developer CLI (`azd`) is installed. See [installation guide](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd). +> [!TIP] +> **Prerequisite**: Ensure Azure Developer CLI (`azd`) is installed. See [installation guide](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd). The primary deployment tool is Azure Developer CLI (`azd`), configured via `azure.yaml`: @@ -793,4 +821,29 @@ The CI pipeline generates semantic versions based on commit messages: --- +## πŸ“Ž Related Documents + +
+TOGAF Architecture Series + +| Document | Description | +|:---------|:------------| +| [πŸ“Š Business Architecture](01-business-architecture.md) | Stakeholder analysis, capabilities, value streams | +| [πŸ—„οΈ Data Architecture](02-data-architecture.md) | Configuration schemas, secrets management, data flows | +| [πŸ›οΈ Application Architecture](03-application-architecture.md) | Bicep module design, dependencies, patterns | +| βš™οΈ **Technology Architecture** | *You are here* | +| [πŸ” Security Architecture](05-security-architecture.md) | Threat model, RBAC, compliance controls | + +
+ +--- + +
+ +**[← Previous: Application Architecture](03-application-architecture.md)** | **[Next: Security Architecture β†’](05-security-architecture.md)** + +--- + *Document generated as part of TOGAF Architecture Documentation for DevExp-DevBox Landing Zone Accelerator* + +
From 8dce170415fba861fd71cf0b035bbd05117fde9b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 16:09:08 -0500 Subject: [PATCH 36/49] Refactor Security Architecture documentation for enhanced clarity, improved navigation, and added target audience and reading time indicators --- docs/architecture/05-security-architecture.md | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/architecture/05-security-architecture.md b/docs/architecture/05-security-architecture.md index de36431a..1b8ce1b4 100644 --- a/docs/architecture/05-security-architecture.md +++ b/docs/architecture/05-security-architecture.md @@ -1,5 +1,32 @@ +--- +title: "Security Architecture" +description: "TOGAF Security Architecture documentation for the DevExp-DevBox Landing Zone Accelerator, covering threat modeling, identity management, RBAC, secrets management, and compliance controls." +author: "DevExp Team" +date: "2026-01-22" +version: "1.0.0" +tags: + - TOGAF + - Security Architecture + - DevExp + - Zero Trust + - Azure Security +--- + # πŸ” Security Architecture +> [!NOTE] +> **Target Audience**: Security Architects, Compliance Teams, Platform Engineers +> **Reading Time**: ~25 minutes + +
+πŸ“ Document Navigation + +| Previous | Index | Next | +|:---------|:-----:|-----:| +| [← Technology Architecture](04-technology-architecture.md) | [Architecture Index](README.md) | β€” | + +
+ > **TOGAF Layer**: Security Architecture > **Version**: 1.0.0 > **Last Updated**: January 22, 2026 From 5e0807614624239fc49f9ee0a0ea74195e869379 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 16:10:14 -0500 Subject: [PATCH 37/49] Refactor architecture documentation for improved navigation and clarity with expandable sections for Stakeholder Registry and RACI Matrix, and add related documents index. --- docs/architecture/01-business-architecture.md | 11 ++ docs/architecture/05-security-architecture.md | 34 ++++- docs/architecture/README.md | 132 ++++++++++++++++++ 3 files changed, 174 insertions(+), 3 deletions(-) create mode 100644 docs/architecture/README.md diff --git a/docs/architecture/01-business-architecture.md b/docs/architecture/01-business-architecture.md index 9fa10035..27bc8586 100644 --- a/docs/architecture/01-business-architecture.md +++ b/docs/architecture/01-business-architecture.md @@ -164,6 +164,9 @@ graph TB ### Stakeholder Registry +
+Click to expand Stakeholder Registry table + | Stakeholder | Role | Concerns | Interests | Engagement Level | |-------------|------|----------|-----------|------------------| | **Platform Engineers** | Build & maintain landing zones | Automation, scalability, maintainability | Infrastructure as Code, self-service capabilities | High - Primary implementers | @@ -175,8 +178,13 @@ graph TB | **CISO** | Security governance | Risk mitigation, compliance adherence | Security posture, audit readiness | Medium - Policy approval | | **CFO** | Financial oversight | Cost control, budget planning | Infrastructure cost visibility, optimization | Low - Budget approval | +
+ ### RACI Matrix +
+Click to expand RACI Matrix + | Activity | Platform Engineers | Dev Teams | Security | Operations | Project Managers | |----------|-------------------|-----------|----------|------------|------------------| | Landing Zone Design | **R/A** | C | C | C | I | @@ -186,8 +194,11 @@ graph TB | Cost Management | R | I | I | C | **A** | | Incident Response | C | I | C | **R/A** | I | +> [!NOTE] > **Legend**: R = Responsible, A = Accountable, C = Consulted, I = Informed +
+ [↑ Back to Top](#-business-architecture) --- diff --git a/docs/architecture/05-security-architecture.md b/docs/architecture/05-security-architecture.md index 1b8ce1b4..f1214dcd 100644 --- a/docs/architecture/05-security-architecture.md +++ b/docs/architecture/05-security-architecture.md @@ -132,7 +132,8 @@ graph TB ### Security Posture Summary -> πŸ›‘οΈ **Security Status Overview**: The accelerator implements strong security controls across identity, secrets, and monitoring. Network security is moderate with optional enhancements available. +> [!NOTE] +> **Security Status Overview**: The accelerator implements strong security controls across identity, secrets, and monitoring. Network security is moderate with optional enhancements available. | Area | Status | Key Controls | |:-----|:------:|:-------------| @@ -203,7 +204,8 @@ graph TB #### Threat: Catalog Tampering -> ⚠️ **Warning**: This threat depends on external source control security. Ensure proper branch protection rules are configured. +> [!WARNING] +> This threat depends on external source control security. Ensure proper branch protection rules are configured. - **STRIDE Category**: Tampering - **Attack Vector**: Attacker modifies Dev Box image definitions in catalog repository @@ -258,7 +260,8 @@ graph TB ### Risk Assessment Matrix -> ⚠️ **Note**: Catalog tampering risk depends on external source control security configuration. +> [!CAUTION] +> Catalog tampering risk depends on external source control security configuration. | Threat | Likelihood | Impact | Risk Score | Mitigation Status | |:-------|:----------:|:------:|:----------:|:-----------------:| @@ -1046,4 +1049,29 @@ gantt --- +## πŸ“Ž Related Documents + +
+TOGAF Architecture Series + +| Document | Description | +|:---------|:------------| +| [πŸ“Š Business Architecture](01-business-architecture.md) | Stakeholder analysis, capabilities, value streams | +| [πŸ—„οΈ Data Architecture](02-data-architecture.md) | Configuration schemas, secrets management, data flows | +| [πŸ›οΈ Application Architecture](03-application-architecture.md) | Bicep module design, dependencies, patterns | +| [βš™οΈ Technology Architecture](04-technology-architecture.md) | Azure services, CI/CD, deployment tools | +| πŸ” **Security Architecture** | *You are here* | + +
+ +--- + +
+ +**[← Previous: Technology Architecture](04-technology-architecture.md)** | **[Back to Index](README.md)** + +--- + *Document generated as part of TOGAF Architecture Documentation for DevExp-DevBox Landing Zone Accelerator* + +
diff --git a/docs/architecture/README.md b/docs/architecture/README.md new file mode 100644 index 00000000..4cb2490f --- /dev/null +++ b/docs/architecture/README.md @@ -0,0 +1,132 @@ +--- +title: "Architecture Documentation Index" +description: "Central index for the DevExp-DevBox Landing Zone Accelerator TOGAF Architecture Documentation series." +author: "DevExp Team" +date: "2026-01-22" +version: "1.0.0" +tags: + - TOGAF + - Architecture + - DevExp + - Index +--- + +# πŸ“š Architecture Documentation Index + +> [!NOTE] +> **Target Audience**: All Technical Stakeholders +> **Purpose**: Central navigation hub for TOGAF architecture documentation + +--- + +## 🎯 Overview + +This documentation series provides comprehensive **TOGAF Architecture Development Method (ADM)** documentation for the **DevExp-DevBox Landing Zone Accelerator**. The documentation follows the BDAT (Business, Data, Application, Technology) framework with an additional Security Architecture layer. + +--- + +## πŸ“‘ Document Series + +| # | Document | Description | Audience | +|:-:|:---------|:------------|:---------| +| 1 | [πŸ“Š Business Architecture](01-business-architecture.md) | Stakeholder analysis, business capabilities, value streams, success metrics | BDMs, PMs, Enterprise Architects | +| 2 | [πŸ—„οΈ Data Architecture](02-data-architecture.md) | Configuration schemas, secrets management, telemetry, data governance | Data Architects, Platform Engineers | +| 3 | [πŸ›οΈ Application Architecture](03-application-architecture.md) | Bicep module catalog, dependencies, deployment orchestration, design patterns | DevOps Engineers, Platform Engineers | +| 4 | [βš™οΈ Technology Architecture](04-technology-architecture.md) | Azure infrastructure, landing zones, networking, CI/CD, deployment tools | Cloud Architects, Infrastructure Teams | +| 5 | [πŸ” Security Architecture](05-security-architecture.md) | Threat model, identity management, RBAC, compliance, security controls | Security Architects, Compliance Teams | + +--- + +## πŸ—ΊοΈ Reading Path + +```mermaid +flowchart LR + A[πŸ“Š Business] --> B[πŸ—„οΈ Data] + B --> C[πŸ›οΈ Application] + C --> D[βš™οΈ Technology] + D --> E[πŸ” Security] + + style A fill:#E3F2FD + style B fill:#FFF3E0 + style C fill:#F3E5F5 + style D fill:#E8F5E9 + style E fill:#FFEBEE +``` + +> [!TIP] +> **Recommended Reading Order**: Follow the numbered sequence for a comprehensive understanding, or jump directly to specific domains based on your role. + +--- + +## 🏷️ Quick Reference + +
+By Role + +### For Business Decision Makers + +- Start with [πŸ“Š Business Architecture](01-business-architecture.md) +- Review success metrics and value propositions + +### For Platform Engineers + +- Focus on [πŸ›οΈ Application Architecture](03-application-architecture.md) and [βš™οΈ Technology Architecture](04-technology-architecture.md) +- Review module catalog and deployment patterns + +### For Security Teams + +- Start with [πŸ” Security Architecture](05-security-architecture.md) +- Review threat model and compliance controls + +### For Data Architects + +- Focus on [πŸ—„οΈ Data Architecture](02-data-architecture.md) +- Review configuration schemas and data flows + +
+ +
+By Topic + +| Topic | Primary Document | Related Sections | +|:------|:-----------------|:-----------------| +| **Azure DevCenter** | [Technology Architecture](04-technology-architecture.md) | Application Architecture | +| **Bicep Modules** | [Application Architecture](03-application-architecture.md) | Technology Architecture | +| **Key Vault & Secrets** | [Data Architecture](02-data-architecture.md) | Security Architecture | +| **RBAC & Identity** | [Security Architecture](05-security-architecture.md) | Technology Architecture | +| **CI/CD Pipelines** | [Technology Architecture](04-technology-architecture.md) | Application Architecture | +| **Compliance** | [Security Architecture](05-security-architecture.md) | Business Architecture | + +
+ +--- + +## πŸ“‹ Document Standards + +All documents in this series follow: + +- **TOGAF ADM** methodology +- **GitHub-Flavored Markdown** (GFM) formatting +- **Mermaid** diagrams for visualization +- **YAML frontmatter** for metadata +- **Consistent navigation** with Previous/Next links + +--- + +## πŸ”— External Resources + +| Resource | Description | +|:---------|:------------| +| [Microsoft Dev Box Documentation](https://learn.microsoft.com/en-us/azure/dev-box/) | Official Azure Dev Box documentation | +| [Azure Landing Zones](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/landing-zone/) | Cloud Adoption Framework landing zones | +| [TOGAF Standard](https://www.opengroup.org/togaf) | The Open Group Architecture Framework | +| [Azure Bicep](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/) | Infrastructure as Code language | + +--- + +
+ +**DevExp-DevBox Landing Zone Accelerator** +*TOGAF Architecture Documentation v1.0.0* + +
From 5ccbb72ee32c0a526267e1fc57e926815d1d2368 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 16:11:48 -0500 Subject: [PATCH 38/49] Refactor Security Architecture documentation to enhance clarity and navigation by adding an expandable section for Control Inventory. --- docs/architecture/05-security-architecture.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/architecture/05-security-architecture.md b/docs/architecture/05-security-architecture.md index f1214dcd..55ee80cd 100644 --- a/docs/architecture/05-security-architecture.md +++ b/docs/architecture/05-security-architecture.md @@ -740,6 +740,9 @@ tags: ### Control Inventory +
+πŸ“‹ Click to expand Control Inventory (10 controls) + | Control ID | Control Name | Category | Framework | Status | Implementation | |------------|--------------|----------|-----------|--------|----------------| | SC-001 | Azure AD Authentication | Identity | NIST AC-14 | βœ… Implemented | All services use Azure AD | @@ -753,6 +756,8 @@ tags: | SC-009 | Encryption at Rest | Data Protection | NIST SC-28 | βœ… Implemented | Platform encryption | | SC-010 | Encryption in Transit | Data Protection | NIST SC-8 | βœ… Implemented | TLS 1.2+ | +
+ ### Control: Azure AD Authentication - **Category**: Identity From 622662bd750826eca15a78fbc77b40825a54503a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 16:12:15 -0500 Subject: [PATCH 39/49] Add expandable section for Compliance Mapping in Security Architecture documentation --- docs/architecture/05-security-architecture.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/architecture/05-security-architecture.md b/docs/architecture/05-security-architecture.md index 55ee80cd..67653778 100644 --- a/docs/architecture/05-security-architecture.md +++ b/docs/architecture/05-security-architecture.md @@ -704,6 +704,9 @@ AzureDiagnostics ### Compliance Mapping +
+πŸ“‹ Click to expand Compliance Mapping (NIST 800-53 + CIS Azure) + | Framework | Control | Implementation | Evidence | |-----------|---------|----------------|----------| | **NIST 800-53** | AC-2 (Account Management) | Azure AD groups + RBAC | Role assignment audit | @@ -714,6 +717,8 @@ AzureDiagnostics | **CIS Azure** | 4.1.3 | Key Vault soft delete | enableSoftDelete: true | | **CIS Azure** | 4.1.4 | Key Vault purge protection | enablePurgeProtection: true | +
+ ### Tagging for Compliance ```yaml From efde186dc8c9aa01c3ce645d1dc2d8d6cfae0bbf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 16:12:46 -0500 Subject: [PATCH 40/49] Refactor Data Architecture documentation to enhance clarity and navigation by adding expandable sections for Security and DevCenter schemas. --- docs/architecture/02-data-architecture.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/architecture/02-data-architecture.md b/docs/architecture/02-data-architecture.md index 6e48e5fd..deba7f51 100644 --- a/docs/architecture/02-data-architecture.md +++ b/docs/architecture/02-data-architecture.md @@ -626,7 +626,8 @@ sequenceDiagram ### JSON Schema References -#### Security Schema (`security.schema.json`) +
+πŸ“œ Security Schema (security.schema.json) ```json { @@ -660,7 +661,10 @@ sequenceDiagram } ``` -#### DevCenter Schema (`devcenter.schema.json`) - Key Definitions +
+ +
+πŸ“œ DevCenter Schema (devcenter.schema.json) - Key Definitions ```json { @@ -698,6 +702,8 @@ sequenceDiagram } ``` +
+ ### Schema Validation Schemas are validated at authoring time using the `yaml-language-server` directive: From bbd647094e470ae9047bd29cefac3a1875c34724 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 16:13:42 -0500 Subject: [PATCH 41/49] Add expandable sections for Security, Workload, and Connectivity Modules in Application Architecture documentation to enhance clarity and navigation. --- .../03-application-architecture.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/architecture/03-application-architecture.md b/docs/architecture/03-application-architecture.md index a52bfa8e..be8753f7 100644 --- a/docs/architecture/03-application-architecture.md +++ b/docs/architecture/03-application-architecture.md @@ -212,6 +212,9 @@ graph TB ### Security Modules +
+πŸ” Click to expand Security Modules (3 modules: security.bicep, keyVault.bicep, secret.bicep) + #### Module: security.bicep - **Path**: `src/security/security.bicep` @@ -293,10 +296,15 @@ graph TB **Dependents**: catalog.bicep, projectCatalog.bicep +
+ --- ### Workload Modules +
+βš™οΈ Click to expand Workload Modules (8 modules: workload.bicep, devCenter.bicep, catalog.bicep, environmentType.bicep, project.bicep, projectCatalog.bicep, projectEnvironmentType.bicep, projectPool.bicep) + #### Module: workload.bicep - **Path**: `src/workload/workload.bicep` @@ -482,10 +490,15 @@ type Catalog = { **Dependents**: None +
+ --- ### Connectivity Modules +
+🌐 Click to expand Connectivity Modules (4 modules: connectivity.bicep, resourceGroup.bicep, vnet.bicep, networkConnection.bicep) + #### Module: connectivity.bicep - **Path**: `src/connectivity/connectivity.bicep` @@ -570,10 +583,15 @@ type Catalog = { **Dependents**: projectPool.bicep +
+ --- ### Identity Modules +
+πŸ”‘ Click to expand Identity Modules (5 modules: devCenterRoleAssignment.bicep, devCenterRoleAssignmentRG.bicep, keyVaultAccess.bicep, orgRoleAssignment.bicep, projectIdentityRoleAssignment.bicep) + #### Module: devCenterRoleAssignment.bicep - **Path**: `src/identity/devCenterRoleAssignment.bicep` From 402000083fa870cb9f06c394b7a5b9d6d22c19a7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 16:14:30 -0500 Subject: [PATCH 42/49] Add expandable sections for Azure Services Inventory in Technology Architecture documentation and close details tag in Application Architecture documentation for improved navigation. --- docs/architecture/03-application-architecture.md | 2 ++ docs/architecture/04-technology-architecture.md | 5 +++++ 2 files changed, 7 insertions(+) diff --git a/docs/architecture/03-application-architecture.md b/docs/architecture/03-application-architecture.md index be8753f7..bf06c74e 100644 --- a/docs/architecture/03-application-architecture.md +++ b/docs/architecture/03-application-architecture.md @@ -654,6 +654,8 @@ type Catalog = { | `roles` | array | Yes | Role definitions to assign | | `principalType` | string | No | Default: `Group` | +
+ --- ## Module Dependencies diff --git a/docs/architecture/04-technology-architecture.md b/docs/architecture/04-technology-architecture.md index 6e4a52a0..e213e564 100644 --- a/docs/architecture/04-technology-architecture.md +++ b/docs/architecture/04-technology-architecture.md @@ -107,6 +107,9 @@ graph TB ### Azure Services Deployed +
+πŸ“‹ Click to expand Azure Services Inventory (10 services) + | Service | Resource Type | Landing Zone | Purpose | |:--------|:--------------|:------------:|:--------| | **Azure DevCenter** | Microsoft.DevCenter/devcenters | Workload | Central management for Dev Box environments | @@ -120,6 +123,8 @@ graph TB | **Network Connections** | Microsoft.DevCenter/networkConnections | Connectivity | Dev Box network attachment | | **Role Assignments** | Microsoft.Authorization/roleAssignments | Cross-cutting | RBAC permissions | +
+ ### Resource Naming Convention ``` From 6a291cced15ecd3c91623608ed37b4379354ad9d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 16:19:03 -0500 Subject: [PATCH 43/49] Refactor TOGAF Architecture Reading Path diagram for improved clarity and navigation by enhancing node relationships and class definitions. --- docs/architecture/README.md | 30 +++++++++++++++++++++--------- 1 file changed, 21 insertions(+), 9 deletions(-) diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 4cb2490f..6ee33438 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -40,17 +40,29 @@ This documentation series provides comprehensive **TOGAF Architecture Developmen ## πŸ—ΊοΈ Reading Path ```mermaid +--- +title: TOGAF Architecture Reading Path +--- flowchart LR - A[πŸ“Š Business] --> B[πŸ—„οΈ Data] - B --> C[πŸ›οΈ Application] - C --> D[βš™οΈ Technology] - D --> E[πŸ” Security] + %% ===== DOCUMENT NODES ===== + A["πŸ“Š Business"] -->|defines context| B["πŸ—„οΈ Data"] + B -->|informs design| C["πŸ›οΈ Application"] + C -->|drives implementation| D["βš™οΈ Technology"] + D -->|requires| E["πŸ” Security"] + + %% ===== CLASS DEFINITIONS ===== + classDef business fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef data fill:#F59E0B,stroke:#D97706,color:#000000 + classDef application fill:#10B981,stroke:#059669,color:#FFFFFF + classDef technology fill:#10B981,stroke:#059669,color:#FFFFFF + classDef security fill:#6B7280,stroke:#4B5563,color:#FFFFFF - style A fill:#E3F2FD - style B fill:#FFF3E0 - style C fill:#F3E5F5 - style D fill:#E8F5E9 - style E fill:#FFEBEE + %% ===== CLASS ASSIGNMENTS ===== + class A business + class B data + class C application + class D technology + class E security ``` > [!TIP] From 9a7849b329523aed87633f0694f80324cdbd5f1b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 16:20:11 -0500 Subject: [PATCH 44/49] Enhance Business Architecture documentation with detailed mermaid diagrams for Target Audience, Stakeholder Map, Business Capability Model, Developer Onboarding Value Stream, and Environment Provisioning Lifecycle to improve clarity and navigation. --- docs/architecture/01-business-architecture.md | 280 +++++++++++------- 1 file changed, 177 insertions(+), 103 deletions(-) diff --git a/docs/architecture/01-business-architecture.md b/docs/architecture/01-business-architecture.md index 27bc8586..e8bc46b9 100644 --- a/docs/architecture/01-business-architecture.md +++ b/docs/architecture/01-business-architecture.md @@ -84,6 +84,9 @@ Modern enterprises face significant challenges in managing developer environment ### Target Audience ```mermaid +--- +title: DevExp-DevBox Target Audience +--- mindmap root((DevExp-DevBox
Accelerator)) Enterprise Organizations @@ -124,42 +127,61 @@ mindmap ### Stakeholder Map ```mermaid +--- +title: Stakeholder Relationship Map +--- graph TB - subgraph "Executive Stakeholders" - CTO[CTO/CIO] - CISO[CISO] - CFO[CFO] + %% ===== EXECUTIVE STAKEHOLDERS ===== + subgraph executives["Executive Stakeholders"] + CTO["CTO/CIO"] + CISO["CISO"] + CFO["CFO"] end - subgraph "Technical Stakeholders" - PE[Platform Engineers] - DE[Development Teams] - SEC[Security Team] - OPS[Operations Team] + %% ===== TECHNICAL STAKEHOLDERS ===== + subgraph technical["Technical Stakeholders"] + PE["Platform Engineers"] + DE["Development Teams"] + SEC["Security Team"] + OPS["Operations Team"] end - subgraph "Business Stakeholders" - PM[Project Managers] - BU[Business Units] + %% ===== BUSINESS STAKEHOLDERS ===== + subgraph business["Business Stakeholders"] + PM["Project Managers"] + BU["Business Units"] end - CTO -->|Strategic Direction| PE - CISO -->|Security Requirements| SEC - CFO -->|Budget Approval| PE + %% ===== RELATIONSHIPS ===== + CTO -->|strategic direction| PE + CISO -->|security requirements| SEC + CFO -->|budget approval| PE + + PE -->|platform services| DE + SEC -->|security controls| PE + OPS -->|operational support| PE + + PM -->|project requirements| DE + BU -->|business needs| PM - PE -->|Platform Services| DE - SEC -->|Security Controls| PE - OPS -->|Operational Support| PE + DE -->|feedback| PE - PM -->|Project Requirements| DE - BU -->|Business Needs| PM + %% ===== CLASS DEFINITIONS ===== + 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 - DE -->|Feedback| PE + %% ===== CLASS ASSIGNMENTS ===== + class PE,DE primary + class SEC,OPS secondary + class CTO,CISO,CFO external + class PM,BU datastore - style PE fill:#4CAF50,color:#fff - style DE fill:#2196F3,color:#fff - style SEC fill:#FF9800,color:#fff - style OPS fill:#9C27B0,color:#fff + %% ===== SUBGRAPH STYLES ===== + style executives fill:#F3F4F6,stroke:#6B7280,stroke-width:2px + style technical fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style business fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px ``` ### Stakeholder Registry @@ -208,70 +230,96 @@ graph TB ### Business Capability Model ```mermaid +--- +title: Business Capability Model +--- graph TB - subgraph "Level 0: Developer Experience Platform" - L0[DevExp-DevBox
Landing Zone Accelerator] + %% ===== LEVEL 0: ROOT ===== + subgraph level0["Level 0: Developer Experience Platform"] + L0["DevExp-DevBox
Landing Zone Accelerator"] end - subgraph "Level 1: Core Capability Domains" - SEC[Security
Management] - MON[Monitoring &
Observability] - CON[Connectivity
Management] - WRK[Workload
Management] + %% ===== LEVEL 1: CORE DOMAINS ===== + subgraph level1["Level 1: Core Capability Domains"] + SEC["Security
Management"] + MON["Monitoring &
Observability"] + CON["Connectivity
Management"] + WRK["Workload
Management"] end - subgraph "Level 2: Security Capabilities" - SEC1[Secrets Management] - SEC2[Identity & Access] - SEC3[Compliance Controls] + %% ===== LEVEL 2: SECURITY ===== + subgraph level2sec["Level 2: Security Capabilities"] + SEC1["Secrets Management"] + SEC2["Identity & Access"] + SEC3["Compliance Controls"] end - subgraph "Level 2: Monitoring Capabilities" - MON1[Log Analytics] - MON2[Diagnostics] - MON3[Alerting] + %% ===== LEVEL 2: MONITORING ===== + subgraph level2mon["Level 2: Monitoring Capabilities"] + MON1["Log Analytics"] + MON2["Diagnostics"] + MON3["Alerting"] end - subgraph "Level 2: Connectivity Capabilities" - CON1[Network Provisioning] - CON2[Network Isolation] - CON3[Hybrid Connectivity] + %% ===== LEVEL 2: CONNECTIVITY ===== + subgraph level2con["Level 2: Connectivity Capabilities"] + CON1["Network Provisioning"] + CON2["Network Isolation"] + CON3["Hybrid Connectivity"] end - subgraph "Level 2: Workload Capabilities" - WRK1[DevCenter Management] - WRK2[Project Management] - WRK3[Pool Management] - WRK4[Catalog Management] + %% ===== LEVEL 2: WORKLOAD ===== + subgraph level2wrk["Level 2: Workload Capabilities"] + WRK1["DevCenter Management"] + WRK2["Project Management"] + WRK3["Pool Management"] + WRK4["Catalog Management"] end - L0 --> SEC - L0 --> MON - L0 --> CON - L0 --> WRK - - SEC --> SEC1 - SEC --> SEC2 - SEC --> SEC3 - - MON --> MON1 - MON --> MON2 - MON --> MON3 - - CON --> CON1 - CON --> CON2 - CON --> CON3 - - WRK --> WRK1 - WRK --> WRK2 - WRK --> WRK3 - WRK --> WRK4 - - style L0 fill:#1976D2,color:#fff - style SEC fill:#D32F2F,color:#fff - style MON fill:#388E3C,color:#fff - style CON fill:#7B1FA2,color:#fff - style WRK fill:#F57C00,color:#fff + %% ===== RELATIONSHIPS ===== + L0 -->|manages| SEC + L0 -->|monitors| MON + L0 -->|connects| CON + L0 -->|orchestrates| WRK + + SEC -->|includes| SEC1 + SEC -->|includes| SEC2 + SEC -->|includes| SEC3 + + MON -->|includes| MON1 + MON -->|includes| MON2 + MON -->|includes| MON3 + + CON -->|includes| CON1 + CON -->|includes| CON2 + CON -->|includes| CON3 + + WRK -->|includes| WRK1 + WRK -->|includes| WRK2 + WRK -->|includes| WRK3 + WRK -->|includes| WRK4 + + %% ===== CLASS DEFINITIONS ===== + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef security fill:#F44336,stroke:#C62828,color:#FFFFFF + classDef monitoring fill:#10B981,stroke:#059669,color:#FFFFFF + classDef connectivity fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + classDef workload fill:#F59E0B,stroke:#D97706,color:#000000 + + %% ===== CLASS ASSIGNMENTS ===== + class L0 primary + class SEC,SEC1,SEC2,SEC3 security + class MON,MON1,MON2,MON3 monitoring + class CON,CON1,CON2,CON3 connectivity + class WRK,WRK1,WRK2,WRK3,WRK4 workload + + %% ===== SUBGRAPH STYLES ===== + style level0 fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style level1 fill:#F3F4F6,stroke:#6B7280,stroke-width:2px + style level2sec fill:#FEE2E2,stroke:#F44336,stroke-width:2px + style level2mon fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style level2con fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style level2wrk fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px ``` ### Capability to Landing Zone Mapping @@ -299,42 +347,65 @@ graph TB ### Developer Onboarding Value Stream ```mermaid +--- +title: Developer Onboarding Value Stream +--- graph LR - subgraph "Stage 1: Request" - A1[Developer
Joins Team] - A2[Access
Request] + %% ===== STAGE 1: REQUEST ===== + subgraph stage1["Stage 1: Request"] + A1["Developer
Joins Team"] + A2["Access
Request"] end - subgraph "Stage 2: Provisioning" - B1[Azure AD
Group Assignment] - B2[Project
Access Granted] - B3[Dev Box
Provisioned] + %% ===== STAGE 2: PROVISIONING ===== + subgraph stage2["Stage 2: Provisioning"] + B1["Azure AD
Group Assignment"] + B2["Project
Access Granted"] + B3["Dev Box
Provisioned"] end - subgraph "Stage 3: Configuration" - C1[Image
Downloaded] - C2[Tools
Installed] - C3[Secrets
Configured] + %% ===== STAGE 3: CONFIGURATION ===== + subgraph stage3["Stage 3: Configuration"] + C1["Image
Downloaded"] + C2["Tools
Installed"] + C3["Secrets
Configured"] end - subgraph "Stage 4: Productive" - D1[Developer
Coding] - D2[Feedback
Loop] + %% ===== STAGE 4: PRODUCTIVE ===== + subgraph stage4["Stage 4: Productive"] + D1["Developer
Coding"] + D2["Feedback
Loop"] end - A1 --> A2 - A2 --> B1 - B1 --> B2 - B2 --> B3 - B3 --> C1 - C1 --> C2 - C2 --> C3 - C3 --> D1 - D1 --> D2 - D2 -.->|Improvements| B3 - - style A1 fill:#E3F2FD - style D1 fill:#E8F5E9 + %% ===== FLOW CONNECTIONS ===== + A1 -->|initiates| A2 + A2 -->|triggers| B1 + B1 -->|enables| B2 + B2 -->|creates| B3 + B3 -->|starts| C1 + C1 -->|installs| C2 + C2 -->|configures| C3 + C3 -->|enables| D1 + D1 -->|generates| D2 + D2 -.->|improvements| B3 + + %% ===== CLASS DEFINITIONS ===== + 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 input fill:#F3F4F6,stroke:#6B7280,color:#000000 + + %% ===== CLASS ASSIGNMENTS ===== + class A1,A2 input + class B1,B2,B3 primary + class C1,C2,C3 secondary + class D1,D2 trigger + + %% ===== SUBGRAPH STYLES ===== + style stage1 fill:#F3F4F6,stroke:#6B7280,stroke-width:2px + style stage2 fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style stage3 fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style stage4 fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px ``` ### Value Stream Metrics @@ -350,6 +421,9 @@ graph LR ### Environment Provisioning Lifecycle ```mermaid +--- +title: Environment Provisioning Lifecycle +--- stateDiagram-v2 [*] --> Requested: Developer Request Requested --> Approved: Manager Approval From f73a39558194be59e2923f3cd8b7c8818a9e2a11 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 16:21:20 -0500 Subject: [PATCH 45/49] Refactor KPI and Data Categories diagrams in Business and Data Architecture documentation for improved clarity and navigation by enhancing node relationships, class definitions, and styles. --- docs/architecture/01-business-architecture.md | 57 +++++++++++----- docs/architecture/02-data-architecture.md | 68 +++++++++++-------- 2 files changed, 81 insertions(+), 44 deletions(-) diff --git a/docs/architecture/01-business-architecture.md b/docs/architecture/01-business-architecture.md index e8bc46b9..614b4e26 100644 --- a/docs/architecture/01-business-architecture.md +++ b/docs/architecture/01-business-architecture.md @@ -483,30 +483,55 @@ stateDiagram-v2 ### Key Performance Indicators (KPIs) ```mermaid +--- +title: Success Metrics KPI Dashboard +--- graph TB - subgraph "Developer Productivity KPIs" - KPI1[Time to
First Commit] - KPI2[Environment
Setup Time] - KPI3[Developer
Satisfaction Score] + %% ===== DEVELOPER PRODUCTIVITY KPIs ===== + subgraph devkpis["Developer Productivity KPIs"] + KPI1["Time to
First Commit"] + KPI2["Environment
Setup Time"] + KPI3["Developer
Satisfaction Score"] end - subgraph "Operational KPIs" - KPI4[Deployment
Success Rate] - KPI5[Mean Time
to Recovery] - KPI6[Infrastructure
Drift Score] + %% ===== OPERATIONAL KPIs ===== + subgraph opskpis["Operational KPIs"] + KPI4["Deployment
Success Rate"] + KPI5["Mean Time
to Recovery"] + KPI6["Infrastructure
Drift Score"] end - subgraph "Security KPIs" - KPI7[Compliance
Score] - KPI8[Security
Incidents] - KPI9[Access Review
Completion] + %% ===== SECURITY KPIs ===== + subgraph seckpis["Security KPIs"] + KPI7["Compliance
Score"] + KPI8["Security
Incidents"] + KPI9["Access Review
Completion"] end - subgraph "Cost KPIs" - KPI10[Cost per
Developer] - KPI11[Resource
Utilization] - KPI12[Budget
Variance] + %% ===== COST KPIs ===== + subgraph costkpis["Cost KPIs"] + KPI10["Cost per
Developer"] + KPI11["Resource
Utilization"] + KPI12["Budget
Variance"] end + + %% ===== CLASS DEFINITIONS ===== + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef security fill:#F44336,stroke:#C62828,color:#FFFFFF + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + + %% ===== CLASS ASSIGNMENTS ===== + class KPI1,KPI2,KPI3 primary + class KPI4,KPI5,KPI6 secondary + class KPI7,KPI8,KPI9 security + class KPI10,KPI11,KPI12 datastore + + %% ===== SUBGRAPH STYLES ===== + style devkpis fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style opskpis fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style seckpis fill:#FEE2E2,stroke:#F44336,stroke-width:2px + style costkpis fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px ``` ### Success Metrics Dashboard diff --git a/docs/architecture/02-data-architecture.md b/docs/architecture/02-data-architecture.md index deba7f51..c5e46989 100644 --- a/docs/architecture/02-data-architecture.md +++ b/docs/architecture/02-data-architecture.md @@ -55,43 +55,55 @@ The DevExp-DevBox Landing Zone Accelerator manages several categories of data th ### Data Categories ```mermaid +--- +title: Data Categories Overview +--- graph TB - subgraph "Configuration Data" - CD1[Resource Organization
azureResources.yaml] - CD2[Security Settings
security.yaml] - CD3[Workload Config
devcenter.yaml] + %% ===== CONFIGURATION DATA ===== + subgraph configData["Configuration Data"] + CD1["Resource Organization
azureResources.yaml"] + CD2["Security Settings
security.yaml"] + CD3["Workload Config
devcenter.yaml"] end - subgraph "Secrets & Credentials" - SC1[GitHub PAT
Key Vault Secret] - SC2[Azure AD Tokens
Managed Identity] - SC3[Service Principal
OIDC Federation] + %% ===== SECRETS & CREDENTIALS ===== + subgraph secretsData["Secrets & Credentials"] + SC1["GitHub PAT
Key Vault Secret"] + SC2["Azure AD Tokens
Managed Identity"] + SC3["Service Principal
OIDC Federation"] end - subgraph "Telemetry Data" - TD1[Resource Logs
Log Analytics] - TD2[Metrics
Azure Monitor] - TD3[Diagnostic Data
Azure Diagnostics] + %% ===== TELEMETRY DATA ===== + subgraph telemetryData["Telemetry Data"] + TD1["Resource Logs
Log Analytics"] + TD2["Metrics
Azure Monitor"] + TD3["Diagnostic Data
Azure Diagnostics"] end - subgraph "State Data" - ST1[Deployment State
azd Environment] - ST2[Resource State
Azure RM] - ST3[RBAC Assignments
Azure AD] + %% ===== STATE DATA ===== + subgraph stateData["State Data"] + ST1["Deployment State
azd Environment"] + ST2["Resource State
Azure RM"] + ST3["RBAC Assignments
Azure AD"] end - style CD1 fill:#E3F2FD - style CD2 fill:#E3F2FD - style CD3 fill:#E3F2FD - style SC1 fill:#FFEBEE - style SC2 fill:#FFEBEE - style SC3 fill:#FFEBEE - style TD1 fill:#E8F5E9 - style TD2 fill:#E8F5E9 - style TD3 fill:#E8F5E9 - style ST1 fill:#FFF3E0 - style ST2 fill:#FFF3E0 - style ST3 fill:#FFF3E0 + %% ===== CLASS DEFINITIONS ===== + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef security fill:#F44336,stroke:#C62828,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + + %% ===== CLASS ASSIGNMENTS ===== + class CD1,CD2,CD3 primary + class SC1,SC2,SC3 security + class TD1,TD2,TD3 secondary + class ST1,ST2,ST3 datastore + + %% ===== SUBGRAPH STYLES ===== + style configData fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style secretsData fill:#FEE2E2,stroke:#F44336,stroke-width:2px + style telemetryData fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style stateData fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px ``` ### Data Classification From c0a4b4839b62036ca98a8c75ad45122396b5c5f1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 16:21:45 -0500 Subject: [PATCH 46/49] Add Data Entity Relationship and Key Vault Security Architecture diagrams to enhance clarity and navigation in Data Architecture documentation. --- docs/architecture/02-data-architecture.md | 52 +++++++++++++++++------ 1 file changed, 39 insertions(+), 13 deletions(-) diff --git a/docs/architecture/02-data-architecture.md b/docs/architecture/02-data-architecture.md index c5e46989..32ff746c 100644 --- a/docs/architecture/02-data-architecture.md +++ b/docs/architecture/02-data-architecture.md @@ -147,6 +147,9 @@ infra/settings/ ### Data Entity Relationship Diagram ```mermaid +--- +title: Data Entity Relationship Model +--- erDiagram LANDING_ZONES ||--o{ RESOURCE_GROUPS : contains RESOURCE_GROUPS ||--o{ RESOURCES : hosts @@ -348,38 +351,61 @@ projects: ### Key Vault Architecture ```mermaid +--- +title: Key Vault Security Architecture +--- graph TB - subgraph "Azure Key Vault" - KV[contoso-*****-kv] - SEC1[gha-token
GitHub PAT] + %% ===== KEY VAULT ===== + subgraph kvault["Azure Key Vault"] + KV["contoso-*****-kv"] + SEC1["gha-token
GitHub PAT"] end - subgraph "Access Patterns" - DC[DevCenter
Managed Identity] - PROJ[Project
Managed Identity] - CICD[CI/CD Pipeline
OIDC] + %% ===== ACCESS PATTERNS ===== + subgraph access["Access Patterns"] + DC["DevCenter
Managed Identity"] + PROJ["Project
Managed Identity"] + CICD["CI/CD Pipeline
OIDC"] end - subgraph "Consumers" - CAT1[DevCenter
Catalogs] - CAT2[Project
Catalogs] + %% ===== CONSUMERS ===== + subgraph consumers["Consumers"] + CAT1["DevCenter
Catalogs"] + CAT2["Project
Catalogs"] end + %% ===== RELATIONSHIPS ===== DC -->|Key Vault Secrets User| KV PROJ -->|Key Vault Secrets User| KV CICD -->|Key Vault Secrets Officer| KV - KV --> SEC1 + KV -->|stores| SEC1 SEC1 -->|secretIdentifier| CAT1 SEC1 -->|secretIdentifier| CAT2 - style KV fill:#0078D4,color:#fff - style SEC1 fill:#D32F2F,color:#fff + %% ===== CLASS DEFINITIONS ===== + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef security fill:#F44336,stroke:#C62828,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + + %% ===== CLASS ASSIGNMENTS ===== + class KV primary + class SEC1 security + class DC,PROJ,CICD secondary + class CAT1,CAT2 primary + + %% ===== SUBGRAPH STYLES ===== + style kvault fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style access fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style consumers fill:#F3F4F6,stroke:#6B7280,stroke-width:2px ``` ### Secret Lifecycle ```mermaid +--- +title: Secret Lifecycle Flow +--- sequenceDiagram participant Admin as Administrator participant GH as GitHub From 6efd099c52d5833c05cb13d4d6418178d32247ad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 16:22:05 -0500 Subject: [PATCH 47/49] Refactor Log Analytics Data Collection diagram for improved clarity and navigation by enhancing node relationships, class definitions, and styles. --- docs/architecture/02-data-architecture.md | 58 ++++++++++++++++------- 1 file changed, 40 insertions(+), 18 deletions(-) diff --git a/docs/architecture/02-data-architecture.md b/docs/architecture/02-data-architecture.md index 32ff746c..8c743485 100644 --- a/docs/architecture/02-data-architecture.md +++ b/docs/architecture/02-data-architecture.md @@ -447,25 +447,32 @@ sequenceDiagram ### Log Analytics Data Collection ```mermaid +--- +title: Log Analytics Data Collection Flow +--- graph LR - subgraph "Data Sources" - DC[DevCenter] - KV[Key Vault] - VNET[Virtual Network] - LA[Log Analytics
Workspace] + %% ===== DATA SOURCES ===== + subgraph dataSources["Data Sources"] + DC["DevCenter"] + KV["Key Vault"] + VNET["Virtual Network"] + LA["Log Analytics
Workspace"] end - subgraph "Log Categories" - LOGS[All Logs
categoryGroup: allLogs] - MET[All Metrics
category: AllMetrics] + %% ===== LOG CATEGORIES ===== + subgraph logCategories["Log Categories"] + LOGS["All Logs
categoryGroup: allLogs"] + MET["All Metrics
category: AllMetrics"] end - subgraph "Analytics" - QRY[KQL Queries] - WBK[Workbooks] - ALR[Alerts] + %% ===== ANALYTICS ===== + subgraph analytics["Analytics"] + QRY["KQL Queries"] + WBK["Workbooks"] + ALR["Alerts"] end + %% ===== RELATIONSHIPS ===== DC -->|Diagnostic Settings| LOGS KV -->|Diagnostic Settings| LOGS VNET -->|Diagnostic Settings| LOGS @@ -474,14 +481,29 @@ graph LR KV -->|Diagnostic Settings| MET VNET -->|Diagnostic Settings| MET - LOGS --> LA - MET --> LA + LOGS -->|ingests| LA + MET -->|ingests| LA - LA --> QRY - LA --> WBK - LA --> ALR + LA -->|enables| QRY + LA -->|enables| WBK + LA -->|enables| ALR - style LA fill:#68217A,color:#fff + %% ===== CLASS DEFINITIONS ===== + 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 + + %% ===== CLASS ASSIGNMENTS ===== + class LA primary + class DC,KV,VNET secondary + class LOGS,MET datastore + class QRY,WBK,ALR external + + %% ===== SUBGRAPH STYLES ===== + style dataSources fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style logCategories fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style analytics fill:#F3F4F6,stroke:#6B7280,stroke-width:2px ``` ### Diagnostic Settings Configuration From 1d87ea0660e906e0cc34cdf5f6b8efd0d16872ca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 16:22:35 -0500 Subject: [PATCH 48/49] Refactor Configuration Loading Flow diagram for improved clarity and navigation by enhancing node relationships, class definitions, and styles. --- docs/architecture/02-data-architecture.md | 61 +++++++++++++++-------- 1 file changed, 41 insertions(+), 20 deletions(-) diff --git a/docs/architecture/02-data-architecture.md b/docs/architecture/02-data-architecture.md index 8c743485..8cf13689 100644 --- a/docs/architecture/02-data-architecture.md +++ b/docs/architecture/02-data-architecture.md @@ -542,33 +542,40 @@ AzureDiagnostics ### Configuration Loading Flow ```mermaid +--- +title: Configuration Loading Flow +--- flowchart TB - subgraph "Source Control" - YAML1[azureResources.yaml] - YAML2[security.yaml] - YAML3[devcenter.yaml] + %% ===== SOURCE CONTROL ===== + subgraph sourceControl["Source Control"] + YAML1["azureResources.yaml"] + YAML2["security.yaml"] + YAML3["devcenter.yaml"] end - subgraph "Bicep Compilation" - MAIN[main.bicep] - LOAD1[loadYamlContent
resourceOrganization] - LOAD2[loadYamlContent
security] - LOAD3[loadYamlContent
workload] + %% ===== BICEP COMPILATION ===== + subgraph bicepCompile["Bicep Compilation"] + MAIN["main.bicep"] + LOAD1["loadYamlContent
resourceOrganization"] + LOAD2["loadYamlContent
security"] + LOAD3["loadYamlContent
workload"] end - subgraph "Azure Resources" - RG1[Security RG] - RG2[Monitoring RG] - RG3[Workload RG] + %% ===== AZURE RESOURCES ===== + subgraph azureResources["Azure Resources"] + RG1["Security RG"] + RG2["Monitoring RG"] + RG3["Workload RG"] end - YAML1 --> LOAD1 - YAML2 --> LOAD2 - YAML3 --> LOAD3 + %% ===== RELATIONSHIPS ===== + YAML1 -->|loads| LOAD1 + YAML2 -->|loads| LOAD2 + YAML3 -->|loads| LOAD3 - MAIN --> LOAD1 - MAIN --> LOAD2 - MAIN --> LOAD3 + MAIN -->|invokes| LOAD1 + MAIN -->|invokes| LOAD2 + MAIN -->|invokes| LOAD3 LOAD1 -->|createResourceGroupName| RG1 LOAD1 -->|createResourceGroupName| RG2 @@ -577,7 +584,21 @@ flowchart TB LOAD2 -->|keyVault config| RG1 LOAD3 -->|devCenter config| RG3 - style MAIN fill:#FF6B35,color:#fff + %% ===== CLASS DEFINITIONS ===== + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + + %% ===== CLASS ASSIGNMENTS ===== + class MAIN primary + class YAML1,YAML2,YAML3 datastore + class LOAD1,LOAD2,LOAD3 secondary + class RG1,RG2,RG3 primary + + %% ===== SUBGRAPH STYLES ===== + style sourceControl fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style bicepCompile fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style azureResources fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px ``` ### Secrets Flow Diagram From a61cc50e2ff652fa0bd1b2913b37433591b1b74a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Thu, 22 Jan 2026 16:23:00 -0500 Subject: [PATCH 49/49] Remove outdated architecture documentation files for Security and Index from the DevExp-DevBox Landing Zone Accelerator repository. --- docs/architecture/01-business-architecture.md | 626 --------- docs/architecture/02-data-architecture.md | 860 ------------ .../03-application-architecture.md | 1210 ----------------- .../04-technology-architecture.md | 854 ------------ docs/architecture/05-security-architecture.md | 1087 --------------- docs/architecture/README.md | 144 -- 6 files changed, 4781 deletions(-) delete mode 100644 docs/architecture/01-business-architecture.md delete mode 100644 docs/architecture/02-data-architecture.md delete mode 100644 docs/architecture/03-application-architecture.md delete mode 100644 docs/architecture/04-technology-architecture.md delete mode 100644 docs/architecture/05-security-architecture.md delete mode 100644 docs/architecture/README.md diff --git a/docs/architecture/01-business-architecture.md b/docs/architecture/01-business-architecture.md deleted file mode 100644 index 614b4e26..00000000 --- a/docs/architecture/01-business-architecture.md +++ /dev/null @@ -1,626 +0,0 @@ ---- -title: "Business Architecture" -description: "TOGAF Business Architecture documentation for the DevExp-DevBox Landing Zone Accelerator, covering stakeholder analysis, business capabilities, value streams, and success metrics." -author: "DevExp Team" -date: "2026-01-22" -version: "1.0.0" -tags: - - TOGAF - - Business Architecture - - DevExp - - Dev Box - - Azure ---- - -# πŸ“Š Business Architecture - -> [!NOTE] -> **Target Audience**: Business Decision Makers, Enterprise Architects, Project Managers -> **Reading Time**: ~15 minutes - -
-πŸ“ Document Navigation - -| Previous | Index | Next | -|:---------|:-----:|-----:| -| β€” | [Architecture Index](README.md) | [Data Architecture β†’](02-data-architecture.md) | - -
- -> **TOGAF Layer**: Business Architecture -> **Version**: 1.0.0 -> **Last Updated**: January 22, 2026 -> **Author**: DevExp Team - ---- - -## πŸ“‘ Table of Contents - -- [πŸ“‹ Executive Summary](#-executive-summary) -- [🎯 Business Context](#-business-context) -- [πŸ‘₯ Stakeholder Analysis](#-stakeholder-analysis) -- [πŸ—οΈ Business Capabilities](#️-business-capabilities) -- [πŸ”„ Value Streams](#-value-streams) -- [πŸ“ Business Requirements](#-business-requirements) -- [πŸ“ˆ Success Metrics](#-success-metrics) -- [πŸ“š References](#-references) -- [πŸ“– Glossary](#-glossary) - ---- - -## πŸ“‹ Executive Summary - -The **DevExp-DevBox Landing Zone Accelerator** is an enterprise-grade infrastructure-as-code solution that streamlines the deployment and management of Microsoft Dev Box environments on Azure. This accelerator enables organizations to rapidly provision secure, compliant, and scalable developer workstations while maintaining governance controls and operational excellence. - -> [!TIP] -> **Key Benefit**: Reduce developer onboarding time from days to minutes with pre-configured, secure environments. - -### Key Business Value Propositions - -| Value Area | Description | -|:-----------|:------------| -| **Accelerated Developer Onboarding** | Reduce new developer setup time from days to minutes through pre-configured Dev Box environments | -| **Standardized Development Environments** | Ensure consistency across teams with role-specific configurations (backend, frontend engineers) | -| **Security & Compliance** | Built-in security controls with Key Vault integration, RBAC, and Azure AD authentication | -| **Cost Optimization** | Right-sized VM SKUs per role and centralized resource management | -| **Operational Efficiency** | Automated provisioning via Azure Developer CLI (azd) with CI/CD integration | - -[↑ Back to Top](#-business-architecture) - ---- - -## 🎯 Business Context - -### Problem Statement - -Modern enterprises face significant challenges in managing developer environments: - -1. **Environment Inconsistency**: Developers spend excessive time configuring local machines, leading to "works on my machine" issues -2. **Security Risks**: Unmanaged developer workstations create security vulnerabilities -3. **Slow Onboarding**: New developer setup can take days or weeks -4. **Compliance Gaps**: Difficulty enforcing organizational policies on distributed workstations -5. **Cost Visibility**: Lack of centralized tracking for developer infrastructure costs - -### Target Audience - -```mermaid ---- -title: DevExp-DevBox Target Audience ---- -mindmap - root((DevExp-DevBox
Accelerator)) - Enterprise Organizations - Large development teams - Multiple project portfolios - Strict compliance requirements - Platform Engineering Teams - Infrastructure automation - Developer experience focus - Self-service enablement - Regulated Industries - Financial services - Healthcare - Government - Cloud-First Companies - Azure-native tooling - DevOps maturity - Remote workforce -``` - -### Business Drivers - -| Driver | Description | Priority | -|:-------|:------------|:--------:| -| **Developer Productivity** | Eliminate environment setup overhead | High | -| **Security Posture** | Centralized security controls and monitoring | High | -| **Operational Excellence** | Automated, repeatable deployments | High | -| **Cost Management** | Predictable infrastructure costs | Medium | -| **Talent Retention** | Modern developer experience | Medium | -| **Compliance** | Meet regulatory requirements | High | - -[↑ Back to Top](#-business-architecture) - ---- - -## πŸ‘₯ Stakeholder Analysis - -### Stakeholder Map - -```mermaid ---- -title: Stakeholder Relationship Map ---- -graph TB - %% ===== EXECUTIVE STAKEHOLDERS ===== - subgraph executives["Executive Stakeholders"] - CTO["CTO/CIO"] - CISO["CISO"] - CFO["CFO"] - end - - %% ===== TECHNICAL STAKEHOLDERS ===== - subgraph technical["Technical Stakeholders"] - PE["Platform Engineers"] - DE["Development Teams"] - SEC["Security Team"] - OPS["Operations Team"] - end - - %% ===== BUSINESS STAKEHOLDERS ===== - subgraph business["Business Stakeholders"] - PM["Project Managers"] - BU["Business Units"] - end - - %% ===== RELATIONSHIPS ===== - CTO -->|strategic direction| PE - CISO -->|security requirements| SEC - CFO -->|budget approval| PE - - PE -->|platform services| DE - SEC -->|security controls| PE - OPS -->|operational support| PE - - PM -->|project requirements| DE - BU -->|business needs| PM - - DE -->|feedback| PE - - %% ===== CLASS DEFINITIONS ===== - 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 - - %% ===== CLASS ASSIGNMENTS ===== - class PE,DE primary - class SEC,OPS secondary - class CTO,CISO,CFO external - class PM,BU datastore - - %% ===== SUBGRAPH STYLES ===== - style executives fill:#F3F4F6,stroke:#6B7280,stroke-width:2px - style technical fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px - style business fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px -``` - -### Stakeholder Registry - -
-Click to expand Stakeholder Registry table - -| Stakeholder | Role | Concerns | Interests | Engagement Level | -|-------------|------|----------|-----------|------------------| -| **Platform Engineers** | Build & maintain landing zones | Automation, scalability, maintainability | Infrastructure as Code, self-service capabilities | High - Primary implementers | -| **Development Teams** | Consume Dev Box environments | Fast onboarding, reliable environments, tool availability | Productivity, modern tooling, minimal friction | High - Primary users | -| **Security Team** | Ensure security compliance | Access control, secrets management, audit trails | Zero-trust architecture, compliance reporting | High - Governance | -| **Operations Team** | Monitor & support infrastructure | Observability, incident response, cost management | Centralized monitoring, automated remediation | Medium - Ongoing support | -| **Project Managers** | Coordinate project delivery | Resource allocation, timeline management | Predictable provisioning, clear ownership | Medium - Coordination | -| **CTO/CIO** | Strategic technology direction | ROI, innovation, competitive advantage | Developer productivity metrics, cost optimization | Low - Strategic oversight | -| **CISO** | Security governance | Risk mitigation, compliance adherence | Security posture, audit readiness | Medium - Policy approval | -| **CFO** | Financial oversight | Cost control, budget planning | Infrastructure cost visibility, optimization | Low - Budget approval | - -
- -### RACI Matrix - -
-Click to expand RACI Matrix - -| Activity | Platform Engineers | Dev Teams | Security | Operations | Project Managers | -|----------|-------------------|-----------|----------|------------|------------------| -| Landing Zone Design | **R/A** | C | C | C | I | -| Dev Box Provisioning | R | **A** | I | C | I | -| Security Configuration | C | I | **R/A** | C | I | -| Monitoring Setup | R | I | C | **A** | I | -| Cost Management | R | I | I | C | **A** | -| Incident Response | C | I | C | **R/A** | I | - -> [!NOTE] -> **Legend**: R = Responsible, A = Accountable, C = Consulted, I = Informed - -
- -[↑ Back to Top](#-business-architecture) - ---- - -## πŸ—οΈ Business Capabilities - -### Business Capability Model - -```mermaid ---- -title: Business Capability Model ---- -graph TB - %% ===== LEVEL 0: ROOT ===== - subgraph level0["Level 0: Developer Experience Platform"] - L0["DevExp-DevBox
Landing Zone Accelerator"] - end - - %% ===== LEVEL 1: CORE DOMAINS ===== - subgraph level1["Level 1: Core Capability Domains"] - SEC["Security
Management"] - MON["Monitoring &
Observability"] - CON["Connectivity
Management"] - WRK["Workload
Management"] - end - - %% ===== LEVEL 2: SECURITY ===== - subgraph level2sec["Level 2: Security Capabilities"] - SEC1["Secrets Management"] - SEC2["Identity & Access"] - SEC3["Compliance Controls"] - end - - %% ===== LEVEL 2: MONITORING ===== - subgraph level2mon["Level 2: Monitoring Capabilities"] - MON1["Log Analytics"] - MON2["Diagnostics"] - MON3["Alerting"] - end - - %% ===== LEVEL 2: CONNECTIVITY ===== - subgraph level2con["Level 2: Connectivity Capabilities"] - CON1["Network Provisioning"] - CON2["Network Isolation"] - CON3["Hybrid Connectivity"] - end - - %% ===== LEVEL 2: WORKLOAD ===== - subgraph level2wrk["Level 2: Workload Capabilities"] - WRK1["DevCenter Management"] - WRK2["Project Management"] - WRK3["Pool Management"] - WRK4["Catalog Management"] - end - - %% ===== RELATIONSHIPS ===== - L0 -->|manages| SEC - L0 -->|monitors| MON - L0 -->|connects| CON - L0 -->|orchestrates| WRK - - SEC -->|includes| SEC1 - SEC -->|includes| SEC2 - SEC -->|includes| SEC3 - - MON -->|includes| MON1 - MON -->|includes| MON2 - MON -->|includes| MON3 - - CON -->|includes| CON1 - CON -->|includes| CON2 - CON -->|includes| CON3 - - WRK -->|includes| WRK1 - WRK -->|includes| WRK2 - WRK -->|includes| WRK3 - WRK -->|includes| WRK4 - - %% ===== CLASS DEFINITIONS ===== - classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF - classDef security fill:#F44336,stroke:#C62828,color:#FFFFFF - classDef monitoring fill:#10B981,stroke:#059669,color:#FFFFFF - classDef connectivity fill:#818CF8,stroke:#4F46E5,color:#FFFFFF - classDef workload fill:#F59E0B,stroke:#D97706,color:#000000 - - %% ===== CLASS ASSIGNMENTS ===== - class L0 primary - class SEC,SEC1,SEC2,SEC3 security - class MON,MON1,MON2,MON3 monitoring - class CON,CON1,CON2,CON3 connectivity - class WRK,WRK1,WRK2,WRK3,WRK4 workload - - %% ===== SUBGRAPH STYLES ===== - style level0 fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px - style level1 fill:#F3F4F6,stroke:#6B7280,stroke-width:2px - style level2sec fill:#FEE2E2,stroke:#F44336,stroke-width:2px - style level2mon fill:#ECFDF5,stroke:#10B981,stroke-width:2px - style level2con fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px - style level2wrk fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px -``` - -### Capability to Landing Zone Mapping - -| Business Capability | Landing Zone | Key Resources | Business Value | -|---------------------|--------------|---------------|----------------| -| **Secrets Management** | Security | Azure Key Vault | Secure credential storage for PAT tokens and service credentials | -| **Identity & Access** | Security | Azure RBAC, Managed Identities | Fine-grained access control with least privilege | -| **Compliance Controls** | Security | Purge Protection, Soft Delete | Data protection and audit compliance | -| **Log Analytics** | Monitoring | Log Analytics Workspace | Centralized logging for troubleshooting and compliance | -| **Diagnostics** | Monitoring | Diagnostic Settings | Resource health and performance monitoring | -| **Network Provisioning** | Connectivity | Virtual Networks, Subnets | Secure network infrastructure for Dev Box | -| **Network Isolation** | Connectivity | NSGs, Network Connections | Workload segmentation and security boundaries | -| **DevCenter Management** | Workload | Azure DevCenter | Central management for developer environments | -| **Project Management** | Workload | DevCenter Projects | Team-level environment organization | -| **Pool Management** | Workload | Dev Box Pools | Role-specific workstation configurations | -| **Catalog Management** | Workload | Git Catalogs | Configuration-as-code for Dev Box definitions | - -[↑ Back to Top](#-business-architecture) - ---- - -## πŸ”„ Value Streams - -### Developer Onboarding Value Stream - -```mermaid ---- -title: Developer Onboarding Value Stream ---- -graph LR - %% ===== STAGE 1: REQUEST ===== - subgraph stage1["Stage 1: Request"] - A1["Developer
Joins Team"] - A2["Access
Request"] - end - - %% ===== STAGE 2: PROVISIONING ===== - subgraph stage2["Stage 2: Provisioning"] - B1["Azure AD
Group Assignment"] - B2["Project
Access Granted"] - B3["Dev Box
Provisioned"] - end - - %% ===== STAGE 3: CONFIGURATION ===== - subgraph stage3["Stage 3: Configuration"] - C1["Image
Downloaded"] - C2["Tools
Installed"] - C3["Secrets
Configured"] - end - - %% ===== STAGE 4: PRODUCTIVE ===== - subgraph stage4["Stage 4: Productive"] - D1["Developer
Coding"] - D2["Feedback
Loop"] - end - - %% ===== FLOW CONNECTIONS ===== - A1 -->|initiates| A2 - A2 -->|triggers| B1 - B1 -->|enables| B2 - B2 -->|creates| B3 - B3 -->|starts| C1 - C1 -->|installs| C2 - C2 -->|configures| C3 - C3 -->|enables| D1 - D1 -->|generates| D2 - D2 -.->|improvements| B3 - - %% ===== CLASS DEFINITIONS ===== - 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 input fill:#F3F4F6,stroke:#6B7280,color:#000000 - - %% ===== CLASS ASSIGNMENTS ===== - class A1,A2 input - class B1,B2,B3 primary - class C1,C2,C3 secondary - class D1,D2 trigger - - %% ===== SUBGRAPH STYLES ===== - style stage1 fill:#F3F4F6,stroke:#6B7280,stroke-width:2px - style stage2 fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px - style stage3 fill:#ECFDF5,stroke:#10B981,stroke-width:2px - style stage4 fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px -``` - -### Value Stream Metrics - -| Stage | Traditional Approach | With DevExp-DevBox | Improvement | -|-------|---------------------|-------------------|-------------| -| **Request to Access** | 1-3 days | < 1 hour | 95% faster | -| **Environment Provisioning** | 4-8 hours | 15-30 minutes | 90% faster | -| **Tool Configuration** | 2-4 hours | Automated | 100% automated | -| **Time to First Commit** | 2-5 days | Same day | 80% faster | -| **Environment Consistency** | Variable | 100% consistent | Standardized | - -### Environment Provisioning Lifecycle - -```mermaid ---- -title: Environment Provisioning Lifecycle ---- -stateDiagram-v2 - [*] --> Requested: Developer Request - Requested --> Approved: Manager Approval - Approved --> Provisioning: Azure RBAC - Provisioning --> Configuring: Dev Box Created - Configuring --> Ready: Tools Installed - Ready --> InUse: Developer Connected - InUse --> Updating: Scheduled Maintenance - Updating --> InUse: Updates Applied - InUse --> Deprovisioning: Project Complete - Deprovisioning --> [*]: Resources Cleaned - - InUse --> Suspended: Cost Optimization - Suspended --> InUse: Developer Resume -``` - -[↑ Back to Top](#-business-architecture) - ---- - -## πŸ“ Business Requirements - -### Functional Requirements - -| ID | Requirement | Priority | Landing Zone | -|:---|:------------|:--------:|:-------------| -| **FR-001** | Deploy Azure DevCenter with project organization | Must Have | Workload | -| **FR-002** | Provision Dev Box pools with role-specific configurations | Must Have | Workload | -| **FR-003** | Integrate Git catalogs for image definitions | Must Have | Workload | -| **FR-004** | Store secrets securely in Azure Key Vault | Must Have | Security | -| **FR-005** | Assign RBAC roles based on Azure AD groups | Must Have | Security | -| **FR-006** | Deploy virtual networks for Dev Box connectivity | Should Have | Connectivity | -| **FR-007** | Enable centralized logging via Log Analytics | Must Have | Monitoring | -| **FR-008** | Support multiple environment types (dev, staging, UAT) | Should Have | Workload | -| **FR-009** | Enable catalog synchronization from GitHub/Azure DevOps | Must Have | Workload | -| **FR-010** | Support managed and unmanaged network configurations | Should Have | Connectivity | - -### Non-Functional Requirements - -| ID | Requirement | Category | Target | Measurement | -|:---|:------------|:---------|:-------|:------------| -| **NFR-001** | Infrastructure deployment time | Performance | < 30 minutes | azd provision duration | -| **NFR-002** | Dev Box startup time | Performance | < 15 minutes | DevCenter metrics | -| **NFR-003** | System availability | Reliability | 99.9% | Azure Monitor | -| **NFR-004** | Secret access latency | Performance | < 100ms | Key Vault diagnostics | -| **NFR-005** | Audit log retention | Compliance | 90 days minimum | Log Analytics | -| **NFR-006** | RBAC propagation time | Performance | < 5 minutes | Manual testing | -| **NFR-007** | Disaster recovery | Reliability | RPO < 24 hours | Bicep redeployment | -| **NFR-008** | Cost visibility | Manageability | Per-project breakdown | Azure Cost Management | - -[↑ Back to Top](#-business-architecture) - ---- - -## πŸ“ˆ Success Metrics - -### Key Performance Indicators (KPIs) - -```mermaid ---- -title: Success Metrics KPI Dashboard ---- -graph TB - %% ===== DEVELOPER PRODUCTIVITY KPIs ===== - subgraph devkpis["Developer Productivity KPIs"] - KPI1["Time to
First Commit"] - KPI2["Environment
Setup Time"] - KPI3["Developer
Satisfaction Score"] - end - - %% ===== OPERATIONAL KPIs ===== - subgraph opskpis["Operational KPIs"] - KPI4["Deployment
Success Rate"] - KPI5["Mean Time
to Recovery"] - KPI6["Infrastructure
Drift Score"] - end - - %% ===== SECURITY KPIs ===== - subgraph seckpis["Security KPIs"] - KPI7["Compliance
Score"] - KPI8["Security
Incidents"] - KPI9["Access Review
Completion"] - end - - %% ===== COST KPIs ===== - subgraph costkpis["Cost KPIs"] - KPI10["Cost per
Developer"] - KPI11["Resource
Utilization"] - KPI12["Budget
Variance"] - end - - %% ===== CLASS DEFINITIONS ===== - classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF - classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF - classDef security fill:#F44336,stroke:#C62828,color:#FFFFFF - classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 - - %% ===== CLASS ASSIGNMENTS ===== - class KPI1,KPI2,KPI3 primary - class KPI4,KPI5,KPI6 secondary - class KPI7,KPI8,KPI9 security - class KPI10,KPI11,KPI12 datastore - - %% ===== SUBGRAPH STYLES ===== - style devkpis fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px - style opskpis fill:#ECFDF5,stroke:#10B981,stroke-width:2px - style seckpis fill:#FEE2E2,stroke:#F44336,stroke-width:2px - style costkpis fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px -``` - -### Success Metrics Dashboard - -| Metric | Baseline | Target | Current | Status | -|--------|----------|--------|---------|--------| -| **Developer Onboarding Time** | 5 days | < 1 day | - | 🎯 Target | -| **Environment Consistency** | 60% | 100% | - | 🎯 Target | -| **Deployment Success Rate** | - | > 95% | - | 🎯 Target | -| **Security Compliance Score** | - | 100% | - | 🎯 Target | -| **Cost per Developer/Month** | Variable | Predictable | - | 🎯 Target | -| **Mean Time to Recovery** | - | < 1 hour | - | 🎯 Target | -| **Developer Satisfaction (NPS)** | - | > 50 | - | 🎯 Target | - -### Business Value Realization - -| Value Area | Metric | Expected Outcome | -|------------|--------|------------------| -| **Productivity** | Developer hours saved per onboarding | 16-32 hours | -| **Quality** | Environment-related incidents reduced | 70% reduction | -| **Security** | Security findings in developer environments | Zero critical findings | -| **Cost** | Infrastructure cost predictability | Β±10% budget variance | -| **Speed** | Time to market for new projects | 2 weeks faster | - -[↑ Back to Top](#-business-architecture) - ---- - -## πŸ“š References - -### Internal Documents - -- [Data Architecture](02-data-architecture.md) - Configuration schemas and data flows -- [Application Architecture](03-application-architecture.md) - Module design and dependencies -- [Technology Architecture](04-technology-architecture.md) - Azure services and infrastructure -- [Security Architecture](05-security-architecture.md) - Security controls and compliance - -### External References - -- [Microsoft Dev Box Documentation](https://learn.microsoft.com/en-us/azure/dev-box/overview-what-is-microsoft-dev-box) -- [Azure Landing Zones](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/landing-zone/) -- [Azure DevCenter Documentation](https://learn.microsoft.com/en-us/azure/dev-box/concept-dev-box-concepts) -- [TOGAF Architecture Framework](https://www.opengroup.org/togaf) - -[↑ Back to Top](#-business-architecture) - ---- - -## πŸ“– Glossary - -| Term | Definition | -|------|------------| -| **Dev Box** | A cloud-based developer workstation provided by Microsoft Azure | -| **DevCenter** | Azure service for managing developer environments at scale | -| **Landing Zone** | A pre-configured Azure environment with governance, security, and networking | -| **Accelerator** | Pre-built infrastructure-as-code templates for rapid deployment | -| **Catalog** | Git repository containing Dev Box image definitions or environment templates | -| **Pool** | Collection of Dev Boxes with shared configuration (VM size, image, network) | -| **RBAC** | Role-Based Access Control - Azure's authorization system | -| **Managed Identity** | Azure AD identity automatically managed for Azure resources | -| **azd** | Azure Developer CLI - Command-line tool for Azure development workflows | - -[↑ Back to Top](#-business-architecture) - ---- - -## πŸ“Ž Related Documents - -
-TOGAF Architecture Series - -| Document | Description | -|:---------|:------------| -| πŸ“Š **Business Architecture** | *You are here* | -| [πŸ—„οΈ Data Architecture](02-data-architecture.md) | Configuration schemas, secrets management, data flows | -| [πŸ›οΈ Application Architecture](03-application-architecture.md) | Bicep module design, dependencies, patterns | -| [βš™οΈ Technology Architecture](04-technology-architecture.md) | Azure services, CI/CD, deployment tools | -| [πŸ” Security Architecture](05-security-architecture.md) | Threat model, RBAC, compliance controls | - -
- ---- - -
- -**[← Previous: Index](README.md)** | **[Next: Data Architecture β†’](02-data-architecture.md)** - ---- - -*Document generated as part of TOGAF Architecture Documentation for DevExp-DevBox Landing Zone Accelerator* - -
diff --git a/docs/architecture/02-data-architecture.md b/docs/architecture/02-data-architecture.md deleted file mode 100644 index 8cf13689..00000000 --- a/docs/architecture/02-data-architecture.md +++ /dev/null @@ -1,860 +0,0 @@ ---- -title: "Data Architecture" -description: "TOGAF Data Architecture documentation for the DevExp-DevBox Landing Zone Accelerator, covering configuration data models, secrets management, telemetry, and data governance." -author: "DevExp Team" -date: "2026-01-22" -version: "1.0.0" -tags: - - TOGAF - - Data Architecture - - DevExp - - Key Vault - - Azure ---- - -# πŸ—„οΈ Data Architecture - -> [!NOTE] -> **Target Audience**: Data Architects, Platform Engineers, Security Teams -> **Reading Time**: ~20 minutes - -
-πŸ“ Document Navigation - -| Previous | Index | Next | -|:---------|:-----:|-----:| -| [← Business Architecture](01-business-architecture.md) | [Architecture Index](README.md) | [Application Architecture β†’](03-application-architecture.md) | - -
- -> **TOGAF Layer**: Data Architecture -> **Version**: 1.0.0 -> **Last Updated**: January 22, 2026 -> **Author**: DevExp Team - ---- - -## πŸ“‘ Table of Contents - -- [πŸ“Š Data Overview](#-data-overview) -- [βš™οΈ Configuration Data Model](#️-configuration-data-model) -- [πŸ” Secrets Management](#-secrets-management) -- [πŸ“‘ Telemetry & Diagnostics](#-telemetry--diagnostics) -- [πŸ”€ Data Flow Diagrams](#-data-flow-diagrams) -- [πŸ›οΈ Data Governance](#️-data-governance) -- [πŸ“‹ Schema Documentation](#-schema-documentation) -- [πŸ“š References](#-references) -- [πŸ“– Glossary](#-glossary) - ---- - -## πŸ“Š Data Overview - -The DevExp-DevBox Landing Zone Accelerator manages several categories of data that flow through the system during deployment and runtime operations. Understanding these data types is essential for security, compliance, and operational management. - -### Data Categories - -```mermaid ---- -title: Data Categories Overview ---- -graph TB - %% ===== CONFIGURATION DATA ===== - subgraph configData["Configuration Data"] - CD1["Resource Organization
azureResources.yaml"] - CD2["Security Settings
security.yaml"] - CD3["Workload Config
devcenter.yaml"] - end - - %% ===== SECRETS & CREDENTIALS ===== - subgraph secretsData["Secrets & Credentials"] - SC1["GitHub PAT
Key Vault Secret"] - SC2["Azure AD Tokens
Managed Identity"] - SC3["Service Principal
OIDC Federation"] - end - - %% ===== TELEMETRY DATA ===== - subgraph telemetryData["Telemetry Data"] - TD1["Resource Logs
Log Analytics"] - TD2["Metrics
Azure Monitor"] - TD3["Diagnostic Data
Azure Diagnostics"] - end - - %% ===== STATE DATA ===== - subgraph stateData["State Data"] - ST1["Deployment State
azd Environment"] - ST2["Resource State
Azure RM"] - ST3["RBAC Assignments
Azure AD"] - end - - %% ===== CLASS DEFINITIONS ===== - classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF - classDef security fill:#F44336,stroke:#C62828,color:#FFFFFF - classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF - classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 - - %% ===== CLASS ASSIGNMENTS ===== - class CD1,CD2,CD3 primary - class SC1,SC2,SC3 security - class TD1,TD2,TD3 secondary - class ST1,ST2,ST3 datastore - - %% ===== SUBGRAPH STYLES ===== - style configData fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px - style secretsData fill:#FEE2E2,stroke:#F44336,stroke-width:2px - style telemetryData fill:#ECFDF5,stroke:#10B981,stroke-width:2px - style stateData fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px -``` - -### Data Classification - -| Data Type | Classification | Sensitivity | Storage Location | Retention | -|:----------|:--------------:|:-----------:|:-----------------|:----------| -| Resource Organization Config | Internal | Low | Git Repository | Version controlled | -| Security Configuration | Confidential | Medium | Git Repository | Version controlled | -| DevCenter Configuration | Internal | Low | Git Repository | Version controlled | -| GitHub PAT Token | Secret | Critical | Azure Key Vault | 7-90 days (soft delete) | -| Managed Identity Tokens | Secret | Critical | Azure AD | Session-based | -| Deployment Logs | Internal | Medium | Log Analytics | 30-90 days | -| Resource Metrics | Internal | Low | Azure Monitor | 93 days | -| Deployment State | Internal | Medium | azd Environment | Until deleted | - -[↑ Back to Top](#️-data-architecture) - ---- - -## βš™οΈ Configuration Data Model - -### Overview - -The accelerator uses YAML-based configuration files with JSON Schema validation to define infrastructure settings. Configuration is loaded at deployment time using Bicep's `loadYamlContent()` function. - -### Configuration File Structure - -``` -infra/settings/ -β”œβ”€β”€ resourceOrganization/ -β”‚ β”œβ”€β”€ azureResources.yaml # Landing zone resource groups -β”‚ └── azureResources.schema.json -β”œβ”€β”€ security/ -β”‚ β”œβ”€β”€ security.yaml # Key Vault configuration -β”‚ └── security.schema.json -└── workload/ - β”œβ”€β”€ devcenter.yaml # DevCenter & projects - └── devcenter.schema.json -``` - -### Data Entity Relationship Diagram - -```mermaid ---- -title: Data Entity Relationship Model ---- -erDiagram - LANDING_ZONES ||--o{ RESOURCE_GROUPS : contains - RESOURCE_GROUPS ||--o{ RESOURCES : hosts - - DEVCENTER ||--o{ PROJECTS : manages - DEVCENTER ||--o{ CATALOGS : syncs - DEVCENTER ||--o{ ENVIRONMENT_TYPES : defines - DEVCENTER ||--|| IDENTITY : has - - PROJECTS ||--o{ POOLS : contains - PROJECTS ||--o{ PROJECT_CATALOGS : syncs - PROJECTS ||--o{ PROJECT_ENV_TYPES : enables - PROJECTS ||--|| NETWORK : uses - PROJECTS ||--|| PROJECT_IDENTITY : has - - IDENTITY ||--o{ ROLE_ASSIGNMENTS : grants - PROJECT_IDENTITY ||--o{ ROLE_ASSIGNMENTS : grants - - KEY_VAULT ||--o{ SECRETS : stores - SECRETS ||--|| CATALOGS : authenticates - SECRETS ||--|| PROJECT_CATALOGS : authenticates - - NETWORK ||--o{ SUBNETS : contains - NETWORK ||--|| NETWORK_CONNECTION : creates - NETWORK_CONNECTION ||--|| DEVCENTER : attaches - - LANDING_ZONES { - string security_name - string monitoring_name - string workload_name - object tags - } - - DEVCENTER { - string name - string catalogItemSyncEnableStatus - string microsoftHostedNetworkEnableStatus - string installAzureMonitorAgentEnableStatus - } - - PROJECTS { - string name - string description - object network - object identity - array pools - array catalogs - array environmentTypes - } - - KEY_VAULT { - string name - boolean enablePurgeProtection - boolean enableSoftDelete - int softDeleteRetentionInDays - boolean enableRbacAuthorization - } - - POOLS { - string name - string imageDefinitionName - string vmSku - } -``` - -### Resource Organization Configuration - -**File**: `infra/settings/resourceOrganization/azureResources.yaml` - -| Property | Type | Description | Example | -|----------|------|-------------|---------| -| `workload.name` | string | Workload resource group name | `devexp-workload` | -| `workload.create` | boolean | Create new or use existing | `true` | -| `workload.tags` | object | Azure resource tags | See tags schema | -| `security.name` | string | Security resource group name | `devexp-security` | -| `security.create` | boolean | Create new or use existing | `true` | -| `monitoring.name` | string | Monitoring resource group name | `devexp-monitoring` | -| `monitoring.create` | boolean | Create new or use existing | `true` | - -**Tags Schema**: - -```yaml -tags: - environment: dev|test|staging|prod - division: string # Business division - team: string # Team name - project: string # Project identifier - costCenter: string # Cost allocation - owner: string # Resource owner - landingZone: string # Landing zone type - resources: string # Resource type -``` - -### Security Configuration - -**File**: `infra/settings/security/security.yaml` - -| Property | Type | Description | Constraints | -|:---------|:-----|:------------|:------------| -| `create` | boolean | Create Key Vault | Required | -| `keyVault.name` | string | Key Vault name prefix | 3-24 chars, alphanumeric | -| `keyVault.description` | string | Purpose description | Optional | -| `keyVault.secretName` | string | Secret name for PAT | Default: `gha-token` | -| `keyVault.enablePurgeProtection` | boolean | Prevent permanent deletion | Recommended: `true` | -| `keyVault.enableSoftDelete` | boolean | Enable recovery period | Recommended: `true` | -| `keyVault.softDeleteRetentionInDays` | integer | Soft delete retention | 7-90 days | -| `keyVault.enableRbacAuthorization` | boolean | Use Azure RBAC | Recommended: `true` | - -### DevCenter Configuration - -**File**: `infra/settings/workload/devcenter.yaml` - -#### Core DevCenter Properties - -| Property | Type | Description | -|----------|------|-------------| -| `name` | string | DevCenter resource name | -| `catalogItemSyncEnableStatus` | Enabled\|Disabled | Catalog sync feature | -| `microsoftHostedNetworkEnableStatus` | Enabled\|Disabled | Microsoft-hosted networking | -| `installAzureMonitorAgentEnableStatus` | Enabled\|Disabled | Azure Monitor agent | -| `identity.type` | SystemAssigned\|UserAssigned | Managed identity type | - -#### Identity & Role Assignments - -```yaml -identity: - type: "SystemAssigned" - roleAssignments: - devCenter: - - id: "b24988ac-6180-42a0-ab88-20f7382dd24c" # Contributor - name: "Contributor" - scope: "Subscription" - - id: "18d7d88d-d35e-4fb5-a5c3-7773c20a72d9" # User Access Admin - name: "User Access Administrator" - scope: "Subscription" - - id: "4633458b-17de-408a-b874-0445c86b69e6" # Key Vault Secrets User - name: "Key Vault Secrets User" - scope: "ResourceGroup" - orgRoleTypes: - - type: DevManager - azureADGroupId: "" - azureADGroupName: "Platform Engineering Team" - azureRBACRoles: - - name: "DevCenter Project Admin" - id: "331c37c6-af14-46d9-b9f4-e1909e1b95a0" - scope: ResourceGroup -``` - -#### Project Configuration - -```yaml -projects: - - name: "eShop" - description: "eShop project" - network: - name: eShop - create: true - resourceGroupName: "eShop-connectivity-RG" - virtualNetworkType: Managed|Unmanaged - addressPrefixes: ["10.0.0.0/16"] - subnets: - - name: eShop-subnet - properties: - addressPrefix: "10.0.1.0/24" - pools: - - name: "backend-engineer" - imageDefinitionName: "eShop-backend-engineer" - vmSku: "general_i_32c128gb512ssd_v2" - - name: "frontend-engineer" - imageDefinitionName: "eShop-frontend-engineer" - vmSku: "general_i_16c64gb256ssd_v2" - catalogs: - - name: "environments" - type: environmentDefinition - sourceControl: gitHub - visibility: private - uri: "https://github.com/org/repo.git" - branch: "main" - path: "/.devcenter/environments" -``` - -[↑ Back to Top](#️-data-architecture) - ---- - -## πŸ” Secrets Management - -> [!IMPORTANT] -> All secrets are stored in Azure Key Vault with RBAC authorization. Never commit secrets to source control. - -### Secret Types - -| Secret | Purpose | Storage | Rotation | -|--------|---------|---------|----------| -| **GitHub PAT** | Catalog authentication for private repos | Key Vault | Manual (recommended: 90 days) | -| **Azure DevOps PAT** | ADO catalog authentication | Key Vault | Manual (recommended: 90 days) | -| **Service Principal** | CI/CD deployment | GitHub Secrets / Azure DevOps | OIDC (no rotation needed) | - -### Key Vault Architecture - -```mermaid ---- -title: Key Vault Security Architecture ---- -graph TB - %% ===== KEY VAULT ===== - subgraph kvault["Azure Key Vault"] - KV["contoso-*****-kv"] - SEC1["gha-token
GitHub PAT"] - end - - %% ===== ACCESS PATTERNS ===== - subgraph access["Access Patterns"] - DC["DevCenter
Managed Identity"] - PROJ["Project
Managed Identity"] - CICD["CI/CD Pipeline
OIDC"] - end - - %% ===== CONSUMERS ===== - subgraph consumers["Consumers"] - CAT1["DevCenter
Catalogs"] - CAT2["Project
Catalogs"] - end - - %% ===== RELATIONSHIPS ===== - DC -->|Key Vault Secrets User| KV - PROJ -->|Key Vault Secrets User| KV - CICD -->|Key Vault Secrets Officer| KV - - KV -->|stores| SEC1 - SEC1 -->|secretIdentifier| CAT1 - SEC1 -->|secretIdentifier| CAT2 - - %% ===== CLASS DEFINITIONS ===== - classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF - classDef security fill:#F44336,stroke:#C62828,color:#FFFFFF - classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF - - %% ===== CLASS ASSIGNMENTS ===== - class KV primary - class SEC1 security - class DC,PROJ,CICD secondary - class CAT1,CAT2 primary - - %% ===== SUBGRAPH STYLES ===== - style kvault fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px - style access fill:#ECFDF5,stroke:#10B981,stroke-width:2px - style consumers fill:#F3F4F6,stroke:#6B7280,stroke-width:2px -``` - -### Secret Lifecycle - -```mermaid ---- -title: Secret Lifecycle Flow ---- -sequenceDiagram - participant Admin as Administrator - participant GH as GitHub - participant CICD as CI/CD Pipeline - participant KV as Key Vault - participant DC as DevCenter - participant Cat as Catalog - - Admin->>GH: Create PAT with repo scope - Admin->>CICD: Store PAT as pipeline secret - CICD->>KV: azd provision (store secret) - KV-->>CICD: Secret URI returned - CICD->>DC: Deploy with secretIdentifier - DC->>Cat: Configure catalog - - loop Catalog Sync - Cat->>KV: Request secret (Managed Identity) - KV-->>Cat: Return PAT - Cat->>GH: Authenticate & sync - GH-->>Cat: Repository content - end -``` - -### Secret Access Patterns - -| Principal | Role | Scope | Purpose | -|-----------|------|-------|---------| -| DevCenter Managed Identity | Key Vault Secrets User | Security RG | Read PAT for catalog sync | -| Project Managed Identity | Key Vault Secrets User | Security RG | Read PAT for project catalogs | -| DevCenter Managed Identity | Key Vault Secrets Officer | Security RG | Manage secrets if needed | -| CI/CD Service Principal | Deployer (custom) | Key Vault | Initial secret provisioning | - -[↑ Back to Top](#️-data-architecture) - ---- - -## πŸ“‘ Telemetry & Diagnostics - -### Log Analytics Data Collection - -```mermaid ---- -title: Log Analytics Data Collection Flow ---- -graph LR - %% ===== DATA SOURCES ===== - subgraph dataSources["Data Sources"] - DC["DevCenter"] - KV["Key Vault"] - VNET["Virtual Network"] - LA["Log Analytics
Workspace"] - end - - %% ===== LOG CATEGORIES ===== - subgraph logCategories["Log Categories"] - LOGS["All Logs
categoryGroup: allLogs"] - MET["All Metrics
category: AllMetrics"] - end - - %% ===== ANALYTICS ===== - subgraph analytics["Analytics"] - QRY["KQL Queries"] - WBK["Workbooks"] - ALR["Alerts"] - end - - %% ===== RELATIONSHIPS ===== - DC -->|Diagnostic Settings| LOGS - KV -->|Diagnostic Settings| LOGS - VNET -->|Diagnostic Settings| LOGS - - DC -->|Diagnostic Settings| MET - KV -->|Diagnostic Settings| MET - VNET -->|Diagnostic Settings| MET - - LOGS -->|ingests| LA - MET -->|ingests| LA - - LA -->|enables| QRY - LA -->|enables| WBK - LA -->|enables| ALR - - %% ===== CLASS DEFINITIONS ===== - 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 - - %% ===== CLASS ASSIGNMENTS ===== - class LA primary - class DC,KV,VNET secondary - class LOGS,MET datastore - class QRY,WBK,ALR external - - %% ===== SUBGRAPH STYLES ===== - style dataSources fill:#ECFDF5,stroke:#10B981,stroke-width:2px - style logCategories fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px - style analytics fill:#F3F4F6,stroke:#6B7280,stroke-width:2px -``` - -### Diagnostic Settings Configuration - -| Resource | Log Categories | Metrics | Destination | -|----------|---------------|---------|-------------| -| Log Analytics Workspace | allLogs | AllMetrics | Self (workspace) | -| Key Vault | allLogs | AllMetrics | Log Analytics | -| DevCenter | allLogs | AllMetrics | Log Analytics | -| Virtual Network | allLogs | AllMetrics | Log Analytics | - -### Telemetry Data Schema - -**DevCenter Logs**: - -``` -AzureDiagnostics -| where ResourceProvider == "MICROSOFT.DEVCENTER" -| project TimeGenerated, OperationName, ResultType, CallerIpAddress -``` - -**Key Vault Logs**: - -``` -AzureDiagnostics -| where ResourceProvider == "MICROSOFT.KEYVAULT" -| project TimeGenerated, OperationName, ResultType, identity_claim_upn_s -``` - -[↑ Back to Top](#️-data-architecture) - ---- - -## πŸ”€ Data Flow Diagrams - -### Configuration Loading Flow - -```mermaid ---- -title: Configuration Loading Flow ---- -flowchart TB - %% ===== SOURCE CONTROL ===== - subgraph sourceControl["Source Control"] - YAML1["azureResources.yaml"] - YAML2["security.yaml"] - YAML3["devcenter.yaml"] - end - - %% ===== BICEP COMPILATION ===== - subgraph bicepCompile["Bicep Compilation"] - MAIN["main.bicep"] - LOAD1["loadYamlContent
resourceOrganization"] - LOAD2["loadYamlContent
security"] - LOAD3["loadYamlContent
workload"] - end - - %% ===== AZURE RESOURCES ===== - subgraph azureResources["Azure Resources"] - RG1["Security RG"] - RG2["Monitoring RG"] - RG3["Workload RG"] - end - - %% ===== RELATIONSHIPS ===== - YAML1 -->|loads| LOAD1 - YAML2 -->|loads| LOAD2 - YAML3 -->|loads| LOAD3 - - MAIN -->|invokes| LOAD1 - MAIN -->|invokes| LOAD2 - MAIN -->|invokes| LOAD3 - - LOAD1 -->|createResourceGroupName| RG1 - LOAD1 -->|createResourceGroupName| RG2 - LOAD1 -->|createResourceGroupName| RG3 - - LOAD2 -->|keyVault config| RG1 - LOAD3 -->|devCenter config| RG3 - - %% ===== CLASS DEFINITIONS ===== - classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF - classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF - classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 - - %% ===== CLASS ASSIGNMENTS ===== - class MAIN primary - class YAML1,YAML2,YAML3 datastore - class LOAD1,LOAD2,LOAD3 secondary - class RG1,RG2,RG3 primary - - %% ===== SUBGRAPH STYLES ===== - style sourceControl fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px - style bicepCompile fill:#ECFDF5,stroke:#10B981,stroke-width:2px - style azureResources fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px -``` - -### Secrets Flow Diagram - -```mermaid -flowchart TB - subgraph "Secret Injection" - ENV[Environment Variable
KEY_VAULT_SECRET] - AZD[azd provision] - PARAM[@secure param
secretValue] - end - - subgraph "Secret Storage" - SEC[security.bicep] - SECMOD[secret.bicep] - KV[(Key Vault
gha-token)] - end - - subgraph "Secret Consumption" - URI[secretIdentifier
URI] - CAT[catalog.bicep] - PCAT[projectCatalog.bicep] - end - - ENV --> AZD - AZD --> PARAM - PARAM --> SEC - SEC --> SECMOD - SECMOD --> KV - - KV -->|properties.secretUri| URI - URI --> CAT - URI --> PCAT - - style KV fill:#D32F2F,color:#fff - style ENV fill:#FFC107,color:#000 -``` - -### Deployment Data Flow - -```mermaid -sequenceDiagram - participant Git as Git Repository - participant AZD as Azure Developer CLI - participant ARM as Azure Resource Manager - participant RG as Resource Groups - participant Res as Azure Resources - participant LA as Log Analytics - - Git->>AZD: Clone & load YAML configs - AZD->>AZD: Compile Bicep templates - AZD->>ARM: Submit deployment - ARM->>RG: Create resource groups - - par Parallel Deployment - ARM->>Res: Deploy Log Analytics - ARM->>Res: Deploy Key Vault - ARM->>Res: Deploy DevCenter - end - - Res->>LA: Configure diagnostics - Res-->>AZD: Return outputs - AZD-->>Git: Store in azd environment -``` - ---- - -## Data Governance - -### Data Classification Matrix - -| Data Element | Classification | Owner | Access Control | Encryption | -|--------------|---------------|-------|----------------|------------| -| YAML Configuration | Internal | Platform Team | Git branch protection | At rest (Git LFS optional) | -| JSON Schemas | Public | Platform Team | Read-only | None required | -| PAT Tokens | Secret | Security Team | Key Vault RBAC | At rest + in transit | -| Deployment Logs | Confidential | Operations | Log Analytics RBAC | At rest | -| Resource Metrics | Internal | Operations | Azure Monitor RBAC | At rest | -| Bicep Templates | Internal | Platform Team | Git branch protection | At rest | - -### Data Retention Policies - -| Data Type | Retention Period | Justification | Archive Location | -|-----------|------------------|---------------|------------------| -| Deployment Logs | 90 days | Compliance/troubleshooting | Log Analytics | -| Key Vault Soft Delete | 7-90 days | Recovery window | Key Vault | -| Resource Metrics | 93 days | Azure default | Azure Monitor | -| Git History | Indefinite | Version control | Git repository | -| azd Environment State | Until deleted | Active deployments | Local/.azure | - -### Compliance Considerations - -| Requirement | Implementation | Evidence | -|-------------|----------------|----------| -| **Data Encryption at Rest** | Azure Storage encryption, Key Vault encryption | Azure Security Center | -| **Data Encryption in Transit** | TLS 1.2+ for all Azure services | Network policies | -| **Access Logging** | Key Vault audit logs, Azure Activity Log | Log Analytics queries | -| **Data Residency** | Region-specific deployment | Bicep location parameter | -| **Right to Erasure** | Key Vault purge, resource deletion | Deletion scripts | - -[↑ Back to Top](#️-data-architecture) - ---- - -## πŸ“‹ Schema Documentation - -### JSON Schema References - -
-πŸ“œ Security Schema (security.schema.json) - -```json -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "title": "Azure Key Vault Security Configuration", - "type": "object", - "required": ["create", "keyVault"], - "properties": { - "create": { "type": "boolean" }, - "keyVault": { - "type": "object", - "required": ["name", "tags"], - "properties": { - "name": { - "type": "string", - "pattern": "^[a-zA-Z0-9-]{3,24}$", - "minLength": 3, - "maxLength": 24 - }, - "enablePurgeProtection": { "type": "boolean" }, - "enableSoftDelete": { "type": "boolean" }, - "softDeleteRetentionInDays": { - "type": "integer", - "minimum": 7, - "maximum": 90 - }, - "enableRbacAuthorization": { "type": "boolean" } - } - } - } -} -``` - -
- -
-πŸ“œ DevCenter Schema (devcenter.schema.json) - Key Definitions - -```json -{ - "definitions": { - "roleAssignment": { - "type": "object", - "properties": { - "id": { "type": "string", "pattern": "^[a-fA-F0-9-]{36}$" }, - "name": { "type": "string" }, - "scope": { "enum": ["Subscription", "ResourceGroup", "Project"] } - } - }, - "catalog": { - "type": "object", - "required": ["name", "type", "uri"], - "properties": { - "name": { "type": "string" }, - "type": { "enum": ["gitHub", "adoGit", "environmentDefinition", "imageDefinition"] }, - "visibility": { "enum": ["public", "private"] }, - "uri": { "type": "string", "format": "uri" }, - "branch": { "type": "string" }, - "path": { "type": "string" } - } - }, - "pool": { - "type": "object", - "required": ["name", "imageDefinitionName", "vmSku"], - "properties": { - "name": { "type": "string" }, - "imageDefinitionName": { "type": "string" }, - "vmSku": { "type": "string" } - } - } - } -} -``` - -
- -### Schema Validation - -Schemas are validated at authoring time using the `yaml-language-server` directive: - -```yaml -# yaml-language-server: $schema=./security.schema.json -``` - -[↑ Back to Top](#️-data-architecture) - ---- - -## πŸ“š References - -### Internal Documents - -- [Business Architecture](01-business-architecture.md) - Business context and stakeholders -- [Application Architecture](03-application-architecture.md) - Module design and Bicep structure -- [Technology Architecture](04-technology-architecture.md) - Azure services and infrastructure -- [Security Architecture](05-security-architecture.md) - Security controls and secrets management - -### External References - -- [Azure Key Vault Best Practices](https://learn.microsoft.com/en-us/azure/key-vault/general/best-practices) -- [Log Analytics Workspace Design](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/workspace-design) -- [Bicep loadYamlContent Function](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/bicep-functions-files#loadyamlcontent) -- [JSON Schema Specification](https://json-schema.org/specification.html) - -[↑ Back to Top](#️-data-architecture) - ---- - -## πŸ“– Glossary - -| Term | Definition | -|------|------------| -| **loadYamlContent()** | Bicep function that loads YAML files as objects at compile time | -| **Secret Identifier** | URI to a specific version of a secret in Azure Key Vault | -| **Diagnostic Settings** | Azure configuration for routing logs and metrics to destinations | -| **Soft Delete** | Key Vault feature allowing recovery of deleted secrets within retention period | -| **Purge Protection** | Key Vault feature preventing permanent deletion during soft delete period | -| **RBAC Authorization** | Key Vault access control using Azure Role-Based Access Control instead of access policies | - -[↑ Back to Top](#️-data-architecture) - ---- - -## πŸ“Ž Related Documents - -
-TOGAF Architecture Series - -| Document | Description | -|:---------|:------------| -| [πŸ“Š Business Architecture](01-business-architecture.md) | Stakeholder analysis, capabilities, value streams | -| πŸ—„οΈ **Data Architecture** | *You are here* | -| [πŸ›οΈ Application Architecture](03-application-architecture.md) | Bicep module design, dependencies, patterns | -| [βš™οΈ Technology Architecture](04-technology-architecture.md) | Azure services, CI/CD, deployment tools | -| [πŸ” Security Architecture](05-security-architecture.md) | Threat model, RBAC, compliance controls | - -
- ---- - -
- -**[← Previous: Business Architecture](01-business-architecture.md)** | **[Next: Application Architecture β†’](03-application-architecture.md)** - ---- - -*Document generated as part of TOGAF Architecture Documentation for DevExp-DevBox Landing Zone Accelerator* - -
diff --git a/docs/architecture/03-application-architecture.md b/docs/architecture/03-application-architecture.md deleted file mode 100644 index bf06c74e..00000000 --- a/docs/architecture/03-application-architecture.md +++ /dev/null @@ -1,1210 +0,0 @@ ---- -title: "Application Architecture" -description: "TOGAF Application Architecture documentation for the DevExp-DevBox Landing Zone Accelerator, covering Bicep module catalog, dependencies, deployment orchestration, and design patterns." -author: "DevExp Team" -date: "2026-01-22" -version: "1.0.0" -tags: - - TOGAF - - Application Architecture - - DevExp - - Bicep - - Infrastructure as Code ---- - -# πŸ›οΈ Application Architecture - -> [!NOTE] -> **Target Audience**: Platform Engineers, DevOps Engineers, Infrastructure Architects -> **Reading Time**: ~25 minutes - -
-πŸ“ Document Navigation - -| Previous | Index | Next | -|:---------|:-----:|-----:| -| [← Data Architecture](02-data-architecture.md) | [Architecture Index](README.md) | [Technology Architecture β†’](04-technology-architecture.md) | - -
- -> **TOGAF Layer**: Application Architecture -> **Version**: 1.0.0 -> **Last Updated**: January 22, 2026 -> **Author**: DevExp Team - ---- - -## πŸ“‘ Table of Contents - -- [πŸ” Architecture Overview](#-architecture-overview) -- [πŸ“¦ Module Catalog](#-module-catalog) -- [πŸ”— Module Dependencies](#-module-dependencies) -- [πŸš€ Deployment Orchestration](#-deployment-orchestration) -- [πŸ“ Interface Contracts](#-interface-contracts) -- [🎨 Design Patterns](#-design-patterns) -- [πŸ”Œ Extension Points](#-extension-points) -- [πŸ“š References](#-references) -- [πŸ“– Glossary](#-glossary) - ---- - -## πŸ” Architecture Overview - -The DevExp-DevBox Landing Zone Accelerator implements a **modular Infrastructure-as-Code (IaC)** architecture using Azure Bicep. The solution follows the **Landing Zone Accelerator** pattern with four distinct zones, each responsible for specific infrastructure concerns. - -### Landing Zone Pattern - -```mermaid -graph TB - subgraph "Subscription Scope" - MAIN[main.bicep
Orchestrator] - end - - subgraph "Security Landing Zone" - SECRG[Security RG] - SEC[security.bicep] - KV[keyVault.bicep] - SECRET[secret.bicep] - end - - subgraph "Monitoring Landing Zone" - MONRG[Monitoring RG] - LA[logAnalytics.bicep] - end - - subgraph "Workload Landing Zone" - WRKRG[Workload RG] - WRK[workload.bicep] - - subgraph "Core" - DC[devCenter.bicep] - CAT[catalog.bicep] - ENV[environmentType.bicep] - end - - subgraph "Project" - PROJ[project.bicep] - PCAT[projectCatalog.bicep] - PENV[projectEnvironmentType.bicep] - POOL[projectPool.bicep] - end - end - - subgraph "Connectivity Landing Zone" - CONRG[Connectivity RG] - CON[connectivity.bicep] - VNET[vnet.bicep] - NC[networkConnection.bicep] - end - - MAIN --> SECRG - MAIN --> MONRG - MAIN --> WRKRG - - SECRG --> SEC - SEC --> KV - SEC --> SECRET - - MONRG --> LA - - WRKRG --> WRK - WRK --> DC - DC --> CAT - DC --> ENV - WRK --> PROJ - PROJ --> PCAT - PROJ --> PENV - PROJ --> POOL - PROJ --> CON - CON --> CONRG - CON --> VNET - VNET --> NC - - style MAIN fill:#1976D2,color:#fff - style SEC fill:#D32F2F,color:#fff - style LA fill:#388E3C,color:#fff - style WRK fill:#F57C00,color:#fff - style CON fill:#7B1FA2,color:#fff -``` - -### Deployment Scopes - -| Zone | Bicep Scope | Resource Group | Purpose | -|:-----|:-----------:|:---------------|:--------| -| **Orchestrator** | `subscription` | Creates RGs | Entry point, resource group creation | -| **Security** | `resourceGroup` | devexp-security-* | Key Vault, secrets management | -| **Monitoring** | `resourceGroup` | devexp-monitoring-* | Log Analytics, diagnostics | -| **Workload** | `resourceGroup` | devexp-workload-* | DevCenter, projects, pools | -| **Connectivity** | `resourceGroup` | *-connectivity-RG | Virtual networks, network connections | - -[↑ Back to Top](#️-application-architecture) - ---- - -## πŸ“¦ Module Catalog - -### Entry Point Module - -#### Module: main.bicep - -- **Path**: `infra/main.bicep` -- **Scope**: `subscription` -- **Purpose**: Subscription-level orchestrator that creates resource groups and invokes landing zone modules - -**Inputs**: - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `location` | string | Yes | Azure region (validated against allowed list) | -| `secretValue` | secureString | Yes | GitHub/ADO PAT for catalog authentication | -| `environmentName` | string | Yes | Environment identifier (2-10 chars) | - -**Outputs**: - -| Output | Type | Description | -|--------|------|-------------| -| `SECURITY_AZURE_RESOURCE_GROUP_NAME` | string | Security RG name | -| `MONITORING_AZURE_RESOURCE_GROUP_NAME` | string | Monitoring RG name | -| `WORKLOAD_AZURE_RESOURCE_GROUP_NAME` | string | Workload RG name | -| `AZURE_LOG_ANALYTICS_WORKSPACE_ID` | string | Log Analytics resource ID | -| `AZURE_LOG_ANALYTICS_WORKSPACE_NAME` | string | Log Analytics workspace name | -| `AZURE_KEY_VAULT_NAME` | string | Key Vault name | -| `AZURE_KEY_VAULT_SECRET_IDENTIFIER` | string | Secret URI | -| `AZURE_KEY_VAULT_ENDPOINT` | string | Key Vault URI | -| `AZURE_DEV_CENTER_NAME` | string | DevCenter name | -| `AZURE_DEV_CENTER_PROJECTS` | array | List of project names | - -**Dependencies**: None (entry point) - -**Dependents**: All other modules - ---- - -### Management Modules - -#### Module: logAnalytics.bicep - -- **Path**: `src/management/logAnalytics.bicep` -- **Scope**: `resourceGroup` -- **Purpose**: Deploys Log Analytics workspace for centralized monitoring - -**Inputs**: - -| Parameter | Type | Required | Default | Description | -|-----------|------|----------|---------|-------------| -| `name` | string | Yes | - | Workspace name prefix | -| `location` | string | No | RG location | Azure region | -| `tags` | object | No | `{}` | Resource tags | -| `sku` | string | No | `PerGB2018` | Pricing tier | - -**Outputs**: - -| Output | Type | Description | -|--------|------|-------------| -| `AZURE_LOG_ANALYTICS_WORKSPACE_ID` | string | Workspace resource ID | -| `AZURE_LOG_ANALYTICS_WORKSPACE_NAME` | string | Workspace name (with unique suffix) | - -**Dependencies**: None - -**Dependents**: security.bicep, workload.bicep, connectivity.bicep (all diagnostic settings) - ---- - -### Security Modules - -
-πŸ” Click to expand Security Modules (3 modules: security.bicep, keyVault.bicep, secret.bicep) - -#### Module: security.bicep - -- **Path**: `src/security/security.bicep` -- **Scope**: `resourceGroup` -- **Purpose**: Orchestrates security resources deployment (Key Vault and secrets) - -**Inputs**: - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `tags` | object | Yes | Resource tags | -| `secretValue` | secureString | Yes | PAT token value | -| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | - -**Outputs**: - -| Output | Type | Description | -|--------|------|-------------| -| `AZURE_KEY_VAULT_NAME` | string | Key Vault name | -| `AZURE_KEY_VAULT_SECRET_IDENTIFIER` | string | Secret URI for catalog auth | -| `AZURE_KEY_VAULT_ENDPOINT` | string | Key Vault vault URI | - -**Dependencies**: logAnalytics.bicep - -**Dependents**: workload.bicep - ---- - -#### Module: keyVault.bicep - -- **Path**: `src/security/keyVault.bicep` -- **Scope**: `resourceGroup` -- **Purpose**: Deploys Azure Key Vault with security configurations - -**Inputs**: - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `keyvaultSettings` | object | Yes | Configuration from security.yaml | -| `location` | string | No | Azure region | -| `tags` | object | Yes | Resource tags | -| `unique` | string | No | Unique suffix for naming | - -**Outputs**: - -| Output | Type | Description | -|--------|------|-------------| -| `AZURE_KEY_VAULT_NAME` | string | Full Key Vault name | -| `AZURE_KEY_VAULT_ENDPOINT` | string | Key Vault URI | - -**Dependencies**: None - -**Dependents**: secret.bicep - ---- - -#### Module: secret.bicep - -- **Path**: `src/security/secret.bicep` -- **Scope**: `resourceGroup` -- **Purpose**: Creates secrets in Key Vault and configures diagnostics - -**Inputs**: - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `name` | string | Yes | Secret name | -| `secretValue` | secureString | Yes | Secret value | -| `keyVaultName` | string | Yes | Parent Key Vault name | -| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | - -**Outputs**: - -| Output | Type | Description | -|--------|------|-------------| -| `AZURE_KEY_VAULT_SECRET_IDENTIFIER` | string | Secret URI | - -**Dependencies**: keyVault.bicep, logAnalytics.bicep - -**Dependents**: catalog.bicep, projectCatalog.bicep - -
- ---- - -### Workload Modules - -
-βš™οΈ Click to expand Workload Modules (8 modules: workload.bicep, devCenter.bicep, catalog.bicep, environmentType.bicep, project.bicep, projectCatalog.bicep, projectEnvironmentType.bicep, projectPool.bicep) - -#### Module: workload.bicep - -- **Path**: `src/workload/workload.bicep` -- **Scope**: `resourceGroup` -- **Purpose**: Orchestrates DevCenter and project deployments - -**Inputs**: - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | -| `secretIdentifier` | secureString | Yes | Key Vault secret URI | -| `securityResourceGroupName` | string | Yes | Security RG for RBAC | -| `location` | string | No | Azure region | - -**Outputs**: - -| Output | Type | Description | -|--------|------|-------------| -| `AZURE_DEV_CENTER_NAME` | string | DevCenter name | -| `AZURE_DEV_CENTER_PROJECTS` | array | Project names array | - -**Dependencies**: security.bicep, logAnalytics.bicep - -**Dependents**: None (terminal module) - ---- - -#### Module: devCenter.bicep - -- **Path**: `src/workload/core/devCenter.bicep` -- **Scope**: `resourceGroup` -- **Purpose**: Deploys Azure DevCenter with identity and role assignments - -**Inputs**: - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `config` | DevCenterConfig | Yes | DevCenter configuration object | -| `catalogs` | array | Yes | Catalog configurations | -| `environmentTypes` | array | Yes | Environment type definitions | -| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | -| `secretIdentifier` | secureString | Yes | Secret URI for catalogs | -| `securityResourceGroupName` | string | Yes | Security RG name | -| `location` | string | No | Azure region | - -**Outputs**: - -| Output | Type | Description | -|--------|------|-------------| -| `AZURE_DEV_CENTER_NAME` | string | DevCenter name | - -**Dependencies**: logAnalytics.bicep, secret.bicep - -**Dependents**: project.bicep, catalog.bicep, environmentType.bicep - ---- - -#### Module: catalog.bicep - -- **Path**: `src/workload/core/catalog.bicep` -- **Scope**: `resourceGroup` -- **Purpose**: Configures DevCenter catalogs for image/environment definitions - -**Inputs**: - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `devCenterName` | string | Yes | Parent DevCenter name | -| `catalogConfig` | Catalog | Yes | Catalog configuration | -| `secretIdentifier` | secureString | Yes | Secret URI for private repos | - -**Type Definition - Catalog**: - -```bicep -type Catalog = { - name: string - type: 'gitHub' | 'adoGit' - visibility: 'public' | 'private' - uri: string - branch: string - path: string -} -``` - -**Outputs**: - -| Output | Type | Description | -|--------|------|-------------| -| `AZURE_DEV_CENTER_CATALOG_NAME` | string | Catalog name | -| `AZURE_DEV_CENTER_CATALOG_ID` | string | Catalog resource ID | -| `AZURE_DEV_CENTER_CATALOG_TYPE` | string | Catalog type | - -**Dependencies**: devCenter.bicep, secret.bicep - -**Dependents**: None - ---- - -#### Module: environmentType.bicep - -- **Path**: `src/workload/core/environmentType.bicep` -- **Scope**: `resourceGroup` -- **Purpose**: Defines environment types (dev, staging, UAT) in DevCenter - -**Inputs**: - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `devCenterName` | string | Yes | Parent DevCenter name | -| `environmentConfig` | EnvironmentType | Yes | Environment type config | - -**Outputs**: - -| Output | Type | Description | -|--------|------|-------------| -| `environmentTypeName` | string | Environment type name | -| `environmentTypeId` | string | Environment type resource ID | - -**Dependencies**: devCenter.bicep - -**Dependents**: projectEnvironmentType.bicep - ---- - -#### Module: project.bicep - -- **Path**: `src/workload/project/project.bicep` -- **Scope**: `resourceGroup` -- **Purpose**: Deploys DevCenter projects with pools, catalogs, and networking - -**Inputs**: - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `devCenterName` | string | Yes | Parent DevCenter name | -| `name` | string | Yes | Project name | -| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | -| `projectDescription` | string | Yes | Project description | -| `catalogs` | object[] | Yes | Project catalog configurations | -| `projectEnvironmentTypes` | array | Yes | Environment types for project | -| `projectPools` | array | Yes | Pool configurations | -| `projectNetwork` | object | Yes | Network configuration | -| `secretIdentifier` | secureString | Yes | Secret URI for catalogs | -| `securityResourceGroupName` | string | Yes | Security RG name | -| `identity` | Identity | Yes | Managed identity config | -| `tags` | object | No | Resource tags | -| `location` | string | No | Azure region | - -**Outputs**: - -| Output | Type | Description | -|--------|------|-------------| -| `AZURE_PROJECT_NAME` | string | Project name | -| `AZURE_PROJECT_ID` | string | Project resource ID | - -**Dependencies**: devCenter.bicep - -**Dependents**: projectCatalog.bicep, projectPool.bicep, projectEnvironmentType.bicep, connectivity.bicep - ---- - -#### Module: projectPool.bicep - -- **Path**: `src/workload/project/projectPool.bicep` -- **Scope**: `resourceGroup` -- **Purpose**: Deploys Dev Box pools with specific VM configurations - -**Inputs**: - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `name` | string | Yes | Pool name | -| `location` | string | No | Azure region | -| `catalogs` | Catalog[] | Yes | Catalog references | -| `imageDefinitionName` | string | Yes | Image definition name | -| `networkConnectionName` | string | Yes | Network connection name | -| `vmSku` | string | Yes | VM SKU (e.g., `general_i_32c128gb512ssd_v2`) | -| `networkType` | string | Yes | `Managed` or `Unmanaged` | -| `projectName` | string | Yes | Parent project name | - -**Dependencies**: project.bicep, connectivity.bicep, projectCatalog.bicep - -**Dependents**: None - -
- ---- - -### Connectivity Modules - -
-🌐 Click to expand Connectivity Modules (4 modules: connectivity.bicep, resourceGroup.bicep, vnet.bicep, networkConnection.bicep) - -#### Module: connectivity.bicep - -- **Path**: `src/connectivity/connectivity.bicep` -- **Scope**: `resourceGroup` -- **Purpose**: Orchestrates network infrastructure for Dev Box connectivity - -**Inputs**: - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `devCenterName` | string | Yes | DevCenter name | -| `projectNetwork` | object | Yes | Network configuration | -| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | -| `location` | string | Yes | Azure region | - -**Outputs**: - -| Output | Type | Description | -|--------|------|-------------| -| `networkConnectionName` | string | Network connection name | -| `networkType` | string | `Managed` or `Unmanaged` | - -**Dependencies**: devCenter.bicep, logAnalytics.bicep - -**Dependents**: projectPool.bicep - ---- - -#### Module: vnet.bicep - -- **Path**: `src/connectivity/vnet.bicep` -- **Scope**: `resourceGroup` -- **Purpose**: Deploys virtual networks and subnets - -**Inputs**: - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `logAnalyticsId` | string | Yes | Log Analytics workspace ID | -| `location` | string | Yes | Azure region | -| `tags` | object | No | Resource tags | -| `settings` | object | Yes | Network settings from YAML | - -**Outputs**: - -| Output | Type | Description | -|--------|------|-------------| -| `AZURE_VIRTUAL_NETWORK` | object | VNet details (name, RG, subnets) | - -**Dependencies**: logAnalytics.bicep - -**Dependents**: networkConnection.bicep - ---- - -#### Module: networkConnection.bicep - -- **Path**: `src/connectivity/networkConnection.bicep` -- **Scope**: `resourceGroup` -- **Purpose**: Creates DevCenter network connections for Dev Box - -**Inputs**: - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `name` | string | Yes | Connection name | -| `devCenterName` | string | Yes | DevCenter name | -| `subnetId` | string | Yes | Subnet resource ID | -| `location` | string | No | Azure region | -| `tags` | object | No | Resource tags | - -**Outputs**: - -| Output | Type | Description | -|--------|------|-------------| -| `vnetAttachmentName` | string | Attached network name | -| `networkConnectionId` | string | Network connection ID | -| `attachedNetworkId` | string | Attached network resource ID | -| `networkConnectionName` | string | Network connection name | - -**Dependencies**: vnet.bicep, devCenter.bicep - -**Dependents**: projectPool.bicep - -
- ---- - -### Identity Modules - -
-πŸ”‘ Click to expand Identity Modules (5 modules: devCenterRoleAssignment.bicep, devCenterRoleAssignmentRG.bicep, keyVaultAccess.bicep, orgRoleAssignment.bicep, projectIdentityRoleAssignment.bicep) - -#### Module: devCenterRoleAssignment.bicep - -- **Path**: `src/identity/devCenterRoleAssignment.bicep` -- **Scope**: `subscription` -- **Purpose**: Assigns RBAC roles to DevCenter managed identity at subscription scope - -**Inputs**: - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `id` | string | Yes | Role definition GUID | -| `principalId` | string | Yes | DevCenter managed identity | -| `principalType` | string | No | Default: `ServicePrincipal` | -| `scope` | string | Yes | `Subscription` or `ResourceGroup` | - -**Outputs**: - -| Output | Type | Description | -|--------|------|-------------| -| `roleAssignmentId` | string | Role assignment ID | -| `scope` | string | Assignment scope | - ---- - -#### Module: projectIdentityRoleAssignment.bicep - -- **Path**: `src/identity/projectIdentityRoleAssignment.bicep` -- **Scope**: `resourceGroup` -- **Purpose**: Assigns RBAC roles to project identities and Azure AD groups - -**Inputs**: - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `projectName` | string | Yes | Project name | -| `principalId` | string | Yes | Principal object ID | -| `roles` | array | Yes | Role definitions to assign | -| `principalType` | string | Yes | `User`, `Group`, or `ServicePrincipal` | - -**Outputs**: - -| Output | Type | Description | -|--------|------|-------------| -| `roleAssignmentIds` | array | Created role assignment details | -| `projectId` | string | Project resource ID | - ---- - -#### Module: orgRoleAssignment.bicep - -- **Path**: `src/identity/orgRoleAssignment.bicep` -- **Scope**: `resourceGroup` -- **Purpose**: Assigns RBAC roles to organizational Azure AD groups - -**Inputs**: - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `principalId` | string | Yes | Azure AD group object ID | -| `roles` | array | Yes | Role definitions to assign | -| `principalType` | string | No | Default: `Group` | - -
- ---- - -## Module Dependencies - -### Dependency Graph - -```mermaid -graph TB - subgraph "Entry Point" - MAIN[main.bicep] - end - - subgraph "Tier 1 - Foundation" - LA[logAnalytics.bicep] - end - - subgraph "Tier 2 - Security" - SEC[security.bicep] - KV[keyVault.bicep] - SECRET[secret.bicep] - end - - subgraph "Tier 3 - Workload Core" - WRK[workload.bicep] - DC[devCenter.bicep] - CAT[catalog.bicep] - ENV[environmentType.bicep] - end - - subgraph "Tier 4 - Project Resources" - PROJ[project.bicep] - PCAT[projectCatalog.bicep] - PENV[projectEnvironmentType.bicep] - end - - subgraph "Tier 5 - Connectivity & Pools" - CON[connectivity.bicep] - VNET[vnet.bicep] - NC[networkConnection.bicep] - POOL[projectPool.bicep] - end - - subgraph "Cross-Cutting - Identity" - DCRA[devCenterRoleAssignment.bicep] - PIRA[projectIdentityRoleAssignment.bicep] - ORA[orgRoleAssignment.bicep] - end - - MAIN --> LA - MAIN --> SEC - MAIN --> WRK - - SEC --> KV - SEC --> SECRET - SECRET -.->|logAnalyticsId| LA - - WRK --> DC - WRK --> PROJ - - DC --> CAT - DC --> ENV - DC --> DCRA - DC --> ORA - DC -.->|logAnalyticsId| LA - DC -.->|secretIdentifier| SECRET - - PROJ --> PCAT - PROJ --> PENV - PROJ --> CON - PROJ --> POOL - PROJ --> PIRA - - CON --> VNET - VNET --> NC - NC -.->|devCenterName| DC - - POOL -.->|networkConnectionName| CON - POOL -.->|catalogs| PCAT - - PCAT -.->|secretIdentifier| SECRET - - style MAIN fill:#1976D2,color:#fff - style LA fill:#388E3C,color:#fff - style SEC fill:#D32F2F,color:#fff - style DC fill:#F57C00,color:#fff -``` - -### Dependency Matrix - -| Module | Depends On | Required By | -|--------|-----------|-------------| -| main.bicep | - | All modules | -| logAnalytics.bicep | main.bicep | security, devCenter, vnet, secret | -| security.bicep | main.bicep, logAnalytics | workload | -| keyVault.bicep | security | secret | -| secret.bicep | keyVault, logAnalytics | catalog, projectCatalog | -| workload.bicep | main.bicep, security, logAnalytics | - | -| devCenter.bicep | workload, logAnalytics, secret | project, catalog, environmentType | -| catalog.bicep | devCenter, secret | - | -| environmentType.bicep | devCenter | projectEnvironmentType | -| project.bicep | devCenter | projectCatalog, projectPool, projectEnvironmentType | -| projectPool.bicep | project, connectivity, projectCatalog | - | -| connectivity.bicep | devCenter, logAnalytics | projectPool | -| vnet.bicep | logAnalytics | networkConnection | -| networkConnection.bicep | vnet, devCenter | connectivity | - -[↑ Back to Top](#️-application-architecture) - ---- - -## πŸš€ Deployment Orchestration - -### Deployment Sequence Diagram - -```mermaid -sequenceDiagram - participant AZD as Azure Developer CLI - participant ARM as Azure Resource Manager - participant RG as Resource Groups - participant MON as Monitoring Zone - participant SEC as Security Zone - participant WRK as Workload Zone - participant CON as Connectivity Zone - - AZD->>ARM: Deploy main.bicep (subscription scope) - - ARM->>RG: Create Security RG - ARM->>RG: Create Monitoring RG - ARM->>RG: Create Workload RG - - ARM->>MON: Deploy logAnalytics.bicep - MON-->>ARM: Return workspaceId - - ARM->>SEC: Deploy security.bicep - SEC->>SEC: Deploy keyVault.bicep - SEC->>SEC: Deploy secret.bicep - SEC-->>ARM: Return secretIdentifier - - ARM->>WRK: Deploy workload.bicep - WRK->>WRK: Deploy devCenter.bicep - - par RBAC Assignments - WRK->>WRK: devCenterRoleAssignment (subscription) - WRK->>WRK: devCenterRoleAssignmentRG (security RG) - WRK->>WRK: orgRoleAssignment - end - - par DevCenter Resources - WRK->>WRK: Deploy catalog.bicep - WRK->>WRK: Deploy environmentType.bicep - end - - loop For Each Project - WRK->>WRK: Deploy project.bicep - - par Project Resources - WRK->>WRK: projectCatalog.bicep - WRK->>WRK: projectEnvironmentType.bicep - WRK->>WRK: projectIdentityRoleAssignment - end - - WRK->>CON: Deploy connectivity.bicep - CON->>CON: Create connectivity RG - CON->>CON: Deploy vnet.bicep - CON->>CON: Deploy networkConnection.bicep - CON-->>WRK: Return networkConnectionName - - WRK->>WRK: Deploy projectPool.bicep - end - - ARM-->>AZD: Deployment Complete + Outputs -``` - -### Deployment Configuration - -**azure.yaml** (azd configuration): - -```yaml -name: ContosoDevExp - -hooks: - preprovision: - shell: sh - continueOnError: false - interactive: true - run: | - ./setup.sh -e ${AZURE_ENV_NAME} -s ${SOURCE_CONTROL_PLATFORM} -``` - -### Environment Variables - -| Variable | Purpose | Source | -|----------|---------|--------| -| `AZURE_ENV_NAME` | Environment name | User input / CI/CD | -| `AZURE_LOCATION` | Azure region | User input / CI/CD | -| `KEY_VAULT_SECRET` | PAT token value | GitHub Secret / ADO Variable | -| `SOURCE_CONTROL_PLATFORM` | `github` or `adogit` | User selection | -| `AZURE_SUBSCRIPTION_ID` | Target subscription | Azure login | - -[↑ Back to Top](#️-application-architecture) - ---- - -## πŸ“ Interface Contracts - -### Module Parameter Standards - -All modules follow consistent parameter patterns: - -```bicep -// Required parameters -@description('Clear description of purpose') -param requiredParam string - -// Secure parameters -@description('Sensitive data - stored securely') -@secure() -param secretParam string - -// Optional with defaults -@description('Optional parameter with sensible default') -param optionalParam string = 'default' - -// Validated parameters -@description('Parameter with validation') -@allowed(['option1', 'option2']) -param validatedParam string - -// Length-validated strings -@minLength(3) -@maxLength(24) -param constrainedParam string -``` - -### Output Standards - -```bicep -// All outputs use SCREAMING_SNAKE_CASE for azd integration -@description('Clear description of output value') -output AZURE_RESOURCE_NAME string = resource.name - -@description('Resource ID for downstream modules') -output AZURE_RESOURCE_ID string = resource.id -``` - -### Type Definitions - -The accelerator uses custom Bicep types for validation: - -```bicep -// Status type for feature toggles -type Status = 'Enabled' | 'Disabled' - -// Identity configuration -type Identity = { - type: 'SystemAssigned' | 'UserAssigned' - roleAssignments: RoleAssignment -} - -// RBAC role definition -type AzureRBACRole = { - id: string - name: string - scope: 'Subscription' | 'ResourceGroup' | 'Project' -} - -// Catalog configuration -type Catalog = { - name: string - type: 'gitHub' | 'adoGit' | 'environmentDefinition' | 'imageDefinition' - visibility: 'public' | 'private' - uri: string - branch: string - path: string -} -``` - -[↑ Back to Top](#️-application-architecture) - ---- - -## 🎨 Design Patterns - -### Pattern 1: Modular Landing Zone Design - -**Description**: Each landing zone (Security, Monitoring, Workload, Connectivity) is implemented as independent, reusable modules. - -**Benefits**: - -- Clear separation of concerns -- Independent scaling and updates -- Easier testing and validation -- Team ownership boundaries - -**Implementation**: - -``` -src/ -β”œβ”€β”€ security/ β†’ Security Landing Zone -β”œβ”€β”€ management/ β†’ Monitoring Landing Zone -β”œβ”€β”€ workload/ β†’ Workload Landing Zone -└── connectivity/ β†’ Connectivity Landing Zone -``` - ---- - -### Pattern 2: Declarative Configuration - -**Description**: Infrastructure configuration is externalized to YAML files with JSON Schema validation. - -**Benefits**: - -- Configuration-as-code -- IDE autocomplete and validation -- Environment-specific overrides -- Non-developer friendly editing - -**Implementation**: - -```yaml -# yaml-language-server: $schema=./security.schema.json -create: true -keyVault: - name: contoso - enablePurgeProtection: true -``` - ---- - -### Pattern 3: RBAC Separation - -**Description**: Role assignments are implemented in dedicated identity modules with scope-specific deployments. - -**Benefits**: - -- Least privilege enforcement -- Clear audit trail -- Reusable role assignment logic -- Scope-appropriate permissions - -**Implementation**: - -``` -src/identity/ -β”œβ”€β”€ devCenterRoleAssignment.bicep β†’ Subscription scope -β”œβ”€β”€ devCenterRoleAssignmentRG.bicep β†’ Resource group scope -β”œβ”€β”€ projectIdentityRoleAssignment.bicep β†’ Project scope -└── orgRoleAssignment.bicep β†’ Organization groups -``` - ---- - -### Pattern 4: Conditional Resource Creation - -**Description**: Resources can be conditionally created or referenced as existing based on configuration. - -**Benefits**: - -- Support for brownfield deployments -- Resource reuse across environments -- Flexible deployment scenarios - -**Implementation**: - -```bicep -// Create new or reference existing Key Vault -resource keyVault 'Microsoft.KeyVault/vaults@...' = if (settings.create) { ... } -resource existingKeyVault 'Microsoft.KeyVault/vaults@...' existing = if (!settings.create) { ... } - -// Output appropriate reference -output name string = settings.create ? keyVault.name : existingKeyVault.name -``` - ---- - -### Pattern 5: Diagnostic Settings Integration - -**Description**: Every resource that supports diagnostics is configured to send logs/metrics to Log Analytics. - -**Benefits**: - -- Centralized observability -- Consistent logging across resources -- Compliance and audit support - -**Implementation**: - -```bicep -resource diagnosticSettings 'Microsoft.Insights/diagnosticSettings@...' = { - scope: targetResource - properties: { - workspaceId: logAnalyticsId - logs: [{ categoryGroup: 'allLogs', enabled: true }] - metrics: [{ category: 'AllMetrics', enabled: true }] - } -} -``` - -[↑ Back to Top](#️-application-architecture) - ---- - -## πŸ”Œ Extension Points - -### Adding a New Project - -1. Edit `infra/settings/workload/devcenter.yaml`: - -```yaml -projects: - - name: "newProject" - description: "New project description" - network: - name: newProject - create: true - resourceGroupName: "newProject-connectivity-RG" - virtualNetworkType: Managed - addressPrefixes: ["10.1.0.0/16"] - subnets: - - name: newProject-subnet - properties: - addressPrefix: "10.1.1.0/24" - pools: - - name: "developer" - imageDefinitionName: "newProject-developer" - vmSku: "general_i_16c64gb256ssd_v2" - catalogs: - - name: "images" - type: imageDefinition - sourceControl: gitHub - visibility: private - uri: "https://github.com/org/newProject.git" - branch: "main" - path: "/.devcenter/imageDefinitions" -``` - -1. Run `azd provision` to deploy the new project. - ---- - -### Adding a New Dev Box Pool - -1. Add pool configuration to the project's `pools` array: - -```yaml -pools: - - name: "data-engineer" - imageDefinitionName: "project-data-engineer" - vmSku: "general_i_32c128gb1024ssd_v2" -``` - -1. Ensure the image definition exists in the referenced catalog. - ---- - -### Adding a New Catalog - -1. Add catalog to DevCenter or project level: - -```yaml -catalogs: - - name: "customEnvironments" - type: environmentDefinition - sourceControl: adoGit - visibility: private - uri: "https://dev.azure.com/org/project/_git/repo" - branch: "main" - path: "/environments" -``` - ---- - -### Adding a New Landing Zone - -1. Create new module directory: `src/newzone/` -2. Create orchestrator module: `src/newzone/newzone.bicep` -3. Add resource group configuration to `azureResources.yaml` -4. Reference from `main.bicep`: - -```bicep -module newzone '../src/newzone/newzone.bicep' = { - scope: resourceGroup(newzoneRgName) - params: { ... } -} -``` - -[↑ Back to Top](#️-application-architecture) - ---- - -## πŸ“š References - -### Internal Documents - -- [Business Architecture](01-business-architecture.md) - Business context and stakeholders -- [Data Architecture](02-data-architecture.md) - Configuration schemas and data flows -- [Technology Architecture](04-technology-architecture.md) - Azure services and infrastructure -- [Security Architecture](05-security-architecture.md) - Security controls and RBAC - -### External References - -- [Azure Bicep Documentation](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/) -- [Azure Developer CLI](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/) -- [Azure Landing Zones](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/landing-zone/) -- [DevCenter API Reference](https://learn.microsoft.com/en-us/rest/api/devcenter/) - -[↑ Back to Top](#️-application-architecture) - ---- - -## πŸ“– Glossary - -| Term | Definition | -|------|------------| -| **Bicep** | Domain-specific language for Azure Resource Manager templates | -| **Module** | Reusable Bicep file that encapsulates resource definitions | -| **Scope** | Deployment target level (subscription, resourceGroup, etc.) | -| **Landing Zone** | Pre-configured environment segment with specific purpose | -| **Orchestrator** | Main entry point module that coordinates other modules | -| **loadYamlContent()** | Bicep function to load YAML configuration at compile time | -| **azd** | Azure Developer CLI for streamlined Azure deployments | - -[↑ Back to Top](#️-application-architecture) - ---- - -## πŸ“Ž Related Documents - -
-TOGAF Architecture Series - -| Document | Description | -|:---------|:------------| -| [πŸ“Š Business Architecture](01-business-architecture.md) | Stakeholder analysis, capabilities, value streams | -| [πŸ—„οΈ Data Architecture](02-data-architecture.md) | Configuration schemas, secrets management, data flows | -| πŸ›οΈ **Application Architecture** | *You are here* | -| [βš™οΈ Technology Architecture](04-technology-architecture.md) | Azure services, CI/CD, deployment tools | -| [πŸ” Security Architecture](05-security-architecture.md) | Threat model, RBAC, compliance controls | - -
- ---- - -
- -**[← Previous: Data Architecture](02-data-architecture.md)** | **[Next: Technology Architecture β†’](04-technology-architecture.md)** - ---- - -*Document generated as part of TOGAF Architecture Documentation for DevExp-DevBox Landing Zone Accelerator* - -
diff --git a/docs/architecture/04-technology-architecture.md b/docs/architecture/04-technology-architecture.md deleted file mode 100644 index e213e564..00000000 --- a/docs/architecture/04-technology-architecture.md +++ /dev/null @@ -1,854 +0,0 @@ ---- -title: "Technology Architecture" -description: "TOGAF Technology Architecture documentation for the DevExp-DevBox Landing Zone Accelerator, covering Azure infrastructure, landing zones, networking, CI/CD, and deployment tools." -author: "DevExp Team" -date: "2026-01-22" -version: "1.0.0" -tags: - - TOGAF - - Technology Architecture - - DevExp - - Azure - - DevOps ---- - -# βš™οΈ Technology Architecture - -> [!NOTE] -> **Target Audience**: Cloud Architects, DevOps Engineers, Infrastructure Teams -> **Reading Time**: ~20 minutes - -
-πŸ“ Document Navigation - -| Previous | Index | Next | -|:---------|:-----:|-----:| -| [← Application Architecture](03-application-architecture.md) | [Architecture Index](README.md) | [Security Architecture β†’](05-security-architecture.md) | - -
- -> **TOGAF Layer**: Technology Architecture -> **Version**: 1.0.0 -> **Last Updated**: January 22, 2026 -> **Author**: DevExp Team - ---- - -## πŸ“‘ Table of Contents - -- [πŸ—οΈ Infrastructure Overview](#️-infrastructure-overview) -- [πŸ›οΈ Landing Zone Design](#️-landing-zone-design) -- [🌐 Network Architecture](#-network-architecture) -- [πŸ”‘ Identity & Access](#-identity--access) -- [πŸ”’ Security Architecture](#-security-architecture) -- [πŸ“Š Monitoring & Observability](#-monitoring--observability) -- [πŸ”„ CI/CD Infrastructure](#-cicd-infrastructure) -- [πŸ› οΈ Deployment Tools](#️-deployment-tools) -- [πŸ“‹ DevOps Practices](#-devops-practices) -- [πŸ“š References](#-references) -- [πŸ“– Glossary](#-glossary) - ---- - -## πŸ—οΈ Infrastructure Overview - -The DevExp-DevBox Landing Zone Accelerator deploys a comprehensive Azure infrastructure to support Microsoft Dev Box environments at enterprise scale. The solution leverages Platform-as-a-Service (PaaS) offerings for reduced operational overhead and built-in security. - -### Azure Resource Topology - -```mermaid -graph TB - subgraph "Azure Subscription" - subgraph "Security Landing Zone" - SECRG[devexp-security-*-RG] - KV[Azure Key Vault] - end - - subgraph "Monitoring Landing Zone" - MONRG[devexp-monitoring-*-RG] - LA[Log Analytics Workspace] - end - - subgraph "Workload Landing Zone" - WRKRG[devexp-workload-*-RG] - DC[Azure DevCenter] - PROJ[DevCenter Projects] - POOL[Dev Box Pools] - ENVT[Environment Types] - CAT[Catalogs] - end - - subgraph "Connectivity Landing Zone" - CONRG[*-connectivity-RG] - VNET[Virtual Networks] - SUB[Subnets] - NC[Network Connections] - end - end - - KV -->|Diagnostic Logs| LA - DC -->|Diagnostic Logs| LA - VNET -->|Diagnostic Logs| LA - - DC --> PROJ - PROJ --> POOL - DC --> CAT - DC --> ENVT - - PROJ --> NC - NC --> SUB - SUB --> VNET - - style KV fill:#D32F2F,color:#fff - style LA fill:#388E3C,color:#fff - style DC fill:#1976D2,color:#fff - style VNET fill:#7B1FA2,color:#fff -``` - -### Azure Services Deployed - -
-πŸ“‹ Click to expand Azure Services Inventory (10 services) - -| Service | Resource Type | Landing Zone | Purpose | -|:--------|:--------------|:------------:|:--------| -| **Azure DevCenter** | Microsoft.DevCenter/devcenters | Workload | Central management for Dev Box environments | -| **DevCenter Projects** | Microsoft.DevCenter/projects | Workload | Team-level Dev Box organization | -| **Dev Box Pools** | Microsoft.DevCenter/projects/pools | Workload | VM configuration templates | -| **Catalogs** | Microsoft.DevCenter/devcenters/catalogs | Workload | Image/environment definitions | -| **Environment Types** | Microsoft.DevCenter/devcenters/environmentTypes | Workload | Deployment environment stages | -| **Azure Key Vault** | Microsoft.KeyVault/vaults | Security | Secrets and credential management | -| **Log Analytics** | Microsoft.OperationalInsights/workspaces | Monitoring | Centralized logging and analytics | -| **Virtual Networks** | Microsoft.Network/virtualNetworks | Connectivity | Network infrastructure | -| **Network Connections** | Microsoft.DevCenter/networkConnections | Connectivity | Dev Box network attachment | -| **Role Assignments** | Microsoft.Authorization/roleAssignments | Cross-cutting | RBAC permissions | - -
- -### Resource Naming Convention - -``` -{landingZone}-{environmentName}-{location}-{resourceType} -``` - -| Component | Example | Description | -|-----------|---------|-------------| -| Landing Zone | `devexp-security` | Functional area identifier | -| Environment | `prod` | Deployment environment | -| Location | `eastus2` | Azure region | -| Resource Type | `RG` | Resource type suffix | - -**Example**: `devexp-security-prod-eastus2-RG` - -### API Versions - -| Resource | API Version | Notes | -|:---------|:-----------:|:------| -| Resource Groups | 2025-04-01 | Latest stable | -| DevCenter | 2025-10-01-preview | Preview for latest features | -| Key Vault | 2025-05-01 | Latest stable | -| Log Analytics | 2025-07-01 | Latest stable | -| Virtual Networks | 2025-01-01 | Latest stable | -| Network Connections | 2025-10-01-preview | Aligned with DevCenter | -| Role Assignments | 2022-04-01 | Stable RBAC API | -| Diagnostic Settings | 2021-05-01-preview | Stable diagnostics API | - -[↑ Back to Top](#️-technology-architecture) - ---- - -## πŸ›οΈ Landing Zone Design - -### Four-Zone Architecture - -```mermaid -graph LR - subgraph "Landing Zone Architecture" - direction TB - - subgraph "Zone 1: Security" - SEC[Security Zone] - SEC1[Key Vault] - SEC2[Secrets] - SEC3[Access Policies] - end - - subgraph "Zone 2: Monitoring" - MON[Monitoring Zone] - MON1[Log Analytics] - MON2[Solutions] - MON3[Diagnostics] - end - - subgraph "Zone 3: Workload" - WRK[Workload Zone] - WRK1[DevCenter] - WRK2[Projects] - WRK3[Pools] - end - - subgraph "Zone 4: Connectivity" - CON[Connectivity Zone] - CON1[VNets] - CON2[Subnets] - CON3[Network Connections] - end - end - - SEC --> SEC1 --> SEC2 --> SEC3 - MON --> MON1 --> MON2 --> MON3 - WRK --> WRK1 --> WRK2 --> WRK3 - CON --> CON1 --> CON2 --> CON3 - - SEC -.->|Logs| MON - WRK -.->|Logs| MON - CON -.->|Logs| MON - WRK -.->|Secrets| SEC - WRK -.->|Network| CON -``` - -### Resource Group Isolation - -| Landing Zone | Resource Group Pattern | Isolation Benefit | -|--------------|----------------------|-------------------| -| **Security** | devexp-security-{env}-{loc}-RG | Secrets isolated from workloads | -| **Monitoring** | devexp-monitoring-{env}-{loc}-RG | Centralized but segregated logging | -| **Workload** | devexp-workload-{env}-{loc}-RG | Application resources separated | -| **Connectivity** | {project}-connectivity-RG | Per-project network isolation | - -### Tagging Strategy - -All resources are tagged for governance and cost management: - -```yaml -tags: - environment: dev|test|staging|prod - division: Platforms - team: DevExP - project: Contoso-DevExp-DevBox - costCenter: IT - owner: Contoso - landingZone: Security|Monitoring|Workload|Connectivity - resources: ResourceType -``` - -[↑ Back to Top](#️-technology-architecture) - ---- - -## 🌐 Network Architecture - -### Network Architecture Diagram - -```mermaid -graph TB - subgraph "Azure Region" - subgraph "Project VNet (10.0.0.0/16)" - SUB1[Dev Box Subnet
10.0.1.0/24] - end - - subgraph "DevCenter" - DC[Azure DevCenter] - NC[Network Connection
AzureADJoin] - end - - subgraph "Managed Network Option" - MN[Microsoft Hosted
Network] - end - end - - subgraph "Identity" - AAD[Azure AD] - end - - subgraph "Internet" - GH[GitHub/ADO] - DEV[Developer Clients] - end - - DC -->|Attached Network| NC - NC -->|domainJoinType| AAD - NC -->|subnetId| SUB1 - - DC -.->|Alternative| MN - - DEV -->|RDP/Web| DC - DC -->|Catalog Sync| GH - - style DC fill:#1976D2,color:#fff - style NC fill:#7B1FA2,color:#fff - style AAD fill:#0078D4,color:#fff -``` - -### Network Configuration Options - -| Option | Type | Use Case | Configuration | -|:-------|:----:|:---------|:--------------| -| **Microsoft Hosted** | Managed | Simple deployments, no custom networking | `virtualNetworkType: Managed` | -| **Customer Managed** | Unmanaged | Hybrid connectivity, custom DNS, firewall | `virtualNetworkType: Unmanaged` | - -### VNet Configuration - -```yaml -network: - name: eShop - create: true - resourceGroupName: "eShop-connectivity-RG" - virtualNetworkType: Managed # or Unmanaged - addressPrefixes: - - 10.0.0.0/16 - subnets: - - name: eShop-subnet - properties: - addressPrefix: 10.0.1.0/24 -``` - -### Network Connection Properties - -| Property | Value | Description | -|----------|-------|-------------| -| `domainJoinType` | AzureADJoin | Azure AD-only join (no hybrid) | -| `subnetId` | Resource ID | Target subnet for Dev Boxes | -| `networkingResourceGroupName` | Auto | Microsoft-managed NIC resources | - -### Network Security Considerations - -- **NSGs**: Not explicitly deployed; rely on Azure DevCenter defaults -- **Private Endpoints**: Can be added for enhanced security -- **DNS**: Azure-provided or custom (for hybrid scenarios) -- **Firewall**: Optional Azure Firewall integration for egress control - -[↑ Back to Top](#️-technology-architecture) - ---- - -## πŸ”‘ Identity & Access - -### Identity & RBAC Model - -```mermaid -graph TB - subgraph "Azure AD" - SP[DevCenter
Managed Identity] - PROJ_SP[Project
Managed Identity] - GROUP1[Platform Engineering
Team Group] - GROUP2[eShop Developers
Group] - end - - subgraph "Subscription Scope" - ROLE1[Contributor] - ROLE2[User Access
Administrator] - end - - subgraph "Resource Group Scope" - ROLE3[Key Vault
Secrets User] - ROLE4[Key Vault
Secrets Officer] - ROLE5[DevCenter
Project Admin] - end - - subgraph "Project Scope" - ROLE6[Contributor] - ROLE7[Dev Box User] - ROLE8[Deployment
Environment User] - end - - SP -->|Subscription| ROLE1 - SP -->|Subscription| ROLE2 - SP -->|Security RG| ROLE3 - SP -->|Security RG| ROLE4 - - PROJ_SP -->|Workload RG| ROLE6 - PROJ_SP -->|Security RG| ROLE3 - - GROUP1 -->|Workload RG| ROLE5 - GROUP2 -->|Project| ROLE6 - GROUP2 -->|Project| ROLE7 - GROUP2 -->|Project| ROLE8 - GROUP2 -->|Security RG| ROLE3 - - style SP fill:#0078D4,color:#fff - style PROJ_SP fill:#0078D4,color:#fff - style GROUP1 fill:#FF9800,color:#fff - style GROUP2 fill:#4CAF50,color:#fff -``` - -### Managed Identities - -| Identity | Type | Purpose | Scope | -|----------|------|---------|-------| -| **DevCenter Identity** | SystemAssigned | DevCenter operations, catalog sync | Subscription + Security RG | -| **Project Identity** | SystemAssigned | Project-level operations | Project + Security RG | - -### Role Assignments Summary - -#### DevCenter Identity Roles - -| Role | Role ID | Scope | Purpose | -|------|---------|-------|---------| -| Contributor | b24988ac-6180-42a0-ab88-20f7382dd24c | Subscription | Manage Azure resources | -| User Access Administrator | 18d7d88d-d35e-4fb5-a5c3-7773c20a72d9 | Subscription | Assign RBAC roles | -| Key Vault Secrets User | 4633458b-17de-408a-b874-0445c86b69e6 | Security RG | Read secrets for catalogs | -| Key Vault Secrets Officer | b86a8fe4-44ce-4948-aee5-eccb2c155cd7 | Security RG | Manage secrets | - -#### Organization Group Roles - -| Group | Role | Scope | Purpose | -|-------|------|-------|---------| -| Platform Engineering Team | DevCenter Project Admin | Workload RG | Manage DevCenter settings | - -#### Project User Roles - -| Group | Role | Scope | Purpose | -|-------|------|-------|---------| -| {Project} Developers | Contributor | Project | Manage project resources | -| {Project} Developers | Dev Box User | Project | Use Dev Boxes | -| {Project} Developers | Deployment Environment User | Project | Deploy environments | -| {Project} Developers | Key Vault Secrets User | Security RG | Access secrets | - -[↑ Back to Top](#️-technology-architecture) - ---- - -## πŸ”’ Security Architecture - -### Key Vault Configuration - -```mermaid -graph TB - subgraph "Key Vault Security" - KV[Azure Key Vault] - - subgraph "Security Features" - PP[Purge Protection
Enabled] - SD[Soft Delete
7 days] - RBAC[RBAC Authorization
Enabled] - end - - subgraph "Access" - MI[Managed Identities
RBAC-based] - DEPLOY[Deployer
Access Policy] - end - - subgraph "Secrets" - PAT[gha-token
GitHub PAT] - end - end - - KV --> PP - KV --> SD - KV --> RBAC - - MI -->|Secrets User| KV - DEPLOY -->|Initial Setup| KV - - KV --> PAT - - style KV fill:#D32F2F,color:#fff - style PP fill:#4CAF50,color:#fff - style SD fill:#4CAF50,color:#fff - style RBAC fill:#4CAF50,color:#fff -``` - -### Security Configuration - -| Setting | Value | Security Impact | -|---------|-------|-----------------| -| `enablePurgeProtection` | true | Prevents permanent secret deletion | -| `enableSoftDelete` | true | Enables secret recovery | -| `softDeleteRetentionInDays` | 7 | Recovery window | -| `enableRbacAuthorization` | true | RBAC instead of access policies | -| SKU | Standard | Cost-effective for most scenarios | - -### Network Security - -- **Service Tags**: Azure DevCenter uses service tags for outbound rules -- **Private Link**: Optional for Key Vault and storage -- **Azure AD Join**: No on-premises domain dependency - -[↑ Back to Top](#️-technology-architecture) - ---- - -## πŸ“Š Monitoring & Observability - -### Log Analytics Integration - -```mermaid -graph LR - subgraph "Data Sources" - DC[DevCenter] - KV[Key Vault] - VNET[Virtual Network] - LA_SELF[Log Analytics] - end - - subgraph "Log Analytics Workspace" - LA[Log Analytics] - SOL[Azure Activity
Solution] - end - - subgraph "Consumption" - QUERY[KQL Queries] - ALERT[Alerts] - WORKBOOK[Workbooks] - EXPORT[Data Export] - end - - DC -->|Diagnostic Settings| LA - KV -->|Diagnostic Settings| LA - VNET -->|Diagnostic Settings| LA - LA_SELF -->|Self Diagnostics| LA - - LA --> SOL - LA --> QUERY - LA --> ALERT - LA --> WORKBOOK - LA --> EXPORT - - style LA fill:#68217A,color:#fff -``` - -### Diagnostic Settings Configuration - -All resources are configured with diagnostic settings: - -```bicep -resource diagnosticSettings 'Microsoft.Insights/diagnosticSettings@...' = { - name: '${resourceName}-diagnostics' - scope: targetResource - properties: { - logAnalyticsDestinationType: 'AzureDiagnostics' - logs: [ - { - categoryGroup: 'allLogs' - enabled: true - } - ] - metrics: [ - { - category: 'AllMetrics' - enabled: true - } - ] - workspaceId: logAnalyticsWorkspaceId - } -} -``` - -### Log Categories - -| Resource | Log Category | Contents | -|----------|--------------|----------| -| Key Vault | AuditEvent | Secret access, management operations | -| DevCenter | DataPlaneRequests | API operations | -| DevCenter | DevBoxProvisioning | Dev Box lifecycle | -| Virtual Network | VMProtectionAlerts | Network protection alerts | - -### Monitoring Queries - -**Key Vault Access Audit**: - -```kusto -AzureDiagnostics -| where ResourceProvider == "MICROSOFT.KEYVAULT" -| where OperationName == "SecretGet" -| project TimeGenerated, CallerIPAddress, identity_claim_upn_s, ResultType -``` - -**DevCenter Operations**: - -```kusto -AzureDiagnostics -| where ResourceProvider == "MICROSOFT.DEVCENTER" -| summarize count() by OperationName, ResultType -``` - -[↑ Back to Top](#️-technology-architecture) - ---- - -## πŸ”„ CI/CD Infrastructure - -### CI/CD Pipeline Flow - -```mermaid -graph LR - subgraph "Source Control" - GH[GitHub Repository] - ADO_REPO[Azure DevOps Repo] - end - - subgraph "CI Pipeline" - CI_TRIGGER[Push/PR Trigger] - VERSION[Generate Version] - BUILD[Build Bicep] - ARTIFACT[Upload Artifacts] - end - - subgraph "CD Pipeline" - MANUAL[Manual Trigger] - AUTH[OIDC Authentication] - PROVISION[azd provision] - end - - subgraph "Azure" - ARM[Azure Resource Manager] - RES[Azure Resources] - end - - GH --> CI_TRIGGER - ADO_REPO --> CI_TRIGGER - - CI_TRIGGER --> VERSION - VERSION --> BUILD - BUILD --> ARTIFACT - - MANUAL --> AUTH - AUTH --> PROVISION - PROVISION --> ARM - ARM --> RES - - style GH fill:#333,color:#fff - style ARM fill:#0078D4,color:#fff -``` - -### GitHub Actions Workflows - -#### CI Workflow (`ci.yml`) - -| Job | Steps | Trigger | -|-----|-------|---------| -| `generate-tag-version` | Checkout, Generate Release | Push to feature/*, PR to main | -| `build` | Checkout, Build Bicep, Upload Artifacts | After version generation | - -#### Deploy Workflow (`deploy.yml`) - -| Job | Steps | Trigger | -|-----|-------|---------| -| `build-and-deploy-to-azure` | Checkout, Install azd, Build, Login (OIDC), Provision | Manual (workflow_dispatch) | - -### Azure DevOps Pipeline (`azure-dev.yml`) - -| Task | Description | -|------|-------------| -| Install azd | Installs Azure Developer CLI | -| Configure AZD Auth | Sets `auth.useAzCliAuth` | -| Provision Infrastructure | Runs `azd provision` | - -### Authentication Methods - -| Platform | Method | Details | -|----------|--------|---------| -| **GitHub Actions** | OIDC Federation | Secretless, federated credentials | -| **Azure DevOps** | Service Connection | Azure CLI service principal | - -### CI/CD Environment Variables - -| Variable | Source | Purpose | -|----------|--------|---------| -| `AZURE_CLIENT_ID` | GitHub/ADO Variable | Service principal client ID | -| `AZURE_TENANT_ID` | GitHub/ADO Variable | Azure AD tenant ID | -| `AZURE_SUBSCRIPTION_ID` | GitHub/ADO Variable | Target subscription | -| `AZURE_ENV_NAME` | Workflow Input | Environment name | -| `AZURE_LOCATION` | Workflow Input | Azure region | -| `KEY_VAULT_SECRET` | GitHub Secret | PAT token value | -| `SOURCE_CONTROL_PLATFORM` | Environment | `github` or `adogit` | - -[↑ Back to Top](#️-technology-architecture) - ---- - -## πŸ› οΈ Deployment Tools - -### Azure Developer CLI (azd) - -> [!TIP] -> **Prerequisite**: Ensure Azure Developer CLI (`azd`) is installed. See [installation guide](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd). - -The primary deployment tool is Azure Developer CLI (`azd`), configured via `azure.yaml`: - -```yaml -name: ContosoDevExp - -hooks: - preprovision: - shell: sh - continueOnError: false - interactive: true - run: | - ./setup.sh -e ${AZURE_ENV_NAME} -s ${SOURCE_CONTROL_PLATFORM} -``` - -### azd Commands - -| Command | Purpose | -|---------|---------| -| `azd init` | Initialize azd environment | -| `azd auth login` | Authenticate to Azure | -| `azd provision` | Deploy infrastructure | -| `azd env new` | Create new environment | -| `azd env set` | Set environment variables | - -### Setup Scripts - -#### setUp.sh (Bash) - -| Function | Purpose | -|----------|---------| -| `test_azure_authentication` | Verify Azure CLI login | -| `test_github_authentication` | Verify GitHub CLI login | -| `get_secure_github_token` | Retrieve GitHub PAT | -| `initialize_azd_environment` | Configure azd environment | -| `start_azure_provisioning` | Run azd provision | - -#### setUp.ps1 (PowerShell) - -Equivalent functionality for Windows environments. - -### Script Flow - -```mermaid -sequenceDiagram - participant User - participant Script as setUp.sh/ps1 - participant AZ as Azure CLI - participant GH as GitHub CLI - participant AZD as Azure Developer CLI - - User->>Script: Run with -e envName -s github - Script->>AZ: Test authentication - AZ-->>Script: Authenticated - Script->>GH: Test authentication - GH-->>Script: Authenticated - Script->>GH: Get PAT token - GH-->>Script: Token retrieved - Script->>AZD: Initialize environment - AZD-->>Script: Environment ready - Script->>AZD: Set KEY_VAULT_SECRET - Script->>AZD: azd provision - AZD->>AZ: Deploy resources - AZ-->>Script: Deployment complete -``` - -[↑ Back to Top](#️-technology-architecture) - ---- - -## πŸ“‹ DevOps Practices - -### Release Strategy - -```mermaid -gitGraph - commit id: "Initial" - branch feature/new-pool - commit id: "Add pool config" - commit id: "Update YAML" - checkout main - merge feature/new-pool id: "PR Merge" - commit id: "Release v1.1.0" tag: "v1.1.0" -``` - -### Branching Model - -| Branch Pattern | Purpose | Protection | -|----------------|---------|------------| -| `main` | Production-ready code | Required reviews, CI pass | -| `feature/*` | New features | CI validation | -| `fix/*` | Bug fixes | CI validation | -| `docs/*` | Documentation updates | Optional CI | - -### Semantic Versioning - -The CI pipeline generates semantic versions based on commit messages: - -| Commit Prefix | Version Bump | Example | -|---------------|--------------|---------| -| `feat:` | Minor | 1.0.0 β†’ 1.1.0 | -| `fix:` | Patch | 1.0.0 β†’ 1.0.1 | -| `BREAKING CHANGE:` | Major | 1.0.0 β†’ 2.0.0 | - -### Artifact Management - -| Artifact | Retention | Contents | -|----------|-----------|----------| -| Bicep ARM Templates | 7 days | Compiled JSON templates | -| Release Assets | Permanent | Tagged releases | - -### Quality Gates - -| Gate | Trigger | Criteria | -|------|---------|----------| -| Bicep Build | PR/Push | Successful compilation | -| Artifact Upload | Build Success | Non-empty artifacts | -| Deploy Approval | Manual | Environment owner approval | - -[↑ Back to Top](#️-technology-architecture) - ---- - -## πŸ“š References - -### Internal Documents - -- [Business Architecture](01-business-architecture.md) - Business context and stakeholders -- [Data Architecture](02-data-architecture.md) - Configuration schemas and data flows -- [Application Architecture](03-application-architecture.md) - Module design and Bicep structure -- [Security Architecture](05-security-architecture.md) - Security controls and compliance - -### External References - -- [Microsoft Dev Box Documentation](https://learn.microsoft.com/en-us/azure/dev-box/) -- [Azure DevCenter API Reference](https://learn.microsoft.com/en-us/rest/api/devcenter/) -- [Azure Developer CLI Documentation](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/) -- [Azure Landing Zones](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/landing-zone/) -- [GitHub Actions for Azure](https://learn.microsoft.com/en-us/azure/developer/github/github-actions) -- [Azure DevOps Pipelines](https://learn.microsoft.com/en-us/azure/devops/pipelines/) - -[↑ Back to Top](#️-technology-architecture) - ---- - -## πŸ“– Glossary - -| Term | Definition | -|------|------------| -| **Landing Zone** | Pre-configured Azure environment segment for specific workloads | -| **DevCenter** | Azure service for managing developer environments at scale | -| **Dev Box** | Cloud-based developer workstation | -| **Network Connection** | Link between DevCenter and VNet subnet | -| **OIDC Federation** | OpenID Connect-based authentication without stored secrets | -| **azd** | Azure Developer CLI - streamlined Azure development tool | -| **ARM** | Azure Resource Manager - Azure's deployment engine | -| **Diagnostic Settings** | Azure configuration for log/metric routing | - -[↑ Back to Top](#️-technology-architecture) - ---- - -## πŸ“Ž Related Documents - -
-TOGAF Architecture Series - -| Document | Description | -|:---------|:------------| -| [πŸ“Š Business Architecture](01-business-architecture.md) | Stakeholder analysis, capabilities, value streams | -| [πŸ—„οΈ Data Architecture](02-data-architecture.md) | Configuration schemas, secrets management, data flows | -| [πŸ›οΈ Application Architecture](03-application-architecture.md) | Bicep module design, dependencies, patterns | -| βš™οΈ **Technology Architecture** | *You are here* | -| [πŸ” Security Architecture](05-security-architecture.md) | Threat model, RBAC, compliance controls | - -
- ---- - -
- -**[← Previous: Application Architecture](03-application-architecture.md)** | **[Next: Security Architecture β†’](05-security-architecture.md)** - ---- - -*Document generated as part of TOGAF Architecture Documentation for DevExp-DevBox Landing Zone Accelerator* - -
diff --git a/docs/architecture/05-security-architecture.md b/docs/architecture/05-security-architecture.md deleted file mode 100644 index 67653778..00000000 --- a/docs/architecture/05-security-architecture.md +++ /dev/null @@ -1,1087 +0,0 @@ ---- -title: "Security Architecture" -description: "TOGAF Security Architecture documentation for the DevExp-DevBox Landing Zone Accelerator, covering threat modeling, identity management, RBAC, secrets management, and compliance controls." -author: "DevExp Team" -date: "2026-01-22" -version: "1.0.0" -tags: - - TOGAF - - Security Architecture - - DevExp - - Zero Trust - - Azure Security ---- - -# πŸ” Security Architecture - -> [!NOTE] -> **Target Audience**: Security Architects, Compliance Teams, Platform Engineers -> **Reading Time**: ~25 minutes - -
-πŸ“ Document Navigation - -| Previous | Index | Next | -|:---------|:-----:|-----:| -| [← Technology Architecture](04-technology-architecture.md) | [Architecture Index](README.md) | β€” | - -
- -> **TOGAF Layer**: Security Architecture -> **Version**: 1.0.0 -> **Last Updated**: January 22, 2026 -> **Author**: DevExp Team - ---- - -## πŸ“‘ Table of Contents - -- [πŸ›‘οΈ Security Overview](#️-security-overview) -- [⚠️ Threat Model](#️-threat-model) -- [πŸ”‘ Identity & Access Management](#-identity--access-management) -- [βœ… Authorization & RBAC](#-authorization--rbac) -- [πŸ”’ Secrets Management](#-secrets-management) -- [🌐 Network Security](#-network-security) -- [πŸ“€ Data Protection](#-data-protection) -- [πŸ“Š Security Monitoring & Logging](#-security-monitoring--logging) -- [πŸ“‹ Compliance & Governance](#-compliance--governance) -- [🎯 Security Controls Matrix](#-security-controls-matrix) -- [🚨 Incident Response](#-incident-response) -- [πŸ› οΈ Security Hardening](#️-security-hardening) -- [πŸ“¦ Supply Chain Security](#-supply-chain-security) -- [πŸ”„ CI/CD Security](#-cicd-security) -- [πŸ’‘ Security Recommendations](#-security-recommendations) -- [πŸ“š References](#-references) -- [πŸ“– Glossary](#-glossary) - ---- - -## πŸ›‘οΈ Security Overview - -The DevExp-DevBox Landing Zone Accelerator implements a **defense-in-depth** security strategy aligned with **Zero Trust** principles. Security controls are embedded at every layer: identity, network, data, and application. - -### Security Architecture Overview - -```mermaid -graph TB - subgraph "Security Perimeter" - subgraph "Identity Layer" - AAD[Azure AD] - MI[Managed Identities] - RBAC[RBAC Roles] - end - - subgraph "Network Layer" - VNET[Virtual Networks] - NSG[Network Security] - PE[Private Endpoints
Optional] - end - - subgraph "Data Layer" - KV[Key Vault] - ENC[Encryption] - SEC[Secrets] - end - - subgraph "Application Layer" - DC[DevCenter] - PROJ[Projects] - CAT[Catalogs] - end - - subgraph "Monitoring Layer" - LA[Log Analytics] - AUDIT[Audit Logs] - ALERT[Security Alerts] - end - end - - AAD --> MI - MI --> RBAC - RBAC --> DC - RBAC --> KV - - VNET --> DC - VNET --> PE - PE --> KV - - KV --> SEC - SEC --> CAT - - DC --> PROJ - - DC -->|Logs| LA - KV -->|Logs| LA - LA --> AUDIT - LA --> ALERT - - style AAD fill:#0078D4,color:#fff - style KV fill:#D32F2F,color:#fff - style LA fill:#388E3C,color:#fff -``` - -### Security Principles - -| Principle | Implementation | -|-----------|----------------| -| **Zero Trust** | No implicit trust; verify explicitly via Azure AD and RBAC | -| **Least Privilege** | Role assignments with minimum necessary permissions | -| **Defense in Depth** | Multiple security layers (identity, network, data, monitoring) | -| **Assume Breach** | Comprehensive logging and monitoring for detection | -| **Secure by Default** | Hardened configurations (purge protection, RBAC authorization) | - -### Security Posture Summary - -> [!NOTE] -> **Security Status Overview**: The accelerator implements strong security controls across identity, secrets, and monitoring. Network security is moderate with optional enhancements available. - -| Area | Status | Key Controls | -|:-----|:------:|:-------------| -| **Identity** | βœ… Strong | Managed identities, Azure AD integration, RBAC | -| **Secrets** | βœ… Strong | Key Vault with purge protection, RBAC authorization | -| **Network** | ⚠️ Moderate | VNet isolation available, private endpoints optional | -| **Monitoring** | βœ… Strong | Centralized logging, diagnostic settings | -| **CI/CD** | βœ… Strong | OIDC federation, no stored secrets | - -[↑ Back to Top](#-security-architecture) - ---- - -## ⚠️ Threat Model - -### STRIDE Analysis - -```mermaid -graph TB - subgraph "STRIDE Threat Categories" - S[Spoofing
Identity] - T[Tampering
Data] - R[Repudiation
Actions] - I[Information Disclosure
Data Leakage] - D[Denial of Service
Availability] - E[Elevation of Privilege
Authorization] - end - - subgraph "Mitigations" - M1[Azure AD + MFA] - M2[RBAC + Audit Logs] - M3[Key Vault Logging] - M4[Encryption + RBAC] - M5[Azure DDoS + Throttling] - M6[Least Privilege RBAC] - end - - S --> M1 - T --> M2 - R --> M3 - I --> M4 - D --> M5 - E --> M6 - - style S fill:#FF5722,color:#fff - style T fill:#FF5722,color:#fff - style R fill:#FF5722,color:#fff - style I fill:#FF5722,color:#fff - style D fill:#FF5722,color:#fff - style E fill:#FF5722,color:#fff -``` - -### Threat Assessment - -#### Threat: Unauthorized Secret Access - -- **STRIDE Category**: Information Disclosure -- **Attack Vector**: Compromised identity attempts to read GitHub PAT from Key Vault -- **Affected Assets**: Key Vault secrets, Git repositories -- **Mitigations**: - - RBAC-based Key Vault authorization - - Managed identities (no stored credentials) - - Key Vault audit logging - - Principle of least privilege -- **Residual Risk**: Low - ---- - -#### Threat: Catalog Tampering - -> [!WARNING] -> This threat depends on external source control security. Ensure proper branch protection rules are configured. - -- **STRIDE Category**: Tampering -- **Attack Vector**: Attacker modifies Dev Box image definitions in catalog repository -- **Affected Assets**: Dev Box images, developer workstations -- **Mitigations**: - - Git branch protection rules - - PAT authentication for private repositories - - Catalog sync audit logs -- **Residual Risk**: Medium (depends on source control security) - ---- - -#### Threat: Privilege Escalation via DevCenter - -- **STRIDE Category**: Elevation of Privilege -- **Attack Vector**: User with Dev Box User role attempts to gain DevCenter Admin access -- **Affected Assets**: DevCenter, all projects -- **Mitigations**: - - Scoped role assignments (Project vs DevCenter) - - Azure AD group-based access - - Role assignment audit logs -- **Residual Risk**: Low - ---- - -#### Threat: Network-based Attacks on Dev Boxes - -- **STRIDE Category**: Denial of Service / Information Disclosure -- **Attack Vector**: External attacker targets Dev Box network -- **Affected Assets**: Virtual networks, Dev Boxes -- **Mitigations**: - - Microsoft-hosted networking (default) - - Azure DDoS protection - - Optional NSGs and private endpoints -- **Residual Risk**: Low (Microsoft-hosted) / Medium (customer-managed) - ---- - -#### Threat: CI/CD Pipeline Compromise - -- **STRIDE Category**: Spoofing / Tampering -- **Attack Vector**: Attacker injects malicious code via compromised pipeline -- **Affected Assets**: Infrastructure deployment, Azure resources -- **Mitigations**: - - OIDC federation (no stored secrets) - - Branch protection rules - - Manual deployment approval - - Artifact integrity verification -- **Residual Risk**: Low - ---- - -### Risk Assessment Matrix - -> [!CAUTION] -> Catalog tampering risk depends on external source control security configuration. - -| Threat | Likelihood | Impact | Risk Score | Mitigation Status | -|:-------|:----------:|:------:|:----------:|:-----------------:| -| Unauthorized Secret Access | Low | High | Medium | βœ… Mitigated | -| Catalog Tampering | Medium | High | High | ⚠️ Partial | -| Privilege Escalation | Low | Critical | Medium | βœ… Mitigated | -| Network Attacks | Low | Medium | Low | βœ… Mitigated | -| CI/CD Compromise | Low | Critical | Medium | βœ… Mitigated | - -[↑ Back to Top](#-security-architecture) - ---- - -## πŸ”‘ Identity & Access Management - -### Identity Architecture - -```mermaid -graph TB - subgraph "Azure AD" - TENANT[Azure AD Tenant] - - subgraph "Users & Groups" - PE_GROUP[Platform Engineering
Team] - DEV_GROUP[Project Developers] - ADMIN[Global Admins] - end - - subgraph "Service Principals" - CICD_SP[CI/CD Service
Principal] - end - - subgraph "Managed Identities" - DC_MI[DevCenter
Managed Identity] - PROJ_MI[Project
Managed Identity] - end - end - - TENANT --> PE_GROUP - TENANT --> DEV_GROUP - TENANT --> ADMIN - TENANT --> CICD_SP - TENANT --> DC_MI - TENANT --> PROJ_MI - - style TENANT fill:#0078D4,color:#fff - style DC_MI fill:#4CAF50,color:#fff - style PROJ_MI fill:#4CAF50,color:#fff -``` - -### Identity Types - -| Identity Type | Use Case | Lifecycle | Credential Management | -|---------------|----------|-----------|----------------------| -| **Azure AD Users** | Human access to Dev Boxes | HR-managed | Password + MFA | -| **Azure AD Groups** | Role assignment targets | Team-managed | N/A | -| **Managed Identities** | Service-to-service auth | Resource lifecycle | Azure-managed (no credentials) | -| **Service Principals** | CI/CD automation | App registration | OIDC federation | - -### Managed Identity Configuration - -```yaml -# DevCenter identity (from devcenter.yaml) -identity: - type: "SystemAssigned" -``` - -**Benefits**: - -- No credential storage required -- Automatic credential rotation -- Azure-managed lifecycle -- Audit trail via Azure AD - -### Authentication Flows - -```mermaid -sequenceDiagram - participant Dev as Developer - participant AAD as Azure AD - participant DC as DevCenter - participant KV as Key Vault - - Dev->>AAD: Authenticate (MFA) - AAD-->>Dev: Access Token - Dev->>DC: Request Dev Box - DC->>AAD: Validate Token - AAD-->>DC: Token Valid - DC->>DC: Check RBAC - DC-->>Dev: Dev Box Provisioned - - Note over DC,KV: Catalog Sync (Managed Identity) - DC->>AAD: Request Token (MI) - AAD-->>DC: MI Token - DC->>KV: Get Secret (MI Token) - KV->>AAD: Validate MI - AAD-->>KV: Authorized - KV-->>DC: Secret Value -``` - -[↑ Back to Top](#-security-architecture) - ---- - -## βœ… Authorization & RBAC - -### RBAC Hierarchy - -```mermaid -graph TB - subgraph "Scope Hierarchy" - SUB[Subscription] - RG_SEC[Security RG] - RG_WRK[Workload RG] - DC[DevCenter] - PROJ[Project] - POOL[Pool] - end - - SUB --> RG_SEC - SUB --> RG_WRK - RG_WRK --> DC - DC --> PROJ - PROJ --> POOL - - subgraph "Role Inheritance" - R1[Contributor
@ Subscription] - R2[Key Vault Secrets User
@ Security RG] - R3[DevCenter Project Admin
@ Workload RG] - R4[Dev Box User
@ Project] - end - - R1 -.->|Inherits down| RG_WRK - R2 -.->|Scoped| RG_SEC - R3 -.->|Scoped| DC - R4 -.->|Scoped| PROJ -``` - -### Role Assignments Table - -| Principal | Role | Role ID | Scope | Purpose | -|-----------|------|---------|-------|---------| -| DevCenter MI | Contributor | b24988ac-6180-42a0-ab88-20f7382dd24c | Subscription | Resource management | -| DevCenter MI | User Access Administrator | 18d7d88d-d35e-4fb5-a5c3-7773c20a72d9 | Subscription | RBAC assignments | -| DevCenter MI | Key Vault Secrets User | 4633458b-17de-408a-b874-0445c86b69e6 | Security RG | Read catalog secrets | -| DevCenter MI | Key Vault Secrets Officer | b86a8fe4-44ce-4948-aee5-eccb2c155cd7 | Security RG | Manage secrets | -| Platform Engineering Team | DevCenter Project Admin | 331c37c6-af14-46d9-b9f4-e1909e1b95a0 | Workload RG | Manage DevCenter | -| Project Developers | Contributor | b24988ac-6180-42a0-ab88-20f7382dd24c | Project | Project resources | -| Project Developers | Dev Box User | 45d50f46-0b78-4001-a660-4198cbe8cd05 | Project | Use Dev Boxes | -| Project Developers | Deployment Environment User | 18e40d4e-8d2e-438d-97e1-9528336e149c | Project | Deploy environments | -| Project Developers | Key Vault Secrets User | 4633458b-17de-408a-b874-0445c86b69e6 | Security RG | Access secrets | - -### Scope Isolation - -| Scope Level | Isolation Benefit | Access Control | -|-------------|-------------------|----------------| -| Subscription | Tenant boundary | Subscription owners | -| Resource Group | Workload separation | RG-level RBAC | -| DevCenter | Platform management | DevCenter admins | -| Project | Team isolation | Project-level roles | - -[↑ Back to Top](#-security-architecture) - ---- - -## πŸ”’ Secrets Management - -### Key Vault Architecture - -```mermaid -graph TB - subgraph "Azure Key Vault" - KV[contoso-*****-kv] - - subgraph "Security Settings" - PP[Purge Protection βœ“] - SD[Soft Delete βœ“] - RBAC_AUTH[RBAC Authorization βœ“] - end - - subgraph "Secrets" - PAT[gha-token
GitHub PAT] - end - - subgraph "Access Control" - DEPLOYER[Deployer Access
Policy] - MI_ACCESS[Managed Identity
RBAC] - end - end - - KV --> PP - KV --> SD - KV --> RBAC_AUTH - KV --> PAT - - DEPLOYER -->|Initial Setup| KV - MI_ACCESS -->|Runtime Access| KV - - style KV fill:#0078D4,color:#fff - style PP fill:#4CAF50,color:#fff - style SD fill:#4CAF50,color:#fff - style RBAC_AUTH fill:#4CAF50,color:#fff -``` - -### Secrets Access Flow - -```mermaid -sequenceDiagram - participant DC as DevCenter - participant AAD as Azure AD - participant KV as Key Vault - participant GH as GitHub - - DC->>AAD: Request token for Key Vault - Note over DC,AAD: Using Managed Identity - AAD-->>DC: Access token - - DC->>KV: GET secret (with token) - KV->>AAD: Validate token & RBAC - AAD-->>KV: Authorized (Secrets User role) - KV-->>DC: Secret value (GitHub PAT) - - DC->>GH: Clone catalog (with PAT) - GH-->>DC: Repository content -``` - -### Key Vault Access Matrix - -| Identity | Permission | Justification | -|----------|------------|---------------| -| DevCenter Managed Identity | secrets/get, secrets/list | Catalog authentication | -| Project Managed Identity | secrets/get, secrets/list | Project catalog authentication | -| CI/CD Service Principal | secrets/set | Initial secret provisioning | -| Deployer (azd) | secrets/* | Deployment operations | - -### Secret Types - -| Secret | Name | Purpose | Rotation | -|--------|------|---------|----------| -| GitHub PAT | gha-token | Private catalog authentication | Manual (90 days recommended) | - -### Security Configuration - -| Setting | Value | Impact | -|---------|-------|--------| -| `enablePurgeProtection` | `true` | Prevents permanent deletion | -| `enableSoftDelete` | `true` | 7-day recovery window | -| `softDeleteRetentionInDays` | `7` | Minimum retention | -| `enableRbacAuthorization` | `true` | RBAC instead of access policies | - -[↑ Back to Top](#-security-architecture) - ---- - -## 🌐 Network Security - -### Network Security Topology - -```mermaid -graph TB - subgraph "Internet" - DEV[Developer] - GH[GitHub] - end - - subgraph "Azure" - subgraph "DevCenter Network" - DC[DevCenter] - NC[Network Connection] - end - - subgraph "Project Network" - VNET[VNet 10.0.0.0/16] - SUBNET[Subnet 10.0.1.0/24] - DEVBOX[Dev Boxes] - end - - subgraph "Security Services" - AAD[Azure AD] - KV[Key Vault] - end - end - - DEV -->|HTTPS/RDP| DC - DC --> NC - NC --> SUBNET - SUBNET --> DEVBOX - - DC -->|HTTPS| GH - DC -->|Managed Identity| AAD - DC -->|Secret Access| KV - - style VNET fill:#7B1FA2,color:#fff - style KV fill:#D32F2F,color:#fff -``` - -### Network Configuration Options - -| Configuration | Type | Security Level | Use Case | -|---------------|------|----------------|----------| -| Microsoft Hosted | Managed | Standard | Simple deployments | -| Customer VNet | Unmanaged | Enhanced | Custom networking, firewall | - -### Network Segmentation - -| Segment | CIDR | Resources | -|---------|------|-----------| -| Project VNet | 10.0.0.0/16 | All project resources | -| Dev Box Subnet | 10.0.1.0/24 | Dev Box VMs | - -### Security Recommendations - -1. **Private Endpoints** (Optional): Add private endpoints for Key Vault -2. **NSG Rules**: Restrict inbound traffic to required ports -3. **Azure Firewall**: Add for egress control in enterprise scenarios -4. **Azure Bastion**: Use for secure Dev Box access - -[↑ Back to Top](#-security-architecture) - ---- - -## πŸ“€ Data Protection - -### Encryption Matrix - -| Data State | Encryption Method | Key Management | -|------------|-------------------|----------------| -| At Rest (Key Vault) | AES-256 | Platform-managed | -| At Rest (Log Analytics) | AES-256 | Platform-managed | -| At Rest (Dev Box Disks) | AES-256 | Platform-managed | -| In Transit | TLS 1.2+ | Azure-managed certificates | - -### Data Classification - -| Data Type | Classification | Protection | -|-----------|---------------|------------| -| GitHub PAT | Secret | Key Vault encryption + RBAC | -| Configuration YAML | Internal | Git encryption | -| Audit Logs | Confidential | Log Analytics encryption | -| Dev Box Content | Variable | Disk encryption | - -### Sensitive Data Handling - -- **Secrets**: Never logged, stored only in Key Vault -- **PAT Tokens**: Retrieved at runtime, not embedded in templates -- **User Data**: Managed on Dev Box disks with encryption - -[↑ Back to Top](#-security-architecture) - ---- - -## πŸ“Š Security Monitoring & Logging - -### Security Logging Architecture - -```mermaid -graph LR - subgraph "Log Sources" - KV_LOG[Key Vault
AuditEvent] - DC_LOG[DevCenter
Operations] - AAD_LOG[Azure AD
Sign-ins] - ACT_LOG[Activity Log
ARM Operations] - end - - subgraph "Log Analytics" - LA[Log Analytics
Workspace] - end - - subgraph "Analysis" - QUERY[Security Queries] - ALERT[Alert Rules] - WORKBOOK[Security Workbooks] - end - - KV_LOG --> LA - DC_LOG --> LA - AAD_LOG --> LA - ACT_LOG --> LA - - LA --> QUERY - LA --> ALERT - LA --> WORKBOOK - - style LA fill:#68217A,color:#fff -``` - -### Security-Relevant Logs - -| Log Source | Category | Security Events | -|------------|----------|-----------------| -| Key Vault | AuditEvent | Secret access, management operations | -| DevCenter | DataPlaneRequests | API operations | -| Azure AD | SignInLogs | Authentication attempts | -| Activity Log | Administrative | Resource modifications | - -### Security Queries - -**Unauthorized Secret Access Attempts**: - -```kusto -AzureDiagnostics -| where ResourceProvider == "MICROSOFT.KEYVAULT" -| where ResultType != "Success" -| project TimeGenerated, OperationName, ResultType, CallerIPAddress -| order by TimeGenerated desc -``` - -**Privilege Escalation Detection**: - -```kusto -AzureActivity -| where OperationNameValue contains "roleAssignments/write" -| project TimeGenerated, Caller, ResourceGroup, Properties -``` - -**Suspicious DevCenter Operations**: - -```kusto -AzureDiagnostics -| where ResourceProvider == "MICROSOFT.DEVCENTER" -| where ResultType != "Success" -| summarize FailedOperations = count() by OperationName, bin(TimeGenerated, 1h) -| where FailedOperations > 10 -``` - -### Alert Rules (Recommended) - -| Alert | Condition | Severity | -|-------|-----------|----------| -| Key Vault Access Denied | ResultType == "Forbidden" | High | -| Mass Secret Reads | Secret reads > 100/hour | Medium | -| Role Assignment Change | roleAssignments/write | High | -| DevCenter Config Change | DevCenter update operations | Medium | - -[↑ Back to Top](#-security-architecture) - ---- - -## πŸ“‹ Compliance & Governance - -### Compliance Mapping - -
-πŸ“‹ Click to expand Compliance Mapping (NIST 800-53 + CIS Azure) - -| Framework | Control | Implementation | Evidence | -|-----------|---------|----------------|----------| -| **NIST 800-53** | AC-2 (Account Management) | Azure AD groups + RBAC | Role assignment audit | -| **NIST 800-53** | AC-6 (Least Privilege) | Scoped role assignments | RBAC configuration | -| **NIST 800-53** | AU-2 (Audit Events) | Diagnostic settings | Log Analytics | -| **NIST 800-53** | SC-12 (Key Management) | Key Vault | Key Vault audit logs | -| **CIS Azure** | 4.1.1 | RBAC authorization for Key Vault | enableRbacAuthorization: true | -| **CIS Azure** | 4.1.3 | Key Vault soft delete | enableSoftDelete: true | -| **CIS Azure** | 4.1.4 | Key Vault purge protection | enablePurgeProtection: true | - -
- -### Tagging for Compliance - -```yaml -tags: - environment: dev|test|staging|prod # Environment classification - owner: Contoso # Resource accountability - costCenter: IT # Financial tracking - project: DevExp-DevBox # Project association -``` - -### Resource Locks (Recommended) - -| Resource | Lock Type | Purpose | -|----------|-----------|---------| -| Key Vault | CanNotDelete | Prevent accidental deletion | -| Log Analytics | CanNotDelete | Preserve audit logs | -| DevCenter | CanNotDelete | Protect platform | - -[↑ Back to Top](#-security-architecture) - ---- - -## 🎯 Security Controls Matrix - -### Control Inventory - -
-πŸ“‹ Click to expand Control Inventory (10 controls) - -| Control ID | Control Name | Category | Framework | Status | Implementation | -|------------|--------------|----------|-----------|--------|----------------| -| SC-001 | Azure AD Authentication | Identity | NIST AC-14 | βœ… Implemented | All services use Azure AD | -| SC-002 | Managed Identities | Identity | NIST IA-2 | βœ… Implemented | DevCenter + Projects | -| SC-003 | RBAC Authorization | Authorization | NIST AC-3 | βœ… Implemented | All resource access | -| SC-004 | Key Vault Secrets | Data Protection | NIST SC-12 | βœ… Implemented | PAT storage | -| SC-005 | Purge Protection | Data Protection | CIS 4.1.4 | βœ… Implemented | Key Vault config | -| SC-006 | Soft Delete | Data Protection | CIS 4.1.3 | βœ… Implemented | 7-day retention | -| SC-007 | Diagnostic Logging | Monitoring | NIST AU-2 | βœ… Implemented | All resources | -| SC-008 | Network Isolation | Network | NIST SC-7 | ⚠️ Partial | VNet available | -| SC-009 | Encryption at Rest | Data Protection | NIST SC-28 | βœ… Implemented | Platform encryption | -| SC-010 | Encryption in Transit | Data Protection | NIST SC-8 | βœ… Implemented | TLS 1.2+ | - -
- -### Control: Azure AD Authentication - -- **Category**: Identity -- **Framework Mapping**: NIST 800-53 AC-14, Azure Security Benchmark IM-1 -- **Implementation**: Azure AD tenant integration, managed identity authentication -- **Status**: Implemented -- **Evidence**: All Azure resources require Azure AD authentication - -### Control: Key Vault RBAC Authorization - -- **Category**: Data Protection -- **Framework Mapping**: CIS Azure 4.1.1, NIST 800-53 AC-3 -- **Implementation**: `enableRbacAuthorization: true` in Key Vault config -- **Status**: Implemented -- **Evidence**: security.yaml configuration - -### Control: Purge Protection - -- **Category**: Data Protection -- **Framework Mapping**: CIS Azure 4.1.4, NIST 800-53 SC-12 -- **Implementation**: `enablePurgeProtection: true` in Key Vault config -- **Status**: Implemented -- **Evidence**: security.yaml configuration - ---- - -## Incident Response - -### Detection Capabilities - -| Detection Type | Mechanism | Response | -|----------------|-----------|----------| -| Secret Access Anomaly | Log Analytics query | Alert β†’ Investigate | -| Role Assignment Change | Activity Log alert | Alert β†’ Review | -| DevCenter Config Change | Diagnostic logs | Alert β†’ Verify | -| Authentication Failure | Azure AD logs | Alert β†’ Lock account | - -### Response Procedures - -#### Secret Compromise Response - -1. **Detect**: Alert triggered for unauthorized Key Vault access -2. **Contain**: Disable affected managed identity / rotate secret -3. **Eradicate**: Rotate GitHub PAT, update Key Vault -4. **Recover**: Re-sync catalogs with new credentials -5. **Lessons Learned**: Review access policies, enhance monitoring - -#### Escalation Path - -| Severity | Initial Response | Escalation | -|----------|-----------------|------------| -| Low | Security Team | N/A | -| Medium | Security Team | Platform Team | -| High | Platform + Security | CISO | -| Critical | All Teams | Incident Commander | - -[↑ Back to Top](#-security-architecture) - ---- - -## πŸ› οΈ Security Hardening - -### Key Vault Hardening - -| Setting | Hardened Value | Default | Impact | -|---------|----------------|---------|--------| -| Purge Protection | Enabled | Disabled | Prevents permanent deletion | -| Soft Delete | Enabled | Enabled | Allows recovery | -| Retention Days | 7-90 | 90 | Balance recovery vs. compliance | -| RBAC Authorization | Enabled | Disabled | Modern access control | -| Network Rules | Optional | None | Network-level restriction | - -### DevCenter Security Settings - -| Setting | Value | Security Impact | -|---------|-------|-----------------| -| `catalogItemSyncEnableStatus` | Enabled | Allows catalog sync | -| `microsoftHostedNetworkEnableStatus` | Enabled | Uses Azure-managed networking | -| `installAzureMonitorAgentEnableStatus` | Enabled | Enables monitoring | - -### Secure Defaults - -The accelerator implements secure defaults: - -- βœ… RBAC authorization for Key Vault (not access policies) -- βœ… Purge protection enabled -- βœ… Soft delete enabled -- βœ… Managed identities (no stored credentials) -- βœ… Diagnostic settings on all resources -- βœ… OIDC federation for CI/CD (no secrets in pipelines) - -[↑ Back to Top](#-security-architecture) - ---- - -## πŸ“¦ Supply Chain Security - -### Catalog Security - -```mermaid -graph LR - subgraph "Source Control" - GH[GitHub Repository] - ADO[Azure DevOps] - end - - subgraph "Authentication" - PAT[PAT Token] - KV[Key Vault] - end - - subgraph "DevCenter" - CAT[Catalog Sync] - IMG[Image Definitions] - end - - GH -->|Private Repo| PAT - ADO -->|Private Repo| PAT - PAT -->|Stored| KV - KV -->|Retrieved| CAT - CAT --> IMG - - style KV fill:#D32F2F,color:#fff -``` - -### Image Provenance - -| Control | Implementation | Status | -|---------|----------------|--------| -| Source Verification | PAT authentication | βœ… | -| Branch Protection | Git settings (external) | ⚠️ Manual | -| Catalog Sync Logs | DevCenter diagnostics | βœ… | - -### Dependency Management - -| Component | Version Control | Security Updates | -|-----------|-----------------|------------------| -| Bicep Templates | Git versioned | PR review required | -| YAML Configs | Git versioned | Schema validation | -| CI/CD Actions | Pinned versions | Dependabot alerts | - -[↑ Back to Top](#-security-architecture) - ---- - -## πŸ”„ CI/CD Security - -### Pipeline Security Architecture - -```mermaid -graph TB - subgraph "GitHub Actions" - TRIGGER[Push/PR Trigger] - OIDC[OIDC Token Request] - BUILD[Build Bicep] - DEPLOY[azd provision] - end - - subgraph "Azure AD" - FED[Federated Credential] - TOKEN[Access Token] - end - - subgraph "Azure" - ARM[Resource Manager] - end - - TRIGGER --> OIDC - OIDC --> FED - FED --> TOKEN - TOKEN --> BUILD - BUILD --> DEPLOY - DEPLOY --> ARM - - style OIDC fill:#4CAF50,color:#fff - style FED fill:#0078D4,color:#fff -``` - -### OIDC Federation (No Stored Secrets) - -```yaml -# GitHub Actions workflow -- name: Log in with Azure (Federated Credentials) - run: | - azd auth login \ - --client-id "${{ vars.AZURE_CLIENT_ID }}" \ - --federated-credential-provider "github" \ - --tenant-id "${{ vars.AZURE_TENANT_ID }}" -``` - -**Benefits**: - -- No long-lived secrets in repository -- Automatic token rotation -- Auditable via Azure AD logs - -### Pipeline Security Controls - -| Control | Implementation | Status | -|---------|----------------|--------| -| OIDC Authentication | Federated credentials | βœ… | -| Branch Protection | Main branch rules | ⚠️ External | -| Artifact Integrity | GitHub artifact storage | βœ… | -| Manual Approval | workflow_dispatch | βœ… | -| Environment Secrets | KEY_VAULT_SECRET only | βœ… | - -### Security Best Practices - -1. **No Hardcoded Secrets**: Use GitHub Secrets for sensitive values -2. **OIDC over Service Principals**: Eliminates secret management -3. **Pinned Action Versions**: Prevent supply chain attacks -4. **Branch Protection**: Require PR reviews for main - -[↑ Back to Top](#-security-architecture) - ---- - -## πŸ’‘ Security Recommendations - -### Current Gaps - -| Gap | Risk Level | Recommendation | Priority | -|-----|------------|----------------|----------| -| No Private Endpoints | Medium | Add PE for Key Vault | Medium | -| No NSG Rules | Low | Add explicit deny rules | Low | -| Manual PAT Rotation | Medium | Implement automated rotation | Medium | -| No Azure Policy | Medium | Add compliance policies | High | - -### Security Roadmap - -```mermaid -gantt - title Security Enhancement Roadmap - dateFormat YYYY-MM-DD - section Phase 1 - Azure Policy Integration :2026-02-01, 30d - Private Endpoints :2026-02-15, 30d - section Phase 2 - Automated Secret Rotation :2026-03-01, 45d - Advanced Monitoring :2026-03-15, 30d - section Phase 3 - Penetration Testing :2026-04-01, 15d - Security Review :2026-04-15, 15d -``` - -### Recommended Enhancements - -1. **Azure Policy**: Enforce Key Vault soft delete, require tags -2. **Private Endpoints**: Key Vault private endpoint for enhanced network security -3. **Secret Rotation**: Azure Automation for PAT rotation -4. **Microsoft Defender**: Enable Defender for Key Vault -5. **Resource Locks**: Prevent accidental deletion - -[↑ Back to Top](#-security-architecture) - ---- - -## πŸ“š References - -### Internal Documents - -- [Business Architecture](01-business-architecture.md) - Business context and stakeholders -- [Data Architecture](02-data-architecture.md) - Configuration schemas and data flows -- [Application Architecture](03-application-architecture.md) - Module design and Bicep structure -- [Technology Architecture](04-technology-architecture.md) - Azure services and infrastructure - -### External References - -- [Azure Security Baseline](https://learn.microsoft.com/en-us/security/benchmark/azure/) -- [Key Vault Security Best Practices](https://learn.microsoft.com/en-us/azure/key-vault/general/best-practices) -- [Azure RBAC Documentation](https://learn.microsoft.com/en-us/azure/role-based-access-control/) -- [Microsoft Cloud Security Benchmark](https://learn.microsoft.com/en-us/security/benchmark/azure/introduction) -- [NIST 800-53 Controls](https://csrc.nist.gov/publications/detail/sp/800-53/rev-5/final) -- [CIS Azure Benchmark](https://www.cisecurity.org/benchmark/azure) - -[↑ Back to Top](#-security-architecture) - ---- - -## πŸ“– Glossary - -| Term | Definition | -|------|------------| -| **Zero Trust** | Security model assuming no implicit trust | -| **RBAC** | Role-Based Access Control | -| **Managed Identity** | Azure-managed service identity | -| **OIDC Federation** | OpenID Connect-based secretless authentication | -| **Purge Protection** | Key Vault feature preventing permanent deletion | -| **Soft Delete** | Key Vault feature allowing secret recovery | -| **STRIDE** | Threat modeling framework (Spoofing, Tampering, Repudiation, Information Disclosure, DoS, Elevation) | -| **Defense in Depth** | Multiple layers of security controls | - -[↑ Back to Top](#-security-architecture) - ---- - -## πŸ“Ž Related Documents - -
-TOGAF Architecture Series - -| Document | Description | -|:---------|:------------| -| [πŸ“Š Business Architecture](01-business-architecture.md) | Stakeholder analysis, capabilities, value streams | -| [πŸ—„οΈ Data Architecture](02-data-architecture.md) | Configuration schemas, secrets management, data flows | -| [πŸ›οΈ Application Architecture](03-application-architecture.md) | Bicep module design, dependencies, patterns | -| [βš™οΈ Technology Architecture](04-technology-architecture.md) | Azure services, CI/CD, deployment tools | -| πŸ” **Security Architecture** | *You are here* | - -
- ---- - -
- -**[← Previous: Technology Architecture](04-technology-architecture.md)** | **[Back to Index](README.md)** - ---- - -*Document generated as part of TOGAF Architecture Documentation for DevExp-DevBox Landing Zone Accelerator* - -
diff --git a/docs/architecture/README.md b/docs/architecture/README.md deleted file mode 100644 index 6ee33438..00000000 --- a/docs/architecture/README.md +++ /dev/null @@ -1,144 +0,0 @@ ---- -title: "Architecture Documentation Index" -description: "Central index for the DevExp-DevBox Landing Zone Accelerator TOGAF Architecture Documentation series." -author: "DevExp Team" -date: "2026-01-22" -version: "1.0.0" -tags: - - TOGAF - - Architecture - - DevExp - - Index ---- - -# πŸ“š Architecture Documentation Index - -> [!NOTE] -> **Target Audience**: All Technical Stakeholders -> **Purpose**: Central navigation hub for TOGAF architecture documentation - ---- - -## 🎯 Overview - -This documentation series provides comprehensive **TOGAF Architecture Development Method (ADM)** documentation for the **DevExp-DevBox Landing Zone Accelerator**. The documentation follows the BDAT (Business, Data, Application, Technology) framework with an additional Security Architecture layer. - ---- - -## πŸ“‘ Document Series - -| # | Document | Description | Audience | -|:-:|:---------|:------------|:---------| -| 1 | [πŸ“Š Business Architecture](01-business-architecture.md) | Stakeholder analysis, business capabilities, value streams, success metrics | BDMs, PMs, Enterprise Architects | -| 2 | [πŸ—„οΈ Data Architecture](02-data-architecture.md) | Configuration schemas, secrets management, telemetry, data governance | Data Architects, Platform Engineers | -| 3 | [πŸ›οΈ Application Architecture](03-application-architecture.md) | Bicep module catalog, dependencies, deployment orchestration, design patterns | DevOps Engineers, Platform Engineers | -| 4 | [βš™οΈ Technology Architecture](04-technology-architecture.md) | Azure infrastructure, landing zones, networking, CI/CD, deployment tools | Cloud Architects, Infrastructure Teams | -| 5 | [πŸ” Security Architecture](05-security-architecture.md) | Threat model, identity management, RBAC, compliance, security controls | Security Architects, Compliance Teams | - ---- - -## πŸ—ΊοΈ Reading Path - -```mermaid ---- -title: TOGAF Architecture Reading Path ---- -flowchart LR - %% ===== DOCUMENT NODES ===== - A["πŸ“Š Business"] -->|defines context| B["πŸ—„οΈ Data"] - B -->|informs design| C["πŸ›οΈ Application"] - C -->|drives implementation| D["βš™οΈ Technology"] - D -->|requires| E["πŸ” Security"] - - %% ===== CLASS DEFINITIONS ===== - classDef business fill:#4F46E5,stroke:#3730A3,color:#FFFFFF - classDef data fill:#F59E0B,stroke:#D97706,color:#000000 - classDef application fill:#10B981,stroke:#059669,color:#FFFFFF - classDef technology fill:#10B981,stroke:#059669,color:#FFFFFF - classDef security fill:#6B7280,stroke:#4B5563,color:#FFFFFF - - %% ===== CLASS ASSIGNMENTS ===== - class A business - class B data - class C application - class D technology - class E security -``` - -> [!TIP] -> **Recommended Reading Order**: Follow the numbered sequence for a comprehensive understanding, or jump directly to specific domains based on your role. - ---- - -## 🏷️ Quick Reference - -
-By Role - -### For Business Decision Makers - -- Start with [πŸ“Š Business Architecture](01-business-architecture.md) -- Review success metrics and value propositions - -### For Platform Engineers - -- Focus on [πŸ›οΈ Application Architecture](03-application-architecture.md) and [βš™οΈ Technology Architecture](04-technology-architecture.md) -- Review module catalog and deployment patterns - -### For Security Teams - -- Start with [πŸ” Security Architecture](05-security-architecture.md) -- Review threat model and compliance controls - -### For Data Architects - -- Focus on [πŸ—„οΈ Data Architecture](02-data-architecture.md) -- Review configuration schemas and data flows - -
- -
-By Topic - -| Topic | Primary Document | Related Sections | -|:------|:-----------------|:-----------------| -| **Azure DevCenter** | [Technology Architecture](04-technology-architecture.md) | Application Architecture | -| **Bicep Modules** | [Application Architecture](03-application-architecture.md) | Technology Architecture | -| **Key Vault & Secrets** | [Data Architecture](02-data-architecture.md) | Security Architecture | -| **RBAC & Identity** | [Security Architecture](05-security-architecture.md) | Technology Architecture | -| **CI/CD Pipelines** | [Technology Architecture](04-technology-architecture.md) | Application Architecture | -| **Compliance** | [Security Architecture](05-security-architecture.md) | Business Architecture | - -
- ---- - -## πŸ“‹ Document Standards - -All documents in this series follow: - -- **TOGAF ADM** methodology -- **GitHub-Flavored Markdown** (GFM) formatting -- **Mermaid** diagrams for visualization -- **YAML frontmatter** for metadata -- **Consistent navigation** with Previous/Next links - ---- - -## πŸ”— External Resources - -| Resource | Description | -|:---------|:------------| -| [Microsoft Dev Box Documentation](https://learn.microsoft.com/en-us/azure/dev-box/) | Official Azure Dev Box documentation | -| [Azure Landing Zones](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/landing-zone/) | Cloud Adoption Framework landing zones | -| [TOGAF Standard](https://www.opengroup.org/togaf) | The Open Group Architecture Framework | -| [Azure Bicep](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/) | Infrastructure as Code language | - ---- - -
- -**DevExp-DevBox Landing Zone Accelerator** -*TOGAF Architecture Documentation v1.0.0* - -