diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..9e08728c --- /dev/null +++ b/docs/README.md @@ -0,0 +1,206 @@ +--- +title: "DevExp-DevBox Documentation" +description: "Complete documentation for the DevExp-DevBox Landing Zone Accelerator" +author: "DevExp Team" +date: 2026-01-23 +version: "1.0.0" +tags: + - documentation + - dev-box + - azure + - landing-zone +--- + +# ๐Ÿ“š DevExp-DevBox Documentation + +> **Complete documentation for the DevExp-DevBox Landing Zone Accelerator** + +> [!NOTE] +> **Welcome!** This documentation hub provides comprehensive guides for deploying and managing Azure Dev Box environments using the DevExp-DevBox Landing Zone Accelerator. + +--- + +## ๐Ÿ“‘ Table of Contents + +- [๐ŸŽฏ Overview](#-overview) +- [๐Ÿ—๏ธ Architecture Documentation](#๏ธ-architecture-documentation) +- [๐Ÿ”„ DevOps Documentation](#-devops-documentation) +- [๐Ÿ“œ Scripts Documentation](#-scripts-documentation) +- [๐Ÿš€ Quick Start](#-quick-start) +- [๐Ÿ“– Additional Resources](#-additional-resources) + +--- + +## ๐ŸŽฏ Overview + +The **DevExp-DevBox Landing Zone Accelerator** is an enterprise-grade Infrastructure-as-Code (IaC) solution that enables organizations to rapidly deploy and manage Microsoft Dev Box environments at scale. + +### Key Features + +| Feature | Description | +|:--------|:------------| +| ๐Ÿข **Enterprise Ready** | Built on Azure Landing Zone principles with security and governance | +| โšก **Rapid Deployment** | Automated provisioning with Azure Developer CLI (azd) | +| ๐Ÿ”’ **Security First** | RBAC, Key Vault integration, and OIDC authentication | +| ๐Ÿ“Š **Observability** | Integrated monitoring with Log Analytics | +| ๐Ÿ”„ **CI/CD Ready** | GitHub Actions workflows for automated deployments | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ—๏ธ Architecture Documentation + +Comprehensive TOGAF-aligned architecture documentation covering business, data, application, technology, security, and deployment aspects. + +| Document | Description | +|:---------|:------------| +| ๐Ÿ“‹ [Business Architecture](architecture/01-business-architecture.md) | Business context, stakeholders, and value propositions | +| ๐Ÿ—„๏ธ [Data Architecture](architecture/02-data-architecture.md) | Configuration data models, secrets management, and telemetry | +| ๐Ÿ“ฆ [Application Architecture](architecture/03-application-architecture.md) | Bicep module catalog, dependencies, and deployment orchestration | +| โ˜๏ธ [Technology Architecture](architecture/04-technology-architecture.md) | Azure services, infrastructure design, and technology standards | +| ๐Ÿ”’ [Security Architecture](architecture/05-security-architecture.md) | Identity management, RBAC, and compliance framework | +| ๐Ÿš€ [Deployment Architecture](architecture/07-deployment-architecture.md) | CI/CD pipeline design and deployment patterns | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”„ DevOps Documentation + +Detailed documentation for GitHub Actions workflows and CI/CD processes. + +| Document | Description | +|:---------|:------------| +| ๐Ÿ“– [DevOps Overview](devops/README.md) | Master pipeline architecture and workflow relationships | +| ๐Ÿ”„ [CI Workflow](devops/ci.md) | Continuous Integration workflow for Bicep validation and build | +| ๐Ÿš€ [Deploy Workflow](devops/deploy.md) | Azure deployment workflow with OIDC authentication | +| ๐Ÿท๏ธ [Release Workflow](devops/release.md) | Branch-based release strategy and semantic versioning | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“œ Scripts Documentation + +PowerShell automation scripts for environment setup, Azure configuration, and GitHub integration. + +### ๐Ÿ“ Root Scripts + +| Document | Description | +|:---------|:------------| +| ๐Ÿ“– [Scripts Overview](scripts/README.md) | Complete scripts architecture and quick reference | +| โš™๏ธ [setUp.ps1](scripts/setup.md) | Azure Dev Box environment setup with source control integration | +| ๐Ÿงน [cleanSetUp.ps1](scripts/clean-setup.md) | Complete infrastructure cleanup orchestrator | + +### โ˜๏ธ Azure Scripts + +| Document | Description | +|:---------|:------------| +| ๐Ÿ”‘ [createCustomRole.ps1](scripts/azure/create-custom-role.md) | Creates custom Azure RBAC role for role assignment management | +| ๐Ÿ‘ฅ [createUsersAndAssignRole.ps1](scripts/azure/create-users-and-assign-role.md) | Assigns DevCenter roles to the current user | +| ๐Ÿ—‘๏ธ [deleteDeploymentCredentials.ps1](scripts/azure/delete-deployment-credentials.md) | Removes Azure AD service principal and app registration | +| ๐Ÿ‘ฅ [deleteUsersAndAssignedRoles.ps1](scripts/azure/delete-users-and-assigned-roles.md) | Removes DevCenter role assignments | +| ๐Ÿ”‘ [generateDeploymentCredentials.ps1](scripts/azure/generate-deployment-credentials.md) | Creates service principal and GitHub secret for CI/CD | + +### โš™๏ธ Configuration Scripts + +| Document | Description | +|:---------|:------------| +| ๐Ÿงน [cleanUp.ps1](scripts/configuration/clean-up.md) | Removes Azure resource groups | +| ๐Ÿ“ฆ [winget-update.ps1](scripts/configuration/winget-update.md) | Updates Microsoft Store applications via winget | + +### ๐Ÿ™ GitHub Scripts + +| Document | Description | +|:---------|:------------| +| ๐Ÿ” [createGitHubSecretAzureCredentials.ps1](scripts/github/create-github-secret-azure-credentials.md) | Creates GitHub repository secret for Azure credentials | +| ๐Ÿ—‘๏ธ [deleteGitHubSecretAzureCredentials.ps1](scripts/github/delete-github-secret-azure-credentials.md) | Removes GitHub repository secret | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿš€ Quick Start + +### Prerequisites + +| Tool | Purpose | Installation | +|:-----|:--------|:-------------| +| Azure CLI (`az`) | Azure resource management | [Install Azure CLI](https://docs.microsoft.com/cli/azure/install-azure-cli) | +| Azure Developer CLI (`azd`) | Deployment orchestration | [Install azd](https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd) | +| GitHub CLI (`gh`) | GitHub integration | [Install GitHub CLI](https://cli.github.com/) | +| PowerShell 5.1+ | Script execution | Pre-installed on Windows | + +### Setup Steps + +1. **Clone the repository** + + ```bash + git clone https://github.com/Evilazaro/DevExp-DevBox.git + cd DevExp-DevBox + ``` + +2. **Authenticate with Azure** + + ```bash + az login + az account set --subscription "" + ``` + +3. **Run the setup script** + + ```powershell + .\setUp.ps1 -EnvName "demo" -SourceControl "github" + ``` + +4. **Deploy to Azure** + + ```bash + azd provision + ``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“– Additional Resources + +### External Links + +| Resource | Description | +|:---------|:------------| +| [Microsoft Dev Box Documentation](https://learn.microsoft.com/azure/dev-box/) | Official Azure Dev Box documentation | +| [Azure Landing Zones](https://learn.microsoft.com/azure/cloud-adoption-framework/ready/landing-zone/) | Cloud Adoption Framework Landing Zones | +| [Azure Bicep Documentation](https://learn.microsoft.com/azure/azure-resource-manager/bicep/) | Bicep language reference | +| [GitHub Actions Documentation](https://docs.github.com/actions) | GitHub Actions workflows | + +### Repository Links + +| Resource | Description | +|:---------|:------------| +| [๐Ÿ“ Infrastructure Code](../infra/) | Bicep templates and configuration | +| [๐Ÿ“ Source Modules](../src/) | Reusable Bicep modules | +| [๐Ÿ“„ azure.yaml](../azure.yaml) | Azure Developer CLI configuration | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +
+ +**[โฌ†๏ธ Back to Repository Root](../README.md)** + +
diff --git a/docs/architecture/01-business-architecture.md b/docs/architecture/01-business-architecture.md new file mode 100644 index 00000000..da4852d3 --- /dev/null +++ b/docs/architecture/01-business-architecture.md @@ -0,0 +1,587 @@ +--- +title: "Business Architecture" +description: "Enterprise business architecture for DevExp-DevBox Landing Zone Accelerator using TOGAF BDAT framework" +author: "DevExp Team" +date: 2026-01-23 +version: "1.0.0" +tags: + - architecture + - business + - togaf + - dev-box + - 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) | + +
+ +| Property | Value | +|:---------|:------| +| **Version** | 1.0.0 | +| **Last Updated** | 2026-01-23 | +| **Author** | DevExp Team | +| **Status** | Published | + +--- + +## ๐Ÿ“‘ 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) +- [๐Ÿ“– Glossary](#glossary) +- [๐Ÿ”— References](#references) + +--- + +## ๐Ÿ“‹ Executive Summary + +The **DevExp-DevBox Landing Zone Accelerator** is an enterprise-grade infrastructure-as-code solution that enables organizations to rapidly deploy and manage Microsoft Dev Box environments at scale. Built on Azure Landing Zone principles, it provides a standardized, secure, and compliant foundation for developer workstation provisioning. + +### Key Business Value + +| Value Proposition | Description | +|-------------------|-------------| +| **Time-to-Productivity** | Reduce developer onboarding from days to hours with pre-configured workstations | +| **Standardization** | Enforce consistent development environments across teams and projects | +| **Security by Design** | Built-in security controls, RBAC, and secrets management | +| **Cost Optimization** | Right-sized VM SKUs and centralized resource governance | +| **Self-Service** | Empower developers to provision their own environments within guardrails | + +### Target Organizations + +- Enterprise software development teams (500+ developers) +- Organizations with multiple development projects requiring environment isolation +- Companies with compliance requirements (SOC2, ISO 27001) +- Platform engineering teams building internal developer platforms (IDPs) + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐ŸŽฏ Business Context + +### Problem Statement + +Modern software development organizations face significant challenges in providing consistent, secure, and rapidly deployable development environments: + +```mermaid +--- +title: Development Environment Challenges +--- +mindmap + root((Development Environment Challenges)) + Onboarding Delays + Manual setup processes + Inconsistent configurations + Knowledge dependencies + Security Risks + Sensitive credentials in repos + Inconsistent access controls + Shadow IT development + Operational Overhead + Manual provisioning + Configuration drift + Resource sprawl + Cost Management + Over-provisioned resources + Underutilized infrastructure + Lack of visibility +``` + +### Business Drivers + +| Driver | Description | Priority | +|--------|-------------|----------| +| **Developer Experience** | Streamline developer workflows and reduce friction | High | +| **Security & Compliance** | Meet enterprise security requirements and regulatory standards | High | +| **Operational Efficiency** | Reduce manual intervention in environment provisioning | Medium | +| **Cost Control** | Optimize infrastructure spending through standardization | Medium | +| **Scalability** | Support growth without linear increase in operational burden | Medium | + +### Target Audience + +The DevExp-DevBox accelerator serves organizations that: + +- Have 50+ developers requiring standardized development environments +- Use Azure as their primary cloud platform +- Follow DevOps/GitOps practices for infrastructure management +- Require centralized governance over development resources +- Need to support multiple projects with different tooling requirements + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ‘ฅ Stakeholder Analysis + +### Stakeholder Map + +```mermaid +--- +title: Stakeholder Map +--- +flowchart TB + %% ===== EXECUTIVE STAKEHOLDERS ===== + subgraph Executive["Executive Stakeholders"] + CTO["CTO/VP Engineering"] + CISO["CISO/Security Director"] + CFO["CFO/Finance Director"] + end + + %% ===== TECHNICAL STAKEHOLDERS ===== + subgraph Technical["Technical Stakeholders"] + PE["Platform Engineers"] + SA["Solution Architects"] + SEC["Security Engineers"] + OPS["Operations Team"] + end + + %% ===== END USERS ===== + subgraph Users["End Users"] + DEV["Developers"] + LEAD["Tech Leads"] + PM["Project Managers"] + end + + %% ===== EXTERNAL PARTIES ===== + subgraph External["External"] + MS["Microsoft Support"] + AUD["Auditors"] + end + + %% ===== RELATIONSHIPS ===== + CTO -->|"oversees"| PE + CISO -->|"directs"| SEC + CFO -->|"manages"| OPS + + PE -->|"supports"| DEV + SA -->|"guides"| LEAD + SEC -->|"enables"| DEV + + AUD -.->|"audits"| SEC + MS -.->|"assists"| PE + + %% ===== NODE STYLES ===== + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef external fill:#6B7280,stroke:#4B5563,color:#FFFFFF,stroke-dasharray:5 5 + classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + + class CTO,CISO,CFO primary + class PE,SA,SEC,OPS secondary + class DEV,LEAD,PM trigger + class MS,AUD external + + %% ===== SUBGRAPH STYLES ===== + style Executive fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style Technical fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Users fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style External fill:#F3F4F6,stroke:#6B7280,stroke-width:2px +``` + +### Stakeholder Register + +| Stakeholder | Role | Concerns | Interests | Influence | +|-------------|------|----------|-----------|-----------| +| **CTO/VP Engineering** | Strategic Decision Maker | ROI, developer productivity, competitive advantage | Faster time-to-market, reduced technical debt | High | +| **CISO/Security Director** | Security Governance | Data protection, compliance, access control | Zero-trust implementation, audit readiness | High | +| **CFO/Finance Director** | Budget Authority | Cost optimization, predictable spending | Resource utilization metrics, cost allocation | Medium | +| **Platform Engineers** | Primary Implementers | Maintainability, automation, extensibility | Infrastructure-as-code, GitOps workflows | High | +| **Solution Architects** | Design Authority | Scalability, integration, standards | Reference architectures, best practices | High | +| **Security Engineers** | Security Implementation | Threat mitigation, vulnerability management | Security controls, monitoring, response | Medium | +| **Operations Team** | Day-2 Operations | Reliability, monitoring, incident response | Observability, runbooks, alerting | Medium | +| **Developers** | End Users | Fast provisioning, self-service, tool availability | Productivity, autonomy, environment parity | Low | +| **Tech Leads** | Team Management | Team productivity, resource allocation | Project-specific configurations, access management | Medium | +| **Project Managers** | Delivery Management | Timeline adherence, resource availability | Status visibility, cost tracking | Low | +| **Microsoft Support** | Vendor Support | Product adoption, issue resolution | Feature requests, bug reports | Low | +| **Auditors** | Compliance Verification | Evidence collection, control validation | Audit trails, documentation | Low | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Business Capabilities + +### Capability Model + +```mermaid +--- +title: Developer Platform Capabilities +--- +flowchart TB + %% ===== ENVIRONMENT MANAGEMENT ===== + subgraph L1["Developer Platform Capabilities"] + subgraph L2A["Environment Management"] + C1["๐Ÿ–ฅ๏ธ Dev Box Provisioning"] + C2["โš™๏ธ Environment Configuration"] + C3["๐Ÿ“ฆ Image Management"] + C4["๐ŸŠ Pool Management"] + end + + %% ===== SECURITY & GOVERNANCE ===== + subgraph L2B["Security & Governance"] + C5["๐Ÿ” Identity Management"] + C6["๐Ÿ›ก๏ธ Access Control"] + C7["๐Ÿ”‘ Secrets Management"] + C8["๐Ÿ“‹ Compliance Enforcement"] + end + + %% ===== OPERATIONS & MONITORING ===== + subgraph L2C["Operations & Monitoring"] + C9["๐Ÿ“Š Resource Monitoring"] + C10["๐Ÿ’ฐ Cost Management"] + C11["๐Ÿ“ Diagnostics & Logging"] + C12["๐Ÿ”” Alerting"] + end + + %% ===== NETWORK & CONNECTIVITY ===== + subgraph L2D["Network & Connectivity"] + C13["๐ŸŒ Network Provisioning"] + C14["๐Ÿ”’ Network Security"] + C15["๐Ÿ”— Hybrid Connectivity"] + end + end + + %% ===== STYLES ===== + 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 datastore fill:#F59E0B,stroke:#D97706,color:#000000 + + class C1,C2,C3,C4 datastore + class C5,C6,C7,C8 failed + class C9,C10,C11,C12 secondary + class C13,C14,C15 primary + + style L2A fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style L2B fill:#FEE2E2,stroke:#F44336,stroke-width:2px + style L2C fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style L2D fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px +``` + +### Capability to Landing Zone Mapping + +| Capability Domain | Landing Zone | Key Resources | Business Value | +|-------------------|--------------|---------------|----------------| +| **Environment Management** | Workload | DevCenter, Projects, Pools | Self-service developer provisioning | +| **Security & Governance** | Security | Key Vault, RBAC Assignments | Protection of sensitive data and access | +| **Operations & Monitoring** | Monitoring | Log Analytics, Diagnostics | Visibility and operational insights | +| **Network & Connectivity** | Connectivity | VNet, Subnets, NSGs | Secure network isolation | + +### Capability Details + +#### Environment Management Capabilities + +| Capability | Description | Maturity Target | +|------------|-------------|-----------------| +| **Dev Box Provisioning** | Automated creation of developer workstations from curated images | Automated | +| **Environment Configuration** | DSC-based configuration of development tools and settings | Declarative | +| **Image Management** | Centralized catalog of approved VM images with versioning | Governed | +| **Pool Management** | Role-based pool configurations with appropriate sizing | Optimized | + +#### Security & Governance Capabilities + +| Capability | Description | Maturity Target | +|------------|-------------|-----------------| +| **Identity Management** | SystemAssigned managed identities for all workloads | Zero-Trust | +| **Access Control** | Fine-grained RBAC at subscription, RG, and resource levels | Least Privilege | +| **Secrets Management** | Centralized secrets with rotation and audit | Automated | +| **Compliance Enforcement** | Policy-driven compliance with tagging and configuration | Continuous | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”„ Value Streams + +### Primary Value Stream: Developer Onboarding + +```mermaid +--- +title: Developer Onboarding Value Stream +--- +flowchart LR + %% ===== TRIGGER ===== + subgraph Trigger["๐ŸŽฏ Trigger"] + T1["๐Ÿ‘ค New Developer Joins"] + end + + %% ===== REQUEST PHASE ===== + subgraph Request["๐Ÿ“ Request Phase"] + R1["๐Ÿ“‹ Request Dev Box Access"] + R2["๐Ÿ“ Assign to Project"] + R3["๐ŸŠ Select Dev Box Pool"] + end + + %% ===== PROVISIONING PHASE ===== + subgraph Provision["โš™๏ธ Provisioning Phase"] + P1["๐Ÿ–ฅ๏ธ Create Dev Box Instance"] + P2["๐Ÿ”ง Apply DSC Configuration"] + P3["๐Ÿ“‚ Clone Repositories"] + end + + %% ===== VALIDATION PHASE ===== + subgraph Validate["โœ… Validation Phase"] + V1["๐Ÿ” Verify Tools Installed"] + V2["๐ŸŒ Test Connectivity"] + V3["๐Ÿ” Confirm Access"] + end + + %% ===== OUTCOME ===== + subgraph Outcome["๐Ÿ† Outcome"] + O1["๐Ÿš€ Developer Productive"] + end + + %% ===== CONNECTIONS ===== + T1 -->|initiates| R1 + R1 -->|approves| R2 + R2 -->|selects| R3 + R3 -->|triggers| P1 + P1 -->|configures| P2 + P2 -->|clones| P3 + P3 -->|verifies| V1 + V1 -->|tests| V2 + V2 -->|confirms| V3 + V3 -->|enables| O1 + + %% ===== STYLES ===== + classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + + class T1 trigger + class R1,R2,R3 primary + class P1,P2,P3 datastore + class V1,V2,V3,O1 secondary + + style Trigger fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style Request fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style Provision fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style Validate fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Outcome fill:#ECFDF5,stroke:#10B981,stroke-width:2px +``` + +### Value Stream Metrics + +| Stage | Target Duration | Key Metric | +|-------|-----------------|------------| +| **Request Phase** | < 15 minutes | Time to request approval | +| **Provisioning Phase** | < 60 minutes | Dev Box creation time | +| **Validation Phase** | < 30 minutes | First successful build | +| **End-to-End** | < 4 hours | Time to first commit | + +### Secondary Value Stream: Environment Lifecycle + +```mermaid +--- +title: Environment Lifecycle States +--- +stateDiagram-v2 + [*] --> Requested: Developer Request + Requested --> Provisioning: Auto-Approved + Requested --> PendingApproval: Manual Review + PendingApproval --> Provisioning: Approved + PendingApproval --> Rejected: Denied + Provisioning --> Active: Ready + Active --> Stopped: User Action + Stopped --> Active: User Action + Active --> Decommissioning: Project End + Stopped --> Decommissioning: Inactivity + Decommissioning --> [*]: Deleted + Rejected --> [*] +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Business Requirements + +### Functional Requirements + +| ID | Requirement | Priority | Source | +|----|-------------|----------|--------| +| **FR-001** | System shall provision Dev Box instances within 60 minutes | High | Developer Experience | +| **FR-002** | System shall support multiple projects with isolated configurations | High | Multi-tenancy | +| **FR-003** | System shall integrate with GitHub and Azure DevOps for catalog sync | High | DevOps Integration | +| **FR-004** | System shall support role-based VM SKU selection per pool | Medium | Cost Optimization | +| **FR-005** | System shall automatically configure development tools via DSC | Medium | Standardization | +| **FR-006** | System shall provide self-service portal access for developers | Medium | Developer Experience | +| **FR-007** | System shall support custom image definitions from Git catalogs | Low | Extensibility | + +### Non-Functional Requirements + +| ID | Requirement | Priority | Target | +|----|-------------|----------|--------| +| **NFR-001** | System shall achieve 99.9% availability for DevCenter services | High | SLA | +| **NFR-002** | System shall encrypt all secrets at rest and in transit | High | Security | +| **NFR-003** | System shall support 1000+ concurrent Dev Box instances | Medium | Scalability | +| **NFR-004** | System shall retain audit logs for 90 days minimum | Medium | Compliance | +| **NFR-005** | System shall complete deployments within 30 minutes | Medium | Performance | +| **NFR-006** | System shall support deployment across multiple Azure regions | Low | Availability | + +### Compliance Requirements + +| Requirement | Framework | Implementation | +|-------------|-----------|----------------| +| Access Control | SOC2 CC6.1 | RBAC with least privilege | +| Encryption | SOC2 CC6.7 | Key Vault with TLS 1.2+ | +| Audit Logging | SOC2 CC7.2 | Log Analytics with retention | +| Change Management | ISO 27001 A.12.1.2 | GitOps with approval workflows | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“Š Success Metrics + +### Key Performance Indicators (KPIs) + +```mermaid +--- +title: Key Performance Indicators Dashboard +--- +flowchart TB + %% ===== DEVELOPER PRODUCTIVITY KPIs ===== + subgraph Developer["Developer Productivity"] + KPI1["โฑ๏ธ Time to First Commit"] + KPI2["๐Ÿš€ Environment Setup Time"] + KPI3["โœ… Self-Service Success Rate"] + end + + %% ===== OPERATIONAL EFFICIENCY KPIs ===== + subgraph Operations["Operational Efficiency"] + KPI4["๐Ÿ“ˆ Deployment Success Rate"] + KPI5["โšก Mean Time to Provision"] + KPI6["๐Ÿ“Š Configuration Drift %"] + end + + %% ===== SECURITY POSTURE KPIs ===== + subgraph Security["Security Posture"] + KPI7["๐Ÿ›ก๏ธ Compliance Score"] + KPI8["๐Ÿ”‘ Secret Rotation Rate"] + KPI9["๐Ÿ‘๏ธ Access Review Completion"] + end + + %% ===== COST MANAGEMENT KPIs ===== + subgraph Cost["Cost Management"] + KPI10["๐Ÿ’ฐ Cost per Developer"] + KPI11["๐Ÿ“Š Resource Utilization"] + KPI12["๐Ÿ“‹ Budget Variance"] + end + + %% ===== STYLES ===== + 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 datastore fill:#F59E0B,stroke:#D97706,color:#000000 + + class KPI1,KPI2,KPI3 secondary + class KPI4,KPI5,KPI6 datastore + class KPI7,KPI8,KPI9 failed + class KPI10,KPI11,KPI12 primary + + %% ===== SUBGRAPH STYLES ===== + style Developer fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Operations fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style Security fill:#FEE2E2,stroke:#F44336,stroke-width:2px + style Cost fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px +``` + +### KPI Targets + +| Category | KPI | Baseline | Target | Measurement | +|----------|-----|----------|--------|-------------| +| **Developer Productivity** | Time to First Commit | 2 days | < 4 hours | Azure DevCenter Metrics | +| **Developer Productivity** | Environment Setup Time | 4 hours | < 60 mins | Provisioning Logs | +| **Developer Productivity** | Self-Service Success Rate | N/A | > 95% | Support Tickets | +| **Operational Efficiency** | Deployment Success Rate | N/A | > 99% | Pipeline Metrics | +| **Operational Efficiency** | Mean Time to Provision | N/A | < 45 mins | DevCenter Telemetry | +| **Operational Efficiency** | Configuration Drift | N/A | < 5% | Compliance Scans | +| **Security Posture** | Compliance Score | N/A | > 90% | Azure Policy | +| **Security Posture** | Secret Rotation Rate | Manual | Automated | Key Vault Metrics | +| **Cost Management** | Cost per Developer | Variable | Predictable | Cost Management APIs | +| **Cost Management** | Resource Utilization | N/A | > 70% | Azure Monitor | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“– Glossary + +| Term | Definition | +|------|------------| +| **Dev Box** | Cloud-hosted developer workstation managed by Microsoft Dev Box service | +| **DevCenter** | Azure resource that serves as the administrative hub for Dev Box and Deployment Environments | +| **Landing Zone** | Pre-configured Azure environment that provides governance, security, and compliance foundations | +| **Pool** | Collection of Dev Boxes with identical configuration (image, VM SKU, network) | +| **Catalog** | Git repository containing Dev Box image definitions or environment templates | +| **DSC** | Desired State Configuration - declarative configuration management for Windows | +| **RBAC** | Role-Based Access Control - Azure authorization mechanism | +| **IaC** | Infrastructure as Code - managing infrastructure through version-controlled definitions | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— References + +### ๐ŸŒ External References + +- [Microsoft Dev Box Documentation](https://learn.microsoft.com/en-us/azure/dev-box/) +- [Azure Landing Zones](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/landing-zone/) +- [TOGAF Standard](https://pubs.opengroup.org/togaf-standard/) +- [Azure Well-Architected Framework](https://learn.microsoft.com/en-us/azure/well-architected/) + +### ๐Ÿ“š Related Documents + +- [Data Architecture](02-data-architecture.md) +- [Application Architecture](03-application-architecture.md) +- [Technology Architecture](04-technology-architecture.md) +- [Security Architecture](05-security-architecture.md) + +--- + +
+ +[โฌ†๏ธ Back to Top](#-table-of-contents) | [Data Architecture โ†’](02-data-architecture.md) + +*DevExp-DevBox Landing Zone Accelerator โ€ข Business Architecture* + +
diff --git a/docs/architecture/02-data-architecture.md b/docs/architecture/02-data-architecture.md new file mode 100644 index 00000000..bf46f76d --- /dev/null +++ b/docs/architecture/02-data-architecture.md @@ -0,0 +1,866 @@ +--- +title: "Data Architecture" +description: "Data architecture defining configuration, secrets, telemetry, and state management for DevExp-DevBox" +author: "DevExp Team" +date: 2026-01-23 +version: "1.0.0" +tags: + - architecture + - data + - togaf + - configuration + - secrets +--- + +# ๐Ÿ—„๏ธ 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) | + +
+ +| Property | Value | +|:---------|:------| +| **Version** | 1.0.0 | +| **Last Updated** | 2026-01-23 | +| **Author** | DevExp Team | +| **Status** | Published | + +--- + +## ๐Ÿ“‘ 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) +- [๐Ÿ“– Glossary](#glossary) +- [๐Ÿ”— References](#references) + +--- + +## ๐Ÿ“Š Data Overview + +The DevExp-DevBox accelerator manages four primary categories of data, each with distinct lifecycle, sensitivity, and storage requirements. + +### Data Categories + +```mermaid +--- +title: Data Categories Overview +--- +flowchart TB + %% ===== DATA CATEGORIES ===== + subgraph DataCategories["๐Ÿ“Š Data Categories"] + %% ===== CONFIGURATION DATA ===== + subgraph Config["โš™๏ธ Configuration Data"] + C1["๐Ÿ“ Resource Organization"] + C2["๐Ÿ”’ Security Settings"] + C3["๐Ÿ“ฆ Workload Definitions"] + end + + %% ===== SECRETS & CREDENTIALS ===== + subgraph Secrets["๐Ÿ” Secrets & Credentials"] + S1["๐Ÿ”‘ GitHub PAT Tokens"] + S2["๐ŸŽซ Azure DevOps PATs"] + S3["๐Ÿ‘ค Service Principal Credentials"] + end + + %% ===== TELEMETRY & DIAGNOSTICS ===== + subgraph Telemetry["๐Ÿ“ถ Telemetry & Diagnostics"] + T1["๐Ÿ“ Resource Logs"] + T2["๐Ÿ“Š Metrics"] + T3["๐Ÿ“‹ Activity Logs"] + end + + %% ===== DEPLOYMENT STATE ===== + subgraph State["๐Ÿ’พ Deployment State"] + ST1["๐ŸŒ azd Environment"] + ST2["๐Ÿ“„ Bicep Outputs"] + ST3["๐Ÿ†” Resource IDs"] + end + end + + %% ===== STYLES ===== + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef failed fill:#F44336,stroke:#C62828,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + + class C1,C2,C3 primary + class S1,S2,S3 failed + class T1,T2,T3 secondary + class ST1,ST2,ST3 datastore + + style Config fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style Secrets fill:#FEE2E2,stroke:#F44336,stroke-width:2px + style Telemetry fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style State fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px +``` + +### Data Classification Matrix + +| Data Type | Classification | Storage Location | Encryption | Retention | +|-----------|---------------|------------------|------------|-----------| +| Resource Organization Config | Internal | Git Repository | At Rest (Git) | Indefinite | +| Security Settings | Internal | Git Repository | At Rest (Git) | Indefinite | +| Workload Definitions | Internal | Git Repository | At Rest (Git) | Indefinite | +| GitHub PAT Tokens | Confidential | Azure Key Vault | AES-256 | Until Rotation | +| Azure DevOps PATs | Confidential | Azure Key Vault | AES-256 | Until Rotation | +| Service Principal Secrets | Confidential | GitHub Secrets | Encrypted | 1 Year | +| Resource Logs | Internal | Log Analytics | At Rest | 90 Days | +| Metrics Data | Internal | Azure Monitor | At Rest | 93 Days | +| Activity Logs | Internal | Log Analytics | At Rest | 90 Days | +| azd Environment State | Internal | Local `.azure/` | None | Session | +| Bicep Outputs | Internal | Azure/Pipeline | At Rest | Deployment | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Configuration Data Model + +The accelerator uses YAML-based configuration files with JSON Schema validation. All configuration is loaded at deployment time using Bicep's `loadYamlContent()` function. + +### Entity Relationship Diagram + +```mermaid +--- +title: Configuration Data Entity Relationships +--- +erDiagram + LANDING_ZONES ||--o{ RESOURCE_GROUP : contains + LANDING_ZONES { + string name + boolean create + string description + object tags + } + + RESOURCE_GROUP ||--o{ AZURE_RESOURCE : hosts + RESOURCE_GROUP { + string name + string location + object tags + } + + DEVCENTER ||--o{ PROJECT : contains + DEVCENTER ||--o{ CATALOG : syncs + DEVCENTER ||--o{ ENVIRONMENT_TYPE : defines + DEVCENTER { + string name + object identity + string catalogItemSyncEnableStatus + string microsoftHostedNetworkEnableStatus + object tags + } + + PROJECT ||--o{ POOL : contains + PROJECT ||--o{ PROJECT_CATALOG : syncs + PROJECT ||--o{ PROJECT_ENV_TYPE : enables + PROJECT { + string name + string description + object identity + object network + object tags + } + + CATALOG { + string name + string type + string visibility + string uri + string branch + string path + } + + POOL { + string name + string imageDefinitionName + string vmSku + } + + KEY_VAULT ||--o{ SECRET : stores + KEY_VAULT { + string name + boolean enablePurgeProtection + boolean enableSoftDelete + int softDeleteRetentionInDays + boolean enableRbacAuthorization + } + + SECRET { + string name + string value + datetime expires + } +``` + +### Configuration File Structure + +``` +infra/settings/ +โ”œโ”€โ”€ resourceOrganization/ +โ”‚ โ”œโ”€โ”€ azureResources.yaml # Landing zone definitions +โ”‚ โ””โ”€โ”€ azureResources.schema.json +โ”œโ”€โ”€ security/ +โ”‚ โ”œโ”€โ”€ security.yaml # Key Vault configuration +โ”‚ โ””โ”€โ”€ security.schema.json +โ””โ”€โ”€ workload/ + โ”œโ”€โ”€ devcenter.yaml # DevCenter & projects + โ””โ”€โ”€ devcenter.schema.json +``` + +### azureResources.yaml Schema + +Defines the landing zone resource group organization following Azure Cloud Adoption Framework principles. + +```yaml +# Schema: azureResources.schema.json +workload: + create: true # Create new or use existing + name: devexp-workload # Base name (suffix added) + description: prodExp + tags: + environment: dev + division: Platforms + team: DevExP + project: Contoso-DevExp-DevBox + costCenter: IT + owner: Contoso + landingZone: Workload + resources: ResourceGroup + +security: + create: true + name: devexp-security + # ... tags + +monitoring: + create: true + name: devexp-monitoring + # ... tags +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `create` | boolean | Yes | Whether to create new resource group | +| `name` | string | Yes | Base name for resource group | +| `description` | string | No | Purpose description | +| `tags` | object | Yes | Resource tags for governance | + +### security.yaml Schema + +Defines Azure Key Vault configuration for secrets management. + +```yaml +# Schema: security.schema.json +create: true + +keyVault: + name: contoso # Globally unique (suffix added) + description: Development Environment Key Vault + secretName: gha-token # Name for GitHub token + + # Security settings + enablePurgeProtection: true + enableSoftDelete: true + softDeleteRetentionInDays: 7 + enableRbacAuthorization: true + + tags: + environment: dev + landingZone: security + # ... additional tags +``` + +| Field | Type | Required | Default | Description | +|-------|------|----------|---------|-------------| +| `create` | boolean | Yes | - | Create new Key Vault | +| `keyVault.name` | string | Yes | - | Base name for Key Vault | +| `keyVault.secretName` | string | Yes | - | Name for PAT secret | +| `keyVault.enablePurgeProtection` | boolean | No | true | Prevent permanent deletion | +| `keyVault.enableSoftDelete` | boolean | No | true | Enable soft delete | +| `keyVault.softDeleteRetentionInDays` | integer | No | 7 | Retention period (7-90) | +| `keyVault.enableRbacAuthorization` | boolean | No | true | Use RBAC for access | + +### devcenter.yaml Schema + +Comprehensive DevCenter configuration including projects, pools, catalogs, and RBAC. + +```yaml +# Schema: devcenter.schema.json +name: "devexp-devcenter" +catalogItemSyncEnableStatus: "Enabled" +microsoftHostedNetworkEnableStatus: "Enabled" +installAzureMonitorAgentEnableStatus: "Enabled" + +identity: + type: "SystemAssigned" + roleAssignments: + devCenter: + - id: "b24988ac-6180-42a0-ab88-20f7382dd24c" + name: "Contributor" + scope: "Subscription" + # ... additional roles + orgRoleTypes: + - type: DevManager + azureADGroupId: "" + azureADGroupName: "Platform Engineering Team" + azureRBACRoles: + - name: "DevCenter Project Admin" + id: "331c37c6-af14-46d9-b9f4-e1909e1b95a0" + scope: ResourceGroup + +catalogs: + - name: "customTasks" + type: gitHub + visibility: public + uri: "https://github.com/microsoft/devcenter-catalog.git" + branch: "main" + path: "./Tasks" + +environmentTypes: + - name: "dev" + - name: "staging" + - name: "UAT" + +projects: + - name: "eShop" + description: "eShop project." + network: + name: eShop + create: true + virtualNetworkType: Managed + addressPrefixes: ["10.0.0.0/16"] + subnets: + - name: eShop-subnet + properties: + addressPrefix: 10.0.1.0/24 + identity: + type: SystemAssigned + roleAssignments: + - azureADGroupId: "" + azureADGroupName: "eShop Developers" + azureRBACRoles: + - name: "Dev Box User" + id: "45d50f46-0b78-4001-a660-4198cbe8cd05" + scope: Project + 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/Evilazaro/eShop.git" + branch: "main" + path: "/.devcenter/environments" +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ” Secrets Management + +### Secret Types and Lifecycle + +```mermaid +--- +title: Secret Types and Lifecycle +--- +flowchart TB + %% ===== SECRET SOURCES ===== + subgraph Sources["๐Ÿ”‘ Secret Sources"] + GH["๐Ÿ™ GitHub CLI
(gh auth token)"] + ADO["๐Ÿ”ท Azure DevOps CLI
Manual Entry"] + SP["๐Ÿ‘ค Service Principal
(az ad sp create-for-rbac)"] + end + + %% ===== SECRET STORAGE ===== + subgraph Storage["๐Ÿ” Secret Storage"] + KV["๐Ÿ›๏ธ Azure Key Vault
(gha-token secret)"] + GHS["๐Ÿ“ฆ GitHub Secrets
(AZURE_CREDENTIALS)"] + ENV["๐Ÿ“„ azd Environment
(.azure/.env)"] + end + + %% ===== SECRET CONSUMERS ===== + subgraph Consumers["โšก Secret Consumers"] + CAT["๐Ÿ“š DevCenter Catalogs
(Private Repos)"] + WF["๐Ÿ”„ GitHub Actions
(OIDC Auth)"] + DEP["๐Ÿš€ azd Provision
(Key Vault)"] + end + + %% ===== CONNECTIONS ===== + GH -->|extracts| ENV + ENV -->|stores| KV + ADO -->|provides| ENV + SP -->|configures| GHS + + KV -->|authenticates| CAT + GHS -->|authorizes| WF + KV -->|provisions| DEP + + %% ===== STYLES ===== + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + classDef failed fill:#F44336,stroke:#C62828,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + + class GH,ADO,SP datastore + class KV,GHS,ENV failed + class CAT,WF,DEP secondary + + style Sources fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style Storage fill:#FEE2E2,stroke:#F44336,stroke-width:2px + style Consumers fill:#ECFDF5,stroke:#10B981,stroke-width:2px +``` + +### Secret Inventory + +| Secret Name | Type | Storage | Consumer | Rotation Policy | +|-------------|------|---------|----------|-----------------| +| `gha-token` | GitHub PAT | Key Vault | DevCenter Catalogs | 90 days | +| `KEY_VAULT_SECRET` | GitHub/ADO PAT | azd Environment | Deployment | Manual | +| `AZURE_CREDENTIALS` | Service Principal JSON | GitHub Secrets | GitHub Actions | 365 days | +| `AZURE_CLIENT_ID` | OIDC Client ID | GitHub Variables | GitHub Actions | N/A (Federated) | +| `AZURE_TENANT_ID` | Tenant ID | GitHub Variables | GitHub Actions | N/A | +| `AZURE_SUBSCRIPTION_ID` | Subscription ID | GitHub Variables | GitHub Actions | N/A | + +### Key Vault Access Pattern + +```mermaid +--- +title: Key Vault Access Pattern +--- +sequenceDiagram + participant DC as ๐Ÿข DevCenter + participant MI as ๐Ÿ” Managed Identity + participant KV as ๐Ÿ›๏ธ Key Vault + participant CAT as ๐Ÿ“š Catalog (GitHub) + + DC->>MI: Request token (SystemAssigned) + MI-->>DC: Access token + DC->>KV: Get secret (secretIdentifier) + Note over DC,KV: RBAC: Key Vault Secrets User + KV-->>DC: PAT Token value + DC->>CAT: Clone repository (PAT auth) + CAT-->>DC: Repository content +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ถ Telemetry & Diagnostics + +### Log Analytics Data Collection + +All resources send diagnostic data to a centralized Log Analytics workspace for unified monitoring and analysis. + +```mermaid +--- +title: Log Analytics Data Collection +--- +flowchart LR + %% ===== AZURE RESOURCES ===== + subgraph Resources["๐Ÿข Azure Resources"] + DC["๐Ÿ–ฅ๏ธ DevCenter"] + KV["๐Ÿ” Key Vault"] + VN["๐ŸŒ Virtual Network"] + LA["๐Ÿ“Š Log Analytics"] + end + + %% ===== LOG ANALYTICS WORKSPACE ===== + subgraph LAW["๐Ÿ“ˆ Log Analytics Workspace"] + LOGS["๐Ÿ“ Diagnostic Logs"] + MET["๐Ÿ“Š Metrics"] + ACT["๐Ÿ“‹ Activity Logs"] + end + + %% ===== SOLUTIONS ===== + subgraph Solutions["๐Ÿ”ง Solutions"] + AA["โ˜๏ธ AzureActivity"] + end + + %% ===== CONNECTIONS ===== + DC -->|sends logs| LOGS + KV -->|sends logs| LOGS + VN -->|sends logs| LOGS + LA -->|sends logs| LOGS + + DC -->|exports metrics| MET + KV -->|exports metrics| MET + VN -->|exports metrics| MET + + LOGS -->|feeds| AA + ACT -->|feeds| AA + + %% ===== STYLES ===== + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + + class DC,KV,VN,LA primary + class LOGS,MET,ACT secondary + class AA datastore + + style Resources fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style LAW fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Solutions fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px +``` + +### Diagnostic Settings Configuration + +Each resource type has diagnostic settings configured in its Bicep module: + +```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: logAnalyticsId + } +} +``` + +### Telemetry Data Retention + +| Data Type | Retention Period | Cost Tier | +|-----------|------------------|-----------| +| Logs (allLogs) | 90 days | PerGB2018 | +| Metrics (AllMetrics) | 93 days | Included | +| Activity Logs | 90 days | Free (first 5GB) | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”„ Data Flow Diagrams + +### Configuration Loading Flow + +```mermaid +--- +title: Configuration Loading Flow +--- +flowchart TB + %% ===== SOURCE LAYER ===== + subgraph Source["๐Ÿ“ Git Repository"] + Y1["๐Ÿ“„ azureResources.yaml"] + Y2["๐Ÿ” security.yaml"] + Y3["๐Ÿ–ฅ๏ธ devcenter.yaml"] + end + + %% ===== BICEP COMPILATION LAYER ===== + subgraph Bicep["โš™๏ธ Bicep Compilation"] + LOAD["๐Ÿ”„ loadYamlContent()"] + MAIN["๐Ÿ“„ main.bicep"] + SEC["๐Ÿ” security.bicep"] + WL["๐Ÿ“ฆ workload.bicep"] + end + + %% ===== DEPLOYMENT LAYER ===== + subgraph Deploy["๐Ÿš€ Deployment"] + ARM["๐Ÿ“‹ ARM Template"] + AZ["โ˜๏ธ Azure Resource Manager"] + end + + %% ===== RESOURCES LAYER ===== + subgraph Resources["๐Ÿข Azure Resources"] + RG["๐Ÿ“ Resource Groups"] + KVRES["๐Ÿ”‘ Key Vault"] + DCRES["๐Ÿ–ฅ๏ธ DevCenter"] + end + + %% ===== CONNECTIONS ===== + Y1 -->|loads| LOAD + Y2 -->|loads| LOAD + Y3 -->|loads| LOAD + + LOAD -->|configures| MAIN + MAIN -->|invokes| SEC + MAIN -->|invokes| WL + + SEC -->|compiles| ARM + WL -->|compiles| ARM + + ARM -->|deploys| AZ + AZ -->|creates| RG + AZ -->|creates| KVRES + AZ -->|creates| DCRES + + %% ===== STYLES ===== + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + + class Y1,Y2,Y3 datastore + class LOAD,MAIN,SEC,WL primary + class ARM,AZ trigger + class RG,KVRES,DCRES secondary + + %% ===== SUBGRAPH STYLES ===== + style Source fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style Bicep fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style Deploy fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style Resources fill:#ECFDF5,stroke:#10B981,stroke-width:2px +``` + +### Secrets Flow Diagram + +```mermaid +--- +title: Secrets Flow Diagram +--- +flowchart TB + %% ===== SETUP PHASE ===== + subgraph Setup["๐Ÿ”ง Setup Phase"] + CLI["๐Ÿ”‘ gh auth token
OR
Manual PAT Entry"] + PS["๐Ÿ“œ setUp.ps1 / setUp.sh"] + end + + %% ===== AZD ENVIRONMENT ===== + subgraph AZD["๐ŸŒ azd Environment"] + ENV["๐Ÿ“„ .azure/{env}/.env
KEY_VAULT_SECRET='...'"] + end + + %% ===== DEPLOYMENT ===== + subgraph Deploy["๐Ÿš€ Deployment"] + PARAMS["๐Ÿ“‹ main.parameters.json
${KEY_VAULT_SECRET}"] + BICEP["โš™๏ธ security.bicep"] + end + + %% ===== AZURE RESOURCES ===== + subgraph Azure["โ˜๏ธ Azure Resources"] + KV["๐Ÿ›๏ธ Key Vault
gha-token secret"] + DC["๐Ÿ–ฅ๏ธ DevCenter
secretIdentifier reference"] + end + + %% ===== RUNTIME ACCESS ===== + subgraph Access["๐Ÿ”“ Runtime Access"] + CAT["๐Ÿ“š Private Catalog
(GitHub/ADO)"] + end + + %% ===== CONNECTIONS ===== + CLI -->|executes| PS + PS -->|configures| ENV + ENV -->|injects| PARAMS + PARAMS -->|deploys| BICEP + BICEP -->|creates| KV + KV -->|references| DC + DC -->|authenticates| CAT + + %% ===== STYLES ===== + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + 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 failed fill:#F44336,stroke:#C62828,color:#FFFFFF + + class CLI,PS datastore + class ENV trigger + class PARAMS,BICEP primary + class KV,DC secondary + class CAT failed + + style Setup fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style AZD fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style Deploy fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style Azure fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Access fill:#FEE2E2,stroke:#F44336,stroke-width:2px +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ›ก๏ธ Data Governance + +### Data Ownership + +| Data Category | Owner | Steward | Access Control | +|---------------|-------|---------|----------------| +| Configuration (YAML) | Platform Engineering | DevOps Team | Git CODEOWNERS | +| Secrets | Security Team | Platform Engineering | Key Vault RBAC | +| Telemetry | Operations | SRE Team | Log Analytics RBAC | +| Deployment State | DevOps | Pipeline Service | Pipeline Variables | + +### Tagging Standards + +All resources must include the following tags for governance: + +| Tag Key | Required | Purpose | Example Values | +|---------|----------|---------|----------------| +| `environment` | Yes | Deployment stage | dev, staging, prod | +| `division` | Yes | Business unit | Platforms, Engineering | +| `team` | Yes | Owning team | DevExP, SRE | +| `project` | Yes | Project name | Contoso-DevExp-DevBox | +| `costCenter` | Yes | Cost allocation | IT, R&D | +| `owner` | Yes | Resource owner | Contoso | +| `landingZone` | Yes | Landing zone type | Workload, Security, Monitoring | +| `resources` | Yes | Resource category | ResourceGroup, DevCenter | + +### Data Quality Rules + +| Rule | Application | Validation | +|------|-------------|------------| +| Schema Validation | YAML configs | JSON Schema (`*.schema.json`) | +| Required Fields | All configs | Bicep parameter validation | +| Name Uniqueness | Key Vault, DevCenter | `uniqueString()` suffix | +| Tag Completeness | All resources | Bicep `union()` with defaults | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Schema Documentation + +### JSON Schema Files + +The repository includes JSON Schema definitions for all YAML configuration files: + +#### azureResources.schema.json + +Location: `infra/settings/resourceOrganization/azureResources.schema.json` + +```json +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "properties": { + "workload": { "$ref": "#/definitions/landingZone" }, + "security": { "$ref": "#/definitions/landingZone" }, + "monitoring": { "$ref": "#/definitions/landingZone" } + }, + "definitions": { + "landingZone": { + "type": "object", + "required": ["create", "name", "tags"], + "properties": { + "create": { "type": "boolean" }, + "name": { "type": "string" }, + "description": { "type": "string" }, + "tags": { "$ref": "#/definitions/tags" } + } + } + } +} +``` + +#### security.schema.json + +Location: `infra/settings/security/security.schema.json` + +Validates Key Vault configuration including security settings and retention policies. + +#### devcenter.schema.json + +Location: `infra/settings/workload/devcenter.schema.json` + +Comprehensive schema for DevCenter, projects, pools, catalogs, and RBAC configuration. + +### Schema Validation in IDE + +Configure VS Code to validate YAML files: + +```yaml +# yaml-language-server: $schema=./azureResources.schema.json +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“– Glossary + +| Term | Definition | +|------|------------| +| **Catalog** | Git repository containing Dev Box images or environment definitions | +| **DSC** | Desired State Configuration - declarative Windows configuration | +| **Environment Type** | Deployment target classification (dev, staging, UAT) | +| **Landing Zone** | Pre-configured resource group with governance policies | +| **loadYamlContent()** | Bicep function to parse YAML at compile time | +| **PAT** | Personal Access Token for Git authentication | +| **Pool** | Collection of Dev Boxes with identical configuration | +| **Schema** | JSON Schema definition for configuration validation | +| **Secret Identifier** | Key Vault URI pointing to specific secret version | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— References + +### ๐Ÿ“š Internal References + +- [Business Architecture](01-business-architecture.md) +- [Application Architecture](03-application-architecture.md) +- [Technology Architecture](04-technology-architecture.md) +- [Security Architecture](05-security-architecture.md) + +### ๐ŸŒ External References + +- [Azure Key Vault Documentation](https://learn.microsoft.com/en-us/azure/key-vault/) +- [Log Analytics Documentation](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/log-analytics-overview) +- [Bicep loadYamlContent](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/bicep-functions-files#loadyamlcontent) +- [JSON Schema Specification](https://json-schema.org/specification.html) + +--- + +
+ +[โ† Business Architecture](01-business-architecture.md) | [โฌ†๏ธ Back to Top](#-table-of-contents) | [Application Architecture โ†’](03-application-architecture.md) + +*DevExp-DevBox Landing Zone Accelerator โ€ข Data Architecture* + +
diff --git a/docs/architecture/03-application-architecture.md b/docs/architecture/03-application-architecture.md new file mode 100644 index 00000000..381938f1 --- /dev/null +++ b/docs/architecture/03-application-architecture.md @@ -0,0 +1,941 @@ +--- +title: "Application Architecture" +description: "Bicep module architecture, dependencies, and deployment orchestration for DevExp-DevBox" +author: "DevExp Team" +date: 2026-01-23 +version: "1.0.0" +tags: + - architecture + - application + - togaf + - bicep + - modules +--- + +# ๐Ÿ“ฆ Application Architecture + +> **DevExp-DevBox Landing Zone Accelerator** + +> [!NOTE] +> **Target Audience:** Platform Engineers, DevOps Engineers, IaC Developers +> **Reading Time:** ~25 minutes + +
+๐Ÿ“ Navigation + +| Previous | Index | Next | +|:---------|:-----:|-----:| +| [โ† Data Architecture](02-data-architecture.md) | [Architecture Index](../README.md) | [Technology Architecture โ†’](04-technology-architecture.md) | + +
+ +| Property | Value | +|:---------|:------| +| **Version** | 1.0.0 | +| **Last Updated** | 2026-01-23 | +| **Author** | DevExp Team | +| **Status** | Published | + +--- + +## ๐Ÿ“‘ Table of Contents + +- [๐Ÿ“Š Application Overview](#application-overview) +- [๐Ÿ“‹ Bicep Module Catalog](#bicep-module-catalog) +- [๐Ÿ”— Module Dependency Graph](#module-dependency-graph) +- [๐Ÿ“œ Interface Contracts](#interface-contracts) +- [๐Ÿš€ Deployment Orchestration](#deployment-orchestration) +- [๐Ÿ”ง Component Details](#component-details) +- [๐Ÿ”„ Integration Patterns](#integration-patterns) +- [๐Ÿ”Œ Extension Points](#extension-points) +- [๐Ÿ“š References](#references) + +--- + +## ๐Ÿ“Š Application Overview + +The DevExp-DevBox accelerator is an Infrastructure as Code (IaC) application built using Azure Bicep. It follows a modular, hierarchical architecture with clear separation of concerns across landing zones. + +### Solution Architecture + +```mermaid +--- +title: Solution Architecture Overview +--- +flowchart TB + %% ===== ORCHESTRATION LAYER ===== + subgraph Orchestration["๐ŸŽฏ Orchestration Layer"] + MAIN["๐Ÿ“„ main.bicep
(Subscription Scope)"] + end + + %% ===== LANDING ZONE MODULES ===== + subgraph LandingZones["๐Ÿ—๏ธ Landing Zone Modules"] + SEC["๐Ÿ” security.bicep"] + MON["๐Ÿ“Š logAnalytics.bicep"] + WL["๐Ÿ“ฆ workload.bicep"] + CONN["๐ŸŒ connectivity.bicep"] + end + + %% ===== CORE RESOURCE MODULES ===== + subgraph CoreResources["โš™๏ธ Core Resource Modules"] + KV["๐Ÿ”‘ keyVault.bicep"] + LA["๐Ÿ“ˆ logAnalytics.bicep"] + DC["๐Ÿ–ฅ๏ธ devCenter.bicep"] + VN["๐Ÿ”— vnet.bicep"] + end + + %% ===== PROJECT MODULES ===== + subgraph ProjectResources["๐Ÿ“ Project Modules"] + PROJ["๐Ÿ“‹ project.bicep"] + POOL["๐ŸŠ projectPool.bicep"] + PCAT["๐Ÿ“š projectCatalog.bicep"] + PENV["๐ŸŒ projectEnvironmentType.bicep"] + end + + %% ===== IDENTITY MODULES ===== + subgraph Identity["๐Ÿ‘ค Identity Modules"] + DCRA["๐Ÿ” devCenterRoleAssignment.bicep"] + ORA["๐Ÿข orgRoleAssignment.bicep"] + PIRA["๐Ÿ‘ฅ projectIdentityRoleAssignment.bicep"] + KVA["๐Ÿ”‘ keyVaultAccess.bicep"] + end + + %% ===== CONNECTIONS ===== + MAIN -->|deploys| SEC + MAIN -->|deploys| MON + MAIN -->|deploys| WL + + SEC -->|creates| KV + MON -->|creates| LA + WL -->|creates| DC + WL -->|includes| CONN + + CONN -->|provisions| VN + DC -->|creates| PROJ + PROJ -->|deploys| POOL + PROJ -->|syncs| PCAT + PROJ -->|enables| PENV + + DC -->|assigns| DCRA + DC -->|assigns| ORA + PROJ -->|assigns| PIRA + SEC -->|grants| KVA + + %% ===== STYLES ===== + classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + + class MAIN trigger + class SEC,MON,WL,CONN primary + class KV,LA,DC,VN secondary + class PROJ,POOL,PCAT,PENV secondary + class DCRA,ORA,PIRA,KVA datastore + + style Orchestration fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style LandingZones fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style CoreResources fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style ProjectResources fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Identity fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px +``` + +### Module Statistics + +| Category | Module Count | Lines of Code | Description | +|----------|-------------|---------------|-------------| +| Orchestration | 1 | ~200 | main.bicep subscription orchestrator | +| Landing Zones | 3 | ~150 | Security, Monitoring, Workload | +| Connectivity | 4 | ~200 | VNet, Network Connection | +| Identity | 5 | ~300 | RBAC role assignments | +| Security | 3 | ~150 | Key Vault, Secrets | +| Workload | 8 | ~500 | DevCenter, Projects, Pools | +| **Total** | **24** | **~1500** | Full infrastructure coverage | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“‹ Bicep Module Catalog + +### Module Inventory + +| Module | Scope | Purpose | Dependencies | +|--------|-------|---------|--------------| +| `main.bicep` | Subscription | Orchestration | All modules | +| `security.bicep` | Resource Group | Key Vault deployment | keyVault.bicep, keyVaultAccess.bicep | +| `logAnalytics.bicep` | Resource Group | Log Analytics workspace | None | +| `workload.bicep` | Resource Group | DevCenter orchestration | devCenter.bicep, connectivity.bicep | +| `connectivity.bicep` | Resource Group | Network orchestration | vnet.bicep, networkConnection.bicep | +| `keyVault.bicep` | Resource | Key Vault creation | secret.bicep | +| `devCenter.bicep` | Resource | DevCenter & catalogs | catalog.bicep, environmentType.bicep | +| `project.bicep` | Resource | Project deployment | projectPool.bicep, projectCatalog.bicep | +| `vnet.bicep` | Resource | Virtual Network | None | + +### Module Classification + +```mermaid +--- +title: Bicep Module Classification +--- +mindmap + root((๐Ÿ“ฆ Bicep Modules)) + ๐ŸŽฏ Orchestration + main.bicep + ๐Ÿ—๏ธ Landing Zones + security.bicep + workload.bicep + ๐ŸŒ Infrastructure + connectivity.bicep + vnet.bicep + networkConnection.bicep + resourceGroup.bicep + โš™๏ธ Resources + keyVault.bicep + secret.bicep + logAnalytics.bicep + ๐Ÿ“ฆ Workload + devCenter.bicep + catalog.bicep + environmentType.bicep + ๐Ÿ“ Projects + project.bicep + projectPool.bicep + projectCatalog.bicep + projectEnvironmentType.bicep + ๐Ÿ‘ค Identity + devCenterRoleAssignment.bicep + devCenterRoleAssignmentRG.bicep + orgRoleAssignment.bicep + projectIdentityRoleAssignment.bicep + projectIdentityRoleAssignmentRG.bicep + keyVaultAccess.bicep +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Module Dependency Graph + +### Complete Dependency Tree + +```mermaid +--- +title: Complete Module Dependency Tree +--- +flowchart TB + %% ===== LAYER 0: ORCHESTRATION ===== + subgraph L0["๐ŸŽฏ Layer 0: Orchestration"] + MAIN["๐Ÿ“„ main.bicep
(targetScope: subscription)"] + end + + %% ===== LAYER 1: RESOURCE GROUPS ===== + subgraph L1["๐Ÿ“ Layer 1: Resource Groups"] + RG_SEC["๐Ÿ” Resource Group
(Security)"] + RG_MON["๐Ÿ“Š Resource Group
(Monitoring)"] + RG_WL["๐Ÿ“ฆ Resource Group
(Workload)"] + end + + %% ===== LAYER 2: LANDING ZONE MODULES ===== + subgraph L2["๐Ÿ—๏ธ Layer 2: Landing Zone Modules"] + SEC["๐Ÿ”’ security.bicep"] + LA["๐Ÿ“ˆ logAnalytics.bicep"] + WL["๐Ÿ“ฆ workload.bicep"] + end + + %% ===== LAYER 3: CORE RESOURCES ===== + subgraph L3["โš™๏ธ Layer 3: Core Resources"] + KV["๐Ÿ”‘ keyVault.bicep"] + LOG["๐Ÿ“Š Log Analytics
Workspace"] + DC["๐Ÿ–ฅ๏ธ devCenter.bicep"] + CONN["๐ŸŒ connectivity.bicep"] + end + + %% ===== LAYER 4: CHILD RESOURCES ===== + subgraph L4["๐Ÿ“ฆ Layer 4: Child Resources"] + SECRET["๐Ÿ” secret.bicep"] + CAT["๐Ÿ“š catalog.bicep"] + ENV["๐ŸŒ environmentType.bicep"] + VN["๐Ÿ”— vnet.bicep"] + NC["๐Ÿ“ถ networkConnection.bicep"] + end + + %% ===== LAYER 5: PROJECT RESOURCES ===== + subgraph L5["๐Ÿ“ Layer 5: Project Resources"] + PROJ["๐Ÿ“‹ project.bicep"] + end + + %% ===== LAYER 6: PROJECT CHILD RESOURCES ===== + subgraph L6["๐Ÿ“ฆ Layer 6: Project Child Resources"] + POOL["๐ŸŠ projectPool.bicep"] + PCAT["๐Ÿ“š projectCatalog.bicep"] + PENV["๐ŸŒ projectEnvironmentType.bicep"] + end + + %% ===== LAYER 7: IDENTITY ===== + subgraph L7["๐Ÿ‘ค Layer 7: Identity"] + DCRA["๐Ÿ” devCenterRoleAssignment"] + ORA["๐Ÿข orgRoleAssignment"] + PIRA["๐Ÿ‘ฅ projectIdentityRoleAssignment"] + KVA["๐Ÿ”‘ keyVaultAccess"] + end + + %% ===== CONNECTIONS ===== + MAIN -->|creates| RG_SEC + MAIN -->|creates| RG_MON + MAIN -->|creates| RG_WL + + RG_SEC -->|scopes| SEC + RG_MON -->|scopes| LA + RG_WL -->|scopes| WL + + SEC -->|deploys| KV + LA -->|deploys| LOG + WL -->|deploys| DC + WL -->|deploys| CONN + + KV -->|creates| SECRET + KV -->|assigns| KVA + DC -->|syncs| CAT + DC -->|defines| ENV + DC -->|assigns| DCRA + DC -->|assigns| ORA + CONN -->|provisions| VN + CONN -->|connects| NC + + DC -->|spawns| PROJ + PROJ -->|deploys| POOL + PROJ -->|syncs| PCAT + PROJ -->|enables| PENV + PROJ -->|assigns| PIRA + + LOG -.->|logAnalyticsId| KV + LOG -.->|logAnalyticsId| DC + LOG -.->|logAnalyticsId| VN + KV -.->|secretIdentifier| CAT + + %% ===== STYLES ===== + classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + + class MAIN trigger + class RG_SEC,RG_MON,RG_WL trigger + class SEC,LA,WL primary + class KV,LOG,DC,CONN primary + class SECRET,CAT,ENV,VN,NC secondary + class PROJ secondary + class POOL,PCAT,PENV secondary + class DCRA,ORA,PIRA,KVA datastore + + style L0 fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style L1 fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style L2 fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style L3 fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style L4 fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style L5 fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style L6 fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style L7 fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px +``` + +### Dependency Matrix + +| Module | Depends On | Provides To | +|--------|------------|-------------| +| `main.bicep` | azureResources.yaml, security.yaml, devcenter.yaml | All modules | +| `security.bicep` | logAnalyticsId, securityConfig | secretIdentifier | +| `logAnalytics.bicep` | monitoringLandingZone | logAnalyticsId | +| `workload.bicep` | logAnalyticsId, secretIdentifier, devCenterConfig | devCenterName, projects | +| `keyVault.bicep` | logAnalyticsId | keyVaultId, secretIdentifier | +| `devCenter.bicep` | logAnalyticsId, secretIdentifier | devCenterId, catalogIds | +| `project.bicep` | devCenterName, networkConnectionId | projectId, poolIds | +| `vnet.bicep` | logAnalyticsId, networkConfig | vnetId, subnetIds | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“œ Interface Contracts + +### main.bicep Parameters + +```bicep +// Orchestration Parameters +@description('Azure region for deployment') +param location string = deployment().location + +@description('Environment suffix (e.g., dev, prod)') +param deploymentEnvironmentName string = 'dev' + +@secure() +@description('PAT token for catalog authentication') +param keyVaultSecret string + +// Configuration Loading +var securityConfig = loadYamlContent('./settings/security/security.yaml') +var devCenterConfig = loadYamlContent('./settings/workload/devcenter.yaml') +var azureResourcesConfig = loadYamlContent('./settings/resourceOrganization/azureResources.yaml') +``` + +### main.bicep Outputs + +```bicep +// Resource Group Outputs +output securityResourceGroupName string = securityResourceGroup.name +output monitoringResourceGroupName string = monitoringResourceGroup.name +output workloadResourceGroupName string = workloadResourceGroup.name + +// Resource Outputs +output logAnalyticsWorkspaceId string = logAnalyticsWorkspace.outputs.logAnalyticsWorkspaceId +output keyVaultName string = security.outputs.keyVaultName +output devCenterName string = workload.outputs.devCenterName +output keyVaultSecretIdentifier string = security.outputs.keyVaultSecretIdentifier +output devCenterProjects array = workload.outputs.devCenterProjects +``` + +### Module Interface: security.bicep + +```bicep +// Input Parameters +@description('Security landing zone configuration') +param landingZone object + +@description('Key Vault configuration') +param keyVaultConfig object + +@description('Log Analytics workspace ID') +param logAnalyticsWorkspaceId string + +@secure() +@description('Secret value to store') +param keyVaultSecret string + +@description('Deployment environment') +param deploymentEnvironmentName string + +@description('Location') +param location string + +// Outputs +output keyVaultName string = keyVault.outputs.keyVaultName +output keyVaultId string = keyVault.outputs.keyVaultId +output keyVaultSecretIdentifier string = keyVault.outputs.secretIdentifier +``` + +### Module Interface: workload.bicep + +```bicep +// Input Parameters +@description('Workload landing zone configuration') +param landingZone object + +@description('DevCenter configuration') +param devCenterConfig object + +@description('Log Analytics workspace ID') +param logAnalyticsId string + +@description('Key Vault secret identifier') +param keyVaultSecretIdentifier string + +@description('Deployment environment') +param deploymentEnvironmentName string + +@description('Location') +param location string + +// Outputs +output devCenterName string = devCenter.outputs.devCenterName +output devCenterProjects array = devCenter.outputs.devCenterProjects +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿš€ Deployment Orchestration + +### Deployment Sequence Diagram + +```mermaid +--- +title: Deployment Sequence +--- +sequenceDiagram + participant U as ๐Ÿ‘ค User/Pipeline + participant AZD as ๐Ÿš€ azd CLI + participant ARM as โ˜๏ธ Azure Resource Manager + participant RG as ๐Ÿ“ Resource Groups + participant SEC as ๐Ÿ” Security Module + participant MON as ๐Ÿ“Š Monitoring Module + participant WL as ๐Ÿ“ฆ Workload Module + + U->>AZD: azd provision + AZD->>ARM: Deploy main.bicep (subscription scope) + + par Create Resource Groups + ARM->>RG: Create Security RG + ARM->>RG: Create Monitoring RG + ARM->>RG: Create Workload RG + end + + Note over ARM,MON: Phase 1: Independent Modules + ARM->>MON: Deploy logAnalytics.bicep + MON-->>ARM: logAnalyticsWorkspaceId + + Note over ARM,SEC: Phase 2: Security (depends on LA) + ARM->>SEC: Deploy security.bicep + SEC-->>ARM: keyVaultSecretIdentifier + + Note over ARM,WL: Phase 3: Workload (depends on LA + KV) + ARM->>WL: Deploy workload.bicep + + WL->>WL: Deploy DevCenter + WL->>WL: Deploy Catalogs + WL->>WL: Deploy Projects + WL->>WL: Deploy Pools + + WL-->>ARM: devCenterName, projects + ARM-->>AZD: Deployment complete + AZD-->>U: Outputs displayed +``` + +### Deployment Dependencies + +```mermaid +--- +title: Deployment Dependencies +--- +flowchart LR + %% ===== PHASE 1: FOUNDATION ===== + subgraph Phase1["๐Ÿ—๏ธ Phase 1: Foundation"] + RG["๐Ÿ“ Resource Groups"] + LA["๐Ÿ“Š Log Analytics"] + end + + %% ===== PHASE 2: SECURITY ===== + subgraph Phase2["๐Ÿ” Phase 2: Security"] + KV["๐Ÿ”‘ Key Vault"] + SEC["๐Ÿ”’ Secrets"] + end + + %% ===== PHASE 3: NETWORK ===== + subgraph Phase3["๐ŸŒ Phase 3: Network"] + VN["๐Ÿ”— Virtual Network"] + NC["๐Ÿ“ถ Network Connection"] + end + + %% ===== PHASE 4: WORKLOAD ===== + subgraph Phase4["๐Ÿ“ฆ Phase 4: Workload"] + DC["๐Ÿ–ฅ๏ธ DevCenter"] + CAT["๐Ÿ“š Catalogs"] + ENV["๐ŸŒ Environment Types"] + end + + %% ===== PHASE 5: PROJECTS ===== + subgraph Phase5["๐Ÿ“ Phase 5: Projects"] + PROJ["๐Ÿ“‹ Projects"] + POOL["๐ŸŠ Pools"] + PCAT["๐Ÿ“– Project Catalogs"] + end + + %% ===== PHASE 6: IDENTITY ===== + subgraph Phase6["๐Ÿ‘ค Phase 6: Identity"] + RBAC["๐Ÿ” RBAC Assignments"] + end + + %% ===== CONNECTIONS ===== + Phase1 -->|enables| Phase2 + Phase1 -->|enables| Phase3 + Phase2 -->|unlocks| Phase4 + Phase3 -->|connects| Phase4 + Phase4 -->|spawns| Phase5 + Phase5 -->|secures| Phase6 + + %% ===== STYLES ===== + classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + + class RG,LA trigger + class KV,SEC primary + class VN,NC primary + class DC,CAT,ENV secondary + class PROJ,POOL,PCAT secondary + class RBAC datastore + + style Phase1 fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style Phase2 fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style Phase3 fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style Phase4 fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Phase5 fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Phase6 fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Component Details + +### main.bicep - Subscription Orchestrator + +**Scope:** `targetScope = 'subscription'` + +**Responsibilities:** + +- Load YAML configuration files +- Create landing zone resource groups +- Orchestrate module deployments with dependencies +- Aggregate and expose outputs + +**Key Implementation Details:** + +```bicep +// Resource Group Creation +module securityResourceGroup 'src/connectivity/resourceGroup.bicep' = if (securityConfig.create) { + name: 'securityResourceGroup' + params: { + name: '${securityLandingZone.name}-${deploymentEnvironmentName}' + location: location + tags: union(defaultTags, securityLandingZone.tags) + } +} + +// Module Dependencies +module security 'src/security/security.bicep' = if (securityConfig.create) { + name: 'securityDeployment' + scope: resourceGroup(securityResourceGroup.outputs.resourceGroupName) + params: { + logAnalyticsWorkspaceId: logAnalyticsWorkspace.outputs.logAnalyticsWorkspaceId + keyVaultSecret: keyVaultSecret + // ... + } + dependsOn: [ + logAnalyticsWorkspace + ] +} +``` + +### devCenter.bicep - DevCenter Core Module + +**Scope:** Resource Group + +**Resources Created:** + +- Microsoft.DevCenter/devcenters +- Diagnostic Settings +- Catalogs (via child module) +- Environment Types (via child module) +- Role Assignments (via child module) + +**Key Features:** + +- SystemAssigned managed identity +- Microsoft-hosted network support +- Azure Monitor agent installation +- Multi-catalog synchronization + +```bicep +resource devCenter 'Microsoft.DevCenter/devcenters@2024-08-01-preview' = { + name: name + location: location + identity: { + type: identity.type + } + properties: { + displayName: name + devCenterUri: name + projectCatalogSettings: { + catalogItemSyncEnableStatus: catalogItemSyncEnableStatus + } + networkSettings: { + microsoftHostedNetworkEnableStatus: microsoftHostedNetworkEnableStatus + } + } + tags: tags +} +``` + +### project.bicep - Project Deployment Module + +**Scope:** DevCenter + +**Resources Created:** + +- Microsoft.DevCenter/devcenters/projects +- Project Pools (via child module) +- Project Catalogs (via child module) +- Project Environment Types (via child module) +- Project Identity Role Assignments + +**Configuration Flow:** + +```mermaid +--- +title: Project Configuration Flow +--- +flowchart TB + %% ===== INPUT CONFIGURATION ===== + subgraph Input["๐Ÿ“ฅ Input Configuration"] + PC["โš™๏ธ project config object"] + NCI["๐Ÿ”— networkConnectionId"] + SID["๐Ÿ”‘ secretIdentifier"] + end + + %% ===== PROJECT RESOURCE ===== + subgraph Project["๐Ÿ“‹ Project Resource"] + PR["๐Ÿข Microsoft.DevCenter/devcenters/projects"] + end + + %% ===== CHILD RESOURCES ===== + subgraph Children["๐Ÿ“ฆ Child Resources"] + PO["๐ŸŠ Pools
(projectPool.bicep)"] + CA["๐Ÿ“š Catalogs
(projectCatalog.bicep)"] + ET["๐ŸŒ Environment Types
(projectEnvironmentType.bicep)"] + end + + %% ===== IDENTITY ===== + subgraph Identity["๐Ÿ‘ค Identity"] + MI["๐Ÿ” SystemAssigned Identity"] + RA["๐Ÿ›ก๏ธ Role Assignments"] + end + + %% ===== CONNECTIONS ===== + Input -->|configures| Project + Project -->|creates| Children + Project -->|provisions| MI + MI -->|enables| RA + + %% ===== STYLES ===== + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + + class PC,NCI,SID datastore + class PR primary + class PO,CA,ET secondary + class MI,RA trigger + + style Input fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style Project fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style Children fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Identity fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”„ Integration Patterns + +### Configuration Integration Pattern + +The accelerator uses the **Configuration as Data** pattern where all deployment parameters are externalized to YAML files. + +```mermaid +--- +title: Configuration Integration Pattern +--- +flowchart LR + %% ===== CONFIGURATION LAYER ===== + subgraph Config["๐Ÿ“ Configuration Layer"] + YAML["๐Ÿ“„ YAML Files
(infra/settings/)"] + SCHEMA["๐Ÿ“‹ JSON Schemas
(validation)"] + end + + %% ===== BICEP LAYER ===== + subgraph Bicep["โš™๏ธ Bicep Layer"] + LOAD["๐Ÿ”„ loadYamlContent()"] + PARAM["๐Ÿ“ฅ Parameters"] + MOD["๐Ÿ“ฆ Modules"] + end + + %% ===== ARM LAYER ===== + subgraph ARM["โ˜๏ธ ARM Layer"] + TEMPLATE["๐Ÿ“‹ ARM Template"] + DEPLOY["๐Ÿš€ Deployment"] + end + + %% ===== CONNECTIONS ===== + SCHEMA -->|validates| YAML + YAML -->|loads| LOAD + LOAD -->|injects| PARAM + PARAM -->|configures| MOD + MOD -->|compiles| TEMPLATE + TEMPLATE -->|executes| DEPLOY + + %% ===== STYLES ===== + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + + class YAML,SCHEMA datastore + class LOAD,PARAM,MOD primary + class TEMPLATE,DEPLOY secondary + + style Config fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style Bicep fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style ARM fill:#ECFDF5,stroke:#10B981,stroke-width:2px +``` + +### Hierarchical Module Pattern + +Modules follow a parent-child pattern where parent modules orchestrate child resources: + +```mermaid +--- +title: Hierarchical Module Pattern +--- +flowchart TB + %% ===== PATTERN ===== + subgraph Pattern["๐Ÿ—๏ธ Hierarchical Module Pattern"] + P["๐Ÿ“„ Parent Module"] + C1["๐Ÿ“ฆ Child Module 1"] + C2["๐Ÿ“ฆ Child Module 2"] + C3["๐Ÿ“ฆ Child Module 3"] + end + + P -->|for loop| C1 + P -->|for loop| C2 + P -->|for loop| C3 + + %% ===== EXAMPLE ===== + subgraph Example["๐Ÿ“ Example: devCenter.bicep"] + DC["๐Ÿ–ฅ๏ธ devCenter.bicep"] + CAT["๐Ÿ“š catalog.bicep
(for each catalog)"] + ENV["๐ŸŒ environmentType.bicep
(for each type)"] + PROJ["๐Ÿ“‹ project.bicep
(for each project)"] + end + + DC -->|module catalogs| CAT + DC -->|module envTypes| ENV + DC -->|module projects| PROJ + + %% ===== STYLES ===== + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + + class P,DC primary + class C1,C2,C3,CAT,ENV,PROJ secondary + + style Pattern fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style Example fill:#ECFDF5,stroke:#10B981,stroke-width:2px +``` + +### Dependency Injection Pattern + +Resources pass outputs to dependent modules: + +```bicep +// Dependency Injection: Log Analytics ID +module workload 'src/workload/workload.bicep' = { + params: { + logAnalyticsId: logAnalyticsWorkspace.outputs.logAnalyticsWorkspaceId + keyVaultSecretIdentifier: security.outputs.keyVaultSecretIdentifier + } +} +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”Œ Extension Points + +### Adding a New Landing Zone + +1. Create YAML configuration in `infra/settings/` +2. Add schema validation file +3. Create landing zone module in `src/` +4. Add resource group creation to `main.bicep` +5. Add module deployment with dependencies + +### Adding New DevCenter Features + +| Extension | Files to Modify | Steps | +|-----------|-----------------|-------| +| New Catalog Type | `catalog.bicep`, `devcenter.yaml` | Add catalog config, create sync logic | +| New Pool SKU | `projectPool.bicep`, `devcenter.yaml` | Add SKU to config, validate in module | +| Custom RBAC Role | `*RoleAssignment.bicep`, `devcenter.yaml` | Define role ID, add assignment logic | +| New Environment Type | `environmentType.bicep`, `devcenter.yaml` | Add type definition to config | + +### Module Extension Template + +```bicep +// Template for new child resource module +@description('Parent resource name') +param parentName string + +@description('Resource configuration') +param config object + +@description('Location') +param location string = resourceGroup().location + +@description('Tags') +param tags object = {} + +// Resource implementation +resource childResource 'Microsoft.Provider/parentType/childType@API-VERSION' = { + name: '${parentName}/${config.name}' + properties: { + // Properties from config + } + tags: tags +} + +// Outputs +output resourceId string = childResource.id +output resourceName string = childResource.name +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“š References + +### ๐Ÿ“š Internal References + +- [Business Architecture](01-business-architecture.md) +- [Data Architecture](02-data-architecture.md) +- [Technology Architecture](04-technology-architecture.md) +- [Security Architecture](05-security-architecture.md) + +### ๐ŸŒ External References + +- [Azure Bicep Documentation](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/) +- [Azure DevCenter API Reference](https://learn.microsoft.com/en-us/rest/api/devcenter/) +- [Bicep Module Best Practices](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/best-practices) +- [ARM Template Scopes](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/deploy-to-subscription) + +--- + +
+ +[โ† Data Architecture](02-data-architecture.md) | [โฌ†๏ธ Back to Top](#-table-of-contents) | [Technology Architecture โ†’](04-technology-architecture.md) + +*DevExp-DevBox Landing Zone Accelerator โ€ข Application Architecture* + +
diff --git a/docs/architecture/04-technology-architecture.md b/docs/architecture/04-technology-architecture.md new file mode 100644 index 00000000..719ca9da --- /dev/null +++ b/docs/architecture/04-technology-architecture.md @@ -0,0 +1,909 @@ +--- +title: "Technology Architecture" +description: "Azure services, infrastructure design, and technology standards for DevExp-DevBox" +author: "DevExp Team" +date: 2026-01-23 +version: "1.0.0" +tags: + - architecture + - technology + - togaf + - azure + - infrastructure +--- + +# โ˜๏ธ Technology Architecture + +> **DevExp-DevBox Landing Zone Accelerator** + +> [!NOTE] +> **Target Audience:** Cloud Architects, Infrastructure Engineers, Platform Teams +> **Reading Time:** ~20 minutes + +
+๐Ÿ“ Navigation + +| Previous | Index | Next | +|:---------|:-----:|-----:| +| [โ† Application Architecture](03-application-architecture.md) | [Architecture Index](../README.md) | [Security Architecture โ†’](05-security-architecture.md) | + +
+ +| Property | Value | +|:---------|:------| +| **Version** | 1.0.0 | +| **Last Updated** | 2026-01-23 | +| **Author** | DevExp Team | +| **Status** | Published | + +--- + +## ๐Ÿ“‘ Table of Contents + +- [๐Ÿ“Š Technology Overview](#technology-overview) +- [๐Ÿ“ฆ Azure Service Catalog](#azure-service-catalog) +- [๐Ÿ—๏ธ Landing Zone Design](#landing-zone-design) +- [๐ŸŒ Network Architecture](#network-architecture) +- [๐Ÿ’ป Compute Architecture](#compute-architecture) +- [๐Ÿ”„ CI/CD Infrastructure](#cicd-infrastructure) +- [๐Ÿ“ถ Monitoring Infrastructure](#monitoring-infrastructure) +- [๐Ÿ“ Infrastructure Sizing](#infrastructure-sizing) +- [๐Ÿ“œ Technology Standards](#technology-standards) +- [๐Ÿ”— References](#references) + +--- + +## ๐Ÿ“Š Technology Overview + +The DevExp-DevBox accelerator leverages Azure's Platform as a Service (PaaS) offerings with a strong emphasis on managed services, security by default, and enterprise governance patterns. + +### Technology Stack Overview + +```mermaid +--- +title: Technology Stack Overview +--- +flowchart TB + %% ===== DEVELOPER TOOLING ===== + subgraph Developer["๐Ÿ‘จโ€๐Ÿ’ป Developer Tooling"] + VSC["๐Ÿ’ป VS Code"] + GH["๐Ÿ™ GitHub"] + AZD["๐Ÿš€ Azure Developer CLI"] + end + + %% ===== INFRASTRUCTURE AS CODE ===== + subgraph IaC["๐Ÿ“œ Infrastructure as Code"] + BICEP["โš™๏ธ Azure Bicep"] + YAML["๐Ÿ“„ YAML Configuration"] + PS["๐Ÿ“ PowerShell/Bash"] + end + + %% ===== CI/CD PLATFORM ===== + subgraph CI_CD["๐Ÿ”„ CI/CD Platform"] + GHA["๐Ÿ”„ GitHub Actions"] + OIDC["๐Ÿ” OIDC Federation"] + end + + %% ===== AZURE PLATFORM ===== + subgraph Azure["โ˜๏ธ Azure Platform"] + subgraph Compute["๐Ÿ’ป Compute Services"] + DC["๐Ÿ–ฅ๏ธ Azure DevCenter"] + DB["๐Ÿ–ฅ๏ธ Dev Boxes"] + end + + subgraph Security["๐Ÿ” Security Services"] + KV["๐Ÿ”‘ Key Vault"] + RBAC["๐Ÿ›ก๏ธ Azure RBAC"] + MI["๐Ÿ‘ค Managed Identities"] + end + + subgraph Network["๐ŸŒ Network Services"] + VNET["๐Ÿ”— Virtual Network"] + NC["๐Ÿ“ถ Network Connections"] + end + + subgraph Monitor["๐Ÿ“Š Monitoring Services"] + LA["๐Ÿ“ˆ Log Analytics"] + MON["๐Ÿ“Š Azure Monitor"] + end + end + + %% ===== CONNECTIONS ===== + Developer -->|develops| IaC + IaC -->|deploys via| CI_CD + CI_CD -->|provisions| Azure + + %% ===== STYLES ===== + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + + class VSC,GH,AZD primary + class BICEP,YAML,PS datastore + class GHA,OIDC trigger + class DC,DB,KV,RBAC,MI,VNET,NC,LA,MON secondary + + style Developer fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style IaC fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style CI_CD fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style Azure fill:#ECFDF5,stroke:#10B981,stroke-width:2px +``` + +### Technology Decision Matrix + +| Category | Technology | Rationale | Alternatives Considered | +|----------|------------|-----------|-------------------------| +| IaC Language | Azure Bicep | Native Azure, type-safe, modular | Terraform, ARM Templates | +| Configuration | YAML | Human-readable, schema validation | JSON, HCL | +| CI/CD | GitHub Actions | Native GitHub integration, OIDC | Azure DevOps, Jenkins | +| Authentication | OIDC Federation | No stored secrets, short-lived tokens | Service Principal + Secret | +| Secrets | Azure Key Vault | Native Azure, RBAC, HSM-backed | GitHub Secrets, HashiCorp Vault | +| Monitoring | Log Analytics | Unified Azure telemetry | Splunk, Datadog | +| Compute | Azure DevCenter | Managed Dev Box service | Azure VMs, AVD | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ฆ Azure Service Catalog + +### Primary Azure Services + +| Service | Resource Type | Purpose | Tier/SKU | +|---------|--------------|---------|----------| +| **Azure DevCenter** | `Microsoft.DevCenter/devcenters` | Developer workstation management | N/A (PaaS) | +| **Dev Box Projects** | `Microsoft.DevCenter/devcenters/projects` | Project-level Dev Box organization | N/A | +| **Dev Box Pools** | `Microsoft.DevCenter/projects/pools` | Dev Box VM allocation | Variable | +| **Azure Key Vault** | `Microsoft.KeyVault/vaults` | Secrets and credential storage | Standard | +| **Log Analytics** | `Microsoft.OperationalInsights/workspaces` | Centralized logging | PerGB2018 | +| **Virtual Network** | `Microsoft.Network/virtualNetworks` | Network isolation | N/A | +| **Network Connection** | `Microsoft.DevCenter/networkConnections` | Dev Box network config | N/A | + +### Service Relationships + +```mermaid +--- +title: Azure Service Relationships +--- +flowchart TB + %% ===== MANAGEMENT PLANE ===== + subgraph Management["๐ŸŽฏ Management Plane"] + ARM["โ˜๏ธ Azure Resource Manager"] + SUB["๐Ÿ“‹ Subscription"] + end + + %% ===== RESOURCE GROUPS ===== + subgraph ResourceGroups["๐Ÿ“ Resource Groups"] + RG_SEC["๐Ÿ” rg-security"] + RG_MON["๐Ÿ“Š rg-monitoring"] + RG_WL["๐Ÿ“ฆ rg-workload"] + end + + %% ===== SECURITY ZONE ===== + subgraph SecurityZone["๐Ÿ” Security Landing Zone"] + KV["๐Ÿ”‘ Key Vault"] + SEC["๐Ÿ”’ Secrets"] + end + + %% ===== MONITORING ZONE ===== + subgraph MonitoringZone["๐Ÿ“Š Monitoring Landing Zone"] + LA["๐Ÿ“ˆ Log Analytics
Workspace"] + SOL["๐Ÿ”ง Solutions"] + end + + %% ===== WORKLOAD ZONE ===== + subgraph WorkloadZone["๐Ÿ“ฆ Workload Landing Zone"] + DC["๐Ÿ–ฅ๏ธ DevCenter"] + PROJ["๐Ÿ“ Projects"] + POOL["๐ŸŠ Pools"] + CAT["๐Ÿ“š Catalogs"] + end + + %% ===== NETWORK ZONE ===== + subgraph NetworkZone["๐ŸŒ Network"] + VNET["๐Ÿ”— Virtual Network"] + SUBNET["๐Ÿ“ถ Subnets"] + NC["๐Ÿ”Œ Network Connection"] + end + + %% ===== CONNECTIONS ===== + ARM -->|manages| SUB + SUB -->|contains| ResourceGroups + + RG_SEC -->|hosts| SecurityZone + RG_MON -->|hosts| MonitoringZone + RG_WL -->|hosts| WorkloadZone + RG_WL -->|hosts| NetworkZone + + KV -.->|secretIdentifier| CAT + LA -.->|diagnostics| KV + LA -.->|diagnostics| DC + LA -.->|diagnostics| VNET + + NC -->|connects| VNET + DC -->|creates| PROJ + PROJ -->|deploys| POOL + + %% ===== STYLES ===== + classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + classDef failed fill:#F44336,stroke:#C62828,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + + class ARM,SUB trigger + class RG_SEC,RG_MON,RG_WL trigger + class KV,SEC failed + class LA,SOL secondary + class DC,PROJ,POOL,CAT primary + class VNET,SUBNET,NC datastore + + style Management fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style ResourceGroups fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style SecurityZone fill:#FEE2E2,stroke:#F44336,stroke-width:2px + style MonitoringZone fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style WorkloadZone fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style NetworkZone fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px +``` + +### API Versions Used + +| Resource Type | API Version | Preview/GA | +|--------------|-------------|------------| +| `Microsoft.DevCenter/devcenters` | 2024-08-01-preview | Preview | +| `Microsoft.DevCenter/devcenters/catalogs` | 2024-08-01-preview | Preview | +| `Microsoft.DevCenter/devcenters/projects` | 2024-08-01-preview | Preview | +| `Microsoft.DevCenter/projects/pools` | 2024-08-01-preview | Preview | +| `Microsoft.DevCenter/networkConnections` | 2024-08-01-preview | Preview | +| `Microsoft.KeyVault/vaults` | 2023-07-01 | GA | +| `Microsoft.KeyVault/vaults/secrets` | 2023-07-01 | GA | +| `Microsoft.OperationalInsights/workspaces` | 2022-10-01 | GA | +| `Microsoft.Network/virtualNetworks` | 2023-09-01 | GA | +| `Microsoft.Insights/diagnosticSettings` | 2021-05-01-preview | GA | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ—๏ธ Landing Zone Design + +### Azure Landing Zone Alignment + +The accelerator implements a simplified Azure Landing Zone pattern with three primary zones plus networking. + +```mermaid +--- +title: Azure Landing Zone Design +--- +flowchart TB + %% ===== SUBSCRIPTION ===== + subgraph Subscription["โ˜๏ธ Azure Subscription"] + %% ===== SECURITY ===== + subgraph Security["๐Ÿ” Security Landing Zone"] + direction TB + RG_S["๐Ÿ“ Resource Group:
devexp-security-{env}"] + KV_R["๐Ÿ”‘ Key Vault"] + SEC_R["๐Ÿ”’ Secrets"] + end + + %% ===== MONITORING ===== + subgraph Monitoring["๐Ÿ“Š Monitoring Landing Zone"] + direction TB + RG_M["๐Ÿ“ Resource Group:
devexp-monitoring-{env}"] + LA_R["๐Ÿ“ˆ Log Analytics"] + SOL_R["๐Ÿ”ง Solutions"] + end + + %% ===== WORKLOAD ===== + subgraph Workload["๐Ÿ“ฆ Workload Landing Zone"] + direction TB + RG_W["๐Ÿ“ Resource Group:
devexp-workload-{env}"] + DC_R["๐Ÿ–ฅ๏ธ DevCenter"] + PROJ_R["๐Ÿ“‹ Projects"] + POOL_R["๐ŸŠ Pools"] + end + + %% ===== CONNECTIVITY ===== + subgraph Network["๐ŸŒ Connectivity"] + direction TB + VNET_R["๐Ÿ”— Virtual Network"] + NC_R["๐Ÿ“ถ Network Connection"] + end + end + + %% ===== CONNECTIONS ===== + Security -->|feeds| Monitoring + Monitoring -->|enables| Workload + Network -->|connects| Workload + + %% ===== STYLES ===== + classDef failed fill:#F44336,stroke:#C62828,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + + class RG_S,KV_R,SEC_R failed + class RG_M,LA_R,SOL_R secondary + class RG_W,DC_R,PROJ_R,POOL_R primary + class VNET_R,NC_R datastore + + style Security fill:#FEE2E2,stroke:#F44336,stroke-width:2px + style Monitoring fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Workload fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style Network fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px +``` + +### Resource Group Naming Convention + +| Landing Zone | Resource Group Pattern | Example | +|--------------|----------------------|---------| +| Security | `{base}-security-{env}` | `devexp-security-dev` | +| Monitoring | `{base}-monitoring-{env}` | `devexp-monitoring-dev` | +| Workload | `{base}-workload-{env}` | `devexp-workload-dev` | + +### Resource Naming Convention + +| Resource Type | Pattern | Example | +|--------------|---------|---------| +| DevCenter | `{name}-{uniqueString}` | `devexp-devcenter-abc123` | +| Key Vault | `kv-{name}-{uniqueString}` | `kv-contoso-xyz789` | +| Log Analytics | `law-{name}-{uniqueString}` | `law-devexp-def456` | +| Virtual Network | `vnet-{project}-{env}` | `vnet-eshop-dev` | +| Subnet | `snet-{purpose}` | `snet-devbox` | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐ŸŒ Network Architecture + +### Network Topology + +```mermaid +--- +title: Network Topology +--- +flowchart TB + %% ===== INTERNET ===== + subgraph Internet["๐ŸŒ Internet"] + DEV["๐Ÿ‘จโ€๐Ÿ’ป Developer
(Remote)"] + GH["๐Ÿ™ GitHub.com"] + ADO["๐Ÿ”ท Azure DevOps"] + end + + %% ===== AZURE ===== + subgraph Azure["โ˜๏ธ Azure"] + subgraph VNet["๐Ÿ”— Virtual Network (10.0.0.0/16)"] + subgraph Subnet["๐Ÿ“ถ DevBox Subnet (10.0.1.0/24)"] + DB1["๐Ÿ–ฅ๏ธ Dev Box 1"] + DB2["๐Ÿ–ฅ๏ธ Dev Box 2"] + DB3["๐Ÿ–ฅ๏ธ Dev Box N"] + end + end + + NC["๐Ÿ“ถ Network Connection
(Managed/Unmanaged)"] + DC["๐Ÿ–ฅ๏ธ DevCenter"] + end + + %% ===== MS HOSTED ===== + subgraph MSHosted["๐Ÿข Microsoft-Hosted Network"] + MHN["โ˜๏ธ Microsoft Managed
Network"] + end + + %% ===== CONNECTIONS ===== + DEV -->|RDP/HTTPS| DB1 + DEV -->|RDP/HTTPS| DB2 + + DB1 -->|HTTPS| GH + DB1 -->|HTTPS| ADO + + DC -->|networkConnectionId| NC + NC -->|subnetId| Subnet + + DC -.->|Alternative| MHN + + %% ===== STYLES ===== + classDef external fill:#6B7280,stroke:#4B5563,color:#FFFFFF,stroke-dasharray:5 5 + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + + class DEV,GH,ADO external + class DB1,DB2,DB3,NC,DC primary + class MHN trigger + + style Internet fill:#F3F4F6,stroke:#6B7280,stroke-width:2px + style VNet fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style MSHosted fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px +``` + +### Network Configuration Options + +| Option | Configuration | Use Case | +|--------|--------------|----------| +| **Microsoft-Hosted** | `microsoftHostedNetworkEnableStatus: Enabled` | Quick start, no VNet management | +| **Azure VNet (Managed)** | `virtualNetworkType: Managed` | Organization VNet, auto-provisioned | +| **Azure VNet (Unmanaged)** | `virtualNetworkType: Unmanaged` | Existing VNet, full control | + +### VNet Configuration (from devcenter.yaml) + +```yaml +network: + name: eShop + create: true + virtualNetworkType: Managed + addressPrefixes: + - "10.0.0.0/16" + subnets: + - name: eShop-subnet + properties: + addressPrefix: 10.0.1.0/24 +``` + +### Network Security Controls + +| Control | Implementation | Purpose | +|---------|---------------|---------| +| NSG | Default Azure NSG | Subnet-level filtering | +| Private Endpoints | Optional | Key Vault private access | +| Service Endpoints | Optional | PaaS service access | +| NAT Gateway | Optional | Outbound connectivity | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ’ป Compute Architecture + +### Dev Box Architecture + +```mermaid +--- +title: Dev Box Architecture +--- +flowchart TB + %% ===== DEVCENTER ===== + subgraph DevCenter["๐Ÿข Azure DevCenter"] + DC["๐Ÿ–ฅ๏ธ DevCenter Resource"] + + %% ===== IMAGES ===== + subgraph Images["๐Ÿ“ฆ Image Definitions"] + IMG1["๐Ÿ’ป eShop-backend-engineer"] + IMG2["๐ŸŽจ eShop-frontend-engineer"] + end + + %% ===== PROJECTS ===== + subgraph Projects["๐Ÿ“ Projects"] + PROJ["๐Ÿ“‹ eShop Project"] + end + + %% ===== POOLS ===== + subgraph Pools["๐ŸŠ Dev Box Pools"] + P1["โš™๏ธ backend-engineer
general_i_32c128gb512ssd_v2"] + P2["๐ŸŽจ frontend-engineer
general_i_16c64gb256ssd_v2"] + end + end + + %% ===== RUNTIME ===== + subgraph Runtime["๐Ÿš€ Runtime Environment"] + DB1["๐Ÿ–ฅ๏ธ Dev Box Instance
(Windows 11)"] + DB2["๐Ÿ–ฅ๏ธ Dev Box Instance
(Windows 11)"] + end + + %% ===== CONNECTIONS ===== + DC -->|manages| Images + DC -->|contains| Projects + Projects -->|deploys| Pools + P1 -->|provisions| DB1 + P2 -->|provisions| DB2 + + IMG1 -->|imageDefinition| P1 + IMG2 -->|imageDefinition| P2 + + %% ===== STYLES ===== + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + + class DC,PROJ primary + class IMG1,IMG2,P1,P2,DB1,DB2 secondary + + style DevCenter fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style Runtime fill:#ECFDF5,stroke:#10B981,stroke-width:2px +``` + +### Dev Box SKU Options + +| SKU | vCPU | Memory | Storage | Use Case | +|-----|------|--------|---------|----------| +| `general_i_8c32gb256ssd_v2` | 8 | 32 GB | 256 GB | Light development | +| `general_i_16c64gb256ssd_v2` | 16 | 64 GB | 256 GB | Frontend development | +| `general_i_16c64gb512ssd_v2` | 16 | 64 GB | 512 GB | General development | +| `general_i_32c128gb512ssd_v2` | 32 | 128 GB | 512 GB | Backend/heavy workloads | +| `general_i_32c128gb1024ssd_v2` | 32 | 128 GB | 1024 GB | Data/ML development | + +### Image Management + +Dev Box images are managed through DevCenter catalogs containing image definitions: + +```mermaid +--- +title: Image Management Flow +--- +flowchart LR + %% ===== CATALOG ===== + subgraph Catalog["๐Ÿ“š DevCenter Catalog"] + GIT["๐Ÿ™ Git Repository"] + IMG_DEF["๐Ÿ“„ Image Definitions
(YAML/JSON)"] + DSC["โš™๏ธ DSC Configurations
(Optional)"] + end + + %% ===== DEVCENTER ===== + subgraph DevCenter["๐Ÿข DevCenter"] + CAT["๐Ÿ”„ Catalog Sync"] + IMG["๐Ÿ“ฆ Image Gallery"] + end + + %% ===== POOL ===== + subgraph Pool["๐ŸŠ Dev Box Pool"] + VM["๐Ÿ–ฅ๏ธ Dev Box VMs"] + end + + %% ===== CONNECTIONS ===== + GIT -->|syncs| CAT + CAT -->|loads| IMG_DEF + IMG_DEF -->|registers| IMG + IMG -->|provisions| VM + DSC -->|configures| IMG + + %% ===== STYLES ===== + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + + class GIT,IMG_DEF,DSC datastore + class CAT,IMG primary + class VM secondary + + style Catalog fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style DevCenter fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style Pool fill:#ECFDF5,stroke:#10B981,stroke-width:2px +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”„ CI/CD Infrastructure + +### GitHub Actions Architecture + +```mermaid +--- +title: GitHub Actions Architecture +--- +flowchart TB + %% ===== GITHUB ===== + subgraph GitHub["๐Ÿ™ GitHub"] + REPO["๐Ÿ“ Repository"] + + %% ===== ACTIONS ===== + subgraph Actions["๐Ÿ”„ GitHub Actions"] + WF_BUILD["๐Ÿ”จ build.yml"] + WF_DEPLOY["๐Ÿš€ deploy.yml"] + WF_RELEASE["๐Ÿ“ฆ release.yml"] + end + + %% ===== SECRETS ===== + subgraph Secrets["๐Ÿ” GitHub Configuration"] + VARS["๐Ÿ“‹ Variables:
- AZURE_CLIENT_ID
- AZURE_TENANT_ID
- AZURE_SUBSCRIPTION_ID"] + SECS["๐Ÿ”‘ Secrets:
- AZURE_CREDENTIALS"] + end + end + + %% ===== AZURE ===== + subgraph Azure["โ˜๏ธ Azure"] + OIDC["๐Ÿ” OIDC Provider
(Microsoft Entra ID)"] + ARM["โ˜๏ธ Azure Resource Manager"] + SUB["๐Ÿ“‹ Subscription"] + end + + %% ===== CONNECTIONS ===== + REPO -->|triggers| Actions + Actions -->|authenticates| OIDC + OIDC -->|Token Exchange| ARM + ARM -->|deploys| SUB + + VARS -->|configures| Actions + SECS -->|configures| Actions + + %% ===== STYLES ===== + classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + + class REPO trigger + class WF_BUILD,WF_DEPLOY,WF_RELEASE datastore + class VARS,SECS datastore + class OIDC,ARM,SUB secondary + + style GitHub fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style Azure fill:#ECFDF5,stroke:#10B981,stroke-width:2px +``` + +### Workflow Pipeline Structure + +```mermaid +--- +title: Workflow Pipeline Structure +--- +flowchart LR + %% ===== BUILD ===== + subgraph Build["๐Ÿ”จ build.yml"] + B1["๐Ÿ“ฅ Checkout"] + B2["โš™๏ธ Setup azd"] + B3["๐Ÿ” Login (OIDC)"] + B4["๐Ÿš€ azd provision"] + end + + %% ===== DEPLOY ===== + subgraph Deploy["๐Ÿš€ deploy.yml"] + D1["๐Ÿ“ฅ Checkout"] + D2["โš™๏ธ Setup azd"] + D3["๐Ÿ” Login (OIDC)"] + D4["๐Ÿ“ฆ Download Artifacts"] + D5["๐Ÿš€ azd deploy"] + end + + %% ===== RELEASE ===== + subgraph Release["๐Ÿ“ฆ release.yml"] + R1["๐Ÿท๏ธ Get Version"] + R2["๐Ÿ”– Create Tag"] + R3["๐Ÿ“ฆ Create Release"] + R4["๐Ÿ“ Generate Notes"] + end + + %% ===== CONNECTIONS ===== + Build -->|artifacts| Deploy + Deploy -->|on success| Release + + %% ===== STYLES ===== + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + + class B1,B2,B3,B4 datastore + class D1,D2,D3,D4,D5 secondary + class R1,R2,R3,R4 primary + + style Build fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style Deploy fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Release fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px +``` + +### Pipeline Components + +| Component | Purpose | Configuration | +|-----------|---------|---------------| +| `build.yml` | Provision infrastructure | OIDC auth, azd provision | +| `deploy.yml` | Deploy applications | Artifact download, azd deploy | +| `release.yml` | Create releases | Semantic versioning, release notes | + +### OIDC Federation Configuration + +```yaml +# GitHub Actions OIDC Configuration +permissions: + id-token: write # Required for OIDC + contents: read # Required for checkout + +steps: + - uses: azure/login@v2 + with: + client-id: ${{ vars.AZURE_CLIENT_ID }} + tenant-id: ${{ vars.AZURE_TENANT_ID }} + subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }} +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ถ Monitoring Infrastructure + +### Log Analytics Architecture + +```mermaid +--- +title: Log Analytics Architecture +--- +flowchart TB + %% ===== TELEMETRY SOURCES ===== + subgraph Sources["๐Ÿ“ถ Telemetry Sources"] + DC["๐Ÿ–ฅ๏ธ DevCenter
Logs & Metrics"] + KV["๐Ÿ”‘ Key Vault
Logs & Metrics"] + VN["๐ŸŒ Virtual Network
Logs & Metrics"] + DB["๐Ÿ–ฅ๏ธ Dev Box
Agent Metrics"] + end + + %% ===== COLLECTION LAYER ===== + subgraph Collection["๐Ÿ”„ Collection Layer"] + DS["โš™๏ธ Diagnostic Settings"] + AMA["๐Ÿ“Š Azure Monitor Agent"] + end + + %% ===== LOG ANALYTICS WORKSPACE ===== + subgraph LAW["๐Ÿ“ˆ Log Analytics Workspace"] + subgraph Tables["๐Ÿ“‹ Tables"] + DIAG["๐Ÿ“ AzureDiagnostics"] + MET["๐Ÿ“Š AzureMetrics"] + ACT["๐Ÿ“‹ AzureActivity"] + end + + subgraph Solutions["๐Ÿ”ง Solutions"] + AA["โ˜๏ธ AzureActivity Solution"] + end + end + + %% ===== CONSUMERS ===== + subgraph Consumers["๐Ÿ‘ฅ Consumers"] + DASH["๐Ÿ“Š Dashboards"] + ALERT["๐Ÿ”” Alerts"] + WB["๐Ÿ“– Workbooks"] + end + + %% ===== CONNECTIONS ===== + DC -->|sends| DS + KV -->|sends| DS + VN -->|sends| DS + DB -->|sends| AMA + + DS -->|ingests| Tables + AMA -->|ingests| Tables + + Tables -->|feeds| Solutions + Tables -->|powers| Consumers + + %% ===== STYLES ===== + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + + class DC,KV,VN,DB datastore + class DS,AMA trigger + class DIAG,MET,ACT,AA primary + class DASH,ALERT,WB secondary + + style Sources fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style Collection fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style LAW fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style Consumers fill:#ECFDF5,stroke:#10B981,stroke-width:2px +``` + +### Diagnostic Settings Configuration + +| Resource | Log Categories | Metrics | +|----------|---------------|---------| +| DevCenter | allLogs | AllMetrics | +| Key Vault | AuditEvent, AzurePolicyEvaluationDetails | AllMetrics | +| Virtual Network | VMProtectionAlerts | AllMetrics | +| Log Analytics | Audit | AllMetrics | + +### Retention and Costs + +| Data Type | Retention | Cost Model | +|-----------|-----------|------------| +| Logs | 90 days | PerGB2018 | +| Metrics | 93 days | Included | +| Activity | 90 days | Free (first 5GB) | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Infrastructure Sizing + +### Resource Sizing Guidelines + +| Resource | Small | Medium | Large | +|----------|-------|--------|-------| +| **DevCenter Projects** | 1-5 | 5-20 | 20+ | +| **Dev Box Pools** | 1-2 per project | 3-5 per project | 5+ per project | +| **Concurrent Dev Boxes** | 10-50 | 50-200 | 200+ | +| **Log Analytics** | 5 GB/day | 10 GB/day | 50+ GB/day | +| **Key Vault Operations** | 1K/month | 10K/month | 100K+/month | + +### Scaling Considerations + +| Component | Scaling Method | Limits | +|-----------|----------------|--------| +| DevCenter | Horizontal (add projects) | 10 projects/DevCenter | +| Pools | Horizontal (add pools) | 5 pools/project | +| Dev Boxes | Auto (pool settings) | Based on quota | +| Network | VNet peering | Regional | +| Key Vault | Automatic | 25K ops/vault/region | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“œ Technology Standards + +### Bicep Coding Standards + +| Standard | Requirement | +|----------|-------------| +| API Versions | Use latest stable or preview as needed | +| Parameters | Use `@description` decorator | +| Secure Values | Use `@secure()` decorator | +| Naming | camelCase for resources, PascalCase for modules | +| Outputs | Document all outputs with descriptions | +| Modules | Single responsibility principle | + +### YAML Configuration Standards + +| Standard | Requirement | +|----------|-------------| +| Schema | All YAML files must reference JSON schema | +| Comments | Document complex configurations | +| Validation | Schema validation in CI/CD | +| Structure | Consistent property ordering | + +### Version Control Standards + +| Standard | Requirement | +|----------|-------------| +| Branching | Feature branches from main | +| Commits | Conventional commits | +| PRs | Required reviews | +| CODEOWNERS | Define for all paths | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— References + +### ๐Ÿ“š Internal References + +- [Business Architecture](01-business-architecture.md) +- [Data Architecture](02-data-architecture.md) +- [Application Architecture](03-application-architecture.md) +- [Security Architecture](05-security-architecture.md) + +### ๐ŸŒ External References + +- [Azure DevCenter Documentation](https://learn.microsoft.com/en-us/azure/dev-box/) +- [Azure Landing Zones](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/landing-zone/) +- [Azure Bicep Documentation](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/) +- [GitHub Actions OIDC](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect) +- [Log Analytics Documentation](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/log-analytics-overview) + +--- + +
+ +[โ† Application Architecture](03-application-architecture.md) | [โฌ†๏ธ Back to Top](#-table-of-contents) | [Security Architecture โ†’](05-security-architecture.md) + +*DevExp-DevBox Landing Zone Accelerator โ€ข Technology Architecture* + +
diff --git a/docs/architecture/05-security-architecture.md b/docs/architecture/05-security-architecture.md new file mode 100644 index 00000000..e22b3748 --- /dev/null +++ b/docs/architecture/05-security-architecture.md @@ -0,0 +1,918 @@ +--- +title: "Security Architecture" +description: "Security controls, identity management, and compliance framework for DevExp-DevBox" +author: "DevExp Team" +date: 2026-01-23 +version: "1.0.0" +tags: + - architecture + - security + - togaf + - rbac + - compliance +--- + +# ๐Ÿ”’ Security Architecture + +> **DevExp-DevBox Landing Zone Accelerator** + +> [!NOTE] +> **Target Audience:** Security Architects, Compliance Officers, Platform Engineers +> **Reading Time:** ~25 minutes + +
+๐Ÿ“ Navigation + +| Previous | Index | Next | +|:---------|:-----:|-----:| +| [โ† Technology Architecture](04-technology-architecture.md) | [Architecture Index](../README.md) | [Deployment Architecture โ†’](07-deployment-architecture.md) | + +
+ +| Property | Value | +|:---------|:------| +| **Version** | 1.0.0 | +| **Last Updated** | 2026-01-23 | +| **Author** | DevExp Team | +| **Status** | Published | + +--- + +## ๐Ÿ“‘ Table of Contents + +- [๐Ÿ“Š Security Overview](#security-overview) +- [โš ๏ธ Threat Model](#threat-model) +- [๐Ÿ”‘ Identity & Access Management](#identity--access-management) +- [๐Ÿ‘ฅ RBAC Hierarchy](#rbac-hierarchy) +- [๐Ÿ” Secrets Management](#secrets-management) +- [๐ŸŒ Network Security](#network-security) +- [๐Ÿ›ก๏ธ Data Protection](#data-protection) +- [โœ… Compliance & Governance](#compliance--governance) +- [๐Ÿ“ถ Security Operations](#security-operations) +- [๐Ÿ“‹ Security Controls Matrix](#security-controls-matrix) +- [๐Ÿ”— References](#references) + +--- + +## ๐Ÿ“Š Security Overview + +The DevExp-DevBox accelerator implements defense-in-depth security principles across all layers: identity, network, data, and application. The security architecture aligns with Azure Security Benchmark and Zero Trust principles. + +### Security Architecture Overview + +```mermaid +--- +title: Security Architecture Overview +--- +flowchart TB + %% ===== EXTERNAL BOUNDARY ===== + subgraph External["๐ŸŒ External Boundary"] + DEV["๐Ÿ‘จโ€๐Ÿ’ป Developers"] + GH["๐Ÿ™ GitHub"] + ADO["๐Ÿ”ท Azure DevOps"] + end + + %% ===== IDENTITY LAYER ===== + subgraph Identity["๐Ÿ” Identity Layer"] + AAD["๐Ÿข Microsoft Entra ID"] + MI["๐Ÿ‘ค Managed Identities"] + OIDC["๐Ÿ”— OIDC Federation"] + end + + %% ===== ACCESS CONTROL LAYER ===== + subgraph Access["๐Ÿ›ก๏ธ Access Control Layer"] + RBAC["๐Ÿ“‹ Azure RBAC"] + KVA["๐Ÿ”‘ Key Vault Access"] + DCA["๐Ÿ–ฅ๏ธ DevCenter Access"] + end + + %% ===== NETWORK LAYER ===== + subgraph Network["๐ŸŒ Network Layer"] + NSG["๐Ÿ›ก๏ธ Network Security Groups"] + VNET["๐Ÿ”— Virtual Network"] + PE["๐Ÿ”’ Private Endpoints"] + end + + %% ===== DATA LAYER ===== + subgraph Data["๐Ÿ’พ Data Layer"] + KV["๐Ÿ”‘ Key Vault
(Secrets)"] + LA["๐Ÿ“Š Log Analytics
(Telemetry)"] + DC["๐Ÿ–ฅ๏ธ DevCenter
(Workloads)"] + end + + %% ===== CONNECTIONS ===== + External -->|authenticates| Identity + Identity -->|authorizes| Access + Access -->|filters| Network + Network -->|protects| Data + + %% ===== STYLES ===== + classDef failed fill:#F44336,stroke:#C62828,color:#FFFFFF + classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + + class DEV,GH,ADO failed + class AAD,MI,OIDC trigger + class RBAC,KVA,DCA datastore + class NSG,VNET,PE primary + class KV,LA,DC secondary + + style External fill:#FEE2E2,stroke:#F44336,stroke-width:2px + style Identity fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style Access fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style Network fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style Data fill:#ECFDF5,stroke:#10B981,stroke-width:2px +``` + +### Security Principles Applied + +| Principle | Implementation | +|-----------|----------------| +| **Least Privilege** | RBAC with minimum required permissions | +| **Defense in Depth** | Multiple security layers | +| **Zero Trust** | Verify explicitly, least privilege access | +| **Separation of Duties** | Distinct landing zones with isolated permissions | +| **Secure by Default** | RBAC authorization, purge protection enabled | +| **Fail Secure** | Soft delete, purge protection on secrets | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš ๏ธ Threat Model + +### STRIDE Analysis + +```mermaid +--- +title: STRIDE Threat Analysis +--- +flowchart TB + %% ===== PROTECTED ASSETS ===== + subgraph Assets["๐ŸŽฏ Protected Assets"] + A1["๐Ÿ”‘ GitHub PAT Tokens"] + A2["๐Ÿ” Azure Credentials"] + A3["๐Ÿ–ฅ๏ธ Dev Box VMs"] + A4["๐Ÿ“‚ Source Code"] + A5["โš™๏ธ Configuration Data"] + end + + %% ===== STRIDE THREATS ===== + subgraph Threats["โš ๏ธ STRIDE Threats"] + T1["๐Ÿ‘ค Spoofing"] + T2["โœ๏ธ Tampering"] + T3["โŒ Repudiation"] + T4["๐Ÿ‘๏ธ Information Disclosure"] + T5["๐Ÿšซ Denial of Service"] + T6["โฌ†๏ธ Elevation of Privilege"] + end + + %% ===== SECURITY CONTROLS ===== + subgraph Mitigations["๐Ÿ›ก๏ธ Security Controls"] + M1["๐Ÿ” OIDC / Managed Identity"] + M2["๐Ÿ“‹ RBAC / Immutable Logs"] + M3["๐Ÿ“ Activity Logs"] + M4["๐Ÿ”‘ Key Vault / Encryption"] + M5["โšก Throttling / Quotas"] + M6["๐Ÿ‘‘ PIM / JIT Access"] + end + + %% ===== CONNECTIONS ===== + T1 -->|mitigated by| M1 + T2 -->|mitigated by| M2 + T3 -->|mitigated by| M3 + T4 -->|mitigated by| M4 + T5 -->|mitigated by| M5 + T6 -->|mitigated by| M6 + + %% ===== STYLES ===== + classDef failed fill:#F44336,stroke:#C62828,color:#FFFFFF + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + + class A1,A2,A3,A4,A5 failed + class T1,T2,T3,T4,T5,T6 datastore + class M1,M2,M3,M4,M5,M6 secondary + + style Assets fill:#FEE2E2,stroke:#F44336,stroke-width:2px + style Threats fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style Mitigations fill:#ECFDF5,stroke:#10B981,stroke-width:2px +``` + +### Threat Categories and Mitigations + +| STRIDE Category | Threat | Risk Level | Mitigation | +|-----------------|--------|------------|------------| +| **Spoofing** | Unauthorized access to DevCenter | High | OIDC federation, no stored secrets | +| **Spoofing** | Impersonation of service principal | High | Managed Identity, certificate auth | +| **Tampering** | Modification of Bicep templates | Medium | Git branch protection, code review | +| **Tampering** | Alteration of Key Vault secrets | High | RBAC, soft delete, purge protection | +| **Repudiation** | Denial of resource changes | Medium | Activity logs, diagnostic settings | +| **Info Disclosure** | PAT token exposure | Critical | Key Vault storage, audit logging | +| **Info Disclosure** | Log data leakage | Medium | RBAC on Log Analytics, retention | +| **DoS** | Resource exhaustion | Medium | Quotas, throttling, monitoring | +| **DoS** | Pipeline disruption | Medium | Retry logic, multiple regions | +| **EoP** | Excessive RBAC permissions | High | Least privilege, regular review | +| **EoP** | DevCenter admin escalation | High | Separate admin/user roles | + +### Attack Surface Diagram + +```mermaid +--- +title: Attack Surface Diagram +--- +flowchart LR + %% ===== EXTERNAL ATTACK SURFACE ===== + subgraph External["๐ŸŒ External Attack Surface"] + A1["๐Ÿ™ GitHub Repository"] + A2["๐Ÿ”„ GitHub Actions"] + A3["๐Ÿ‘จโ€๐Ÿ’ป Developer Endpoints"] + end + + %% ===== INTERNAL ATTACK SURFACE ===== + subgraph Internal["๐Ÿข Internal Attack Surface"] + B1["๐ŸŒ Azure Portal"] + B2["๐Ÿ”‘ Key Vault API"] + B3["๐Ÿ–ฅ๏ธ DevCenter API"] + B4["๐Ÿ–ฅ๏ธ Dev Box RDP"] + end + + %% ===== DATA AT RISK ===== + subgraph Data["๐ŸŽฏ Data at Risk"] + C1["๐Ÿ”‘ PAT Tokens"] + C2["๐Ÿ“‚ Source Code"] + C3["๐Ÿ’พ Dev Box Data"] + end + + %% ===== CONNECTIONS ===== + A1 -->|targets| B1 + A2 -->|targets| B2 + A3 -->|targets| B4 + + B1 -->|accesses| C1 + B2 -->|accesses| C1 + B3 -->|accesses| C2 + B4 -->|accesses| C3 + + %% ===== STYLES ===== + classDef failed fill:#F44336,stroke:#C62828,color:#FFFFFF + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + + class A1,A2,A3 failed + class B1,B2,B3,B4 datastore + class C1,C2,C3 trigger + + style External fill:#FEE2E2,stroke:#F44336,stroke-width:2px + style Internal fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style Data fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”‘ Identity & Access Management + +### Identity Types + +```mermaid +--- +title: Identity Types +--- +flowchart TB + %% ===== USER IDENTITIES ===== + subgraph UserIdentities["๐Ÿ‘ฅ User Identities"] + AAD_USER["๐Ÿ‘ค Azure AD Users"] + AAD_GROUP["๐Ÿ‘ฅ Azure AD Groups"] + end + + %% ===== SERVICE IDENTITIES ===== + subgraph ServiceIdentities["โš™๏ธ Service Identities"] + MI_SYS["๐Ÿ” SystemAssigned
Managed Identity"] + MI_USER["๐Ÿ‘ค UserAssigned
Managed Identity"] + SP["๐Ÿ”— Service Principal
(OIDC Federation)"] + end + + %% ===== RESOURCES ===== + subgraph Resources["๐Ÿข Resources"] + DC["๐Ÿ–ฅ๏ธ DevCenter"] + PROJ["๐Ÿ“ Projects"] + KV["๐Ÿ”‘ Key Vault"] + end + + %% ===== CONNECTIONS ===== + AAD_USER -->|member of| AAD_GROUP + AAD_GROUP -->|RBAC| DC + AAD_GROUP -->|RBAC| PROJ + + MI_SYS -->|assigned to| DC + MI_SYS -->|assigned to| PROJ + + SP -->|GitHub Actions| Resources + MI_SYS -->|DevCenter โ†’ Key Vault| KV + + %% ===== STYLES ===== + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + + class AAD_USER,AAD_GROUP primary + class MI_SYS,MI_USER,SP secondary + class DC,PROJ,KV datastore + + style UserIdentities fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style ServiceIdentities fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Resources fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px +``` + +### Identity Configuration (from devcenter.yaml) + +```yaml +identity: + type: "SystemAssigned" + roleAssignments: + devCenter: + - id: "b24988ac-6180-42a0-ab88-20f7382dd24c" + name: "Contributor" + scope: "Subscription" + - id: "00482a5a-887f-4fb3-b363-3b7fe8e74483" + name: "Key Vault Administrator" + scope: "Subscription" + - id: "4633458b-17de-408a-b874-0445c86b69e6" + name: "Key Vault Secrets User" + scope: "Subscription" +``` + +### Authentication Methods + +| Method | Use Case | Security Level | +|--------|----------|----------------| +| **OIDC Federation** | GitHub Actions โ†’ Azure | High (no stored secrets) | +| **SystemAssigned MI** | DevCenter โ†’ Key Vault | High (automatic rotation) | +| **Azure AD Groups** | User โ†’ DevCenter | High (centralized) | +| **PAT Tokens** | DevCenter โ†’ GitHub | Medium (stored in Key Vault) | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ‘ฅ RBAC Hierarchy + +### Role Assignment Model + +```mermaid +--- +title: RBAC Role Assignment Model +--- +flowchart TB + %% ===== SUBSCRIPTION SCOPE ===== + subgraph Subscription["๐Ÿ“‹ Subscription Scope"] + R1["๐Ÿ”ง Contributor"] + R2["๐Ÿ”‘ Key Vault Administrator"] + R3["๐Ÿ” Key Vault Secrets User"] + end + + %% ===== RESOURCE GROUP SCOPE ===== + subgraph ResourceGroup["๐Ÿ“ Resource Group Scope"] + R4["๐Ÿ–ฅ๏ธ DevCenter Project Admin"] + R5["๐Ÿ“Š Log Analytics Contributor"] + end + + %% ===== RESOURCE SCOPE ===== + subgraph Resource["๐ŸŽฏ Resource Scope"] + R6["๐Ÿ’ป Dev Box User"] + R7["๐ŸŒ Deployment Environments User"] + end + + %% ===== PRINCIPALS ===== + subgraph Principals["๐Ÿ‘ฅ Principals"] + P1["๐Ÿ” DevCenter MI"] + P2["๐Ÿ‘ท Platform Engineering Team"] + P3["๐Ÿ‘จโ€๐Ÿ’ป Project Developers"] + end + + %% ===== CONNECTIONS ===== + P1 -->|assigned| R1 + P1 -->|assigned| R2 + P1 -->|assigned| R3 + + P2 -->|assigned| R4 + P2 -->|assigned| R5 + + P3 -->|assigned| R6 + P3 -->|assigned| R7 + + %% ===== STYLES ===== + classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + + class R1,R2,R3 trigger + class R4,R5 primary + class R6,R7 secondary + class P1,P2,P3 secondary + + style Subscription fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style ResourceGroup fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style Resource fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Principals fill:#ECFDF5,stroke:#10B981,stroke-width:2px +``` + +### Built-in Roles Used + +| Role Name | Role ID | Scope | Assigned To | Purpose | +|-----------|---------|-------|-------------|---------| +| Contributor | `b24988ac-6180-42a0-ab88-20f7382dd24c` | Subscription | DevCenter MI | Resource management | +| Key Vault Administrator | `00482a5a-887f-4fb3-b363-3b7fe8e74483` | Subscription | DevCenter MI | Vault management | +| Key Vault Secrets User | `4633458b-17de-408a-b874-0445c86b69e6` | Subscription | DevCenter MI | Secret read access | +| DevCenter Project Admin | `331c37c6-af14-46d9-b9f4-e1909e1b95a0` | ResourceGroup | Platform Team | Project administration | +| Dev Box User | `45d50f46-0b78-4001-a660-4198cbe8cd05` | Project | Developers | Dev Box access | +| Deployment Environments User | `18e40d4e-8d2e-438d-97e1-9528336e149c` | Project | Developers | Environment access | + +### Organizational Role Types + +From `devcenter.yaml`: + +```yaml +orgRoleTypes: + - type: DevManager + azureADGroupId: "" + azureADGroupName: "Platform Engineering Team" + azureRBACRoles: + - name: "DevCenter Project Admin" + id: "331c37c6-af14-46d9-b9f4-e1909e1b95a0" + scope: ResourceGroup +``` + +### Role Assignment Flow + +```mermaid +--- +title: Role Assignment Flow +--- +sequenceDiagram + participant YAML as ๐Ÿ“„ devcenter.yaml + participant MAIN as ๐Ÿ“„ main.bicep + participant DC as ๐Ÿ–ฅ๏ธ devCenter.bicep + participant RA as ๐Ÿ” roleAssignment.bicep + participant ARM as โ˜๏ธ Azure Resource Manager + participant AAD as ๐Ÿข Microsoft Entra ID + + YAML->>MAIN: Load role configuration + MAIN->>DC: Pass roleAssignments + DC->>RA: Deploy role assignment module + RA->>ARM: Create roleAssignment resource + ARM->>AAD: Validate principal exists + AAD-->>ARM: Principal validated + ARM-->>RA: Role assigned +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ” Secrets Management + +### Secrets Architecture + +```mermaid +--- +title: Secrets Architecture +--- +flowchart TB + %% ===== SECRET SOURCES ===== + subgraph Sources["๐Ÿ”‘ Secret Sources"] + GH_CLI["๐Ÿ™ gh auth token"] + MANUAL["โœ๏ธ Manual Entry"] + AZD_ENV["๐Ÿ“„ .azure/.env"] + end + + %% ===== KEY VAULT ===== + subgraph KeyVault["๐Ÿ›๏ธ Azure Key Vault"] + KV["๐Ÿ” Key Vault Resource"] + + subgraph Settings["โš™๏ธ Security Settings"] + PP["โœ… Purge Protection: Enabled"] + SD["โœ… Soft Delete: Enabled"] + RET["๐Ÿ“… Retention: 7-90 days"] + RBAC["๐Ÿ›ก๏ธ RBAC Authorization: Enabled"] + end + + subgraph Secrets["๐Ÿ”’ Secrets"] + PAT["๐Ÿ”‘ gha-token
(GitHub PAT)"] + end + end + + %% ===== SECRET ACCESS ===== + subgraph Access["๐Ÿ”“ Secret Access"] + MI["๐Ÿ” DevCenter
Managed Identity"] + CAT["๐Ÿ“š Catalog
(Private Repo)"] + end + + %% ===== CONNECTIONS ===== + GH_CLI -->|extracts| AZD_ENV + MANUAL -->|inputs| AZD_ENV + AZD_ENV -->|provision| KV + + KV -->|stores| Secrets + + MI -->|Key Vault Secrets User| PAT + PAT -->|secretIdentifier| CAT + + %% ===== STYLES ===== + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + classDef failed fill:#F44336,stroke:#C62828,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + + class GH_CLI,MANUAL,AZD_ENV datastore + class KV,PP,SD,RET,RBAC,PAT failed + class MI,CAT secondary + + style Sources fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style KeyVault fill:#FEE2E2,stroke:#F44336,stroke-width:2px + style Access fill:#ECFDF5,stroke:#10B981,stroke-width:2px +``` + +### Key Vault Configuration + +```yaml +# From security.yaml +keyVault: + name: contoso + enablePurgeProtection: true + enableSoftDelete: true + softDeleteRetentionInDays: 7 + enableRbacAuthorization: true +``` + +### Secret Lifecycle + +| Phase | Action | Security Control | +|-------|--------|------------------| +| **Creation** | Store PAT in Key Vault | RBAC, encryption at rest | +| **Access** | DevCenter reads via MI | Key Vault Secrets User role | +| **Rotation** | Update secret value | Versioned, old versions retained | +| **Deletion** | Soft delete | Recoverable for retention period | +| **Purge** | Permanent deletion | Purge protection delay | + +### Secret Access Flow + +```mermaid +--- +title: Secret Access Flow +--- +sequenceDiagram + participant DC as ๐Ÿ–ฅ๏ธ DevCenter + participant MI as ๐Ÿ” Managed Identity + participant AAD as ๐Ÿข Microsoft Entra ID + participant KV as ๐Ÿ”‘ Key Vault + participant GH as ๐Ÿ™ GitHub (Private) + + DC->>MI: Request access token + MI->>AAD: Authenticate (SystemAssigned) + AAD-->>MI: Access token + + DC->>KV: GET /secrets/gha-token + Note over DC,KV: Authorization: Bearer {token}
RBAC: Key Vault Secrets User + + KV-->>DC: Secret value (PAT) + + DC->>GH: Clone repository + Note over DC,GH: Authorization: token {PAT} + GH-->>DC: Repository content +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐ŸŒ Network Security + +### Network Security Architecture + +```mermaid +--- +title: Network Security Architecture +--- +flowchart TB + %% ===== INTERNET ===== + subgraph Internet["๐ŸŒ Internet"] + DEV["๐Ÿ‘จโ€๐Ÿ’ป Developer"] + GH["๐Ÿ™ GitHub.com"] + end + + %% ===== AZURE NETWORK SECURITY ===== + subgraph AzureNetwork["๐Ÿ›ก๏ธ Azure Network Security"] + subgraph NSG["๐Ÿ”’ Network Security Group"] + RULE1["โœ… Allow RDP (3389)
from Corporate"] + RULE2["โœ… Allow HTTPS (443)
Outbound"] + RULE3["โŒ Deny All
Default"] + end + + subgraph VNet["๐Ÿ”— Virtual Network"] + SUBNET["๐Ÿ“ถ Dev Box Subnet
10.0.1.0/24"] + end + + subgraph PE["๐Ÿ”’ Private Endpoints"] + KV_PE["๐Ÿ”‘ Key Vault PE
(Optional)"] + LA_PE["๐Ÿ“Š Log Analytics PE
(Optional)"] + end + end + + %% ===== RESOURCES ===== + subgraph Resources["๐Ÿข Azure Resources"] + DB["๐Ÿ–ฅ๏ธ Dev Box"] + KV["๐Ÿ”‘ Key Vault"] + LA["๐Ÿ“Š Log Analytics"] + end + + %% ===== CONNECTIONS ===== + DEV -->|RDP| NSG + NSG -->|allows| SUBNET + SUBNET -->|hosts| DB + + DB -->|HTTPS| GH + DB -->|accesses| PE + PE -->|connects| KV + PE -->|connects| LA + + %% ===== STYLES ===== + 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 + + class DEV,GH external + class RULE1,RULE2,RULE3,SUBNET,KV_PE,LA_PE primary + class DB,KV,LA secondary + + style Internet fill:#F3F4F6,stroke:#6B7280,stroke-width:2px + style AzureNetwork fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style Resources fill:#ECFDF5,stroke:#10B981,stroke-width:2px +``` + +### Network Configuration Options + +| Option | Security Level | Configuration | +|--------|---------------|---------------| +| **Microsoft-Hosted** | Medium | No VNet, default Azure network | +| **Managed VNet** | High | Azure-managed VNet with NSG | +| **Unmanaged VNet** | Highest | Customer VNet with full control | + +### Network Controls (from devcenter.yaml) + +```yaml +network: + name: eShop + create: true + virtualNetworkType: Managed + addressPrefixes: + - "10.0.0.0/16" + subnets: + - name: eShop-subnet + properties: + addressPrefix: 10.0.1.0/24 +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ›ก๏ธ Data Protection + +### Encryption Model + +| Data State | Encryption | Key Management | +|------------|------------|----------------| +| **At Rest (Key Vault)** | AES-256 | Microsoft-managed | +| **At Rest (Log Analytics)** | AES-256 | Microsoft-managed | +| **At Rest (Dev Box)** | BitLocker | Customer option | +| **In Transit** | TLS 1.2+ | Automatic | +| **Secrets** | AES-256 + HSM | Key Vault | + +### Data Classification and Handling + +| Data Type | Classification | Handling Requirements | +|-----------|---------------|----------------------| +| PAT Tokens | Confidential | Key Vault only, audit access | +| Configuration | Internal | Git, no secrets in YAML | +| Telemetry | Internal | Log Analytics, 90-day retention | +| Source Code | Confidential | GitHub, branch protection | +| Dev Box Data | Variable | User responsibility | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โœ… Compliance & Governance + +### Tagging for Governance + +All resources include mandatory tags for compliance: + +```yaml +tags: + environment: dev + division: Platforms + team: DevExP + project: Contoso-DevExp-DevBox + costCenter: IT + owner: Contoso + landingZone: Workload +``` + +### Compliance Controls + +| Control | Implementation | Evidence | +|---------|---------------|----------| +| **Access Control** | Azure RBAC | Role assignments | +| **Audit Logging** | Diagnostic Settings | Activity logs | +| **Data Encryption** | Key Vault, TLS | Configuration | +| **Network Security** | NSG, VNet | Network rules | +| **Secret Management** | Key Vault + RBAC | Vault policies | +| **Change Management** | Git + CI/CD | Commit history | + +### Regulatory Alignment + +| Framework | Relevant Controls | +|-----------|-------------------| +| Azure Security Benchmark | NS-1, NS-2, IM-1, IM-2, PA-1, PA-7, DP-3, DP-5 | +| CIS Azure Benchmark | 1.x (IAM), 4.x (Storage), 8.x (Key Vault) | +| SOC 2 | CC6 (Logical Access), CC7 (System Operations) | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ถ Security Operations + +### Security Monitoring + +```mermaid +--- +title: Security Monitoring Architecture +--- +flowchart TB + %% ===== AUDIT SOURCES ===== + subgraph Sources["๐Ÿ“ก Audit Sources"] + KV_AUDIT["๐Ÿ”‘ Key Vault
AuditEvent"] + AAD_AUDIT["๐Ÿข Azure AD
Sign-in Logs"] + ACT_LOG["๐Ÿ“‹ Activity Log"] + DC_LOG["๐Ÿ–ฅ๏ธ DevCenter
Diagnostics"] + end + + %% ===== LOG ANALYTICS ===== + subgraph Collection["๐Ÿ“Š Log Analytics"] + LA["๐Ÿ“ˆ Workspace"] + TABLES["๐Ÿ“‹ Security Tables"] + end + + %% ===== DETECTION ===== + subgraph Detection["๐Ÿ” Detection"] + RULES["๐Ÿ”” Alert Rules"] + SENT["๐Ÿ›ก๏ธ Microsoft Sentinel
(Optional)"] + end + + %% ===== RESPONSE ===== + subgraph Response["๐Ÿšจ Response"] + EMAIL["๐Ÿ“ง Email Notifications"] + TICKET["๐ŸŽซ Service Tickets"] + AUTO["โšก Automation"] + end + + %% ===== CONNECTIONS ===== + Sources -->|ingests| Collection + Collection -->|analyzes| Detection + Detection -->|triggers| Response + + %% ===== STYLES ===== + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + + class KV_AUDIT,AAD_AUDIT,ACT_LOG,DC_LOG datastore + class LA,TABLES primary + class RULES,SENT trigger + class EMAIL,TICKET,AUTO secondary + + style Sources fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style Collection fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style Detection fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style Response fill:#ECFDF5,stroke:#10B981,stroke-width:2px +``` + +### Recommended Alerts + +| Alert | Condition | Severity | +|-------|-----------|----------| +| Key Vault Secret Access | Unexpected principal access | High | +| Failed RBAC Assignment | Permission denied | Medium | +| DevCenter Admin Change | Role assignment modification | High | +| Network Rule Change | NSG modification | Medium | +| Resource Deletion | Critical resource deleted | High | + +### Incident Response + +| Phase | Actions | +|-------|---------| +| **Detection** | Alert triggered, Log Analytics query | +| **Analysis** | Review activity logs, identify scope | +| **Containment** | Revoke access, rotate secrets | +| **Eradication** | Remove threat, patch vulnerability | +| **Recovery** | Restore service, verify security | +| **Lessons Learned** | Update runbooks, improve controls | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“‹ Security Controls Matrix + +### Control Implementation Summary + +| Domain | Control | Implementation | Status | +|--------|---------|----------------|--------| +| **Identity** | | | | +| | Authentication | OIDC Federation, Managed Identity | โœ… Implemented | +| | Authorization | Azure RBAC | โœ… Implemented | +| | MFA | Azure AD Conditional Access | โš™๏ธ Configure | +| | PIM | Privileged Identity Management | โš™๏ธ Configure | +| **Network** | | | | +| | Segmentation | Virtual Network, Subnets | โœ… Implemented | +| | Filtering | NSG Rules | โœ… Implemented | +| | Private Access | Private Endpoints | โš™๏ธ Optional | +| **Data** | | | | +| | Encryption at Rest | Key Vault, Storage | โœ… Implemented | +| | Encryption in Transit | TLS 1.2 | โœ… Implemented | +| | Key Management | Key Vault | โœ… Implemented | +| **Logging** | | | | +| | Audit Logs | Activity Log | โœ… Implemented | +| | Diagnostic Logs | Log Analytics | โœ… Implemented | +| | Retention | 90 days default | โœ… Implemented | +| **Governance** | | | | +| | Tagging | Mandatory tags | โœ… Implemented | +| | Policy | Azure Policy | โš™๏ธ Configure | +| | Compliance | ASB alignment | โœ… Documented | + +### Legend + +| Symbol | Meaning | +|--------|---------| +| โœ… | Fully implemented | +| โš™๏ธ | Requires additional configuration | +| โŒ | Not implemented | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— References + +### ๐Ÿ“š Internal References + +- [Business Architecture](01-business-architecture.md) +- [Data Architecture](02-data-architecture.md) +- [Application Architecture](03-application-architecture.md) +- [Technology Architecture](04-technology-architecture.md) + +### ๐ŸŒ External References + +- [Azure Security Benchmark](https://learn.microsoft.com/en-us/security/benchmark/azure/overview) +- [Azure Key Vault Security](https://learn.microsoft.com/en-us/azure/key-vault/general/security-features) +- [Azure DevCenter Security](https://learn.microsoft.com/en-us/azure/dev-box/concept-dev-box-security) +- [GitHub Actions Security](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions) +- [Zero Trust Architecture](https://learn.microsoft.com/en-us/security/zero-trust/) +- [STRIDE Threat Model](https://learn.microsoft.com/en-us/azure/security/develop/threat-modeling-tool-threats) + +--- + +
+ +[โ† Technology Architecture](04-technology-architecture.md) | [โฌ†๏ธ Back to Top](#-table-of-contents) | [Deployment Architecture โ†’](07-deployment-architecture.md) + +*DevExp-DevBox Landing Zone Accelerator โ€ข Security Architecture* + +
diff --git a/docs/architecture/07-deployment-architecture.md b/docs/architecture/07-deployment-architecture.md new file mode 100644 index 00000000..ccefaecb --- /dev/null +++ b/docs/architecture/07-deployment-architecture.md @@ -0,0 +1,502 @@ +--- +title: "Deployment Architecture" +description: "CI/CD pipeline design and deployment patterns for DevExp-DevBox Landing Zone Accelerator" +author: "DevExp Team" +date: 2026-01-23 +version: "1.0.0" +tags: + - architecture + - deployment + - cicd + - github-actions + - azure +--- + +# ๐Ÿš€ Deployment Architecture + +> ๐Ÿ“– This document describes the deployment architecture and CI/CD pipeline design for the Dev Box Accelerator project. + +> [!NOTE] +> **Target Audience:** DevOps Engineers, Platform Engineers, Release Managers +> **Reading Time:** ~15 minutes + +
+๐Ÿ“ Navigation + +| Previous | Index | Next | +|:---------|:-----:|-----:| +| [โ† Security Architecture](05-security-architecture.md) | [Architecture Index](../README.md) | โ€” | + +
+ +--- + +## ๐Ÿ“‘ Table of Contents + +- [๐ŸŽฏ Overview](#overview) +- [๐Ÿ—๏ธ High-Level Architecture](#high-level-architecture) +- [๐Ÿ”„ Pipeline Architecture](#pipeline-architecture) +- [๐ŸŒ Deployment Environments](#deployment-environments) +- [๐Ÿ”’ Security Architecture](#security-architecture) +- [๐Ÿ“ฆ Infrastructure Components](#infrastructure-components) +- [๐Ÿ’พ Artifact Management](#artifact-management) +- [๐Ÿ› ๏ธ Deployment Process](#deployment-process) +- [๐Ÿ“ถ Monitoring & Observability](#monitoring--observability) +- [๐Ÿ”— Related Documentation](#related-documentation) + +--- + +## ๐ŸŽฏ Overview + +The Dev Box Accelerator uses a modern GitOps-style deployment approach with GitHub Actions for continuous integration and continuous deployment (CI/CD). The infrastructure is defined as code using Bicep templates and deployed to Azure using the Azure Developer CLI (azd). + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ—๏ธ High-Level Architecture + +```mermaid +flowchart TB + subgraph "๐Ÿ‘จโ€๐Ÿ’ป Development" + DEV1["Developer Workstation"] + DEV2["VS Code + Bicep Extension"] + DEV1 --> DEV2 + end + + subgraph "๐Ÿ“ฆ Source Control" + GH1["GitHub Repository"] + GH2["Branch Strategy"] + GH3["Pull Requests"] + GH1 --> GH2 + GH2 --> GH3 + end + + subgraph "๐Ÿ”„ CI/CD Pipeline" + direction TB + CI["๐Ÿ”จ CI Workflow"] + RELEASE["๐Ÿท๏ธ Release Workflow"] + DEPLOY["๐Ÿš€ Deploy Workflow"] + end + + subgraph "โ˜๏ธ Azure" + direction TB + SUB["Azure Subscription"] + RG["Resource Groups"] + DC["Dev Center"] + KV["Key Vault"] + VNET["Virtual Network"] + SUB --> RG + RG --> DC & KV & VNET + end + + DEV2 --> |"git push"| GH1 + GH2 --> |"feature/fix branches"| CI + GH3 --> |"PR to main"| CI + GH1 --> |"manual trigger"| RELEASE + GH1 --> |"manual trigger"| DEPLOY + DEPLOY --> |"azd provision"| SUB + + classDef dev fill:#E3F2FD,stroke:#1565C0,color:#000 + classDef gh fill:#F3E5F5,stroke:#6A1B9A,color:#000 + classDef cicd fill:#FFF3E0,stroke:#EF6C00,color:#000 + classDef azure fill:#E8F5E9,stroke:#2E7D32,color:#000 + + class DEV1,DEV2 dev + class GH1,GH2,GH3 gh + class CI,RELEASE,DEPLOY cicd + class SUB,RG,DC,KV,VNET azure +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”„ Pipeline Architecture + +### Workflow Relationships + +```mermaid +flowchart LR + subgraph "Trigger Events" + T1([Push to feature/**]) + T2([Push to fix/**]) + T3([PR to main]) + T4([Manual Dispatch]) + end + + subgraph "Workflows" + direction TB + W1["ci.yml
Continuous Integration"] + W2["release.yml
Branch-Based Release"] + W3["deploy.yml
Deploy to Azure"] + end + + subgraph "Artifacts & Outputs" + A1[/"Versioned Artifacts"/] + A2[/"GitHub Release"/] + A3[(Azure Resources)] + end + + T1 & T2 --> W1 + T3 --> W1 + T4 --> W2 + T4 --> W3 + + W1 --> A1 + W2 --> A1 + W2 --> A2 + W3 --> A3 + + classDef trigger fill:#2196F3,stroke:#1565C0,color:#fff + classDef workflow fill:#FF9800,stroke:#EF6C00,color:#fff + classDef artifact fill:#4CAF50,stroke:#2E7D32,color:#fff + + class T1,T2,T3,T4 trigger + class W1,W2,W3 workflow + class A1,A2,A3 artifact +``` + +### Detailed CI/CD Flow + +```mermaid +sequenceDiagram + participant Dev as Developer + participant GH as GitHub + participant CI as CI Workflow + participant Release as Release Workflow + participant Deploy as Deploy Workflow + participant Azure as Azure + + rect rgb(227, 242, 253) + Note over Dev,GH: Feature Development + Dev->>GH: Push to feature/** branch + GH->>CI: Trigger CI workflow + CI->>CI: Generate version tag + CI->>CI: Build Bicep templates + CI->>GH: Upload artifacts + end + + rect rgb(243, 229, 245) + Note over Dev,GH: Pull Request + Dev->>GH: Create PR to main + GH->>CI: Trigger CI workflow + CI->>CI: Validate & build + CI-->>GH: PR check status + end + + rect rgb(255, 243, 224) + Note over GH,Release: Release Creation + Dev->>Release: Manual trigger + Release->>Release: Calculate version + Release->>Release: Build artifacts + Release->>GH: Create GitHub Release + end + + rect rgb(232, 245, 233) + Note over Deploy,Azure: Deployment + Dev->>Deploy: Manual trigger + Deploy->>Deploy: Build Bicep + Deploy->>Azure: OIDC Authentication + Deploy->>Azure: azd provision + Azure-->>Deploy: Deployment status + end +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐ŸŒ Deployment Environments + +### Environment Strategy + +| Environment | Trigger | Purpose | Approval Required | +|-------------|---------|---------|-------------------| +| `dev` | Manual | Development testing | No | +| `staging` | Manual | Pre-production validation | Optional | +| `prod` | Manual | Production deployment | Yes (recommended) | + +### Environment Configuration + +```mermaid +flowchart TB + subgraph "GitHub Environments" + direction LR + ENV1["dev"] + ENV2["staging"] + ENV3["prod"] + end + + subgraph "Azure Subscriptions" + direction LR + SUB1["Dev Subscription"] + SUB2["Staging Subscription"] + SUB3["Prod Subscription"] + end + + ENV1 --> |OIDC| SUB1 + ENV2 --> |OIDC| SUB2 + ENV3 --> |OIDC| SUB3 + + classDef env fill:#2196F3,stroke:#1565C0,color:#fff + classDef azure fill:#4CAF50,stroke:#2E7D32,color:#fff + + class ENV1,ENV2,ENV3 env + class SUB1,SUB2,SUB3 azure +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”’ Security Architecture + +### Authentication Flow + +```mermaid +flowchart LR + subgraph "GitHub Actions" + GH1["Workflow Run"] + GH2["Request OIDC Token"] + end + + subgraph "Azure AD" + AD1["Validate Token"] + AD2["Issue Access Token"] + AD3["Federated Credential"] + end + + subgraph "Azure Resources" + AZ1["Subscription"] + AZ2["Resource Group"] + end + + GH1 --> GH2 + GH2 --> |"JWT"| AD1 + AD1 --> AD3 + AD3 --> AD2 + AD2 --> |"Bearer Token"| AZ1 + AZ1 --> AZ2 + + classDef github fill:#24292E,stroke:#1B1F23,color:#fff + classDef azure fill:#0078D4,stroke:#005A9E,color:#fff + + class GH1,GH2 github + class AD1,AD2,AD3,AZ1,AZ2 azure +``` + +### Security Controls + +| Control | Implementation | Purpose | +|---------|----------------|---------| +| OIDC Authentication | Federated credentials | No stored secrets | +| Action Pinning | SHA commit references | Supply chain security | +| Least Privilege | Minimal permissions | Reduced attack surface | +| Concurrency Control | Job grouping | Prevent race conditions | +| Environment Protection | GitHub Environments | Approval gates | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ฆ Infrastructure Components + +### Bicep Module Structure + +```mermaid +flowchart TB + subgraph "Entry Point" + MAIN["main.bicep"] + end + + subgraph "src/workload" + W1["workload.bicep"] + W2["core/devCenter.bicep"] + W3["core/catalog.bicep"] + W4["core/environmentType.bicep"] + W5["project/project.bicep"] + W6["project/projectPool.bicep"] + end + + subgraph "src/connectivity" + C1["connectivity.bicep"] + C2["vnet.bicep"] + C3["networkConnection.bicep"] + end + + subgraph "src/security" + S1["security.bicep"] + S2["keyVault.bicep"] + S3["secret.bicep"] + end + + subgraph "src/identity" + I1["devCenterRoleAssignment.bicep"] + I2["projectIdentityRoleAssignment.bicep"] + end + + MAIN --> W1 & C1 & S1 & I1 + W1 --> W2 & W3 & W4 & W5 & W6 + C1 --> C2 & C3 + S1 --> S2 & S3 + + classDef main fill:#F44336,stroke:#C62828,color:#fff + classDef workload fill:#2196F3,stroke:#1565C0,color:#fff + classDef connectivity fill:#4CAF50,stroke:#2E7D32,color:#fff + classDef security fill:#FF9800,stroke:#EF6C00,color:#fff + classDef identity fill:#9C27B0,stroke:#6A1B9A,color:#fff + + class MAIN main + class W1,W2,W3,W4,W5,W6 workload + class C1,C2,C3 connectivity + class S1,S2,S3 security + class I1,I2 identity +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ’พ Artifact Management + +### Artifact Flow + +```mermaid +flowchart LR + subgraph "Build Stage" + B1["Bicep Source"] + B2["az bicep build"] + B3["ARM Templates"] + B1 --> B2 --> B3 + end + + subgraph "Storage" + S1["GitHub Artifacts
30-day retention"] + S2["GitHub Releases
Permanent"] + end + + subgraph "Deployment" + D1["azd provision"] + D2["Azure Resources"] + D1 --> D2 + end + + B3 --> S1 + B3 --> S2 + S1 --> D1 + S2 --> D1 + + classDef build fill:#FF9800,stroke:#EF6C00,color:#fff + classDef storage fill:#2196F3,stroke:#1565C0,color:#fff + classDef deploy fill:#4CAF50,stroke:#2E7D32,color:#fff + + class B1,B2,B3 build + class S1,S2 storage + class D1,D2 deploy +``` + +### Versioning Scheme + +| Component | Format | Example | +|-----------|--------|---------| +| Main releases | `v{major}.{minor}.{patch}` | `v1.2.3` | +| Feature builds | `v{major}.{minor}.{patch}-feature.{name}` | `v1.2.4-feature.auth` | +| Fix builds | `v{major}.{minor}.{patch}-fix.{name}` | `v1.3.0-fix.security` | +| PR builds | `v{major}.{minor}.{patch}-{type}-pr{number}` | `v1.2.4-feature.auth-pr123` | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ› ๏ธ Deployment Process + +### Pre-Deployment Checklist + +- [ ] Azure subscription configured with OIDC federation +- [ ] GitHub repository variables set (`AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_SUBSCRIPTION_ID`) +- [ ] GitHub secrets configured (`KEY_VAULT_SECRET`) +- [ ] Target region validated for resource availability +- [ ] Environment protection rules configured (optional) + +### Deployment Steps + +1. **Trigger Deployment** + - Navigate to Actions โ†’ Deploy to Azure + - Select environment and region + - Run workflow + +2. **Build Phase** + - Validates Azure configuration + - Compiles Bicep templates + - Uploads build artifacts + +3. **Authentication** + - Requests OIDC token from GitHub + - Exchanges for Azure access token + - Authenticates with azd CLI + +4. **Provision** + - Runs `azd provision` + - Creates/updates Azure resources + - Generates deployment summary + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ถ Monitoring & Observability + +### Workflow Monitoring + +| Metric | Location | Purpose | +|--------|----------|---------| +| Workflow runs | GitHub Actions | Pipeline execution history | +| Job duration | GitHub Actions | Performance tracking | +| Step summaries | GitHub Actions | Detailed execution logs | +| Deployment status | Azure Portal | Resource provisioning status | + +### Recommended Alerts + +- Workflow failure notifications +- Long-running deployment alerts +- Azure resource health monitoring + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Related Documentation + +- [DevOps Workflows](../devops/README.md) - Detailed workflow documentation +- [CI Workflow](../devops/ci.md) - Continuous integration details +- [Deploy Workflow](../devops/deploy.md) - Deployment process +- [Release Workflow](../devops/release.md) - Release management + +--- + +
+ +[โ† Security Architecture](05-security-architecture.md) | [โฌ†๏ธ Back to Top](#-table-of-contents) + +*DevExp-DevBox Landing Zone Accelerator โ€ข Deployment Architecture* + +
diff --git a/docs/devops/README.md b/docs/devops/README.md new file mode 100644 index 00000000..fd7e34bc --- /dev/null +++ b/docs/devops/README.md @@ -0,0 +1,338 @@ +--- +title: "DevOps Documentation" +description: "Comprehensive documentation for GitHub Actions workflows in the Dev Box Accelerator project" +author: "DevExp Team" +date: 2026-01-23 +version: "1.0.0" +tags: + - devops + - github-actions + - cicd + - workflows +--- + +# ๐Ÿ”„ DevOps Documentation + +> [!TIP] +> ๐Ÿ“– **Comprehensive documentation** for GitHub Actions workflows in the Dev Box Accelerator project. This guide covers CI/CD pipelines, deployment automation, and release management. + +> [!NOTE] +> **Target Audience:** DevOps Engineers, Platform Engineers, CI/CD Administrators +> **Reading Time:** ~10 minutes + +
+๐Ÿ“ Navigation + +| Previous | Index | Next | +|:---------|:-----:|-----:| +| โ€” | [Docs Index](../README.md) | [CI Workflow โ†’](ci.md) | + +
+ +--- + +## ๐Ÿ“‘ Table of Contents + +- [๐ŸŽฏ Overview](#-overview) +- [๐Ÿ—๏ธ Master Pipeline Architecture](#%EF%B8%8F-master-pipeline-architecture) +- [๐Ÿ“š Workflow Documentation](#-workflow-documentation) +- [โšก Quick Reference](#-quick-reference) +- [๐Ÿ”„ Reusable Components](#-reusable-components) +- [๐Ÿท๏ธ Versioning Strategy](#%EF%B8%8F-versioning-strategy) +- [โœ… Best Practices](#-best-practices) +- [๐Ÿ”— Related Documentation](#-related-documentation) + +--- + +## ๐ŸŽฏ Overview + +This folder contains detailed documentation for all CI/CD workflows that automate the build, test, and deployment processes for the Dev Box Accelerator infrastructure-as-code project. + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ—๏ธ Master Pipeline Architecture + +The following diagram shows the complete CI/CD pipeline architecture and how all workflows relate to each other: + +```mermaid +--- +title: Master Pipeline Architecture +--- +flowchart TB + %% ===== TRIGGERS ===== + subgraph Triggers["๐ŸŽฏ Triggers"] + direction LR + T1(["๐ŸŒฟ Push: feature/**"]) + T2(["๐Ÿ”ง Push: fix/**"]) + T3(["๐Ÿ“ PR to main"]) + T4(["๐Ÿ–ฑ๏ธ Manual: Deploy"]) + T5(["๐Ÿ–ฑ๏ธ Manual: Release"]) + end + + %% ===== CONTINUOUS INTEGRATION ===== + subgraph CI["๐Ÿ”„ Continuous Integration"] + direction TB + CI1["๐Ÿ“Š generate-tag-version"] + CI2["๐Ÿ”จ build"] + CI1 -->|calculates| CI2 + end + + %% ===== DEPLOYMENT ===== + subgraph Deployment["๐Ÿš€ Deployment"] + direction TB + D1["โœ… Validate Variables"] + D2["๐Ÿ”จ Build Bicep"] + D3["๐Ÿ” Azure OIDC Auth"] + D4["โ˜๏ธ azd provision"] + D1 -->|validates| D2 -->|authenticates| D3 -->|provisions| D4 + end + + %% ===== RELEASE ===== + subgraph Release["๐Ÿท๏ธ Release"] + direction TB + R1["๐Ÿ“Š generate-release"] + R2["๐Ÿ”จ build"] + R3["๐ŸŽ‰ publish-release"] + R4["๐Ÿ“‹ summary"] + R1 -->|prepares| R2 -->|publishes| R3 -->|summarizes| R4 + end + + %% ===== OUTPUTS ===== + subgraph Outputs["๐Ÿ“ฆ Outputs"] + direction TB + O1[/"โœ… Versioned Artifacts"/] + O2[/"๐Ÿท๏ธ GitHub Release"/] + O3[("โ˜๏ธ Azure Resources")] + end + + %% ===== CONNECTIONS ===== + T1 & T2 & T3 -->|triggers| CI1 + T4 -->|triggers| D1 + T5 -->|triggers| R1 + + CI2 -->|produces| O1 + R3 -->|creates| O1 + R3 -->|creates| O2 + D4 -->|provisions| O3 + + %% ===== STYLES ===== + classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + classDef external fill:#6B7280,stroke:#4B5563,color:#FFFFFF,stroke-dasharray:5 5 + + class T1,T2,T3,T4,T5 trigger + class CI1,CI2 primary + class D1,D2,D3,D4 secondary + class R1,R2,R3,R4 datastore + class O1,O2,O3 external + + %% ===== SUBGRAPH STYLES ===== + style Triggers fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style CI fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style Deployment fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Release fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style Outputs fill:#F3F4F6,stroke:#6B7280,stroke-width:2px +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“š Workflow Documentation + +| Workflow | File | Purpose | Trigger | +|----------|------|---------|---------| +| [Continuous Integration](ci.md) | `ci.yml` | Builds and validates Bicep templates | Push to `feature/**`, `fix/**`; PRs to `main` | +| [Deploy to Azure](deploy.md) | `deploy.yml` | Provisions infrastructure to Azure | Manual (`workflow_dispatch`) | +| [Branch-Based Release](release.md) | `release.yml` | Creates GitHub releases with versioned artifacts | Manual (`workflow_dispatch`) | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โšก Quick Reference + +### Trigger Summary + +```mermaid +--- +title: Trigger Summary +--- +flowchart LR + %% ===== AUTOMATIC TRIGGERS ===== + subgraph AutoTriggers["๐Ÿ”„ Automatic Triggers"] + A1["๐ŸŒฟ Push to feature/**"] -->|triggers| CI["๐Ÿ“Š CI Workflow"] + A2["๐Ÿ”ง Push to fix/**"] -->|triggers| CI + A3["๐Ÿ“ PR to main"] -->|triggers| CI + end + + %% ===== MANUAL TRIGGERS ===== + subgraph ManualTriggers["๐Ÿ–ฑ๏ธ Manual Triggers"] + M1["๐Ÿ–ฑ๏ธ workflow_dispatch"] -->|triggers| DEPLOY["๐Ÿš€ Deploy Workflow"] + M2["๐Ÿ–ฑ๏ธ workflow_dispatch"] -->|triggers| RELEASE["๐Ÿท๏ธ Release Workflow"] + end + + %% ===== STYLES ===== + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + + class A1,A2,A3 secondary + class M1,M2 trigger + class CI,DEPLOY,RELEASE datastore + + %% ===== SUBGRAPH STYLES ===== + style AutoTriggers fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style ManualTriggers fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px +``` + +### Required Secrets & Variables + +| Name | Type | Used By | Description | +|------|------|---------|-------------| +| `AZURE_CLIENT_ID` | Variable | Deploy | Azure AD App Registration Client ID | +| `AZURE_TENANT_ID` | Variable | Deploy | Azure AD Tenant ID | +| `AZURE_SUBSCRIPTION_ID` | Variable | Deploy | Target Azure Subscription | +| `KEY_VAULT_SECRET` | Secret | Deploy | Key Vault secret value | +| `GITHUB_TOKEN` | Secret (Auto) | Release | Auto-provided for GitHub API access | + +### Permissions Matrix + +| Permission | CI | Deploy | Release | Purpose | +|------------|:--:|:------:|:-------:|---------| +| `contents: write` | โœ… | โŒ | โœ… | Create tags and releases | +| `contents: read` | โœ… | โœ… | โœ… | Checkout repository | +| `pull-requests: read` | โœ… | โŒ | โœ… | Access PR information | +| `id-token: write` | โŒ | โœ… | โŒ | OIDC authentication | +| `actions: read` | โŒ | โŒ | โœ… | Workflow introspection | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”„ Reusable Components + +### Composite Actions + +| Action | Location | Purpose | +|--------|----------|---------| +| Bicep Standard CI | `.github/actions/ci/bicep-standard-ci` | Builds Bicep templates and uploads artifacts | +| Generate Release | `.github/actions/ci/generate-release` | Calculates semantic versions based on branch strategy | + +### Action Flow + +```mermaid +--- +title: Reusable Actions Flow +--- +flowchart LR + %% ===== GENERATE RELEASE ACTION ===== + subgraph GenerateRelease["๐Ÿท๏ธ generate-release"] + GR1["๐Ÿ“‹ Get Branch Info"] + GR2["๐Ÿท๏ธ Get Latest Tag"] + GR3["๐Ÿ” Determine Release Type"] + GR4["๐Ÿ“Š Count Commits"] + GR5["๐Ÿ”ข Calculate Version"] + GR6["๐Ÿท๏ธ Create Tag"] + GR1 -->|gets| GR2 -->|determines| GR3 -->|counts| GR4 -->|calculates| GR5 -->|creates| GR6 + end + + %% ===== BICEP STANDARD CI ACTION ===== + subgraph BicepCI["๐Ÿ”จ bicep-standard-ci"] + BC1["๐Ÿ“ฆ Build Bicep"] + BC2["๐Ÿ“ค Upload Artifacts"] + BC3["๐Ÿ“Š Generate Summary"] + BC1 -->|uploads| BC2 -->|summarizes| BC3 + end + + %% ===== STYLES ===== + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + + class GR1,GR2,GR3,GR4,GR5,GR6 primary + class BC1,BC2,BC3 secondary + + %% ===== SUBGRAPH STYLES ===== + style GenerateRelease fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style BicepCI fill:#ECFDF5,stroke:#10B981,stroke-width:2px +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿท๏ธ Versioning Strategy + +The project uses a **branch-based semantic versioning** strategy: + +| Branch | Version Behavior | Example | +|--------|------------------|---------| +| `main` | Conditional major increment | `v2.0.0` | +| `feature/**` | Patch increment + suffix | `v1.2.4-feature.auth` | +| `fix/**` | Minor increment + suffix | `v1.3.0-fix.security` | + +### Version Overflow Handling + +- **Patch > 99**: Resets to 0, increments minor +- **Minor > 99**: Resets to 0, increments major + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โœ… Best Practices + +### Security + +> [!IMPORTANT] +> Security is a top priority. All workflows follow GitHub's security hardening guidelines. + +- โœ… All actions pinned to SHA commits for supply chain security +- โœ… OIDC authentication used for Azure (no long-lived secrets) +- โœ… Least-privilege permissions configured per workflow +- โœ… Concurrency controls prevent conflicting operations + +### Reliability + +- โœ… Timeout limits set on all jobs +- โœ… Comprehensive error handling and validation +- โœ… Step summaries for visibility into workflow execution +- โœ… Artifact retention policies configured + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Related Documentation + +- [Deployment Architecture](../architecture/07-deployment-architecture.md) - Infrastructure deployment patterns +- [Azure Developer CLI](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/) - Tool used for deployments +- [GitHub Actions Security](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions) - Security best practices + +--- + +
+ +[โฌ†๏ธ Back to Top](#-devops-documentation) | [CI Workflow โ†’](ci.md) + +*DevExp-DevBox โ€ข DevOps Documentation* + +
diff --git a/docs/devops/ci.md b/docs/devops/ci.md new file mode 100644 index 00000000..4c8866c3 --- /dev/null +++ b/docs/devops/ci.md @@ -0,0 +1,290 @@ +--- +title: "Continuous Integration Workflow" +description: "CI workflow documentation for validating and building Bicep templates" +author: "DevExp Team" +date: 2026-01-23 +version: "1.0.0" +tags: + - devops + - ci + - github-actions + - bicep +--- + +# ๐Ÿ”„ Continuous Integration Workflow + +> [!NOTE] +> **Target Audience:** DevOps Engineers, Platform Engineers +> **Reading Time:** ~8 minutes + +
+๐Ÿ“ Navigation + +| Previous | Index | Next | +|:---------|:-----:|-----:| +| [โ† DevOps Overview](README.md) | [DevOps Index](README.md) | [Deploy Workflow โ†’](deploy.md) | + +
+ +--- + +## ๐Ÿ“‘ Table of Contents + +- [๐ŸŽฏ Overview](#-overview) +- [๐Ÿ“Š Pipeline Visualization](#-pipeline-visualization) +- [๐ŸŽฏ Triggers](#-triggers) +- [โš™๏ธ Jobs & Steps](#%EF%B8%8F-jobs--steps) +- [๐Ÿ” Prerequisites](#-prerequisites) +- [๐Ÿท๏ธ Versioning Strategy](#%EF%B8%8F-versioning-strategy) +- [๐Ÿ“ฆ Artifacts](#-artifacts) +- [๐Ÿ”ง Troubleshooting](#-troubleshooting) +- [๐Ÿ”— Related Documentation](#-related-documentation) + +--- + +## ๐ŸŽฏ Overview + +The **Continuous Integration (CI)** workflow validates and builds Bicep templates for the Dev Box Accelerator project. It runs automatically on feature and fix branches, as well as pull requests to the main branch, ensuring code quality before merging. + +> [!TIP] +> This workflow is the first line of defense for code quality. It automatically validates your infrastructure code before it can be merged to main. + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“Š Pipeline Visualization + +```mermaid +--- +title: CI Pipeline Visualization +--- +flowchart TD + %% ===== TRIGGERS ===== + subgraph Triggers["๐ŸŽฏ Triggers"] + T1(["๐ŸŒฟ Push to feature/**"]) + T2(["๐Ÿ”ง Push to fix/**"]) + T3(["๐Ÿ“ PR to main"]) + end + + %% ===== GENERATE TAG VERSION JOB ===== + subgraph GenerateTag["๐Ÿ“Š generate-tag-version"] + direction TB + GTV1["๐Ÿ”„ Checkout Repository"] + GTV2["๐Ÿท๏ธ Generate Release Information"] + GTV3[/"๐Ÿ“ฆ new_version, release_type, previous_tag"/] + GTV1 -->|clones| GTV2 -->|outputs| GTV3 + end + + %% ===== BUILD JOB ===== + subgraph Build["๐Ÿ”จ build"] + direction TB + B1["๐Ÿ”„ Checkout Repository"] + B2["๐Ÿ“ฆ Build Bicep Code"] + B3[/"โœ… Versioned Artifacts"/] + B1 -->|clones| B2 -->|produces| B3 + end + + %% ===== CONNECTIONS ===== + T1 & T2 & T3 -->|triggers| GTV1 + GTV3 -->|success| B1 + GTV3 -.->|failure| SKIP((โญ๏ธ Skipped)) + + %% ===== STYLES ===== + classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + classDef external fill:#6B7280,stroke:#4B5563,color:#FFFFFF,stroke-dasharray:5 5 + + class T1,T2,T3 trigger + class GTV1,GTV2,B1,B2 primary + class GTV3,B3 secondary + class SKIP external + + %% ===== SUBGRAPH STYLES ===== + style Triggers fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style GenerateTag fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style Build fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐ŸŽฏ Triggers + +| Trigger Type | Condition | Description | +| -------------- | -------------------------------------------- | ------------------------------------------------ | +| `push` | Branches: `feature/**`, `fix/**` | Runs on every push to feature or fix branches | +| `pull_request` | Target: `main`, Types: opened, synchronize, reopened | Runs on PRs targeting the main branch | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Jobs & Steps + +### Job: `generate-tag-version` + +**Purpose:** Calculate semantic version based on branch and commit history. + +| Property | Value | +| ---------------- | --------------- | +| **Runner** | `ubuntu-latest` | +| **Timeout** | 10 minutes | +| **Dependencies** | None | + +#### Steps + +| Step | Name | Description | +| ---- | ------------------------------ | ---------------------------------------------------------- | +| 1 | Checkout Repository | Clones the repository with full history (`fetch-depth: 0`) | +| 2 | Generate Release Information | Uses composite action `.github/actions/ci/generate-release` to calculate version | + +#### Outputs + +| Output | Description | +| ---------------- | -------------------------------------------------------- | +| `new_version` | The new semantic version (e.g., `v1.2.3`) | +| `release_type` | Type of release: `main`, `feature`, `fix`, or `none` | +| `previous_tag` | The last tag before this release | +| `should_release` | Whether a release tag should be created (`true`/`false`) | +| `should_publish` | Whether to publish a GitHub release (`true`/`false`) | +| `branch_name` | The name of the branch being built | + +--- + +### Job: `build` + +**Purpose:** Compile Bicep templates and create versioned artifacts. + +| Property | Value | +| ---------------- | ----------------------------------------------- | +| **Runner** | `ubuntu-latest` | +| **Timeout** | 15 minutes | +| **Dependencies** | `generate-tag-version` | +| **Condition** | `needs.generate-tag-version.result == 'success'` | + +#### Steps + +| Step | Name | Description | +| ---- | -------------------- | --------------------------------------------------------------------- | +| 1 | Checkout Repository | Clones the repository for the current branch | +| 2 | Build Bicep Code | Uses composite action `.github/actions/ci/bicep-standard-ci` to build | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ” Prerequisites + +### Permissions + +```yaml +permissions: + contents: write # Required for creating tags + pull-requests: read # Required for PR triggers +``` + +### Required Actions + +This workflow depends on the following composite actions: + +| Action | Purpose | +| ----------------------------------------- | ------------------------------------------ | +| `.github/actions/ci/generate-release` | Generates semantic version and release metadata | +| `.github/actions/ci/bicep-standard-ci` | Builds Bicep templates and uploads artifacts | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐ŸŒ Environment Variables + +This workflow does not use environment-specific variables. All configuration is derived from the branch name and commit history. + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿท๏ธ Versioning Strategy + +The CI workflow implements a **branch-based versioning strategy**: + +| Branch Pattern | Version Behavior | Example Output | +| -------------- | ------------------------------------------ | ----------------------------- | +| `main` | Major version increment (conditional) | `v2.0.0` | +| `feature/**` | Patch increment with feature suffix | `v1.2.4-feature.my-feature` | +| `fix/**` | Minor increment with fix suffix | `v1.3.0-fix.bugfix-name` | +| Pull Request | Adds `-pr` suffix to version | `v1.2.4-feature.test-pr123` | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ฆ Artifacts + +| Artifact Name | Contents | Retention | +| -------------------------- | ------------------------------- | --------- | +| `artifacts-{version}` | Compiled ARM templates | 30 days | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Troubleshooting + +> [!WARNING] +> Build failures can block PR merges. Review these common issues to quickly resolve problems. + +### Common Issues + +| Issue | Cause | Solution | +| ---------------------------------- | ------------------------------------------ | -------------------------------------------------- | +| Build fails with "Azure CLI not available" | Missing Azure CLI in runner | Ensure runner has `az` CLI installed | +| Version calculation incorrect | Missing git history | Ensure `fetch-depth: 0` in checkout step | +| Tag already exists | Duplicate version calculated | Check branch naming and commit history | + +### Debugging Tips + +1. Check the **GitHub Actions summary** for version calculation details +2. Review the `generate-tag-version` job outputs for version information +3. Verify branch name follows supported patterns (`feature/**`, `fix/**`, or `main`) + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Related Documentation + +- [Release Workflow](release.md) - Full release process with GitHub Releases +- [Deploy Workflow](deploy.md) - Azure deployment process + +--- + +
+ +[โ† DevOps Overview](README.md) | [โฌ†๏ธ Back to Top](#-continuous-integration-workflow) | [Deploy Workflow โ†’](deploy.md) + +*DevExp-DevBox โ€ข CI Workflow Documentation* + +
diff --git a/docs/devops/deploy.md b/docs/devops/deploy.md new file mode 100644 index 00000000..db486158 --- /dev/null +++ b/docs/devops/deploy.md @@ -0,0 +1,385 @@ +--- +title: "Deploy to Azure Workflow" +description: "Deployment workflow documentation for provisioning Azure infrastructure with azd" +author: "DevExp Team" +date: 2026-01-23 +version: "1.0.0" +tags: + - devops + - deployment + - azure + - github-actions + - azd +--- + +# ๐Ÿš€ Deploy to Azure Workflow + +> [!NOTE] +> **Target Audience:** DevOps Engineers, Platform Engineers, Release Managers +> **Reading Time:** ~12 minutes + +
+๐Ÿ“ Navigation + +| Previous | Index | Next | +|:---------|:-----:|-----:| +| [โ† CI Workflow](ci.md) | [DevOps Index](README.md) | [Release Workflow โ†’](release.md) | + +
+ +--- + +## ๐Ÿ“‘ Table of Contents + +- [๐ŸŽฏ Overview](#-overview) +- [๐Ÿ“Š Pipeline Visualization](#-pipeline-visualization) +- [๐ŸŽฏ Triggers](#-triggers) +- [โš™๏ธ Jobs & Steps](#%EF%B8%8F-jobs--steps) +- [๐Ÿ” Prerequisites](#-prerequisites) +- [๐ŸŒ Environment Variables](#-environment-variables) +- [๐Ÿ”’ Concurrency Control](#-concurrency-control) +- [๐Ÿ“ฆ Artifacts](#-artifacts) +- [๐Ÿ“ Usage Examples](#-usage-examples) +- [๐Ÿ”ง Troubleshooting](#-troubleshooting) +- [๐Ÿ›ก๏ธ Security Considerations](#%EF%B8%8F-security-considerations) +- [๐Ÿ”— Related Documentation](#-related-documentation) + +--- + +## ๐ŸŽฏ Overview + +The **Deploy to Azure** workflow provisions infrastructure to Azure using the Azure Developer CLI (azd) with OIDC authentication. This is a **manual workflow** that deploys the Dev Box Accelerator infrastructure to a specified Azure environment. + +> [!TIP] +> Use this workflow when you're ready to provision Azure resources. It handles authentication, validation, and deployment automatically. + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“Š Pipeline Visualization + +```mermaid +--- +title: Deploy to Azure Pipeline Visualization +--- +flowchart TD + %% ===== TRIGGER ===== + subgraph Trigger["๐ŸŽฏ Trigger"] + T1(["๐Ÿ–ฑ๏ธ Manual Dispatch"]) + end + + %% ===== INPUTS ===== + subgraph Inputs["๐Ÿ“ Inputs"] + direction LR + I1[/"๐ŸŒ AZURE_ENV_NAME"/] + I2[/"๐Ÿ“ AZURE_LOCATION"/] + end + + %% ===== BUILD AND DEPLOY JOB ===== + subgraph BuildDeploy["๐Ÿš€ build-and-deploy-to-azure"] + direction TB + V1["โœ… Validate Required Variables"] + V1 -->|validates| C1["๐Ÿ”„ Checkout Repository"] + C1 -->|installs| AZD["๐Ÿ“ฅ Install Azure Developer CLI"] + AZD -->|compiles| B1["๐Ÿ”จ Build Bicep Templates"] + B1 -->|uploads| U1["๐Ÿ“ค Upload Build Artifacts"] + U1 -->|generates| S1["๐Ÿ“Š Generate Build Summary"] + S1 -->|authenticates| AUTH["๐Ÿ” Authenticate with Azure OIDC"] + AUTH -->|provisions| D1["๐Ÿš€ Deploy Infrastructure to Azure"] + D1 -->|summarizes| DS["๐Ÿ“‹ Generate Deployment Summary"] + end + + %% ===== AZURE RESOURCES ===== + subgraph AzureResources["โ˜๏ธ Azure Resources"] + AZ1[("๐Ÿ”‘ Azure Subscription")] + AZ2["๐Ÿ–ฅ๏ธ Dev Center"] + AZ3["๐Ÿ” Key Vault"] + AZ4["๐ŸŒ Virtual Network"] + end + + %% ===== CONNECTIONS ===== + T1 -->|provides| I1 & I2 + I1 & I2 -->|configures| V1 + D1 -->|creates| AZ1 + AZ1 -->|provisions| AZ2 & AZ3 & AZ4 + + %% ===== STYLES ===== + classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + classDef input fill:#F59E0B,stroke:#D97706,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 + + class T1 trigger + class I1,I2 input + class V1,C1,AZD,B1,U1,S1 primary + class AUTH,D1,DS secondary + class AZ1,AZ2,AZ3,AZ4 datastore + + %% ===== SUBGRAPH STYLES ===== + style Trigger fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style Inputs fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style BuildDeploy fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style AzureResources fill:#ECFDF5,stroke:#10B981,stroke-width:2px +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐ŸŽฏ Triggers + +| Trigger Type | Description | +| ------------------- | ----------------------------------------------------- | +| `workflow_dispatch` | Manual trigger only - requires user to start workflow | + +### Workflow Inputs + +| Input | Type | Required | Default | Description | +| ----------------- | -------- | -------- | ----------- | ---------------------------------------------- | +| `AZURE_ENV_NAME` | `string` | Yes | `demo` | Azure environment name (e.g., dev, staging, prod) | +| `AZURE_LOCATION` | `string` | Yes | `eastus2` | Azure region for deployment | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Jobs & Steps + +### Job: `build-and-deploy-to-azure` + +**Purpose:** Build Bicep templates and deploy infrastructure to Azure. + +| Property | Value | +| ---------------- | ------------------------------- | +| **Runner** | `ubuntu-latest` | +| **Timeout** | 60 minutes | +| **Environment** | `${{ inputs.AZURE_ENV_NAME }}` | +| **Concurrency** | One deployment per environment | + +#### Steps + +| Step | Name | Description | +| ---- | ---------------------------------- | -------------------------------------------------------- | +| 1 | Validate Required Variables | Checks for required Azure configuration variables | +| 2 | Checkout Repository | Clones the repository | +| 3 | Install Azure Developer CLI | Installs azd CLI v2.2.1 | +| 4 | Build Bicep Templates | Compiles `infra/main.bicep` to ARM templates | +| 5 | Upload Build Artifacts | Uploads compiled templates as artifacts | +| 6 | Generate Build Summary | Creates a summary of the build process | +| 7 | Authenticate with Azure (OIDC) | Uses federated credentials to authenticate with Azure | +| 8 | Deploy Infrastructure to Azure | Runs `azd provision` to deploy resources | +| 9 | Generate Deployment Summary | Creates a summary of the deployment result | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ” Prerequisites + +### Permissions + +```yaml +permissions: + id-token: write # Required for requesting OIDC JWT token + contents: read # Required for actions/checkout +``` + +### Required Repository Variables + +These variables must be configured in the repository settings under **Settings > Secrets and variables > Actions > Variables**: + +| Variable | Description | +| ------------------------ | ----------------------------------------------- | +| `AZURE_CLIENT_ID` | Service Principal/App Registration Client ID | +| `AZURE_TENANT_ID` | Azure AD Tenant ID | +| `AZURE_SUBSCRIPTION_ID` | Target Azure Subscription ID | +| `AZURE_LOCATION` | Default Azure region (fallback) | + +### Required Secrets + +| Secret | Description | +| ----------------- | ----------------------------------------------- | +| `KEY_VAULT_SECRET`| Secret value for Key Vault configuration | + +### Azure OIDC Configuration + +> [!IMPORTANT] +> OIDC authentication is required for secure, secretless deployment. Complete these steps before running the workflow. + +This workflow uses **OpenID Connect (OIDC)** for secure, secretless authentication. You must configure federated credentials in Azure AD: + +1. Create an App Registration in Azure AD +2. Add a Federated Credential for GitHub Actions +3. Configure the credential with: + - Organization: `{your-org}` + - Repository: `DevExp-DevBox` + - Entity type: `Environment` + - Environment name: `{AZURE_ENV_NAME}` + +> [!TIP] +> ๐Ÿ“– See [Azure OIDC Authentication Documentation](https://learn.microsoft.com/en-us/azure/developer/github/connect-from-azure) for detailed setup instructions. + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐ŸŒ Environment Variables + +| Variable | Source | Description | +| ----------------------- | ----------------------------------- | ------------------------------------- | +| `AZURE_CLIENT_ID` | Repository variable | Azure AD Application ID | +| `AZURE_TENANT_ID` | Repository variable | Azure AD Tenant ID | +| `AZURE_SUBSCRIPTION_ID` | Repository variable | Target Azure Subscription | +| `AZURE_ENV_NAME` | Workflow input | Environment name for deployment | +| `AZURE_LOCATION` | Workflow input / Repository variable| Azure region | +| `KEY_VAULT_SECRET` | Repository secret | Key Vault secret value | +| `SOURCE_CONTROL_PLATFORM`| Hardcoded | Set to `github` | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”’ Concurrency Control + +```yaml +concurrency: + group: deploy-${{ github.event.inputs.AZURE_ENV_NAME || 'default' }} + cancel-in-progress: false +``` + +- **Group:** Deployments are grouped by environment name +- **Behavior:** Only one deployment can run per environment at a time +- **Cancellation:** Running deployments are NOT cancelled if a new one is triggered + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ฆ Artifacts + +| Artifact Name | Contents | Retention | +| --------------------------------------- | ----------------------- | --------- | +| `bicep-artifacts-{run_number}` | Compiled ARM templates | 7 days | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Usage Examples + +### Manual Trigger via GitHub UI + +1. Navigate to **Actions** tab in the repository +2. Select **Deploy to Azure** workflow +3. Click **Run workflow** +4. Fill in the inputs: + - `AZURE_ENV_NAME`: `dev` (or your environment) + - `AZURE_LOCATION`: `eastus2` (or your region) +5. Click **Run workflow** + +### Manual Trigger via GitHub CLI + +```bash +gh workflow run deploy.yml \ + -f AZURE_ENV_NAME=dev \ + -f AZURE_LOCATION=eastus2 +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Troubleshooting + +> [!WARNING] +> Deployment failures can leave resources in an inconsistent state. Always check Azure portal for orphaned resources after failures. + +### Common Issues + +| Issue | Cause | Solution | +| ---------------------------------------- | ------------------------------------------ | ------------------------------------------------------ | +| "Missing required repository variables" | Variables not configured | Add `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_SUBSCRIPTION_ID` | +| OIDC authentication failed | Federated credential misconfigured | Verify federated credential entity type and values | +| "Azure CLI not available" | CLI not installed on runner | The workflow uses `Azure/setup-azd@v2.2.1` | +| Deployment timeout | Large infrastructure or network issues | Increase timeout or check Azure service health | +| Concurrent deployment blocked | Another deployment running | Wait for the current deployment to complete | + +### Debugging Steps + +1. **Check Variable Configuration:** + + ```bash + gh variable list + ``` + +2. **Verify OIDC Setup:** + - Ensure the App Registration has the correct federated credential + - Check the subject identifier matches the workflow environment + +3. **Review Deployment Logs:** + - Check the `azd provision` output for specific errors + - Look for ARM template validation errors + +4. **Validate Bicep Templates Locally:** + + ```bash + az bicep build --file ./infra/main.bicep --outdir ./test-output + ``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ›ก๏ธ Security Considerations + +> [!CAUTION] +> Never commit sensitive values like secrets or credentials. Use GitHub Secrets and Azure Key Vault for all sensitive configuration. + +- โœ… Uses **OIDC authentication** - no long-lived secrets stored +- โœ… **Least-privilege permissions** - only requests necessary scopes +- โœ… **Environment protection** - can be combined with environment approval rules +- โœ… **Concurrency control** - prevents conflicting deployments + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Related Documentation + +- [CI Workflow](ci.md) - Continuous integration process +- [Release Workflow](release.md) - GitHub release creation +- [Azure Developer CLI](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/) + +--- + +
+ +[โ† CI Workflow](ci.md) | [โฌ†๏ธ Back to Top](#-deploy-to-azure-workflow) | [Release Workflow โ†’](release.md) + +*DevExp-DevBox โ€ข Deploy Workflow Documentation* + +
diff --git a/docs/devops/release.md b/docs/devops/release.md new file mode 100644 index 00000000..053e83f5 --- /dev/null +++ b/docs/devops/release.md @@ -0,0 +1,506 @@ +--- +title: "Branch-Based Release Strategy Workflow" +description: "Release workflow documentation for semantic versioning and GitHub releases" +author: "DevExp Team" +date: 2026-01-23 +version: "1.0.0" +tags: + - devops + - release + - versioning + - github-actions +--- + +# ๐Ÿท๏ธ Branch-Based Release Strategy Workflow + +> [!NOTE] +> **Target Audience:** Release Managers, DevOps Engineers, Platform Engineers +> **Reading Time:** ~15 minutes + +
+๐Ÿ“ Navigation + +| Previous | Index | Next | +|:---------|:-----:|-----:| +| [โ† Deploy Workflow](deploy.md) | [DevOps Index](README.md) | โ€” | + +
+ +--- + +## ๐Ÿ“‘ Table of Contents + +- [๐ŸŽฏ Overview](#-overview) +- [๐Ÿ“Š Pipeline Visualization](#-pipeline-visualization) +- [๐ŸŽฏ Triggers](#-triggers) +- [โš™๏ธ Jobs & Steps](#%EF%B8%8F-jobs--steps) +- [๐Ÿ” Prerequisites](#-prerequisites) +- [๐Ÿท๏ธ Versioning Strategy](#%EF%B8%8F-versioning-strategy) +- [๐Ÿ”’ Concurrency Control](#-concurrency-control) +- [๐Ÿ“ฆ Artifacts](#-artifacts) +- [๐ŸŽ‰ GitHub Release Contents](#-github-release-contents) +- [๐Ÿ“ Usage Examples](#-usage-examples) +- [๐Ÿ”ง Troubleshooting](#-troubleshooting) +- [๐Ÿ”— Related Documentation](#-related-documentation) + +--- + +## ๐ŸŽฏ Overview + +The **Branch-Based Release Strategy** workflow generates semantic versions and publishes GitHub releases for the Dev Box Accelerator project. It implements a sophisticated versioning strategy that supports multiple branch types with overflow handling and automated release notes generation. + +> [!TIP] +> This workflow automates the entire release process. Simply trigger it manually, and it will calculate versions, build artifacts, and publish GitHub releases. + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“Š Pipeline Visualization + +```mermaid +--- +title: Release Pipeline Visualization +--- +flowchart TD + %% ===== TRIGGER ===== + subgraph Trigger["๐ŸŽฏ Trigger"] + T1(["๐Ÿ–ฑ๏ธ Manual Dispatch"]) + I1[/"๐Ÿ”„ force_release: boolean"/] + T1 -->|configures| I1 + end + + %% ===== GENERATE RELEASE JOB ===== + subgraph GenerateRelease["๐Ÿ“Š generate-release"] + direction TB + GR1["๐Ÿ”„ Checkout Repository"] + GR2["๐Ÿท๏ธ Generate Release Information"] + GR3["๐Ÿ“‹ Release Strategy Summary"] + GR4[/"๐Ÿ“ฆ new_version, release_type, should_release"/] + GR1 -->|clones| GR2 -->|summarizes| GR3 -->|outputs| GR4 + end + + %% ===== BUILD JOB ===== + subgraph Build["๐Ÿ”จ build"] + direction TB + B1["๐Ÿ”„ Checkout Repository"] + B2["๐Ÿ“ฆ Build Bicep Templates"] + B3["๐Ÿ“Š Build Summary"] + B1 -->|compiles| B2 -->|reports| B3 + end + + %% ===== PUBLISH RELEASE JOB ===== + subgraph PublishRelease["๐Ÿš€ publish-release"] + direction TB + PR1["๐Ÿ”„ Checkout Repository"] + PR2["๐Ÿ“ฅ Download Build Artifacts"] + PR3["๐Ÿ“ Generate Release Notes"] + PR4["๐ŸŽ‰ Create GitHub Release"] + PR5["๐Ÿ“‹ Release Summary"] + PR1 -->|downloads| PR2 -->|generates| PR3 -->|publishes| PR4 -->|summarizes| PR5 + end + + %% ===== SUMMARY JOB ===== + subgraph Summary["๐Ÿ“Š summary"] + direction TB + S1["๐Ÿ“ˆ Workflow Summary"] + end + + %% ===== CONNECTIONS ===== + I1 -->|triggers| GR1 + GR4 -->|should_release == true| B1 + GR4 -.->|should_release == false| SKIP1((โญ๏ธ Skip Build)) + B3 -->|build.result == success| PR1 + B3 -.->|build failed| SKIP2((โญ๏ธ Skip Release)) + GR4 -.->|should_publish == false| SKIP2 + PR5 -->|completes| S1 + SKIP1 -->|reports| S1 + SKIP2 -->|reports| S1 + + %% ===== STYLES ===== + classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + classDef external fill:#6B7280,stroke:#4B5563,color:#FFFFFF,stroke-dasharray:5 5 + + class T1,I1 trigger + class GR1,GR2,GR3,GR4 primary + class B1,B2,B3 datastore + class PR1,PR2,PR3,PR4,PR5 secondary + class S1 primary + class SKIP1,SKIP2 external + + %% ===== SUBGRAPH STYLES ===== + style Trigger fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style GenerateRelease fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style Build fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style PublishRelease fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Summary fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐ŸŽฏ Triggers + +| Trigger Type | Description | +| ------------------- | ----------------------------------------------------- | +| `workflow_dispatch` | Manual trigger only - requires user to start workflow | + +### Workflow Inputs + +| Input | Type | Required | Default | Description | +| --------------- | --------- | -------- | ------- | ------------------------------------------------ | +| `force_release` | `boolean` | No | `false` | Force create a release even for non-main branches | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Jobs & Steps + +### Job: `generate-release` + +**Purpose:** Calculate semantic version and prepare release metadata. + +| Property | Value | +| ---------------- | --------------- | +| **Runner** | `ubuntu-latest` | +| **Timeout** | 15 minutes | +| **Dependencies** | None | + +#### Steps + +| Step | Name | Description | +| ---- | ------------------------------ | ---------------------------------------------------------- | +| 1 | Checkout Repository | Clones repository with full history (`fetch-depth: 0`) | +| 2 | Generate Release Information | Uses `.github/actions/ci/generate-release` composite action| +| 3 | Release Strategy Summary | Outputs summary to GitHub Actions UI | + +#### Outputs + +| Output | Description | +| ---------------- | -------------------------------------------------------- | +| `new_version` | The new semantic version (e.g., `v1.2.3`) | +| `release_type` | Type of release: `main`, `feature`, `fix`, or `none` | +| `previous_tag` | The last tag before this release | +| `should_release` | Whether a release tag should be created | +| `should_publish` | Whether to publish a GitHub release | +| `branch_name` | The name of the branch being released | +| `commit_sha` | The commit SHA being released | + +--- + +### Job: `build` + +**Purpose:** Compile Bicep templates and create versioned artifacts. + +| Property | Value | +| ---------------- | ------------------------------------------------ | +| **Runner** | `ubuntu-latest` | +| **Timeout** | 20 minutes | +| **Dependencies** | `generate-release` | +| **Condition** | `needs.generate-release.outputs.should_release == 'true'` | + +#### Steps + +| Step | Name | Description | +| ---- | --------------------- | ---------------------------------------------------------------- | +| 1 | Checkout Repository | Clones repository with full history | +| 2 | Build Bicep Templates | Uses `.github/actions/ci/bicep-standard-ci` composite action | +| 3 | Build Summary | Outputs artifact information to GitHub Actions UI | + +--- + +### Job: `publish-release` + +**Purpose:** Create and publish GitHub Release with artifacts. + +| Property | Value | +| ---------------- | ---------------------------------------------------- | +| **Runner** | `ubuntu-latest` | +| **Timeout** | 15 minutes | +| **Dependencies** | `generate-release`, `build` | +| **Condition** | Complex - see below | + +#### Condition Logic + +```yaml +if: | + always() && + needs.generate-release.outputs.should_release == 'true' && + needs.build.result == 'success' && + (needs.generate-release.outputs.should_publish == 'true' || + github.event.inputs.force_release == 'true') +``` + +This job runs when: + +- `should_release` is `true` AND +- Build job succeeded AND +- Either `should_publish` is `true` OR `force_release` input is `true` + +#### Steps + +| Step | Name | Description | +| ---- | ----------------------- | --------------------------------------------------------- | +| 1 | Checkout Repository | Clones repository with full history | +| 2 | Download Build Artifacts| Downloads artifacts from the build job | +| 3 | Generate Release Notes | Creates markdown release notes with version information | +| 4 | Create GitHub Release | Uses `softprops/action-gh-release` to publish release | +| 5 | Release Summary | Outputs release link to GitHub Actions UI | + +--- + +### Job: `summary` + +**Purpose:** Provide workflow execution summary. + +| Property | Value | +| ---------------- | -------------------------------------------------------- | +| **Runner** | `ubuntu-latest` | +| **Dependencies** | `generate-release`, `build`, `publish-release` | +| **Condition** | `always()` - runs regardless of previous job results | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ” Prerequisites + +### Permissions + +```yaml +permissions: + contents: write # Required for creating tags and releases + pull-requests: read # Required for PR information + actions: read # Required for workflow introspection +``` + +### Required Actions + +| Action | Purpose | +| -------------------------------------- | ------------------------------------------------- | +| `.github/actions/ci/generate-release` | Generates semantic version and release metadata | +| `.github/actions/ci/bicep-standard-ci` | Builds Bicep templates and uploads artifacts | +| `softprops/action-gh-release@v2.3.2` | Creates GitHub Releases | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿท๏ธ Versioning Strategy + +> [!IMPORTANT] +> Understanding the versioning strategy is crucial for release planning. Version numbers are calculated automatically based on branch type and commit history. + +### Branch-Based Version Calculation + +```mermaid +flowchart LR + subgraph "๐Ÿ“Š Version Calculation" + direction TB + START((Start)) --> CHECK{Branch Type?} + CHECK --> |main| MAIN["Conditional Major
if minor=0 AND patch=0"] + CHECK --> |feature/**| FEAT["Patch + commits
Suffix: -feature.name"] + CHECK --> |fix/**| FIX["Minor + commits
Suffix: -fix.name"] + + MAIN --> OVERFLOW1{Overflow?} + FEAT --> OVERFLOW2{patch > 99?} + FIX --> OVERFLOW3{minor > 99?} + + OVERFLOW1 --> |"patch > 99"| INCMIN["minor++, patch=0"] + OVERFLOW2 --> |Yes| INCMIN2["minor++, patch=0"] + OVERFLOW3 --> |Yes| INCMAJ["major++, minor=0"] + + INCMIN --> FINALV[/"Final Version"/] + INCMIN2 --> FINALV + INCMAJ --> FINALV + OVERFLOW1 --> |No| FINALV + OVERFLOW2 --> |No| FINALV + OVERFLOW3 --> |No| FINALV + end + + classDef decision fill:#FFC107,stroke:#FFA000,color:#000 + classDef process fill:#2196F3,stroke:#1565C0,color:#fff + classDef output fill:#4CAF50,stroke:#2E7D32,color:#fff + + class CHECK,OVERFLOW1,OVERFLOW2,OVERFLOW3 decision + class MAIN,FEAT,FIX,INCMIN,INCMIN2,INCMAJ process + class FINALV output +``` + +### Version Rules by Branch + +| Branch Pattern | Version Component | Overflow Handling | Example | +| -------------- | ----------------- | ----------------- | --------------------- | +| `main` | Conditional major | Patch โ†’ Minor โ†’ Major | `v2.0.0` | +| `feature/**` | Patch + commits | Patch > 99 โ†’ Minor++ | `v1.2.45-feature.auth` | +| `fix/**` | Minor + commits | Minor > 99 โ†’ Major++ | `v1.5.0-fix.security` | + +### Main Branch Special Rule + +For the `main` branch, the version increment follows this rule: + +- **If** `minor == 0` AND `patch == 0`: Increment `major` (e.g., `v1.0.0` โ†’ `v2.0.0`) +- **Otherwise**: Increment `patch` with overflow handling + +### Pre-release Versions + +| Source | Pre-release Suffix | +| ---------------- | ------------------------------- | +| Feature branch | `-feature.{branch-name}` | +| Fix branch | `-fix.{branch-name}` | +| Pull Request | Additional `-pr{number}` suffix | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”’ Concurrency Control + +```yaml +concurrency: + group: release-${{ github.ref }} + cancel-in-progress: false +``` + +- **Group:** Releases are grouped by branch reference +- **Behavior:** Only one release workflow can run per branch at a time +- **Cancellation:** Running releases are NOT cancelled if a new one is triggered + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ฆ Artifacts + +| Artifact Name | Contents | Retention | +| -------------------------- | ------------------------------- | --------- | +| `artifacts-{version}` | Compiled ARM templates | 30 days | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐ŸŽ‰ GitHub Release Contents + +Each published release includes: + +| Content | Description | +| ------------------------ | ------------------------------------------------ | +| **Tag** | Semantic version tag (e.g., `v1.2.3`) | +| **Release Name** | `Release {version}` | +| **Release Notes** | Auto-generated with version info and commit link | +| **Artifacts** | Compiled ARM templates from `./artifacts/` | +| **Pre-release Flag** | Set for non-main branches | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Usage Examples + +### Trigger Release from Main Branch + +1. Navigate to **Actions** tab +2. Select **Branch-Based Release Strategy** +3. Click **Run workflow** +4. Select `main` branch +5. Leave `force_release` unchecked +6. Click **Run workflow** + +### Force Release from Feature Branch + +> [!CAUTION] +> Force releases from non-main branches create pre-release versions. Use with care in production environments. + +1. Navigate to **Actions** tab +2. Select **Branch-Based Release Strategy** +3. Click **Run workflow** +4. Select your feature branch (e.g., `feature/new-feature`) +5. Check `force_release` โœ… +6. Click **Run workflow** + +### Via GitHub CLI + +```bash +# Release from main +gh workflow run release.yml -r main + +# Force release from feature branch +gh workflow run release.yml -r feature/my-feature -f force_release=true +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Troubleshooting + +> [!WARNING] +> Release failures may leave orphaned tags in the repository. Use `git tag -d` to clean up failed release tags before retrying. + +### Common Issues + +| Issue | Cause | Solution | +| ---------------------------------- | ------------------------------------------ | -------------------------------------------------- | +| "Tag already exists" | Version collision | Check existing tags, may need to delete duplicate | +| Build job skipped | `should_release` is false | Verify branch name follows supported patterns | +| Publish job skipped | `should_publish` is false | Use `force_release: true` for non-main branches | +| Release notes empty | Failed to generate release notes | Check `release_notes.md` generation step | + +### Debugging Tips + +1. **Check Release Strategy Summary** in the `generate-release` job output +2. **Verify Job Conditions:** + - `should_release`: Must be `true` for build + - `should_publish`: Must be `true` for publish (or use `force_release`) +3. **Review Tag History:** + + ```bash + git tag --list 'v*' | sort -V | tail -10 + ``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Related Documentation + +- [CI Workflow](ci.md) - Continuous integration process +- [Deploy Workflow](deploy.md) - Azure deployment process + +--- + +
+ +[โ† Deploy Workflow](deploy.md) | [โฌ†๏ธ Back to Top](#%EF%B8%8F-branch-based-release-strategy-workflow) + +*DevExp-DevBox โ€ข Release Workflow Documentation* + +
diff --git a/docs/scripts/README.md b/docs/scripts/README.md new file mode 100644 index 00000000..da3cb013 --- /dev/null +++ b/docs/scripts/README.md @@ -0,0 +1,406 @@ +--- +title: "PowerShell Scripts Documentation" +description: "Comprehensive documentation for all PowerShell automation scripts in the DevExp-DevBox project" +author: "DevExp Team" +date: 2026-01-23 +version: "1.0.0" +tags: + - scripts + - powershell + - automation + - azure + - github +--- + +# ๐Ÿ“œ DevExp-DevBox PowerShell Scripts Documentation + +> ๐Ÿ“– Comprehensive documentation for all PowerShell automation scripts in the DevExp-DevBox project. + +> [!NOTE] +> **Target Audience:** DevOps Engineers, Platform Engineers, System Administrators +> **Reading Time:** ~10 minutes + +
+๐Ÿ“ Navigation + +| Previous | Index | Next | +|:---------|:-----:|-----:| +| โ€” | [Docs Index](../README.md) | [setUp.ps1 โ†’](setup.md) | + +
+ +--- + +## ๐Ÿ“‘ Table of Contents + +- [๐ŸŽฏ Overview](#overview) +- [๐Ÿ—๏ธ Scripts Architecture](#scripts-architecture) +- [โšก Quick Reference](#quick-reference) +- [๐Ÿ“‚ Scripts by Category](#scripts-by-category) +- [โš™๏ธ Prerequisites Summary](#prerequisites-summary) +- [๐Ÿ”„ Common Workflows](#common-workflows) +- [โš ๏ธ Error Handling Patterns](#error-handling-patterns) +- [๐Ÿ“ File Structure](#file-structure) +- [๐Ÿ”— Related Documentation](#related-documentation) +- [๐Ÿค Contributing](#contributing) + +--- + +## ๐ŸŽฏ Overview + +This documentation covers the PowerShell scripts used to set up, manage, and clean up Azure Dev Box environments with GitHub or Azure DevOps integration. The scripts follow Azure best practices for security, error handling, and resource management. + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ—๏ธ Scripts Architecture + +```mermaid +--- +title: Scripts Architecture +--- +flowchart TB + %% ===== ROOT SCRIPTS ===== + subgraph RootScripts["๐Ÿš€ Root Scripts"] + setUp["๐Ÿ“ฅ setUp.ps1
(Environment Setup)"] + cleanSetUp["๐Ÿ—‘๏ธ cleanSetUp.ps1
(Full Cleanup)"] + end + + %% ===== AZURE SCRIPTS ===== + subgraph AzureScripts["โ˜๏ธ Azure Scripts"] + createRole["๐Ÿ” createCustomRole.ps1"] + createUsers["๐Ÿ‘ฅ createUsersAndAssignRole.ps1"] + genCreds["๐Ÿ”‘ generateDeploymentCredentials.ps1"] + deleteUsers["๐Ÿ‘ค deleteUsersAndAssignedRoles.ps1"] + deleteCreds["๐Ÿ”’ deleteDeploymentCredentials.ps1"] + end + + %% ===== GITHUB SCRIPTS ===== + subgraph GitHubScripts["๐Ÿ™ GitHub Scripts"] + createSecret["๐Ÿ“ createGitHubSecret
AzureCredentials.ps1"] + deleteSecret["โŒ deleteGitHubSecret
AzureCredentials.ps1"] + end + + %% ===== UTILITY SCRIPTS ===== + subgraph UtilityScripts["๐Ÿ”ง Utility Scripts"] + cleanUp["๐Ÿ—‘๏ธ cleanUp.ps1
(Resource Groups)"] + wingetUpdate["๐Ÿ“ฆ winget-update.ps1
(Store Apps)"] + end + + %% ===== CONNECTIONS ===== + setUp -->|initializes| genCreds + genCreds -->|calls| createUsers + genCreds -->|calls| createSecret + + cleanSetUp -->|orchestrates| deleteUsers + cleanSetUp -->|orchestrates| deleteCreds + cleanSetUp -->|orchestrates| deleteSecret + cleanSetUp -->|orchestrates| cleanUp + + %% ===== STYLES ===== + classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + + class setUp,cleanSetUp trigger + class createRole,createUsers,genCreds,deleteUsers,deleteCreds primary + class createSecret,deleteSecret secondary + class cleanUp,wingetUpdate datastore + + %% ===== SUBGRAPH STYLES ===== + style RootScripts fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style AzureScripts fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style GitHubScripts fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style UtilityScripts fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โšก Quick Reference + +### Setup Scripts (Execute in Order) + +| # | Script | Purpose | Required | +|---|--------|---------|----------| +| 1 | [setUp.ps1](setup.md) | Initialize azd environment | Yes | +| 2 | [createCustomRole.ps1](azure/create-custom-role.md) | Create RBAC role for assignments | Optional | +| 3 | [generateDeploymentCredentials.ps1](azure/generate-deployment-credentials.md) | Create service principal + GitHub secret | For CI/CD | +| 4 | [createUsersAndAssignRole.ps1](azure/create-users-and-assign-role.md) | Assign DevCenter roles | Yes | + +### Cleanup Scripts (Execute in Order) + +| # | Script | Purpose | +|---|--------|---------| +| 1 | [cleanSetUp.ps1](clean-setup.md) | **Full orchestrated cleanup** (calls all below) | +| 2 | [deleteUsersAndAssignedRoles.ps1](azure/delete-users-and-assigned-roles.md) | Remove role assignments | +| 3 | [deleteDeploymentCredentials.ps1](azure/delete-deployment-credentials.md) | Remove service principal | +| 4 | [deleteGitHubSecretAzureCredentials.ps1](github/delete-github-secret-azure-credentials.md) | Remove GitHub secret | +| 5 | [cleanUp.ps1](configuration/clean-up.md) | Delete resource groups | + +### Utility Scripts + +| Script | Purpose | +|--------|---------| +| [winget-update.ps1](configuration/winget-update.md) | Update Microsoft Store apps (Dev Box workloads) | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“‚ Scripts by Category + +### Root Scripts + +Entry-point scripts for environment lifecycle management. + +| Script | Description | Documentation | +|--------|-------------|---------------| +| `setUp.ps1` | Sets up Azure Dev Box environment with GitHub/ADO integration | [setup.md](setup.md) | +| `cleanSetUp.ps1` | Complete environment cleanup orchestrator | [clean-setup.md](clean-setup.md) | + +### Azure Identity & Access Scripts + +Scripts for managing Azure AD and RBAC configurations. + +| Script | Description | Documentation | +|--------|-------------|---------------| +| `createCustomRole.ps1` | Creates custom RBAC role for role assignment management | [azure/create-custom-role.md](azure/create-custom-role.md) | +| `createUsersAndAssignRole.ps1` | Assigns DevCenter roles to current user | [azure/create-users-and-assign-role.md](azure/create-users-and-assign-role.md) | +| `deleteUsersAndAssignedRoles.ps1` | Removes DevCenter role assignments | [azure/delete-users-and-assigned-roles.md](azure/delete-users-and-assigned-roles.md) | +| `generateDeploymentCredentials.ps1` | Creates service principal for CI/CD | [azure/generate-deployment-credentials.md](azure/generate-deployment-credentials.md) | +| `deleteDeploymentCredentials.ps1` | Removes service principal and app registration | [azure/delete-deployment-credentials.md](azure/delete-deployment-credentials.md) | + +### GitHub Integration Scripts + +Scripts for managing GitHub repository secrets. + +| Script | Description | Documentation | +|--------|-------------|---------------| +| `createGitHubSecretAzureCredentials.ps1` | Creates AZURE_CREDENTIALS secret | [github/create-github-secret-azure-credentials.md](github/create-github-secret-azure-credentials.md) | +| `deleteGitHubSecretAzureCredentials.ps1` | Removes GitHub repository secret | [github/delete-github-secret-azure-credentials.md](github/delete-github-secret-azure-credentials.md) | + +### Configuration & Utility Scripts + +Scripts for resource management and Dev Box configuration. + +| Script | Description | Documentation | +|--------|-------------|---------------| +| `cleanUp.ps1` | Deletes Azure resource groups | [configuration/clean-up.md](configuration/clean-up.md) | +| `winget-update.ps1` | Updates Microsoft Store applications | [configuration/winget-update.md](configuration/winget-update.md) | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Prerequisites Summary + +### Required Tools + +| Tool | Version | Required For | Installation | +|------|---------|--------------|--------------| +| PowerShell | 5.1+ | All scripts | Pre-installed on Windows | +| Azure CLI | Latest | Azure operations | [Install](https://docs.microsoft.com/cli/azure/install-azure-cli) | +| Azure Developer CLI | Latest | Environment setup | [Install](https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd) | +| GitHub CLI | Latest | GitHub operations | [Install](https://cli.github.com/) | +| Windows Package Manager | 1.11+ | winget-update.ps1 | [App Installer](https://apps.microsoft.com/store/detail/app-installer/9NBLGGH4NNS1) | + +### Required Permissions + +| Resource | Permission | Scripts | +|----------|------------|---------| +| Azure Subscription | Owner or Contributor + UAA | All Azure scripts | +| Azure AD | Application Administrator | Credential scripts | +| GitHub Repository | Admin | Secret scripts | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”„ Common Workflows + +### New Environment Setup + +```mermaid +--- +title: New Environment Setup Flow +--- +flowchart LR + A["โ˜๏ธ az login"] -->|authenticates| B["๐Ÿ“ฅ setUp.ps1"] + B -->|initializes| C["๐Ÿ”‘ generateDeploymentCredentials.ps1"] + C -->|provisions| D["๐Ÿš€ azd provision"] + + %% ===== STYLES ===== + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + + class A,D secondary + class B trigger + class C datastore +``` + +```powershell +# 1. Authenticate to Azure +az login + +# 2. Run setup script +.\setUp.ps1 -EnvName "prod" -SourceControl "github" + +# 3. Generate CI/CD credentials (if needed) +.\.configuration\setup\powershell\Azure\generateDeploymentCredentials.ps1 ` + -AppName "myapp-cicd" ` + -DisplayName "MyApp CI/CD Service Principal" + +# 4. Provision Azure resources +azd provision -e prod +``` + +### Environment Cleanup + +```powershell +# Full cleanup with one command +.\cleanSetUp.ps1 -EnvName "prod" -Location "eastus2" +``` + +Or step-by-step: + +```powershell +# 1. Remove user role assignments +.\.configuration\setup\powershell\Azure\deleteUsersAndAssignedRoles.ps1 + +# 2. Remove deployment credentials +.\.configuration\setup\powershell\Azure\deleteDeploymentCredentials.ps1 ` + -AppDisplayName "MyApp CI/CD Service Principal" + +# 3. Remove GitHub secret +.\.configuration\setup\powershell\GitHub\deleteGitHubSecretAzureCredentials.ps1 ` + -GhSecretName "AZURE_CREDENTIALS" + +# 4. Delete resource groups +.\.configuration\powershell\cleanUp.ps1 -EnvName "prod" -Location "eastus2" +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš ๏ธ Error Handling Patterns + +All scripts follow consistent error handling: + +```powershell +# Standard error preference +$ErrorActionPreference = 'Stop' +$WarningPreference = 'Stop' + +# Exit codes +# 0 = Success +# 1 = Failure + +# WhatIf support (where applicable) +[CmdletBinding(SupportsShouldProcess)] +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ File Structure + +``` +DevExp-DevBox/ +โ”œโ”€โ”€ setUp.ps1 # Main setup entry point +โ”œโ”€โ”€ cleanSetUp.ps1 # Main cleanup entry point +โ”œโ”€โ”€ .configuration/ +โ”‚ โ”œโ”€โ”€ powershell/ +โ”‚ โ”‚ โ””โ”€โ”€ cleanUp.ps1 # Resource group cleanup +โ”‚ โ”œโ”€โ”€ devcenter/ +โ”‚ โ”‚ โ””โ”€โ”€ workloads/ +โ”‚ โ”‚ โ””โ”€โ”€ winget-update.ps1 # Store app updates +โ”‚ โ””โ”€โ”€ setup/ +โ”‚ โ””โ”€โ”€ powershell/ +โ”‚ โ”œโ”€โ”€ Azure/ +โ”‚ โ”‚ โ”œโ”€โ”€ createCustomRole.ps1 +โ”‚ โ”‚ โ”œโ”€โ”€ createUsersAndAssignRole.ps1 +โ”‚ โ”‚ โ”œโ”€โ”€ deleteDeploymentCredentials.ps1 +โ”‚ โ”‚ โ”œโ”€โ”€ deleteUsersAndAssignedRoles.ps1 +โ”‚ โ”‚ โ””โ”€โ”€ generateDeploymentCredentials.ps1 +โ”‚ โ””โ”€โ”€ GitHub/ +โ”‚ โ”œโ”€โ”€ createGitHubSecretAzureCredentials.ps1 +โ”‚ โ””โ”€โ”€ deleteGitHubSecretAzureCredentials.ps1 +โ””โ”€โ”€ docs/ + โ””โ”€โ”€ scripts/ # This documentation + โ”œโ”€โ”€ README.md # This file + โ”œโ”€โ”€ setup.md + โ”œโ”€โ”€ clean-setup.md + โ”œโ”€โ”€ azure/ + โ”‚ โ”œโ”€โ”€ create-custom-role.md + โ”‚ โ”œโ”€โ”€ create-users-and-assign-role.md + โ”‚ โ”œโ”€โ”€ delete-deployment-credentials.md + โ”‚ โ”œโ”€โ”€ delete-users-and-assigned-roles.md + โ”‚ โ””โ”€โ”€ generate-deployment-credentials.md + โ”œโ”€โ”€ github/ + โ”‚ โ”œโ”€โ”€ create-github-secret-azure-credentials.md + โ”‚ โ””โ”€โ”€ delete-github-secret-azure-credentials.md + โ””โ”€โ”€ configuration/ + โ”œโ”€โ”€ clean-up.md + โ””โ”€โ”€ winget-update.md +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Related Documentation + +| Document | Description | +|----------|-------------| +| [Architecture Overview](../architecture/07-deployment-architecture.md) | Deployment architecture details | +| [CI/CD Overview](../devops/README.md) | DevOps pipeline documentation | +| [Deployment Guide](../devops/deploy.md) | Deployment instructions | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿค Contributing + +When adding new PowerShell scripts: + +1. Follow the established patterns for error handling and logging +2. Include comprehensive comment-based help (`.SYNOPSIS`, `.DESCRIPTION`, `.PARAMETER`, `.EXAMPLE`) +3. Create corresponding documentation in this folder +4. Update this README with the new script reference +5. Use consistent parameter validation (`ValidateNotNullOrEmpty`, `ValidateSet`, etc.) + +--- + +
+ +[โฌ†๏ธ Back to Top](#-table-of-contents) | [setUp.ps1 โ†’](setup.md) + +*DevExp-DevBox โ€ข PowerShell Scripts Documentation* + +
diff --git a/docs/scripts/azure/README.md b/docs/scripts/azure/README.md new file mode 100644 index 00000000..cb692636 --- /dev/null +++ b/docs/scripts/azure/README.md @@ -0,0 +1,204 @@ +--- +title: "Azure PowerShell Scripts" +description: "Documentation for Azure RBAC, service principal, and credential management scripts" +author: "DevExp Team" +date: 2026-01-23 +version: "1.0.0" +tags: + - scripts + - azure + - rbac + - service-principal + - security +--- + +# โ˜๏ธ Azure PowerShell Scripts + +> **Documentation for Azure RBAC, service principal, and credential management scripts** + +> [!NOTE] +> **Target Audience:** Azure Administrators, DevOps Engineers, Platform Engineers +> **Reading Time:** ~5 minutes + +
+๐Ÿ“ Navigation + +| Previous | Index | Next | +|:---------|:-----:|-----:| +| [โ† Scripts Index](../README.md) | [Scripts Index](../README.md) | [GitHub Scripts โ†’](../github/README.md) | + +
+ +--- + +## ๐Ÿ“‘ Table of Contents + +- [๐ŸŽฏ Overview](#-overview) +- [๐Ÿ“œ Scripts Inventory](#-scripts-inventory) +- [๐Ÿ”„ Workflow Diagram](#-workflow-diagram) +- [โš™๏ธ Prerequisites](#%EF%B8%8F-prerequisites) +- [๐Ÿš€ Quick Start](#-quick-start) +- [๐Ÿ”— Related Documentation](#-related-documentation) + +--- + +## ๐ŸŽฏ Overview + +This folder contains PowerShell scripts for managing Azure Role-Based Access Control (RBAC), service principals, and deployment credentials. These scripts are essential for setting up secure CI/CD pipelines and managing DevCenter access. + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“œ Scripts Inventory + +| Script | Purpose | Documentation | +|--------|---------|---------------| +| ๐Ÿ”‘ `createCustomRole.ps1` | Creates custom Azure RBAC role for role assignment management | [create-custom-role.md](create-custom-role.md) | +| ๐Ÿ‘ฅ `createUsersAndAssignRole.ps1` | Assigns DevCenter roles to the current signed-in user | [create-users-and-assign-role.md](create-users-and-assign-role.md) | +| ๐Ÿ—‘๏ธ `deleteDeploymentCredentials.ps1` | Removes Azure AD service principal and application registration | [delete-deployment-credentials.md](delete-deployment-credentials.md) | +| ๐Ÿ‘ฅ `deleteUsersAndAssignedRoles.ps1` | Removes DevCenter role assignments from users | [delete-users-and-assigned-roles.md](delete-users-and-assigned-roles.md) | +| ๐Ÿ”‘ `generateDeploymentCredentials.ps1` | Creates service principal and GitHub secret for CI/CD | [generate-deployment-credentials.md](generate-deployment-credentials.md) | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”„ Workflow Diagram + +```mermaid +--- +title: Azure Scripts Workflow +--- +flowchart LR + %% ===== SETUP PHASE ===== + subgraph Setup["๐Ÿš€ Setup Phase"] + direction TB + A["๐Ÿ”‘ createCustomRole.ps1"] + B["๐Ÿ”‘ generateDeploymentCredentials.ps1"] + C["๐Ÿ‘ฅ createUsersAndAssignRole.ps1"] + end + + %% ===== CLEANUP PHASE ===== + subgraph Cleanup["๐Ÿ—‘๏ธ Cleanup Phase"] + direction TB + D["๐Ÿ‘ฅ deleteUsersAndAssignedRoles.ps1"] + E["๐Ÿ—‘๏ธ deleteDeploymentCredentials.ps1"] + end + + %% ===== CONNECTIONS ===== + A -->|"creates RBAC role"| B + B -->|"configures credentials"| C + D -->|"removes roles"| E + + Setup -.->|"Reverse Operations"| Cleanup + + %% ===== NODE STYLES ===== + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef failed fill:#F44336,stroke:#C62828,color:#FFFFFF + + class A,B,C secondary + class D,E failed + + %% ===== SUBGRAPH STYLES ===== + style Setup fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Cleanup fill:#FEE2E2,stroke:#F44336,stroke-width:2px +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Prerequisites + +> [!IMPORTANT] +> All scripts require the following tools and permissions to be configured. + +### Required Tools + +| Tool | Purpose | Installation | +|------|---------|--------------| +| Azure CLI (`az`) | Manage Azure resources and RBAC | [Install Azure CLI](https://docs.microsoft.com/cli/azure/install-azure-cli) | +| PowerShell 5.1+ | Script execution | Pre-installed on Windows | +| GitHub CLI (`gh`) | Create repository secrets (for credential scripts) | [Install GitHub CLI](https://cli.github.com/) | + +### Required Permissions + +| Permission | Scripts | Purpose | +|------------|---------|---------| +| **Owner** or **User Access Administrator** | All scripts | Manage role assignments | +| **Application Administrator** | Credential scripts | Manage service principals | +| **GitHub Repository Admin** | `generateDeploymentCredentials.ps1` | Create secrets | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿš€ Quick Start + +### Initial Setup + +> [!TIP] +> Run these scripts in order for complete environment setup. + +```powershell +# 1. Login to Azure +az login + +# 2. Create custom RBAC role (optional) +.\createCustomRole.ps1 + +# 3. Generate deployment credentials and configure GitHub +.\generateDeploymentCredentials.ps1 -AppName "my-app-cicd" -DisplayName "My App CI/CD" +``` + +### Cleanup + +> [!WARNING] +> Cleanup operations are irreversible. Ensure CI/CD pipelines are updated before running. + +```powershell +# 1. Remove user role assignments +.\deleteUsersAndAssignedRoles.ps1 + +# 2. Delete service principal and app registration +.\deleteDeploymentCredentials.ps1 -AppDisplayName "My App CI/CD" +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Related Documentation + +| Document | Description | +|----------|-------------| +| [Scripts Index](../README.md) | Main scripts documentation | +| [GitHub Scripts](../github/README.md) | GitHub secret management scripts | +| [Security Architecture](../../architecture/05-security-architecture.md) | Security design and RBAC strategy | +| [Deployment Architecture](../../architecture/07-deployment-architecture.md) | CI/CD pipeline configuration | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +
+ +[โ† Scripts Index](../README.md) | [โฌ†๏ธ Back to Top](#-table-of-contents) | [GitHub Scripts โ†’](../github/README.md) + +*DevExp-DevBox โ€ข Azure Scripts Documentation* + +
diff --git a/docs/scripts/azure/create-custom-role.md b/docs/scripts/azure/create-custom-role.md new file mode 100644 index 00000000..be9914e6 --- /dev/null +++ b/docs/scripts/azure/create-custom-role.md @@ -0,0 +1,377 @@ +--- +title: "createCustomRole.ps1 Script" +description: "Creates a custom Azure RBAC role for role assignment management" +author: "DevExp Team" +date: 2026-01-23 +version: "1.0.0" +tags: + - scripts + - azure + - rbac + - security +--- + +# ๐Ÿ”‘ createCustomRole.ps1 + +> **Creates a custom Azure RBAC role for role assignment management** + +> [!IMPORTANT] +> This script requires **Owner** or **User Access Administrator** permissions on the target subscription. + +> [!NOTE] +> **Target Audience:** Azure Administrators, Security Engineers +> **Reading Time:** ~8 minutes + +
+๐Ÿ“ Navigation + +| Previous | Index | Next | +|:---------|:-----:|-----:| +| [โ† cleanSetUp.ps1](../clean-setup.md) | [Scripts Index](../README.md) | [createUsersAndAssignRole.ps1 โ†’](create-users-and-assign-role.md) | + +
+ +--- + +## ๐Ÿ“‘ Table of Contents + +- [๐ŸŽฏ Overview](#-overview) +- [๐Ÿ“Š Flow Visualization](#-flow-visualization) +- [๐Ÿ“ Parameters](#-parameters) +- [โš™๏ธ Prerequisites](#-prerequisites) +- [๐Ÿ“œ Role Definition](#-role-definition) +- [๐Ÿ”ง Functions Reference](#-functions-reference) +- [๐Ÿ“ Usage Examples](#-usage-examples) +- [โš ๏ธ Error Handling](#-error-handling) +- [๐Ÿ”ง Troubleshooting](#-troubleshooting) +- [๐Ÿ” Security Considerations](#-security-considerations) +- [๐Ÿ”— Related Scripts](#-related-scripts) + +--- + +## ๐ŸŽฏ Overview + +This script creates a custom Azure RBAC role definition that grants permissions to manage role assignments. The role includes permissions to read, write, and delete role assignments within a specified subscription scope. Use this script when you need to delegate role assignment capabilities without granting full User Access Administrator permissions. + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“Š Flow Visualization + +```mermaid +--- +title: Create Custom Role Flow +--- +flowchart TD + %% ===== SCRIPT ENTRY ===== + subgraph Entry["๐Ÿ“ฅ Script Entry"] + A(["๐Ÿš€ createCustomRole.ps1 Start"]) + B[/"๐Ÿ“ Parse Parameters"/] + end + + %% ===== SUBSCRIPTION RESOLUTION ===== + subgraph SubCheck["๐Ÿ” Subscription Resolution"] + C{"๐Ÿ“‹ SubscriptionId provided?"} + D["โš™๏ธ Get-CurrentSubscriptionId"] + E[("โ˜๏ธ Azure CLI")] + end + + %% ===== ROLE CREATION ===== + subgraph RoleCreation["๐Ÿ” Role Definition Creation"] + F["โš™๏ธ New-CustomRoleDefinition"] + F1["๐Ÿ“„ Build role definition JSON"] + F2["๐Ÿ“ Write to temp file"] + F3{"๐Ÿ”„ Force flag set?"} + F4["๐Ÿ—‘๏ธ Delete existing role"] + F5[("๐Ÿ”‘ az role definition create")] + end + + %% ===== CLEANUP ===== + subgraph Cleanup["๐Ÿงน Cleanup"] + G["๐Ÿ—‘๏ธ Remove temp file"] + end + + %% ===== SCRIPT EXIT ===== + subgraph Exit["๐Ÿ“ค Script Exit"] + H{"โœ… Success?"} + I[\"๐ŸŽ‰ Role Created"\] + J{{"โŒ Error Handler"}} + end + + %% ===== CONNECTIONS ===== + A -->|parses| B -->|checks| C + C -->|No| D -->|calls| E + C -->|Yes| F + E -->|provides| F + F -->|builds| F1 -->|writes| F2 -->|checks| F3 + F3 -->|Yes| F4 -->|creates| F5 + F3 -->|No| F5 + F5 -->|cleans| G -->|evaluates| H + H -->|Yes| I + H -->|No| J + + %% ===== STYLES ===== + classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + classDef input fill:#F3F4F6,stroke:#6B7280,color:#000000 + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef external fill:#6B7280,stroke:#4B5563,color:#FFFFFF,stroke-dasharray:5 5 + classDef decision fill:#FFFBEB,stroke:#F59E0B,color:#000000 + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef failed fill:#F44336,stroke:#C62828,color:#FFFFFF + + class A trigger + class B input + class D,F,F1,F2,F4,G primary + class E,F5 external + class C,F3,H decision + class I secondary + class J failed + + %% ===== SUBGRAPH STYLES ===== + style Entry fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style SubCheck fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style RoleCreation fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style Cleanup fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Exit fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Parameters + +| Parameter | Type | Required | Default | Validation | Description | +|-----------|------|----------|---------|------------|-------------| +| `-RoleName` | `string` | No | `"Contoso DevBox - Role Assignment Writer"` | `ValidateNotNullOrEmpty` | Display name for the custom role | +| `-SubscriptionId` | `string` | No | Current subscription | `ValidatePattern` (GUID format) | Azure subscription ID for scope | +| `-Description` | `string` | No | `"Allows creating role assignments."` | - | Description for the custom role | +| `-Force` | `switch` | No | `$false` | - | Delete existing role before creating | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Prerequisites + +### Required Tools + +| Tool | Purpose | Installation | +|------|---------|--------------| +| Azure CLI (`az`) | Create role definitions | [Install Azure CLI](https://docs.microsoft.com/cli/azure/install-azure-cli) | +| PowerShell 5.1+ | Script execution | Pre-installed on Windows | + +### Required Permissions + +- **Azure**: `Microsoft.Authorization/roleDefinitions/write` at subscription scope +- Typically requires **Owner** or **User Access Administrator** role + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“œ Role Definition + +The created role includes these permissions: + +```json +{ + "Name": "Contoso DevBox - Role Assignment Writer", + "IsCustom": true, + "Description": "Allows creating role assignments.", + "Actions": [ + "Microsoft.Authorization/roleAssignments/write", + "Microsoft.Authorization/roleAssignments/delete", + "Microsoft.Authorization/roleAssignments/read" + ], + "NotActions": [], + "DataActions": [], + "NotDataActions": [], + "AssignableScopes": [ + "/subscriptions/{subscriptionId}" + ] +} +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Functions Reference + +### Function: `Get-CurrentSubscriptionId` + +**Purpose:** Retrieves the current Azure subscription ID from Azure CLI context. + +**Parameters:** None + +**Returns:** `[string]` - The subscription ID GUID + +**Throws:** Error if not logged into Azure CLI + +--- + +### Function: `New-CustomRoleDefinition` + +**Purpose:** Creates a custom Azure RBAC role definition from a JSON template. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `RoleName` | `string` | Yes | Name of the custom role | +| `SubscriptionId` | `string` | Yes | Subscription ID for scope | +| `Description` | `string` | No | Role description | +| `RemoveExisting` | `switch` | No | Delete existing role first | + +**Returns:** `[bool]` - `$true` if successful, `$false` otherwise + +**Behavior:** + +1. Builds role definition hashtable +2. Converts to JSON and writes to temp file in `$env:TEMP` +3. Optionally deletes existing role with same name +4. Creates role via `az role definition create` +5. Cleans up temp file (in finally block) + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Usage Examples + +### Basic Usage (Current Subscription) + +```powershell +.\createCustomRole.ps1 +``` + +Creates role with default name in the current subscription. + +### Specific Subscription + +```powershell +.\createCustomRole.ps1 -SubscriptionId "12345678-1234-1234-1234-123456789012" +``` + +### Custom Role Name + +```powershell +.\createCustomRole.ps1 -RoleName "MyCompany - Role Writer" -Description "Custom role for CI/CD pipelines" +``` + +### Replace Existing Role + +```powershell +.\createCustomRole.ps1 -Force +``` + +Deletes any existing role with the same name before creating. + +### Dry Run (WhatIf) + +```powershell +.\createCustomRole.ps1 -WhatIf +``` + +Shows what would be created without making changes. + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš ๏ธ Error Handling + +### Error Action Preference + +```powershell +$ErrorActionPreference = 'Stop' +$ProgressPreference = 'SilentlyContinue' +``` + +### Exit Codes + +| Code | Meaning | +|------|---------| +| `0` | Role created successfully | +| `1` | Role creation failed | + +### Cleanup Guarantee + +The temporary JSON file is always cleaned up via `finally` block, even if creation fails. + +## ๐Ÿ”ง Troubleshooting + +### Common Issues + +| Issue | Cause | Solution | +|-------|-------|----------| +| "Failed to retrieve current subscription ID" | Not logged into Azure | Run `az login` | +| "Failed to create custom role definition" | Insufficient permissions | Verify Owner/UAA role | +| Role already exists error | Role with same name exists | Use `-Force` parameter | +| Invalid subscription ID format | GUID validation failed | Check subscription ID format | + +--- + +### Verify Role Creation + +```powershell +# List custom roles +az role definition list --custom-role-only true --query "[?roleName=='Contoso DevBox - Role Assignment Writer']" +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ” Security Considerations + +- Custom roles should follow **least privilege** principle +- The created role only grants role assignment permissions, not resource management +- Consider scope carefully - subscription-wide vs resource group specific +- Temporary JSON file is written to `$env:TEMP` and immediately deleted + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Related Scripts + +| Script | Purpose | Link | +|--------|---------|------| +| `createUsersAndAssignRole.ps1` | Assign DevCenter roles to users | [create-users-and-assign-role.md](create-users-and-assign-role.md) | +| `deleteUsersAndAssignedRoles.ps1` | Remove role assignments | [delete-users-and-assigned-roles.md](delete-users-and-assigned-roles.md) | +| `generateDeploymentCredentials.ps1` | Create CI/CD service principal | [generate-deployment-credentials.md](generate-deployment-credentials.md) | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +
+ +[โ† cleanSetUp.ps1](../clean-setup.md) | [โฌ†๏ธ Back to Top](#-table-of-contents) | [createUsersAndAssignRole.ps1 โ†’](create-users-and-assign-role.md) + +*DevExp-DevBox โ€ข createCustomRole.ps1 Documentation* + +
diff --git a/docs/scripts/azure/create-users-and-assign-role.md b/docs/scripts/azure/create-users-and-assign-role.md new file mode 100644 index 00000000..6bf68e8f --- /dev/null +++ b/docs/scripts/azure/create-users-and-assign-role.md @@ -0,0 +1,371 @@ +--- +title: "createUsersAndAssignRole.ps1 Script" +description: "Assigns Azure DevCenter roles to the current signed-in user" +author: "DevExp Team" +date: 2026-01-23 +version: "1.0.0" +tags: + - scripts + - azure + - rbac + - devcenter +--- + +# ๐Ÿ‘ฅ createUsersAndAssignRole.ps1 + +> **Assigns Azure DevCenter roles to the current signed-in user** + +> [!NOTE] +> **Target Audience:** Azure Administrators, Platform Engineers +> **Reading Time:** ~8 minutes + +
+๐Ÿ“ Navigation + +| Previous | Index | Next | +|:---------|:-----:|-----:| +| [โ† createCustomRole.ps1](create-custom-role.md) | [Scripts Index](../README.md) | [deleteDeploymentCredentials.ps1 โ†’](delete-deployment-credentials.md) | + +
+ +--- + +## ๐Ÿ“‘ Table of Contents + +- [๐ŸŽฏ Overview](#-overview) +- [๐Ÿ“Š Flow Visualization](#-flow-visualization) +- [๐Ÿ“ Parameters](#-parameters) +- [โš™๏ธ Prerequisites](#-prerequisites) +- [๐Ÿ”‘ Assigned Roles](#-assigned-roles) +- [๐Ÿ”ง Functions Reference](#-functions-reference) +- [๐Ÿ“ Usage Examples](#-usage-examples) +- [โš ๏ธ Error Handling](#-error-handling) +- [๐Ÿ”ง Troubleshooting](#-troubleshooting) +- [๐Ÿ” Security Considerations](#-security-considerations) +- [๐Ÿ”— Related Scripts](#-related-scripts) + +--- + +## ๐ŸŽฏ Overview + +This script retrieves the current Azure AD signed-in user and assigns DevCenter-related RBAC roles at the subscription scope. Use this script when setting up a new user for DevCenter access or as part of environment initialization. + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“Š Flow Visualization + +```mermaid +--- +title: Create Users and Assign Role Flow +--- +flowchart TD + %% ===== SCRIPT ENTRY ===== + subgraph Entry["๐Ÿ“ฅ Script Entry"] + A(["๐Ÿš€ createUsersAndAssignRole.ps1 Start"]) + B[/"๐Ÿ“ Parse Parameters"/] + end + + %% ===== SUBSCRIPTION RESOLUTION ===== + subgraph SubCheck["๐Ÿ” Subscription Resolution"] + C{"๐Ÿ“‹ SubscriptionId provided?"} + D[("โ˜๏ธ az account show")] + end + + %% ===== USER IDENTIFICATION ===== + subgraph UserLookup["๐Ÿ‘ค User Identification"] + E["โš™๏ธ New-UserRoleAssignments"] + F[("๐Ÿ” az ad signed-in-user show")] + G["๐Ÿ†” Get current user Object ID"] + end + + %% ===== ROLE ASSIGNMENT LOOP ===== + subgraph RoleLoop["๐Ÿ”„ Role Assignment Loop"] + H["๐Ÿ“‹ For each DevCenter role"] + I["๐Ÿ” Set-AzureRole"] + I1{"โœ… Role already assigned?"} + I2["โญ๏ธ Skip - already assigned"] + I3[("๐Ÿ”‘ az role assignment create")] + end + + %% ===== SCRIPT EXIT ===== + subgraph Exit["๐Ÿ“ค Script Exit"] + J{"โœ… All succeeded?"} + K[\"๐ŸŽ‰ Roles Assigned"\] + L{{"โŒ Error Handler"}} + end + + %% ===== CONNECTIONS ===== + A -->|parses| B -->|checks| C + C -->|No| D -->|continues| E + C -->|Yes| E + E -->|calls| F -->|retrieves| G -->|iterates| H + H -->|assigns| I -->|checks| I1 + I1 -->|Yes| I2 -->|next| H + I1 -->|No| I3 -->|next| H + H -->|All roles processed| J + J -->|Yes| K + J -->|No| L + + %% ===== STYLES ===== + classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + classDef input fill:#F3F4F6,stroke:#6B7280,color:#000000 + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef external fill:#6B7280,stroke:#4B5563,color:#FFFFFF,stroke-dasharray:5 5 + classDef decision fill:#FFFBEB,stroke:#F59E0B,color:#000000 + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef failed fill:#F44336,stroke:#C62828,color:#FFFFFF + + class A trigger + class B input + class E,G,H,I,I2 primary + class D,F,I3 external + class C,I1,J decision + class K secondary + class L failed + + %% ===== SUBGRAPH STYLES ===== + style Entry fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style SubCheck fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style UserLookup fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style RoleLoop fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style Exit fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Parameters + +| Parameter | Type | Required | Default | Validation | Description | +|-----------|------|----------|---------|------------|-------------| +| `-SubscriptionId` | `string` | No | Current subscription | `ValidatePattern` (GUID format) | Azure subscription ID for role scope | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Prerequisites + +### Required Tools + +| Tool | Purpose | Installation | +|------|---------|--------------| +| Azure CLI (`az`) | Manage role assignments | [Install Azure CLI](https://docs.microsoft.com/cli/azure/install-azure-cli) | +| PowerShell 5.1+ | Script execution | Pre-installed on Windows | + +### Required Permissions + +- **Azure**: `Microsoft.Authorization/roleAssignments/write` at subscription scope +- Typically requires **Owner** or **User Access Administrator** role + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”‘ Assigned Roles + +The script assigns these DevCenter-specific roles: + +| Role Name | Purpose | +|-----------|---------| +| `DevCenter Dev Box User` | Create and manage Dev Boxes | +| `DevCenter Project Admin` | Administer DevCenter projects | +| `Deployment Environments Reader` | View deployment environments | +| `Deployment Environments User` | Use deployment environments | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Functions Reference + +### Function: `Set-AzureRole` + +**Purpose:** Assigns an Azure RBAC role to a user, checking for existing assignment first. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `UserIdentityId` | `string` | Yes | Object ID of the user | +| `RoleName` | `string` | Yes | Name of the RBAC role | +| `PrincipalType` | `string` | Yes | Type: User, ServicePrincipal, or Group | +| `SubscriptionId` | `string` | Yes | Subscription ID for scope | + +**Returns:** `[bool]` - `$true` if assignment succeeded or already exists, `$false` on error + +**Behavior:** + +1. Checks if role is already assigned using `az role assignment list` +2. If not assigned, creates new assignment +3. Skips with message if already assigned + +--- + +### Function: `New-UserRoleAssignments` + +**Purpose:** Creates all DevCenter role assignments for the current signed-in user. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `SubscriptionId` | `string` | Yes | Subscription ID for role assignments | + +**Returns:** `[bool]` - `$true` if all assignments succeeded, `$false` otherwise + +**Behavior:** + +1. Retrieves current user's Object ID via `az ad signed-in-user show` +2. Iterates through predefined DevCenter roles +3. Calls `Set-AzureRole` for each role +4. Tracks success/failure of each assignment + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Usage Examples + +### Basic Usage (Current Subscription) + +```powershell +.\createUsersAndAssignRole.ps1 +``` + +Assigns all DevCenter roles to the currently signed-in user. + +### Specific Subscription + +```powershell +.\createUsersAndAssignRole.ps1 -SubscriptionId "12345678-1234-1234-1234-123456789012" +``` + +
+Expected Output + +``` +Creating role assignments for user: a1b2c3d4-e5f6-7890-abcd-ef1234567890 +Assigning 'DevCenter Dev Box User' role to identity a1b2c3d4-e5f6-7890-abcd-ef1234567890... +Role 'DevCenter Dev Box User' assigned successfully. +Assigning 'DevCenter Project Admin' role to identity a1b2c3d4-e5f6-7890-abcd-ef1234567890... +Role 'DevCenter Project Admin' assigned successfully. +Assigning 'Deployment Environments Reader' role to identity a1b2c3d4-e5f6-7890-abcd-ef1234567890... +Role 'Deployment Environments Reader' assigned successfully. +Assigning 'Deployment Environments User' role to identity a1b2c3d4-e5f6-7890-abcd-ef1234567890... +Role 'Deployment Environments User' assigned successfully. +All role assignments completed successfully for user: a1b2c3d4-e5f6-7890-abcd-ef1234567890 +``` + +
+ +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš ๏ธ Error Handling + +### Error Action Preference + +```powershell +$ErrorActionPreference = 'Stop' +$WarningPreference = 'Stop' +``` + +### Exit Codes + +| Code | Meaning | +|------|---------| +| `0` | All role assignments succeeded | +| `1` | One or more role assignments failed | + +### Idempotency + +The script is **idempotent** - running it multiple times will: + +- Skip roles that are already assigned +- Only attempt to assign missing roles +- Not cause errors for existing assignments + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Troubleshooting + +### Common Issues + +| Issue | Cause | Solution | +|-------|-------|----------| +| "Failed to retrieve current subscription ID" | Not logged into Azure | Run `az login` | +| "Failed to retrieve current signed-in user's object ID" | Not logged into Azure AD | Run `az login` with Azure AD account | +| "Failed to assign role" | Insufficient permissions | Verify Owner/UAA role | +| Role already exists warning | Role previously assigned | This is expected - script continues | + +### Verify Role Assignments + +```powershell +# List current user's role assignments +$userId = az ad signed-in-user show --query id --output tsv +az role assignment list --assignee $userId --query "[].roleDefinitionName" --output table +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ” Security Considerations + +- Script requires elevated Azure permissions to create role assignments +- Roles are assigned at **subscription scope** - consider if more restrictive scope is needed +- DevCenter roles grant access to Dev Box and Environment resources +- Review role capabilities before assignment + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Related Scripts + +| Script | Purpose | Link | +|--------|---------|------| +| `deleteUsersAndAssignedRoles.ps1` | Remove these role assignments | [delete-users-and-assigned-roles.md](delete-users-and-assigned-roles.md) | +| `createCustomRole.ps1` | Create custom role definitions | [create-custom-role.md](create-custom-role.md) | +| `generateDeploymentCredentials.ps1` | Create CI/CD service principal | [generate-deployment-credentials.md](generate-deployment-credentials.md) | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +
+ +[โ† createCustomRole.ps1](create-custom-role.md) | [โฌ†๏ธ Back to Top](#-table-of-contents) | [deleteDeploymentCredentials.ps1 โ†’](delete-deployment-credentials.md) + +*DevExp-DevBox โ€ข createUsersAndAssignRole.ps1 Documentation* + +
diff --git a/docs/scripts/azure/delete-deployment-credentials.md b/docs/scripts/azure/delete-deployment-credentials.md new file mode 100644 index 00000000..e67cec6f --- /dev/null +++ b/docs/scripts/azure/delete-deployment-credentials.md @@ -0,0 +1,341 @@ +--- +title: "deleteDeploymentCredentials.ps1 Script" +description: "Removes Azure AD service principal and application registration for CI/CD cleanup" +author: "DevExp Team" +date: 2026-01-23 +version: "1.0.0" +tags: + - scripts + - azure + - service-principal + - cleanup +--- + +# ๐Ÿ—‘๏ธ deleteDeploymentCredentials.ps1 + +> **Removes Azure AD service principal and application registration for CI/CD cleanup** + +> [!WARNING] +> This script permanently deletes service principals. Ensure CI/CD pipelines are updated before execution. + +> [!NOTE] +> **Target Audience:** Azure Administrators, DevOps Engineers +> **Reading Time:** ~8 minutes + +
+๐Ÿ“ Navigation + +| Previous | Index | Next | +|:---------|:-----:|-----:| +| [โ† createUsersAndAssignRole.ps1](create-users-and-assign-role.md) | [Scripts Index](../README.md) | [deleteUsersAndAssignedRoles.ps1 โ†’](delete-users-and-assigned-roles.md) | + +
+ +--- + +## ๐Ÿ“‘ Table of Contents + +- [๐ŸŽฏ Overview](#-overview) +- [๐Ÿ“Š Flow Visualization](#-flow-visualization) +- [๐Ÿ“ Parameters](#-parameters) +- [โš™๏ธ Prerequisites](#-prerequisites) +- [๐Ÿ”ง Functions Reference](#-functions-reference) +- [๐Ÿ“ Usage Examples](#-usage-examples) +- [โš ๏ธ Error Handling](#-error-handling) +- [๐Ÿ”ง Troubleshooting](#-troubleshooting) +- [๐Ÿ” Security Considerations](#-security-considerations) +- [๐Ÿ”— Related Scripts](#-related-scripts) + +--- + +## ๐ŸŽฏ Overview + +This script removes an Azure AD service principal and its associated application registration by looking up the display name. Use this script to clean up deployment credentials created for CI/CD pipelines, such as those used by GitHub Actions. + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“Š Flow Visualization + +```mermaid +--- +title: Delete Deployment Credentials Flow +--- +flowchart TD + %% ===== SCRIPT ENTRY ===== + subgraph Entry["๐Ÿ“ฅ Script Entry"] + A(["๐Ÿš€ deleteDeploymentCredentials.ps1 Start"]) + B[/"๐Ÿ“ Parse Parameters"/] + end + + %% ===== APPLICATION LOOKUP ===== + subgraph Lookup["๐Ÿ” Application Lookup"] + C["โš™๏ธ Remove-AzureDeploymentCredentials"] + D[("๐Ÿ” az ad app list")] + E{"๐Ÿ“‹ App found?"} + F["๐Ÿ†” Get App ID"] + end + + %% ===== CREDENTIAL DELETION ===== + subgraph Delete["๐Ÿ—‘๏ธ Credential Deletion"] + G[("๐Ÿ—‘๏ธ az ad sp delete")] + H["๐Ÿ‘ค Delete service principal"] + I[("๐Ÿ—‘๏ธ az ad app delete")] + J["๐Ÿ“ Delete app registration"] + end + + %% ===== SCRIPT EXIT ===== + subgraph Exit["๐Ÿ“ค Script Exit"] + K{"โœ… Success?"} + L[\"๐ŸŽ‰ Credentials Deleted"\] + M[\"โญ๏ธ Not Found - Skip"\] + N{{"โŒ Error Handler"}} + end + + %% ===== CONNECTIONS ===== + A -->|parses| B -->|invokes| C -->|queries| D -->|checks| E + E -->|No| M + E -->|Yes| F -->|deletes| G -->|continues| H -->|deletes| I -->|completes| J -->|evaluates| K + K -->|Yes| L + K -->|No| N + + %% ===== STYLES ===== + classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + classDef input fill:#F3F4F6,stroke:#6B7280,color:#000000 + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef external fill:#6B7280,stroke:#4B5563,color:#FFFFFF,stroke-dasharray:5 5 + classDef decision fill:#FFFBEB,stroke:#F59E0B,color:#000000 + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef failed fill:#F44336,stroke:#C62828,color:#FFFFFF + + class A trigger + class B input + class C,F,H,J primary + class D,G,I external + class E,K decision + class L,M secondary + class N failed + + %% ===== SUBGRAPH STYLES ===== + style Entry fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style Lookup fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style Delete fill:#FEE2E2,stroke:#F44336,stroke-width:2px + style Exit fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Parameters + +| Parameter | Type | Required | Default | Validation | Description | +|-----------|------|----------|---------|------------|-------------| +| `-AppDisplayName` | `string` | Yes | - | `ValidateNotNullOrEmpty` | Display name of the application registration to delete | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Prerequisites + +### Required Tools + +| Tool | Purpose | Installation | +|------|---------|--------------| +| Azure CLI (`az`) | Manage Azure AD objects | [Install Azure CLI](https://docs.microsoft.com/cli/azure/install-azure-cli) | +| PowerShell 5.1+ | Script execution | Pre-installed on Windows | + +### Required Permissions + +- **Azure AD**: `Application.ReadWrite.All` or **Application Administrator** role +- Permission to delete service principals in the tenant + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Functions Reference + +### Function: `Remove-AzureDeploymentCredentials` + +**Purpose:** Removes an Azure AD service principal and application registration by display name. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `DisplayName` | `string` | Yes | Display name of the application | + +**Returns:** `[bool]` - `$true` if deletion succeeded or app not found, `$false` on error + +**Deletion Sequence:** + +1. Look up application by display name +2. If not found, return `$true` with warning (idempotent) +3. Delete service principal first (`az ad sp delete`) +4. Delete application registration (`az ad app delete`) + +**Important:** Service principal must be deleted before the application registration. + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Usage Examples + +### Delete Default CI/CD Credentials + +```powershell +.\deleteDeploymentCredentials.ps1 -AppDisplayName "ContosoDevEx GitHub Actions Enterprise App" +``` + +### Delete Custom Named Application + +```powershell +.\deleteDeploymentCredentials.ps1 -AppDisplayName "MyCompany DevOps Service Principal" +``` + +### Dry Run (WhatIf) + +```powershell +.\deleteDeploymentCredentials.ps1 -AppDisplayName "ContosoDevEx GitHub Actions Enterprise App" -WhatIf +``` + +
+Expected Output (Successful Deletion) + +``` +Starting deployment credentials cleanup for: ContosoDevEx GitHub Actions Enterprise App +Found application with App ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890 +Deleting service principal... +Service principal deleted successfully. +Deleting application registration... +Application registration deleted successfully. +Deployment credentials cleanup completed for: ContosoDevEx GitHub Actions Enterprise App +Cleanup completed successfully. +``` + +
+ +
+Expected Output (Application Not Found) + +``` +Starting deployment credentials cleanup for: NonExistentApp +Application with display name 'NonExistentApp' not found. Nothing to delete. +Cleanup completed successfully. +``` + +
+ +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš ๏ธ Error Handling + +### Error Action Preference + +```powershell +$ErrorActionPreference = 'Stop' +$WarningPreference = 'Stop' +``` + +### Exit Codes + +| Code | Meaning | +|------|---------| +| `0` | Deletion succeeded or application not found | +| `1` | Deletion failed | + +### Idempotency + +The script is **idempotent**: + +- If application doesn't exist, returns success with warning +- Safe to run multiple times + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Troubleshooting + +### Common Issues + +| Issue | Cause | Solution | +|-------|-------|----------| +| "Failed to query Azure AD applications" | Not logged into Azure | Run `az login` | +| "Application not found" | Wrong display name or already deleted | Verify display name | +| "Failed to delete service principal" | SP already deleted | Continue to app deletion | +| "Failed to delete application registration" | Insufficient permissions | Verify Azure AD admin role | + +### Verify Deletion + +```powershell +# Check if application still exists +az ad app list --display-name "ContosoDevEx GitHub Actions Enterprise App" --query "[].appId" --output tsv +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ” Security Considerations + +- Deleting service principals **immediately revokes** all associated credentials +- Any CI/CD pipelines using these credentials will **fail** after deletion +- Consider rotating credentials first if gradual transition is needed +- This action is **not reversible** - app must be recreated + +### Before Deletion Checklist + +- [ ] Verify no active deployments are using these credentials +- [ ] Update or disable CI/CD workflows that use `AZURE_CREDENTIALS` +- [ ] Confirm you have permission to recreate if needed + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Related Scripts + +| Script | Purpose | Link | +|--------|---------|------| +| `generateDeploymentCredentials.ps1` | Create new deployment credentials | [generate-deployment-credentials.md](generate-deployment-credentials.md) | +| `deleteGitHubSecretAzureCredentials.ps1` | Remove GitHub secret | [../github/delete-github-secret-azure-credentials.md](../github/delete-github-secret-azure-credentials.md) | +| `cleanSetUp.ps1` | Full environment cleanup | [../clean-setup.md](../clean-setup.md) | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +
+ +[โ† createUsersAndAssignRole.ps1](create-users-and-assign-role.md) | [โฌ†๏ธ Back to Top](#-table-of-contents) | [deleteUsersAndAssignedRoles.ps1 โ†’](delete-users-and-assigned-roles.md) + +*DevExp-DevBox โ€ข deleteDeploymentCredentials.ps1 Documentation* + +
diff --git a/docs/scripts/azure/delete-users-and-assigned-roles.md b/docs/scripts/azure/delete-users-and-assigned-roles.md new file mode 100644 index 00000000..9dacfe56 --- /dev/null +++ b/docs/scripts/azure/delete-users-and-assigned-roles.md @@ -0,0 +1,392 @@ +--- +title: "deleteUsersAndAssignedRoles.ps1 Script" +description: "Removes DevCenter role assignments from the current signed-in user" +author: "DevExp Team" +date: 2026-01-23 +version: "1.0.0" +tags: + - scripts + - azure + - rbac + - cleanup +--- + +# ๐Ÿ‘ฅ deleteUsersAndAssignedRoles.ps1 + +> **Removes DevCenter role assignments from the current signed-in user** + +> [!NOTE] +> **Target Audience:** Azure Administrators, Platform Engineers +> **Reading Time:** ~8 minutes + +
+๐Ÿ“ Navigation + +| Previous | Index | Next | +|:---------|:-----:|-----:| +| [โ† deleteDeploymentCredentials.ps1](delete-deployment-credentials.md) | [Scripts Index](../README.md) | [generateDeploymentCredentials.ps1 โ†’](generate-deployment-credentials.md) | + +
+ +--- + +## ๐Ÿ“‘ Table of Contents + +- [๐ŸŽฏ Overview](#-overview) +- [๐Ÿ“Š Flow Visualization](#-flow-visualization) +- [๐Ÿ“ Parameters](#-parameters) +- [โš™๏ธ Prerequisites](#-prerequisites) +- [๐Ÿ”‘ Removed Roles](#-removed-roles) +- [๐Ÿ”ง Functions Reference](#-functions-reference) +- [๐Ÿ“ Usage Examples](#-usage-examples) +- [โš ๏ธ Error Handling](#-error-handling) +- [๐Ÿ”ง Troubleshooting](#-troubleshooting) +- [๐Ÿ” Security Considerations](#-security-considerations) +- [๐Ÿ”— Related Scripts](#-related-scripts) + +--- + +## ๐ŸŽฏ Overview + +This script removes Azure RBAC role assignments that were created for DevCenter operations from the current signed-in user. Use this script during environment cleanup or when revoking DevCenter access. + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“Š Flow Visualization + +```mermaid +--- +title: Delete Users and Assigned Roles Flow +--- +flowchart TD + %% ===== SCRIPT ENTRY ===== + subgraph Entry["๐Ÿ“ฅ Script Entry"] + A(["๐Ÿš€ deleteUsersAndAssignedRoles.ps1 Start"]) + B[/"๐Ÿ“ Parse Parameters"/] + end + + %% ===== SUBSCRIPTION RESOLUTION ===== + subgraph SubCheck["๐Ÿ” Subscription Resolution"] + C{"๐Ÿ“‹ SubscriptionId provided?"} + D[("โ˜๏ธ az account show")] + end + + %% ===== USER IDENTIFICATION ===== + subgraph UserLookup["๐Ÿ‘ค User Identification"] + E["โš™๏ธ Remove-UserRoleAssignments"] + F[("๐Ÿ” az ad signed-in-user show")] + G["๐Ÿ†” Get current user Object ID"] + end + + %% ===== ROLE REMOVAL LOOP ===== + subgraph RoleLoop["๐Ÿ”„ Role Removal Loop"] + H["๐Ÿ“‹ For each DevCenter role"] + I["๐Ÿ—‘๏ธ Remove-UserRoleAssignment"] + I1{"โœ… Role assigned?"} + I2["โญ๏ธ Skip - not assigned"] + I3[("๐Ÿ—‘๏ธ az role assignment delete")] + end + + %% ===== SCRIPT EXIT ===== + subgraph Exit["๐Ÿ“ค Script Exit"] + J{"โœ… All succeeded?"} + K[\"๐ŸŽ‰ Roles Removed"\] + L{{"โŒ Error Handler"}} + end + + %% ===== CONNECTIONS ===== + A -->|parses| B -->|checks| C + C -->|No| D -->|continues| E + C -->|Yes| E + E -->|calls| F -->|retrieves| G -->|iterates| H + H -->|checks| I -->|evaluates| I1 + I1 -->|No| I2 -->|next| H + I1 -->|Yes| I3 -->|next| H + H -->|All roles processed| J + J -->|Yes| K + J -->|No| L + + %% ===== STYLES ===== + classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + classDef input fill:#F3F4F6,stroke:#6B7280,color:#000000 + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef external fill:#6B7280,stroke:#4B5563,color:#FFFFFF,stroke-dasharray:5 5 + classDef decision fill:#FFFBEB,stroke:#F59E0B,color:#000000 + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef failed fill:#F44336,stroke:#C62828,color:#FFFFFF + + class A trigger + class B input + class E,G,H,I,I2 primary + class D,F,I3 external + class C,I1,J decision + class K secondary + class L failed + + %% ===== SUBGRAPH STYLES ===== + style Entry fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style SubCheck fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style UserLookup fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style RoleLoop fill:#FEE2E2,stroke:#F44336,stroke-width:2px + style Exit fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Parameters + +| Parameter | Type | Required | Default | Validation | Description | +|-----------|------|----------|---------|------------|-------------| +| `-AppDisplayName` | `string` | No | - | - | Associated application name (for logging) | +| `-SubscriptionId` | `string` | No | Current subscription | `ValidatePattern` (GUID format) | Azure subscription ID for role scope | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Prerequisites + +### Required Tools + +| Tool | Purpose | Installation | +|------|---------|--------------| +| Azure CLI (`az`) | Manage role assignments | [Install Azure CLI](https://docs.microsoft.com/cli/azure/install-azure-cli) | +| PowerShell 5.1+ | Script execution | Pre-installed on Windows | + +### Required Permissions + +- **Azure**: `Microsoft.Authorization/roleAssignments/delete` at subscription scope +- Typically requires **Owner** or **User Access Administrator** role + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”‘ Removed Roles + +The script removes these DevCenter-specific roles: + +| Role Name | Purpose | +|-----------|---------| +| `DevCenter Dev Box User` | Create and manage Dev Boxes | +| `DevCenter Project Admin` | Administer DevCenter projects | +| `Deployment Environments Reader` | View deployment environments | +| `Deployment Environments User` | Use deployment environments | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Functions Reference + +### Function: `Remove-UserRoleAssignment` + +**Purpose:** Removes a specific Azure RBAC role assignment from a user. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `UserIdentityId` | `string` | Yes | Object ID of the user | +| `RoleName` | `string` | Yes | Name of the RBAC role | +| `SubscriptionId` | `string` | Yes | Subscription ID for scope | + +**Returns:** `[bool]` - `$true` if removal succeeded or role not assigned, `$false` on error + +**Behavior:** + +1. Checks if role is assigned using `az role assignment list` +2. If assigned, removes via `az role assignment delete` +3. If not assigned, skips with informational message +4. Supports `-WhatIf` via `SupportsShouldProcess` + +--- + +### Function: `Remove-UserRoleAssignments` + +**Purpose:** Removes all DevCenter role assignments from the current signed-in user. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `SubscriptionId` | `string` | Yes | Subscription ID for role removal | + +**Returns:** `[bool]` - `$true` if all removals succeeded, `$false` otherwise + +**Behavior:** + +1. Retrieves current user's Object ID via `az ad signed-in-user show` +2. Iterates through predefined DevCenter roles +3. Calls `Remove-UserRoleAssignment` for each role +4. Tracks success/failure of each removal + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Usage Examples + +### Basic Usage (Current Subscription) + +```powershell +.\deleteUsersAndAssignedRoles.ps1 +``` + +Removes all DevCenter roles from the currently signed-in user. + +### With Application Context (for logging) + +```powershell +.\deleteUsersAndAssignedRoles.ps1 -AppDisplayName "ContosoDevEx GitHub Actions Enterprise App" +``` + +### Specific Subscription + +```powershell +.\deleteUsersAndAssignedRoles.ps1 -SubscriptionId "12345678-1234-1234-1234-123456789012" +``` + +### Dry Run (WhatIf) + +```powershell +.\deleteUsersAndAssignedRoles.ps1 -WhatIf +``` + +
+Expected Output + +``` +Starting role cleanup for application: ContosoDevEx GitHub Actions Enterprise App +Removing role assignments for user: a1b2c3d4-e5f6-7890-abcd-ef1234567890 +Removing 'DevCenter Dev Box User' role from identity a1b2c3d4-e5f6-7890-abcd-ef1234567890... +Role 'DevCenter Dev Box User' removed successfully. +Removing 'DevCenter Project Admin' role from identity a1b2c3d4-e5f6-7890-abcd-ef1234567890... +Role 'DevCenter Project Admin' removed successfully. +Removing 'Deployment Environments Reader' role from identity a1b2c3d4-e5f6-7890-abcd-ef1234567890... +Role 'Deployment Environments Reader' removed successfully. +Removing 'Deployment Environments User' role from identity a1b2c3d4-e5f6-7890-abcd-ef1234567890... +Role 'Deployment Environments User' removed successfully. +All role assignments removed successfully for user: a1b2c3d4-e5f6-7890-abcd-ef1234567890 +User role assignments cleanup completed successfully. +``` + +
+ +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš ๏ธ Error Handling + +### Error Action Preference + +```powershell +$ErrorActionPreference = 'Stop' +$WarningPreference = 'Stop' +``` + +### Exit Codes + +| Code | Meaning | +|------|---------| +| `0` | All role removals succeeded | +| `1` | One or more role removals failed | + +### Idempotency + +The script is **idempotent** - running it multiple times will: + +- Skip roles that are not assigned +- Not cause errors for missing assignments +- Only attempt to remove existing assignments + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Troubleshooting + +### Common Issues + +| Issue | Cause | Solution | +|-------|-------|----------| +| "Failed to retrieve current subscription ID" | Not logged into Azure | Run `az login` | +| "Failed to retrieve current signed-in user's object ID" | Not logged into Azure AD | Run `az login` | +| "Failed to remove role" | Insufficient permissions | Verify Owner/UAA role | +| Role not assigned warning | Role already removed or never assigned | Expected behavior | + +### Verify Role Removal + +```powershell +# List current user's remaining role assignments +$userId = az ad signed-in-user show --query id --output tsv +az role assignment list --assignee $userId --query "[].roleDefinitionName" --output table +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ” Security Considerations + +- Removing roles **immediately revokes** DevCenter access +- User will lose ability to create Dev Boxes or access Deployment Environments +- Verify user doesn't have active Dev Boxes before removing access +- Consider if role removal affects ongoing work + +### Before Removal Checklist + +- [ ] Verify user has no active Dev Boxes that need access +- [ ] Confirm role removal aligns with access policy +- [ ] Document reason for access revocation + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Related Scripts + +| Script | Purpose | Link | +|--------|---------|------| +| `createUsersAndAssignRole.ps1` | Create these role assignments | [create-users-and-assign-role.md](create-users-and-assign-role.md) | +| `deleteDeploymentCredentials.ps1` | Remove service principal | [delete-deployment-credentials.md](delete-deployment-credentials.md) | +| `cleanSetUp.ps1` | Full environment cleanup | [../clean-setup.md](../clean-setup.md) | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +
+ +[โ† deleteDeploymentCredentials.ps1](delete-deployment-credentials.md) | [โฌ†๏ธ Back to Top](#-table-of-contents) | [generateDeploymentCredentials.ps1 โ†’](generate-deployment-credentials.md) + +*DevExp-DevBox โ€ข deleteUsersAndAssignedRoles.ps1 Documentation* + +
diff --git a/docs/scripts/azure/generate-deployment-credentials.md b/docs/scripts/azure/generate-deployment-credentials.md new file mode 100644 index 00000000..9069a006 --- /dev/null +++ b/docs/scripts/azure/generate-deployment-credentials.md @@ -0,0 +1,459 @@ +--- +title: "generateDeploymentCredentials.ps1 Script" +description: "Creates Azure service principal and GitHub secret for CI/CD pipelines" +author: "DevExp Team" +date: 2026-01-23 +version: "1.0.0" +tags: + - scripts + - azure + - service-principal + - github + - cicd +--- + +# ๐Ÿ”‘ generateDeploymentCredentials.ps1 + +> **Creates Azure service principal and GitHub secret for CI/CD pipelines** + +> [!IMPORTANT] +> This script creates credentials with elevated permissions. Review the [Security Considerations](#security-considerations) section before use. + +> [!NOTE] +> **Target Audience:** DevOps Engineers, Platform Engineers +> **Reading Time:** ~12 minutes + +
+๐Ÿ“ Navigation + +| Previous | Index | Next | +|:---------|:-----:|-----:| +| [โ† deleteUsersAndAssignedRoles.ps1](delete-users-and-assigned-roles.md) | [Scripts Index](../README.md) | [Configuration Scripts โ†’](../configuration/clean-up.md) | + +
+ +--- + +## ๐Ÿ“‘ Table of Contents + +- [๐ŸŽฏ Overview](#-overview) +- [๐Ÿ“Š Flow Visualization](#-flow-visualization) +- [๐Ÿ”„ Service Principal Creation Flow](#-service-principal-creation-flow) +- [๐Ÿ“ Parameters](#-parameters) +- [โš™๏ธ Prerequisites](#-prerequisites) +- [๐Ÿ‘ฅ Assigned Roles](#-assigned-roles) +- [๐Ÿ”ง Functions Reference](#-functions-reference) +- [๐Ÿ“ Usage Examples](#-usage-examples) +- [โš ๏ธ Error Handling](#-error-handling) +- [๐Ÿ”’ Security Considerations](#-security-considerations) +- [๐Ÿ› ๏ธ Troubleshooting](#-troubleshooting) +- [๐Ÿ”— Related Scripts](#-related-scripts) + +--- + +## ๐ŸŽฏ Overview + +This script creates an Azure AD service principal with required roles for CI/CD pipelines and configures the credentials as a GitHub repository secret. Use this script when setting up GitHub Actions workflows that need to deploy Azure resources. + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“Š Flow Visualization + +```mermaid +--- +title: Generate Deployment Credentials Flow +--- +flowchart TD + %% ===== SCRIPT ENTRY ===== + subgraph Entry["๐Ÿ“ฅ Script Entry"] + A(["๐Ÿš€ generateDeploymentCredentials.ps1 Start"]) + B[/"๐Ÿ“ Parse Parameters"/] + end + + %% ===== SERVICE PRINCIPAL CREATION ===== + subgraph SPCreation["๐Ÿ” Service Principal Creation"] + C["โš™๏ธ New-AzureDeploymentCredentials"] + D[("๐Ÿ”‘ az ad sp create-for-rbac")] + E["๐Ÿ‘ค Assign Contributor role"] + F[("๐Ÿ›ก๏ธ az role assignment create")] + G["๐Ÿ” Assign User Access Administrator"] + H["๐Ÿ†” Assign Managed Identity Contributor"] + end + + %% ===== USER ROLE SETUP ===== + subgraph UserRoles["๐Ÿ‘ฅ User Role Setup"] + I["โš™๏ธ Invoke-UserRoleAssignment"] + J[("๐Ÿ”ง createUsersAndAssignRole.ps1")] + end + + %% ===== GITHUB SECRET CREATION ===== + subgraph GitHubSecret["๐Ÿ™ GitHub Secret Creation"] + K["โš™๏ธ Invoke-GitHubSecretCreation"] + L[("๐Ÿ“ createGitHubSecretAzureCredentials.ps1")] + end + + %% ===== SCRIPT EXIT ===== + subgraph Exit["๐Ÿ“ค Script Exit"] + M{"โœ… All succeeded?"} + N[\"๐ŸŽ‰ Credentials Created"\] + O{{"โš ๏ธ Warning: Partial failure"}} + end + + %% ===== CONNECTIONS ===== + A -->|parses| B -->|invokes| C -->|creates| D -->|assigns| E -->|calls| F -->|assigns| G -->|assigns| H + H -->|invokes| I -->|runs| J + J -->|invokes| K -->|runs| L -->|evaluates| M + M -->|Yes| N + M -->|No| O + + %% ===== STYLES ===== + classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + classDef input fill:#F3F4F6,stroke:#6B7280,color:#000000 + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef external fill:#6B7280,stroke:#4B5563,color:#FFFFFF,stroke-dasharray:5 5 + classDef decision fill:#FFFBEB,stroke:#F59E0B,color:#000000 + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef failed fill:#F44336,stroke:#C62828,color:#FFFFFF + + class A trigger + class B input + class C,E,G,H,I,K primary + class D,F,J,L external + class M decision + class N secondary + class O failed + + %% ===== SUBGRAPH STYLES ===== + style Entry fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style SPCreation fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style UserRoles fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style GitHubSecret fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Exit fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”„ Service Principal Creation Flow + +```mermaid +sequenceDiagram + participant Script as generateDeploymentCredentials.ps1 + participant AzCLI as Azure CLI + participant AzAD as Azure AD + participant GhCLI as GitHub CLI + participant GhRepo as GitHub Repository + + Script->>AzCLI: az account show + AzCLI-->>Script: Subscription ID + + Script->>AzCLI: az ad sp create-for-rbac + AzCLI->>AzAD: Create App Registration + AzAD-->>AzCLI: App ID + Secret + AzCLI-->>Script: JSON credentials + + Script->>AzCLI: az role assignment create (UAA) + Script->>AzCLI: az role assignment create (MIC) + + Script->>Script: createUsersAndAssignRole.ps1 + + Script->>Script: createGitHubSecretAzureCredentials.ps1 + Script->>GhCLI: gh secret set AZURE_CREDENTIALS + GhCLI->>GhRepo: Store encrypted secret + GhRepo-->>Script: Secret created +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Parameters + +| Parameter | Type | Required | Default | Validation | Description | +|-----------|------|----------|---------|------------|-------------| +| `-AppName` | `string` | Yes | - | `ValidateNotNullOrEmpty` | Name for the Azure AD application registration | +| `-DisplayName` | `string` | Yes | - | `ValidateNotNullOrEmpty` | Display name for the service principal | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Prerequisites + +### Required Tools + +| Tool | Purpose | Installation | +|------|---------|--------------| +| Azure CLI (`az`) | Create service principal and roles | [Install Azure CLI](https://docs.microsoft.com/cli/azure/install-azure-cli) | +| GitHub CLI (`gh`) | Create repository secret | [Install GitHub CLI](https://cli.github.com/) | +| PowerShell 5.1+ | Script execution | Pre-installed on Windows | + +### Required Permissions + +- **Azure**: Owner or Contributor + User Access Administrator on subscription +- **Azure AD**: `Application.ReadWrite.All` or Application Administrator +- **GitHub**: Repository admin access to create secrets + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ‘ฅ Assigned Roles + +The created service principal receives these roles at subscription scope: + +| Role | Purpose | +|------|---------| +| `Contributor` | Deploy and manage Azure resources | +| `User Access Administrator` | Create role assignments for deployed resources | +| `Managed Identity Contributor` | Create and manage managed identities | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Functions Reference + +### Function: `New-AzureDeploymentCredentials` + +**Purpose:** Creates an Azure service principal with required roles for CI/CD. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `AppName` | `string` | Yes | Application registration name | +| `DisplayName` | `string` | Yes | Service principal display name | + +**Returns:** `[string]` - JSON credentials body for GitHub Actions, or `$null` on failure + +**Created Credentials Format:** + +```json +{ + "clientId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "clientSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", + "subscriptionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" +} +``` + +--- + +### Function: `Invoke-UserRoleAssignment` + +**Purpose:** Executes the `createUsersAndAssignRole.ps1` script to assign DevCenter roles. + +**Returns:** `[bool]` - `$true` if successful, `$false` otherwise + +**Called Script:** `createUsersAndAssignRole.ps1` (same directory) + +--- + +### Function: `Invoke-GitHubSecretCreation` + +**Purpose:** Executes the GitHub secret creation script. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `CredentialsJson` | `string` | Yes | JSON credentials to store as secret | + +**Returns:** `[bool]` - `$true` if successful, `$false` otherwise + +**Called Script:** `..\GitHub\createGitHubSecretAzureCredentials.ps1` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Usage Examples + +### Create Deployment Credentials + +```powershell +.\generateDeploymentCredentials.ps1 -AppName "contoso-devbox-cicd" -DisplayName "Contoso DevBox CI/CD" +``` + +### With Verbose Output + +```powershell +.\generateDeploymentCredentials.ps1 -AppName "myapp-deploy" -DisplayName "MyApp Deployment SP" -Verbose +``` + +
+Expected Output + +``` +Starting deployment credentials generation... +App Name: contoso-devbox-cicd +Display Name: Contoso DevBox CI/CD +Creating service principal 'Contoso DevBox CI/CD' in subscription: 12345678-1234-1234-1234-123456789012 +Service principal created with App ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890 +Assigning additional roles... +Assigned: User Access Administrator +Assigned: Managed Identity Contributor +Role assignments completed successfully. + +Service principal credentials (for reference): +{ + "clientId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "clientSecret": "xxx~xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", + "subscriptionId": "12345678-1234-1234-1234-123456789012", + "tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" +} + +Creating user role assignments... +User role assignments completed successfully. +Creating GitHub secret for Azure credentials... +GitHub secret created successfully. + +Deployment credentials generation completed. +``` + +
+ +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš ๏ธ Error Handling + +### Error Action Preference + +```powershell +$ErrorActionPreference = 'Stop' +$WarningPreference = 'Stop' +``` + +### Exit Codes + +| Code | Meaning | +|------|---------| +| `0` | Credentials created (GitHub secret may have warnings) | +| `1` | Critical failure during credential creation | + +### Partial Failure Handling + +The script continues with warnings if: + +- User role assignment fails (non-critical) +- GitHub secret creation fails (credentials still valid) + +Credentials are displayed on console if GitHub secret creation fails. + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”’ Security Considerations + +### Credential Exposure + +- Credentials are displayed on console during creation +- Ensure console output is not logged or captured +- Credentials are immediately stored as encrypted GitHub secret + +### Secret Rotation + +- Client secret has default 1-year expiration +- Plan for credential rotation before expiration +- Use `deleteDeploymentCredentials.ps1` to clean up old credentials + +### Principle of Least Privilege + +The service principal has elevated permissions: + +- **User Access Administrator**: Can grant any role +- **Managed Identity Contributor**: Can create identities + +Consider if these are necessary for your workflow. + +### GitHub Secret Security + +- Secret is encrypted at rest in GitHub +- Only accessible to repository workflows +- Secret value cannot be read after creation +- Audit logs track secret usage + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ› ๏ธ Troubleshooting + +### Common Issues + +| Issue | Cause | Solution | +|-------|-------|----------| +| "Failed to retrieve subscription ID" | Not logged into Azure | Run `az login` | +| "Failed to create service principal" | Insufficient Azure AD permissions | Verify Application Administrator role | +| "Failed to assign role" | Insufficient Azure permissions | Verify Owner/UAA role | +| "GitHub secret script not found" | Directory structure issue | Verify script paths | + +### Verify Service Principal + +```powershell +# List service principal details +az ad sp list --display-name "Contoso DevBox CI/CD" --query "[].{appId:appId, displayName:displayName}" --output table +``` + +### Verify GitHub Secret + +```powershell +# List repository secrets +gh secret list +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Related Scripts + +| Script | Purpose | Link | +|--------|---------|------| +| `deleteDeploymentCredentials.ps1` | Remove service principal | [delete-deployment-credentials.md](delete-deployment-credentials.md) | +| `createUsersAndAssignRole.ps1` | Assign user roles | [create-users-and-assign-role.md](create-users-and-assign-role.md) | +| `createGitHubSecretAzureCredentials.ps1` | Create GitHub secret | [../github/create-github-secret-azure-credentials.md](../github/create-github-secret-azure-credentials.md) | +| `cleanSetUp.ps1` | Full environment cleanup | [../clean-setup.md](../clean-setup.md) | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +
+ +[โ† deleteUsersAndAssignedRoles.ps1](delete-users-and-assigned-roles.md) | [โฌ†๏ธ Back to Top](#-table-of-contents) | [Configuration Scripts โ†’](../configuration/clean-up.md) + +*DevExp-DevBox โ€ข generateDeploymentCredentials.ps1 Documentation* + +
diff --git a/docs/scripts/clean-setup.md b/docs/scripts/clean-setup.md new file mode 100644 index 00000000..6d4675ab --- /dev/null +++ b/docs/scripts/clean-setup.md @@ -0,0 +1,402 @@ +--- +title: "cleanSetUp.ps1 Script" +description: "Complete DevExp-DevBox infrastructure cleanup orchestrator script" +author: "DevExp Team" +date: 2026-01-23 +version: "1.0.0" +tags: + - scripts + - cleanup + - azure + - orchestration +--- + +# ๐Ÿงน cleanSetUp.ps1 + +> **Complete DevExp-DevBox infrastructure cleanup orchestrator** + +> [!WARNING] +> This script performs **destructive operations**. Ensure you have backups and have verified the target environment before execution. + +> [!NOTE] +> **Target Audience:** DevOps Engineers, Platform Engineers, System Administrators +> **Reading Time:** ~10 minutes + +
+๐Ÿ“ Navigation + +| Previous | Index | Next | +|:---------|:-----:|-----:| +| [โ† setUp.ps1](setup.md) | [Scripts Index](README.md) | [Azure Scripts โ†’](azure/create-custom-role.md) | + +
+ +--- + +## ๐Ÿ“‘ Table of Contents + +- [๐ŸŽฏ Overview](#overview) +- [๐Ÿ“Š Flow Visualization](#flow-visualization) +- [๐Ÿ“ Parameters](#parameters) +- [โš™๏ธ Prerequisites](#prerequisites) +- [๐Ÿ”ง Functions Reference](#functions-reference) +- [๐Ÿ“ Usage Examples](#usage-examples) +- [โš ๏ธ Error Handling](#error-handling) +- [๐Ÿ”ง Troubleshooting](#troubleshooting) +- [๐Ÿ”— Related Scripts](#related-scripts) + +--- + +## ๐ŸŽฏ Overview + +This script orchestrates the complete cleanup of DevExp-DevBox infrastructure, including Azure deployments, user role assignments, service principals, GitHub secrets, and resource groups. Use this script when you need to tear down an entire DevExp-DevBox environment. + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“Š Flow Visualization + +```mermaid +--- +title: Clean Setup Script Flow +--- +flowchart TD + %% ===== SCRIPT ENTRY ===== + subgraph Entry["๐Ÿ“ฅ Script Entry"] + A(["๐Ÿš€ cleanSetUp.ps1 Start"]) + B[/"๐Ÿ“ Parse Parameters"/] + end + + %% ===== MAIN ORCHESTRATION ===== + subgraph Main["๐ŸŽฏ Main Orchestration"] + C["โš™๏ธ Start-FullCleanup"] + end + + %% ===== SUBSCRIPTION DEPLOYMENTS ===== + subgraph Deployments["๐Ÿ“‹ Subscription Deployments"] + D["๐Ÿ—‘๏ธ Remove-SubscriptionDeployments"] + D1{"๐Ÿ“Š Deployments exist?"} + D2["๐Ÿ”„ Delete each deployment"] + D3[\"โœ… Deployments removed"\] + end + + %% ===== USER CLEANUP ===== + subgraph Users["๐Ÿ‘ฅ User Cleanup"] + E["โš™๏ธ Invoke-CleanupScript"] + E1[("๐Ÿ”ง deleteUsersAndAssignedRoles.ps1")] + end + + %% ===== CREDENTIALS CLEANUP ===== + subgraph Credentials["๐Ÿ”‘ Credentials Cleanup"] + F["โš™๏ธ Invoke-CleanupScript"] + F1[("๐Ÿ”ง deleteDeploymentCredentials.ps1")] + end + + %% ===== GITHUB SECRET CLEANUP ===== + subgraph GitHub["๐Ÿ™ GitHub Secret Cleanup"] + G["โš™๏ธ Invoke-CleanupScript"] + G1[("๐Ÿ”ง deleteGitHubSecretAzureCredentials.ps1")] + end + + %% ===== RESOURCE GROUPS ===== + subgraph Resources["๐Ÿข Resource Groups"] + H["โš™๏ธ Invoke-CleanupScript"] + H1[("๐Ÿ”ง cleanUp.ps1")] + end + + %% ===== SCRIPT EXIT ===== + subgraph Exit["๐Ÿ“ค Script Exit"] + I{"โœ… All succeeded?"} + J[\"๐ŸŽ‰ Success"\] + K{{"โŒ Error Handler"}} + end + + %% ===== CONNECTIONS ===== + A -->|parses| B -->|orchestrates| C + C -->|removes| D + D -->|checks| D1 + D1 -->|Yes| D2 -->|completes| D3 + D1 -->|No| D3 + D3 -->|invokes| E -->|runs| E1 + E1 -->|invokes| F -->|runs| F1 + F1 -->|invokes| G -->|runs| G1 + G1 -->|invokes| H -->|runs| H1 + H1 -->|evaluates| I + I -->|Yes| J + I -->|No| K + + %% ===== STYLES ===== + classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + classDef input fill:#F59E0B,stroke:#D97706,color:#000000 + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef external fill:#6B7280,stroke:#4B5563,color:#FFFFFF,stroke-dasharray:5 5 + classDef decision fill:#FFFBEB,stroke:#F59E0B,color:#000000 + classDef failed fill:#F44336,stroke:#C62828,color:#FFFFFF + + class A trigger + class B input + class C,D,E,F,G,H primary + class D2,D3,J secondary + class E1,F1,G1,H1 external + class D1,I decision + class K failed + + %% ===== SUBGRAPH STYLES ===== + style Entry fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style Main fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style Deployments fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style Users fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Credentials fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style GitHub fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Resources fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Exit fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Parameters + +| Parameter | Type | Required | Default | Validation | Description | +|-----------|------|----------|---------|------------|-------------| +| `-EnvName` | `string` | No | `"gitHub"` | `ValidateNotNullOrEmpty` | The environment name used in resource naming | +| `-Location` | `string` | No | `"eastus2"` | `ValidateSet` | Azure region (eastus, eastus2, westus, westus2, westus3, northeurope, westeurope) | +| `-AppDisplayName` | `string` | No | `"ContosoDevEx GitHub Actions Enterprise App"` | `ValidateNotNullOrEmpty` | Display name of the Azure AD application to delete | +| `-GhSecretName` | `string` | No | `"AZURE_CREDENTIALS"` | `ValidateNotNullOrEmpty` | Name of the GitHub secret to delete | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Prerequisites + +### Required Tools + +| Tool | Purpose | Installation | +|------|---------|--------------| +| Azure CLI (`az`) | Manage Azure resources and deployments | [Install Azure CLI](https://docs.microsoft.com/cli/azure/install-azure-cli) | +| GitHub CLI (`gh`) | Manage GitHub secrets | [Install GitHub CLI](https://cli.github.com/) | +| PowerShell 5.1+ | Script execution | Pre-installed on Windows | + +### Required Permissions + +- **Azure**: Owner or Contributor + User Access Administrator on the subscription +- **Azure AD**: Application Administrator to delete service principals +- **GitHub**: Repository admin access to delete secrets + +### Environment Variables + +None required - all configuration via parameters. + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Functions Reference + +### Function: `Remove-SubscriptionDeployments` + +**Purpose:** Deletes all Azure Resource Manager deployments at the subscription level. + +**Parameters:** None + +**Returns:** `[bool]` - `$true` if successful, `$false` otherwise + +**Behavior:** + +1. Lists all subscription-level deployments using `az deployment sub list` +2. Iterates through each deployment and deletes it +3. Supports `-WhatIf` via `SupportsShouldProcess` +4. Continues on individual deployment failures + +
+Example Output + +``` +Retrieving subscription deployments... +Deleting deployment: main-deployment-20240115 +Deployment 'main-deployment-20240115' deleted. +``` + +
+ +--- + +### Function: `Invoke-CleanupScript` + +**Purpose:** Executes a cleanup PowerShell script with proper error handling and path resolution. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `ScriptPath` | `string` | Yes | Relative path to the script from script directory | +| `Parameters` | `hashtable` | No | Parameters to pass to the invoked script | +| `Description` | `string` | Yes | Description for logging purposes | + +**Returns:** `[bool]` - `$true` if successful or script not found (non-fatal), `$false` on execution failure + +**Behavior:** + +1. Resolves full path using `$Script:ScriptDirectory` +2. Validates script exists (returns `$true` with warning if missing) +3. Executes script with splatted parameters +4. Checks `$LASTEXITCODE` for success + +--- + +### Function: `Start-FullCleanup` + +**Purpose:** Orchestrates the complete cleanup process by calling all cleanup operations in sequence. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `AppDisplayName` | `string` | Yes | Azure AD application display name | +| `GhSecretName` | `string` | Yes | GitHub secret name | +| `EnvName` | `string` | Yes | Environment name | +| `Location` | `string` | Yes | Azure region | + +**Returns:** `[bool]` - `$true` if all operations succeeded, `$false` otherwise + +**Cleanup Sequence:** + +1. Delete subscription deployments +2. Delete users and assigned roles +3. Delete deployment credentials (service principal) +4. Delete GitHub secret +5. Clean up resource groups + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Usage Examples + +### Basic Cleanup (Default Parameters) + +```powershell +.\cleanSetUp.ps1 +``` + +Cleans up the environment using: + +- Environment: `gitHub` +- Location: `eastus2` +- App: `ContosoDevEx GitHub Actions Enterprise App` +- Secret: `AZURE_CREDENTIALS` + +### Production Environment Cleanup + +```powershell +.\cleanSetUp.ps1 -EnvName "prod" -Location "westus2" +``` + +### Custom Application Cleanup + +```powershell +.\cleanSetUp.ps1 -AppDisplayName "MyCompany DevOps Service Principal" -GhSecretName "AZURE_SP_CREDENTIALS" +``` + +### Dry Run (WhatIf) + +```powershell +.\cleanSetUp.ps1 -WhatIf +``` + +Shows what would be deleted without making changes. + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš ๏ธ Error Handling + +### Error Action Preference + +```powershell +$ErrorActionPreference = 'Stop' +$WarningPreference = 'Stop' +``` + +The script uses strict error handling - any unhandled error terminates execution. + +### Exit Codes + +| Code | Meaning | +|------|---------| +| `0` | All cleanup operations completed successfully | +| `1` | One or more cleanup operations failed | + +### Error Recovery + +- Individual operation failures are logged but don't stop other cleanup operations +- The script tracks success/failure of each operation +- Final status reflects whether all operations succeeded + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Troubleshooting + +### Common Issues + +| Issue | Cause | Solution | +|-------|-------|----------| +| "Not logged into Azure" | Azure CLI not authenticated | Run `az login` before executing | +| "Failed to delete deployment" | Deployment in progress or locked | Wait for operations to complete or remove locks | +| Script not found warnings | Missing dependency scripts | Ensure all scripts exist in `.configuration` folder | +| Permission denied | Insufficient Azure/GitHub permissions | Verify role assignments | + +### Debugging + +Enable verbose output: + +```powershell +.\cleanSetUp.ps1 -Verbose +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Related Scripts + +| Script | Purpose | Link | +|--------|---------|------| +| `setUp.ps1` | Initial environment setup (opposite of cleanup) | [setup.md](setup.md) | +| `deleteUsersAndAssignedRoles.ps1` | Remove user role assignments | [azure/delete-users-and-assigned-roles.md](azure/delete-users-and-assigned-roles.md) | +| `deleteDeploymentCredentials.ps1` | Remove service principals | [azure/delete-deployment-credentials.md](azure/delete-deployment-credentials.md) | +| `deleteGitHubSecretAzureCredentials.ps1` | Remove GitHub secrets | [github/delete-github-secret-azure-credentials.md](github/delete-github-secret-azure-credentials.md) | +| `cleanUp.ps1` | Remove Azure resource groups | [configuration/clean-up.md](configuration/clean-up.md) | + +--- + +
+ +[โ† setUp.ps1](setup.md) | [โฌ†๏ธ Back to Top](#-table-of-contents) | [Azure Scripts โ†’](azure/create-custom-role.md) + +*DevExp-DevBox โ€ข cleanSetUp.ps1 Documentation* + +
diff --git a/docs/scripts/configuration/README.md b/docs/scripts/configuration/README.md new file mode 100644 index 00000000..c6256646 --- /dev/null +++ b/docs/scripts/configuration/README.md @@ -0,0 +1,194 @@ +--- +title: "Configuration PowerShell Scripts" +description: "Documentation for Azure resource cleanup and Windows configuration scripts" +author: "DevExp Team" +date: 2026-01-23 +version: "1.0.0" +tags: + - scripts + - configuration + - azure + - windows + - cleanup +--- + +# โš™๏ธ Configuration PowerShell Scripts + +> **Documentation for Azure resource cleanup and Windows configuration scripts** + +> [!NOTE] +> **Target Audience:** Azure Administrators, System Administrators, DevOps Engineers +> **Reading Time:** ~3 minutes + +
+๐Ÿ“ Navigation + +| Previous | Index | Next | +|:---------|:-----:|-----:| +| [โ† GitHub Scripts](../github/README.md) | [Docs Index](../../README.md) | โ€” | + +
+ +--- + +## ๐Ÿ“‘ Table of Contents + +- [๐ŸŽฏ Overview](#-overview) +- [๐Ÿ“œ Scripts Inventory](#-scripts-inventory) +- [๐Ÿ”„ Workflow Diagram](#-workflow-diagram) +- [โš™๏ธ Prerequisites](#-prerequisites) +- [๐Ÿš€ Quick Start](#-quick-start) +- [๐Ÿ”— Related Documentation](#-related-documentation) + +--- + +## ๐ŸŽฏ Overview + +This folder contains PowerShell scripts for managing Azure resource groups and configuring Windows environments. These utility scripts support environment cleanup and Dev Box workload configuration. + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“œ Scripts Inventory + +| Script | Purpose | Documentation | +|:-------|:--------|:--------------| +| ๐Ÿงน `cleanUp.ps1` | Deletes Azure resource groups for DevExp-DevBox | [clean-up.md](clean-up.md) | +| ๐Ÿ“ฆ `winget-update.ps1` | Updates Microsoft Store applications silently | [winget-update.md](winget-update.md) | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”„ Workflow Diagram + +```mermaid +--- +title: Configuration Scripts Workflow +--- +flowchart TB + %% ===== CLEANUP SCRIPTS ===== + subgraph Cleanup["๐Ÿ—‘๏ธ Azure Cleanup"] + direction TB + A["๐Ÿงน cleanUp.ps1"] + A1["Delete resource groups"] + A2["Remove deployments"] + end + + %% ===== CONFIGURATION SCRIPTS ===== + subgraph Config["๐Ÿ“ฆ Windows Configuration"] + direction TB + B["๐Ÿ“ฆ winget-update.ps1"] + B1["Update Store apps"] + B2["Multi-pass upgrade"] + end + + %% ===== CONNECTIONS ===== + A --> A1 --> A2 + B --> B1 --> B2 + + %% ===== NODE STYLES ===== + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + + class A,A1,A2 primary + class B,B1,B2 secondary + + %% ===== SUBGRAPH STYLES ===== + style Cleanup fill:#FEE2E2,stroke:#F44336,stroke-width:2px + style Config fill:#ECFDF5,stroke:#10B981,stroke-width:2px +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Prerequisites + +> [!IMPORTANT] +> Each script has specific requirements. See individual documentation for details. + +### cleanUp.ps1 Requirements + +| Tool | Purpose | Installation | +|:-----|:--------|:-------------| +| Azure CLI (`az`) | Delete Azure resources | [Install Azure CLI](https://docs.microsoft.com/cli/azure/install-azure-cli) | +| PowerShell 5.1+ | Script execution | Pre-installed on Windows | + +### winget-update.ps1 Requirements + +| Tool | Purpose | Installation | +|:-----|:--------|:-------------| +| Windows Package Manager (`winget`) | Package management | [App Installer](https://apps.microsoft.com/store/detail/app-installer/9NBLGGH4NNS1) | +| PowerShell 5.1+ | Script execution | Pre-installed on Windows | +| Administrator privileges | Machine-wide updates | Run as Administrator | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿš€ Quick Start + +### Resource Group Cleanup + +> [!CAUTION] +> This operation is **destructive** and cannot be undone. + +```powershell +# 1. Login to Azure +az login + +# 2. Run cleanup with default parameters +.\cleanUp.ps1 + +# 3. Or specify environment and location +.\cleanUp.ps1 -EnvName "prod" -Location "westus2" +``` + +### Windows Store App Updates + +> [!TIP] +> Run as Administrator for machine-wide updates. + +```powershell +# Run with elevated privileges +Start-Process powershell -Verb RunAs -ArgumentList "-File `".\winget-update.ps1`"" +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Related Documentation + +| Document | Description | +|:---------|:------------| +| [Scripts Index](../README.md) | Main scripts documentation | +| [cleanSetUp.ps1](../clean-setup.md) | Full environment cleanup orchestrator | +| [Azure Scripts](../azure/README.md) | Azure RBAC and credential management | +| [GitHub Scripts](../github/README.md) | GitHub secret management | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +
+ +[โ† GitHub Scripts](../github/README.md) | [โฌ†๏ธ Back to Top](#-table-of-contents) + +*DevExp-DevBox โ€ข Configuration Scripts Documentation* + +
diff --git a/docs/scripts/configuration/clean-up.md b/docs/scripts/configuration/clean-up.md new file mode 100644 index 00000000..95dcd502 --- /dev/null +++ b/docs/scripts/configuration/clean-up.md @@ -0,0 +1,433 @@ +--- +title: "cleanUp.ps1 Script" +description: "Removes Azure resource groups for DevExp-DevBox environment" +author: "DevExp Team" +date: 2026-01-23 +version: "1.0.0" +tags: + - scripts + - azure + - cleanup + - resource-groups +--- + +# ๐Ÿงน cleanUp.ps1 + +> **Removes Azure resource groups for DevExp-DevBox environment** + +> [!CAUTION] +> This script **permanently deletes** Azure resource groups and all their contents. This action cannot be undone. + +> [!NOTE] +> **Target Audience:** Azure Administrators, Platform Engineers +> **Reading Time:** ~10 minutes + +
+๐Ÿ“ Navigation + +| Previous | Index | Next | +|:---------|:-----:|-----:| +| [โ† generateDeploymentCredentials.ps1](../azure/generate-deployment-credentials.md) | [Scripts Index](../README.md) | [winget-update.ps1 โ†’](winget-update.md) | + +
+ +--- + +## ๐Ÿ“‘ Table of Contents + +- [๐ŸŽฏ Overview](#-overview) +- [๐Ÿ“Š Flow Visualization](#-flow-visualization) +- [๐Ÿ“ Parameters](#-parameters) +- [โš™๏ธ Prerequisites](#-prerequisites) +- [๐Ÿ—‚๏ธ Resource Groups Deleted](#-resource-groups-deleted) +- [๐Ÿ”ง Functions Reference](#-functions-reference) +- [๐Ÿ“ Usage Examples](#-usage-examples) +- [โš ๏ธ Error Handling](#-error-handling) +- [๐Ÿ› ๏ธ Troubleshooting](#-troubleshooting) +- [๐Ÿ”’ Security Considerations](#-security-considerations) +- [๐Ÿ”— Related Scripts](#-related-scripts) + +--- + +## ๐ŸŽฏ Overview + +This script deletes Azure resource groups and their associated deployments for the DevExp-DevBox infrastructure. It removes workload, connectivity, monitoring, security, and supporting resource groups based on a naming convention. + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“Š Flow Visualization + +```mermaid +--- +title: Resource Group Cleanup Flow +--- +flowchart TD + %% ===== SCRIPT ENTRY ===== + subgraph Entry["๐Ÿ“ฅ Script Entry"] + A(["๐Ÿš€ cleanUp.ps1 Start"]) + B[/"๐Ÿ“ Parse Parameters"/] + end + + %% ===== MAIN ORCHESTRATION ===== + subgraph Main["๐ŸŽฏ Main Orchestration"] + C["โš™๏ธ Remove-AllResourceGroups"] + D["๐Ÿ“‹ Build resource group names"] + end + + %% ===== RESOURCE GROUP DELETION LOOP ===== + subgraph RGLoop["๐Ÿ”„ Resource Group Deletion Loop"] + E["๐Ÿ“‹ For each resource group"] + F["๐Ÿ—‘๏ธ Remove-AzureResourceGroup"] + F1[("โ˜๏ธ az group exists")] + F2{"๐Ÿ“‹ RG exists?"} + F3[("๐Ÿ“‹ az deployment group list")] + F4["๐Ÿ—‘๏ธ Delete deployments"] + F5[("๐Ÿ—‘๏ธ az group delete --no-wait")] + end + + %% ===== SCRIPT EXIT ===== + subgraph Exit["๐Ÿ“ค Script Exit"] + G{"โœ… All succeeded?"} + H[\"๐ŸŽ‰ Deletions Initiated"\] + I{{"โš ๏ธ Partial Failure"}} + end + + %% ===== CONNECTIONS ===== + A -->|parses| B -->|invokes| C -->|builds| D -->|iterates| E + E -->|processes| F -->|checks| F1 -->|evaluates| F2 + F2 -->|No| E + F2 -->|Yes| F3 -->|clears| F4 -->|deletes| F5 -->|next| E + E -->|All processed| G + G -->|Yes| H + G -->|No| I + + %% ===== STYLES ===== + classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + classDef external fill:#6B7280,stroke:#4B5563,color:#FFFFFF,stroke-dasharray:5 5 + classDef failed fill:#F44336,stroke:#C62828,color:#FFFFFF + classDef decision fill:#FFFBEB,stroke:#F59E0B,color:#000000 + classDef input fill:#F3F4F6,stroke:#6B7280,color:#000000 + classDef matrix fill:#D1FAE5,stroke:#10B981,color:#000000 + + class A trigger + class B input + class C,D,E,F,F4 primary + class F1,F3,F5 external + class F2,G decision + class H secondary + class I failed + + %% ===== SUBGRAPH STYLES ===== + style Entry fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style Main fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style RGLoop fill:#FEE2E2,stroke:#F44336,stroke-width:2px + style Exit fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Parameters + +| Parameter | Type | Required | Default | Validation | Description | +|:----------|:-----|:--------:|:--------|:-----------|:------------| +| `-EnvName` | `string` | No | `"demo"` | `ValidateNotNullOrEmpty` | Environment name for resource group naming | +| `-Location` | `string` | No | `"eastus2"` | `ValidateSet` | Azure region (eastus, eastus2, westus, westus2, westus3, northeurope, westeurope) | +| `-WorkloadName` | `string` | No | `"devexp"` | `ValidateNotNullOrEmpty` | Workload name prefix for resource groups | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Prerequisites + +### Required Tools + +| Tool | Purpose | Installation | +|:-----|:--------|:-------------| +| Azure CLI (`az`) | Delete Azure resources | [Install Azure CLI](https://docs.microsoft.com/cli/azure/install-azure-cli) | +| PowerShell 5.1+ | Script execution | Pre-installed on Windows | + +### Required Permissions + +- **Azure**: Contributor or Owner on the subscription +- Permission to delete resource groups and deployments + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ—‚๏ธ Resource Groups Deleted + +Based on the naming convention `{WorkloadName}-{type}-{EnvName}-{Location}-rg`: + +| Resource Group Pattern | Purpose | +|:-----------------------|:--------| +| `{workload}-workload-{env}-{location}-rg` | DevCenter and related resources | +| `{workload}-connectivity-{env}-{location}-rg` | VNets and network connections | +| `{workload}-monitoring-{env}-{location}-rg` | Log Analytics and monitoring | +| `{workload}-security-{env}-{location}-rg` | Key Vault and security resources | +| `NetworkWatcherRG` | Azure-managed network watcher | +| `Default-ActivityLogAlerts` | Default alert rules | +| `DefaultResourceGroup-WUS2` | Default Azure-created resources | + +### Example Resource Groups (with defaults) + +``` +devexp-workload-demo-eastus2-rg +devexp-connectivity-demo-eastus2-rg +devexp-monitoring-demo-eastus2-rg +devexp-security-demo-eastus2-rg +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Functions Reference + +### Function: `Remove-AzureResourceGroup` + +**Purpose:** Deletes an Azure resource group and its deployments. + +**Parameters:** + +| Name | Type | Required | Description | +|:-----|:-----|:--------:|:------------| +| `ResourceGroupName` | `string` | Yes | Name of the resource group to delete | + +**Returns:** `[bool]` - `$true` if deletion initiated successfully, `$false` on error + +**Behavior:** + +1. Checks if resource group exists (`az group exists`) +2. If exists, lists all deployments in the group +3. Deletes each deployment first +4. Waits 10 seconds for deployment deletions +5. Initiates async resource group deletion (`--no-wait`) +6. Supports `-WhatIf` via `SupportsShouldProcess` + +--- + +### Function: `Remove-AllResourceGroups` + +**Purpose:** Removes all DevExp-DevBox related resource groups. + +**Parameters:** + +| Name | Type | Required | Description | +|:-----|:-----|:--------:|:------------| +| `WorkloadName` | `string` | Yes | Workload name prefix | +| `Environment` | `string` | Yes | Environment name | +| `Location` | `string` | Yes | Azure region | + +**Returns:** `[bool]` - `$true` if all deletions initiated, `$false` otherwise + +**Builds and deletes these resource groups:** + +- `{WorkloadName}-workload-{Environment}-{Location}-rg` +- `{WorkloadName}-connectivity-{Environment}-{Location}-rg` +- `{WorkloadName}-monitoring-{Environment}-{Location}-rg` +- `{WorkloadName}-security-{Environment}-{Location}-rg` +- `NetworkWatcherRG` +- `Default-ActivityLogAlerts` +- `DefaultResourceGroup-WUS2` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Usage Examples + +### Default Cleanup + +```powershell +.\cleanUp.ps1 +``` + +Deletes resource groups for: + +- Workload: `devexp` +- Environment: `demo` +- Location: `eastus2` + +### Production Environment Cleanup + +```powershell +.\cleanUp.ps1 -EnvName "prod" -Location "westus2" +``` + +### Custom Workload Name + +```powershell +.\cleanUp.ps1 -WorkloadName "mycompany" -EnvName "dev" -Location "northeurope" +``` + +### Dry Run (WhatIf) + +```powershell +.\cleanUp.ps1 -WhatIf +``` + +
+Expected Output + +``` +DevExp-DevBox Resource Cleanup +============================== +Starting cleanup of resource groups... +Environment: demo +Location: eastus2 + +Deleting deployment: initial-deployment +Deployment 'initial-deployment' deleted. +Deleting resource group: devexp-workload-demo-eastus2-rg (async)... +Resource group 'devexp-workload-demo-eastus2-rg' deletion initiated. +Resource group 'devexp-connectivity-demo-eastus2-rg' does not exist. Skipping. +... + +All resource group deletions initiated successfully. +``` + +
+ +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš ๏ธ Error Handling + +### Error Action Preference + +```powershell +$ErrorActionPreference = 'Stop' +$WarningPreference = 'Stop' +``` + +### Exit Codes + +| Code | Meaning | +|:----:|:--------| +| `0` | All deletions initiated successfully | +| `1` | One or more deletions failed | + +### Asynchronous Deletion + +Resource groups are deleted with `--no-wait` flag: + +- Script returns immediately after initiating deletion +- Actual deletion continues in the background +- May take several minutes to complete + +### Idempotency + +The script is **idempotent**: + +- Non-existent resource groups are skipped with message +- Safe to run multiple times +- No error if already deleted + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ› ๏ธ Troubleshooting + +### Common Issues + +| Issue | Cause | Solution | +|:------|:------|:---------| +| "Failed to check if resource group exists" | Not logged into Azure | Run `az login` | +| "Failed to initiate resource group deletion" | Resource locks present | Remove locks first | +| Deployment deletion fails | Deployment in progress | Wait and retry | +| Slow deletion | Large resources (Dev Boxes) | Allow more time | + +### Monitor Deletion Progress + +```powershell +# Check if resource group still exists +az group exists --name "devexp-workload-demo-eastus2-rg" + +# List resource groups matching pattern +az group list --query "[?contains(name, 'devexp')]" --output table +``` + +### Force Delete Locked Resources + +```powershell +# Remove lock first +az lock delete --name {lock-name} --resource-group {rg-name} +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”’ Security Considerations + +### Destructive Operation + +- This script **permanently deletes** Azure resources +- Deleted resources cannot be recovered +- All data in the resource groups will be lost + +### Before Execution Checklist + +- [ ] Verify correct environment and location parameters +- [ ] Confirm no production workloads in target resource groups +- [ ] Back up any important data or configurations +- [ ] Consider using `-WhatIf` first + +### Resource Locks + +Azure resource locks can prevent accidental deletion: + +- Remove locks before running cleanup +- Or use Azure portal to delete locked resources + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Related Scripts + +| Script | Purpose | Link | +|:-------|:--------|:-----| +| `cleanSetUp.ps1` | Full environment cleanup orchestrator | [../clean-setup.md](../clean-setup.md) | +| `setUp.ps1` | Environment setup (opposite operation) | [../setup.md](../setup.md) | + +--- + +
+ +[โ† generateDeploymentCredentials.ps1](../azure/generate-deployment-credentials.md) | [โฌ†๏ธ Back to Top](#-table-of-contents) | [winget-update.ps1 โ†’](winget-update.md) + +*DevExp-DevBox โ€ข cleanUp.ps1 Documentation* + +
diff --git a/docs/scripts/configuration/winget-update.md b/docs/scripts/configuration/winget-update.md new file mode 100644 index 00000000..4fe5d4a7 --- /dev/null +++ b/docs/scripts/configuration/winget-update.md @@ -0,0 +1,542 @@ +--- +title: "winget-update.ps1 Script" +description: "Silently updates all Microsoft Store applications using Windows Package Manager" +author: "DevExp Team" +date: 2026-01-23 +version: "1.0.0" +tags: + - scripts + - windows + - winget + - updates + - dsc +--- + +# ๐Ÿ“ฆ winget-update.ps1 + +> **Silently updates all Microsoft Store applications using Windows Package Manager** + +> [!TIP] +> Run this script with Administrator privileges for machine-wide app updates. + +> [!NOTE] +> **Target Audience:** System Administrators, DevOps Engineers +> **Reading Time:** ~12 minutes + +
+๐Ÿ“ Navigation + +| Previous | Index | Next | +|:---------|:-----:|-----:| +| [โ† cleanUp.ps1](clean-up.md) | [Scripts Index](../README.md) | [GitHub Scripts โ†’](../github/create-github-secret-azure-credentials.md) | + +
+ +--- + +## ๐Ÿ“‘ Table of Contents + +- [๐ŸŽฏ Overview](#-overview) +- [๐Ÿ“Š Flow Visualization](#-flow-visualization) +- [๐Ÿ”„ Update Process Flow](#-update-process-flow) +- [๐Ÿ“ Parameters](#-parameters) +- [โš™๏ธ Prerequisites](#-prerequisites) +- [๐Ÿ› ๏ธ Configuration](#-configuration) +- [๐Ÿ”ง Functions Reference](#-functions-reference) +- [๐Ÿ“ Usage Examples](#-usage-examples) +- [โš ๏ธ Error Handling](#-error-handling) +- [๐Ÿ” Troubleshooting](#-troubleshooting) +- [๐Ÿ”„ DSC Integration](#-dsc-integration) +- [๐Ÿ”’ Security Considerations](#-security-considerations) +- [๐Ÿ”— Related Files](#-related-files) + +--- + +## ๐ŸŽฏ Overview + +This script performs a comprehensive, non-interactive update of all Microsoft Store applications using Windows Package Manager (winget). It handles self-updates of winget, runs multiple passes to catch stubborn apps, and maintains detailed logging. + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“Š Flow Visualization + +```mermaid +--- +title: WinGet Update Flow +--- +flowchart TD + %% ===== SCRIPT ENTRY ===== + subgraph Entry["๐Ÿ“ฅ Script Entry"] + A(["๐Ÿš€ winget-update.ps1 Start"]) + B["๐Ÿ“ Configure logging"] + C["๐Ÿ” Set ExecutionPolicy Bypass"] + end + + %% ===== PREFLIGHT CHECKS ===== + subgraph Preflight["โœ… Preflight Checks"] + D["๐Ÿ” Resolve-WinGetExecutable"] + E["๐Ÿงช Test-WinGetAvailability"] + F{"๐Ÿ“‹ WinGet available?"} + end + + %% ===== SERVICE PREPARATION ===== + subgraph Services["โš™๏ธ Service Preparation"] + G["๐Ÿš€ Start-StoreInstallService"] + H["๐Ÿ”„ Initialize-WinGetSources"] + end + + %% ===== UPDATE PASSES ===== + subgraph Updates["๐Ÿ“ฆ Update Passes"] + I["โฌ†๏ธ Update-MicrosoftStoreApps"] + I1["๐Ÿ“‹ Pass 1: Standard upgrade"] + I2["๐Ÿ”ง Pass 2: Forced upgrade"] + I3["๐Ÿ›ก๏ธ Pass 3: Safety net pass"] + I4["๐Ÿ“Š Summary check"] + end + + %% ===== SCRIPT EXIT ===== + subgraph Exit["๐Ÿ“ค Script Exit"] + J[\"๐ŸŽ‰ Updates Complete"\] + K{{"โŒ Error Exit"}} + end + + %% ===== CONNECTIONS ===== + A -->|configures| B -->|sets| C -->|resolves| D -->|tests| E -->|evaluates| F + F -->|No| K + F -->|Yes| G -->|initializes| H -->|updates| I + I -->|runs| I1 -->|forces| I2 -->|safety| I3 -->|summarizes| I4 -->|completes| J + + %% ===== STYLES ===== + classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef datastore fill:#F59E0B,stroke:#D97706,color:#000000 + classDef external fill:#6B7280,stroke:#4B5563,color:#FFFFFF,stroke-dasharray:5 5 + classDef failed fill:#F44336,stroke:#C62828,color:#FFFFFF + classDef decision fill:#FFFBEB,stroke:#F59E0B,color:#000000 + classDef input fill:#F3F4F6,stroke:#6B7280,color:#000000 + classDef matrix fill:#D1FAE5,stroke:#10B981,color:#000000 + + class A trigger + class B,C,D,E,G,H primary + class F decision + class I,I1,I2,I3,I4 secondary + class J secondary + class K failed + + %% ===== SUBGRAPH STYLES ===== + style Entry fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style Preflight fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style Services fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style Updates fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Exit fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”„ Update Process Flow + +```mermaid +--- +title: Update Process Flow +--- +sequenceDiagram + autonumber + participant Script as winget-update.ps1 + participant WinGet as Windows Package Manager + participant Store as Microsoft Store + participant Log as Log File + + Script->>Log: Initialize logging + Script->>WinGet: Resolve executable path + Script->>WinGet: Test availability + + Script->>Script: Start InstallService + Script->>WinGet: source update + + Note over Script,WinGet: Pass 1: Standard Upgrade + Script->>WinGet: upgrade --all --source msstore + WinGet->>Store: Check for updates + Store-->>WinGet: Available updates + WinGet-->>Script: Update results + Script->>Log: Log results + + Note over Script,WinGet: Pass 2: Forced Upgrade + Script->>WinGet: upgrade --all --force --source msstore + WinGet-->>Script: Update results + Script->>Log: Log results + + Note over Script,WinGet: Pass 3: Safety Net + Script->>WinGet: upgrade --all + WinGet-->>Script: Final results + Script->>Log: Log results + + Script->>Log: Complete - log file path +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Parameters + +This script has no parameters. All configuration is handled internally. + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Prerequisites + +### Required Tools + +| Tool | Purpose | Installation | +|:-----|:--------|:-------------| +| Windows Package Manager (`winget`) | Package management | Pre-installed or via [App Installer](https://apps.microsoft.com/store/detail/app-installer/9NBLGGH4NNS1) | +| PowerShell 5.1+ | Script execution | Pre-installed on Windows | + +### Recommended Execution Context + +- **Elevated (Administrator)**: Required for machine-wide app updates +- **Standard User**: Will update user-scoped apps only + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ› ๏ธ Configuration + +### Environment Variables Set + +| Variable | Value | Purpose | +|:---------|:------|:--------| +| `WINGET_DISABLE_INTERACTIVITY` | `1` | Prevents all prompts | + +### Script Preferences + +| Preference | Value | Purpose | +|:-----------|:------|:--------| +| `$ErrorActionPreference` | `Stop` | Terminate on errors | +| `$ProgressPreference` | `SilentlyContinue` | Suppress progress bars | +| `ExecutionPolicy` | `Bypass` (Process) | Allow script execution | + +### Logging + +- **Log Directory:** `C:\ProgramData\Winget-StoreUpgrade\` +- **Log File Format:** `upgrade-YYYYMMDD-HHMMSS.log` +- **Log Levels:** `[INFO ]`, `[WARN ]`, `[ERROR]` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Functions Reference + +### Function: `Write-LogInfo` + +**Purpose:** Writes an informational message to console and log file. + +**Parameters:** + +| Name | Type | Description | +|:-----|:-----|:------------| +| `Message` | `string` | Message to write | + +--- + +### Function: `Write-LogWarning` + +**Purpose:** Writes a warning message to console and log file. + +--- + +### Function: `Write-LogError` + +**Purpose:** Writes an error message to console and log file. + +--- + +### Function: `Resolve-WinGetExecutable` + +**Purpose:** Finds the path to winget.exe, preferring the packaged App Installer location. + +**Returns:** `[string]` - Full path to winget.exe + +**Resolution Order:** + +1. Packaged App Installer location (via `Get-AppxPackage`) +2. PowerShell command resolution (fallback) + +--- + +### Function: `Invoke-WinGetCommand` + +**Purpose:** Executes winget with proper logging and retry on self-update. + +**Parameters:** + +| Name | Type | Required | Description | +|:-----|:-----|:--------:|:------------| +| `CommandArgs` | `string[]` | Yes | Arguments to pass to winget | +| `RetryOnSelfUpdate` | `switch` | No | Retry if winget updated itself | + +**Returns:** `[string]` - Output from winget command + +**Self-Update Handling:** + +- Detects "Restart the application to complete the upgrade" +- Re-resolves winget path and retries once + +--- + +### Function: `Test-WinGetAvailability` + +**Purpose:** Verifies winget is installed and working. + +**Returns:** `[bool]` - `$true` if winget is available + +--- + +### Function: `Start-StoreInstallService` + +**Purpose:** Ensures Microsoft Store Install Service is running. + +**Service:** `InstallService` + +--- + +### Function: `Initialize-WinGetSources` + +**Purpose:** Verifies and updates winget sources. + +**Behavior:** + +1. Checks if `msstore` source exists +2. Resets source if missing +3. Updates all sources + +--- + +### Function: `Update-MicrosoftStoreApps` + +**Purpose:** Performs multi-pass update of all Microsoft Store apps. + +**Update Passes:** + +| Pass | Purpose | Flags | +|:----:|:--------|:------| +| 1 | Standard upgrade | `--include-unknown --silent` | +| 2 | Forced upgrade | `--force --silent` | +| 3 | Safety net | Unfiltered (all sources) | + +**Common Flags for All Passes:** + +- `--accept-source-agreements` +- `--accept-package-agreements` +- `--disable-interactivity` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Usage Examples + +### Standard Execution + +```powershell +.\winget-update.ps1 +``` + +### With Elevated Privileges + +```powershell +# Run as Administrator for machine-wide updates +Start-Process powershell -Verb RunAs -ArgumentList "-File `".\winget-update.ps1`"" +``` + +
+Expected Console Output + +``` +[INFO ] Log file: C:\ProgramData\Winget-StoreUpgrade\upgrade-20250123-143022.log +[INFO ] Starting Microsoft Store updates... +[INFO ] Pass 1: upgrading Microsoft Store apps (include-unknown)... +[INFO ] Pass 2: forced upgrade (msstore) for remaining/unknown version apps... +[INFO ] Safety net: unfiltered pass to catch any remaining packages... +[INFO ] Summary check for remaining Microsoft Store upgrades... +[INFO ] Completed. Full log: C:\ProgramData\Winget-StoreUpgrade\upgrade-20250123-143022.log +``` + +
+ +
+Example Log File Contents + +``` +[INFO ] Log file: C:\ProgramData\Winget-StoreUpgrade\upgrade-20250123-143022.log +[INFO ] Starting Microsoft Store updates... +[INFO ] Pass 1: upgrading Microsoft Store apps (include-unknown)... +Name Id Version Available Source +--------------- ---------------------------------- ----------- ----------- ------ +Microsoft To Do Microsoft.Todos 2.97.123.0 2.98.456.0 msstore +... +[INFO ] Pass 2: forced upgrade (msstore) for remaining/unknown version apps... +No applicable upgrade found. +[INFO ] Safety net: unfiltered pass to catch any remaining packages... +No applicable upgrade found. +[INFO ] Summary check for remaining Microsoft Store upgrades... +No applicable upgrade found. +[INFO ] Completed. Full log: C:\ProgramData\Winget-StoreUpgrade\upgrade-20250123-143022.log +``` + +
+ +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš ๏ธ Error Handling + +### Exit Codes + +| Code | Meaning | +|:----:|:--------| +| `0` | Updates completed (may include skipped apps) | +| `1` | Critical failure (winget not found, etc.) | + +### Graceful Degradation + +- Source operation failures trigger warnings but don't stop execution +- Individual app update failures don't stop the process +- Service start failures are logged as warnings + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ” Troubleshooting + +### Common Issues + +| Issue | Cause | Solution | +|:------|:------|:---------| +| "winget not found" | App Installer not installed | Install from Microsoft Store | +| No updates applied | All apps current | Check log for details | +| Permission errors | Not running elevated | Run as Administrator | +| Self-update loop | Winget updating repeatedly | Allow self-update to complete | + +### Check Log File + +```powershell +# View latest log +Get-Content "C:\ProgramData\Winget-StoreUpgrade\upgrade-*.log" | Select-Object -Last 50 +``` + +### Verify WinGet Version + +```powershell +winget --version +``` + +### Manual Source Reset + +```powershell +winget source reset --force +winget source update +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”„ DSC Integration + +This script is designed to work with Windows Desired State Configuration (DSC). Related DSC files: + +| File | Purpose | +|:-----|:--------| +| `winget-upgrade-packages.dsc.yaml` | DSC configuration for package updates | +| `common-config.dsc.yaml` | Common DSC configuration | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”’ Security Considerations + +### Execution Policy + +The script sets `ExecutionPolicy Bypass` for the current process only: + +```powershell +Set-ExecutionPolicy Bypass -Scope Process -Force +``` + +This does not affect system-wide policy. + +### Logging Location + +Logs are written to `C:\ProgramData\`: + +- Accessible by all users +- Persists across reboots +- May contain package names and versions + +### Source Agreements + +The script automatically accepts: + +- Source agreements (`--accept-source-agreements`) +- Package agreements (`--accept-package-agreements`) + +Review these agreements at [Microsoft Store Terms](https://www.microsoft.com/store/b/terms-of-use). + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Related Files + +| File | Purpose | Location | +|:-----|:--------|:---------| +| `winget-upgrade-packages.dsc.yaml` | DSC configuration | Same directory | +| `common-config.dsc.yaml` | Common workload config | Same directory | +| `common-backend-config.dsc.yaml` | Backend workload config | Same directory | + +--- + +
+ +[โ† cleanUp.ps1](clean-up.md) | [โฌ†๏ธ Back to Top](#-table-of-contents) | [GitHub Scripts โ†’](../github/create-github-secret-azure-credentials.md) + +*DevExp-DevBox โ€ข winget-update.ps1 Documentation* + +
diff --git a/docs/scripts/github/README.md b/docs/scripts/github/README.md new file mode 100644 index 00000000..08036184 --- /dev/null +++ b/docs/scripts/github/README.md @@ -0,0 +1,188 @@ +--- +title: "GitHub PowerShell Scripts" +description: "Documentation for GitHub repository secret management scripts" +author: "DevExp Team" +date: 2026-01-23 +version: "1.0.0" +tags: + - scripts + - github + - secrets + - cicd +--- + +# ๐Ÿ™ GitHub PowerShell Scripts + +> **Documentation for GitHub repository secret management scripts** + +> [!NOTE] +> **Target Audience:** DevOps Engineers, Platform Engineers +> **Reading Time:** ~3 minutes + +
+๐Ÿ“ Navigation + +| Previous | Index | Next | +|:---------|:-----:|-----:| +| [โ† Azure Scripts](../azure/README.md) | [Docs Index](../../README.md) | [Configuration Scripts โ†’](../configuration/clean-up.md) | + +
+ +--- + +## ๐Ÿ“‘ Table of Contents + +- [๐ŸŽฏ Overview](#-overview) +- [๐Ÿ“œ Scripts Inventory](#-scripts-inventory) +- [๐Ÿ”„ Workflow Diagram](#-workflow-diagram) +- [โš™๏ธ Prerequisites](#-prerequisites) +- [๐Ÿš€ Quick Start](#-quick-start) +- [๐Ÿ”— Related Documentation](#-related-documentation) + +--- + +## ๐ŸŽฏ Overview + +This folder contains PowerShell scripts for managing GitHub repository secrets. These scripts are essential for setting up secure CI/CD pipelines by storing Azure credentials in GitHub for use with GitHub Actions workflows. + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“œ Scripts Inventory + +| Script | Purpose | Documentation | +|:-------|:--------|:--------------| +| ๐Ÿ” `createGitHubSecretAzureCredentials.ps1` | Creates `AZURE_CREDENTIALS` secret for GitHub Actions | [create-github-secret-azure-credentials.md](create-github-secret-azure-credentials.md) | +| ๐Ÿ—‘๏ธ `deleteGitHubSecretAzureCredentials.ps1` | Removes GitHub repository secrets | [delete-github-secret-azure-credentials.md](delete-github-secret-azure-credentials.md) | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”„ Workflow Diagram + +```mermaid +--- +title: GitHub Scripts Workflow +--- +flowchart LR + %% ===== SETUP PHASE ===== + subgraph Setup["๐Ÿš€ Setup Phase"] + direction TB + A["๐Ÿ” createGitHubSecretAzureCredentials.ps1"] + end + + %% ===== CLEANUP PHASE ===== + subgraph Cleanup["๐Ÿ—‘๏ธ Cleanup Phase"] + direction TB + B["๐Ÿ—‘๏ธ deleteGitHubSecretAzureCredentials.ps1"] + end + + %% ===== CONNECTIONS ===== + A -.->|"Reverse Operation"| B + + %% ===== NODE STYLES ===== + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef failed fill:#F44336,stroke:#C62828,color:#FFFFFF + + class A secondary + class B failed + + %% ===== SUBGRAPH STYLES ===== + style Setup fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Cleanup fill:#FEE2E2,stroke:#F44336,stroke-width:2px +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Prerequisites + +> [!IMPORTANT] +> All scripts require the following tools and permissions to be configured. + +### Required Tools + +| Tool | Purpose | Installation | +|:-----|:--------|:-------------| +| GitHub CLI (`gh`) | Manage repository secrets | [Install GitHub CLI](https://cli.github.com/) | +| PowerShell 5.1+ | Script execution | Pre-installed on Windows | + +### Required Permissions + +| Permission | Scripts | Purpose | +|:-----------|:--------|:--------| +| **Repository Admin** or **Secrets Write** | All scripts | Create/delete repository secrets | +| **GitHub CLI Authentication** | All scripts | `gh auth login` with `repo` scope | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿš€ Quick Start + +### Create Secret + +> [!TIP] +> This script is typically called by `generateDeploymentCredentials.ps1`, not run directly. + +```powershell +# 1. Login to GitHub CLI +gh auth login + +# 2. Navigate to repository directory +cd path/to/your/repo + +# 3. Create secret with Azure credentials JSON +$creds = az ad sp create-for-rbac --name "my-sp" --role Contributor --json-auth +.\createGitHubSecretAzureCredentials.ps1 -GhSecretBody $creds +``` + +### Delete Secret + +> [!WARNING] +> Deleting secrets immediately affects any workflows using them. + +```powershell +# Remove the AZURE_CREDENTIALS secret +.\deleteGitHubSecretAzureCredentials.ps1 -GhSecretName "AZURE_CREDENTIALS" +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Related Documentation + +| Document | Description | +|:---------|:------------| +| [Scripts Index](../README.md) | Main scripts documentation | +| [Azure Scripts](../azure/README.md) | Azure RBAC and credential management scripts | +| [generateDeploymentCredentials.ps1](../azure/generate-deployment-credentials.md) | Creates SP and calls GitHub secret script | +| [Deployment Architecture](../../architecture/07-deployment-architecture.md) | CI/CD pipeline configuration | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +
+ +[โ† Azure Scripts](../azure/README.md) | [โฌ†๏ธ Back to Top](#-table-of-contents) | [Configuration Scripts โ†’](../configuration/clean-up.md) + +*DevExp-DevBox โ€ข GitHub Scripts Documentation* + +
diff --git a/docs/scripts/github/create-github-secret-azure-credentials.md b/docs/scripts/github/create-github-secret-azure-credentials.md new file mode 100644 index 00000000..ff5469ef --- /dev/null +++ b/docs/scripts/github/create-github-secret-azure-credentials.md @@ -0,0 +1,405 @@ +--- +title: "createGitHubSecretAzureCredentials.ps1 Script" +description: "Creates a GitHub repository secret for Azure service principal credentials" +author: "DevExp Team" +date: 2026-01-23 +version: "1.0.0" +tags: + - scripts + - github + - secrets + - azure + - cicd +--- + +# ๐Ÿ” createGitHubSecretAzureCredentials.ps1 + +> **Creates a GitHub repository secret for Azure service principal credentials** + +> [!NOTE] +> **Target Audience:** DevOps Engineers, Platform Engineers +> **Reading Time:** ~10 minutes + +
+๐Ÿ“ Navigation + +| Previous | Index | Next | +|:---------|:-----:|-----:| +| [โ† winget-update.ps1](../configuration/winget-update.md) | [Scripts Index](../README.md) | [deleteGitHubSecretAzureCredentials.ps1 โ†’](delete-github-secret-azure-credentials.md) | + +
+ +--- + +## ๐Ÿ“‘ Table of Contents + +- [๐ŸŽฏ Overview](#-overview) +- [๐Ÿ“Š Flow Visualization](#-flow-visualization) +- [๐Ÿ“ Parameters](#-parameters) +- [โš™๏ธ Prerequisites](#-prerequisites) +- [๐Ÿ“ฅ Expected Input Format](#-expected-input-format) +- [๐Ÿ”ง Functions Reference](#-functions-reference) +- [๐Ÿ“ Usage Examples](#-usage-examples) +- [โš™๏ธ Using the Secret in GitHub Actions](#-using-the-secret-in-github-actions) +- [โš ๏ธ Error Handling](#-error-handling) +- [๐Ÿ› ๏ธ Troubleshooting](#-troubleshooting) +- [๐Ÿ”’ Security Considerations](#-security-considerations) +- [๐Ÿ”— Related Scripts](#-related-scripts) + +--- + +## ๐ŸŽฏ Overview + +This script authenticates to GitHub using the GitHub CLI and creates a repository secret named `AZURE_CREDENTIALS` containing Azure service principal credentials for use in GitHub Actions workflows. + +--- + +[โฌ†๏ธ Back to Top](#-creategithubsecretazurecredentialsps1) + +--- + +## ๐Ÿ“Š Flow Visualization + +```mermaid +--- +title: Create GitHub Secret Flow +--- +flowchart TD + %% ===== SCRIPT ENTRY ===== + subgraph Entry["๐Ÿ“ฅ Script Entry"] + A(["๐Ÿš€ createGitHubSecretAzureCredentials.ps1 Start"]) + B[/"๐Ÿ“ Parse Parameters"/] + end + + %% ===== GITHUB AUTHENTICATION ===== + subgraph Auth["๐Ÿ” GitHub Authentication"] + C["โš™๏ธ Connect-GitHubCli"] + D[("๐Ÿ™ gh auth status")] + E{"โœ… Authenticated?"} + F[("๐Ÿ”‘ gh auth login")] + end + + %% ===== SECRET CREATION ===== + subgraph SecretCreation["๐Ÿ“ Secret Creation"] + G["โš™๏ธ Set-GitHubRepositorySecret"] + H[("๐Ÿ”’ gh secret set")] + end + + %% ===== SCRIPT EXIT ===== + subgraph Exit["๐Ÿ“ค Script Exit"] + I{"โœ… Success?"} + J[\"๐ŸŽ‰ Secret Created"\] + K{{"โŒ Error Handler"}} + end + + %% ===== CONNECTIONS ===== + A -->|parses| B -->|connects| C -->|checks| D -->|evaluates| E + E -->|Yes| G + E -->|No| F -->|authenticates| G + G -->|creates| H -->|evaluates| I + I -->|Yes| J + I -->|No| K + + %% ===== STYLES ===== + classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + classDef input fill:#F59E0B,stroke:#D97706,color:#000000 + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef external fill:#6B7280,stroke:#4B5563,color:#FFFFFF,stroke-dasharray:5 5 + classDef decision fill:#FFFBEB,stroke:#F59E0B,color:#000000 + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef failed fill:#F44336,stroke:#C62828,color:#FFFFFF + + class A trigger + class B input + class C,G primary + class D,F,H external + class E,I decision + class J secondary + class K failed + + %% ===== SUBGRAPH STYLES ===== + style Entry fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style Auth fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style SecretCreation fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style Exit fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Parameters + +| Parameter | Type | Required | Default | Validation | Description | +|-----------|------|----------|---------|------------|-------------| +| `-GhSecretBody` | `string` | Yes | - | `ValidateNotNullOrEmpty` | JSON body containing Azure credentials | + +**Aliases:** `ghSecretBody` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Prerequisites + +### Required Tools + +| Tool | Purpose | Installation | +|------|---------|--------------| +| GitHub CLI (`gh`) | Manage repository secrets | [Install GitHub CLI](https://cli.github.com/) | +| PowerShell 5.1+ | Script execution | Pre-installed on Windows | + +### Required Permissions + +- **GitHub**: Repository admin or secrets write permission +- Must be in a Git repository directory or specify repository + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ฅ Expected Input Format + +The `GhSecretBody` parameter should contain Azure service principal credentials in this JSON format: + +```json +{ + "clientId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "clientSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", + "subscriptionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" +} +``` + +This format is output by `az ad sp create-for-rbac --json-auth`. + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Functions Reference + +### Function: `Connect-GitHubCli` + +**Purpose:** Ensures GitHub CLI is authenticated, prompting for login if needed. + +**Parameters:** None + +**Returns:** `[bool]` - `$true` if authenticated successfully, `$false` otherwise + +**Behavior:** + +1. Checks authentication status with `gh auth status` +2. If not authenticated, triggers `gh auth login` interactive flow +3. Returns success/failure status + +--- + +### Function: `Set-GitHubRepositorySecret` + +**Purpose:** Creates or updates a GitHub repository secret. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `SecretName` | `string` | Yes | Name of the secret | +| `SecretValue` | `string` | Yes | Value to store | + +**Returns:** `[bool]` - `$true` if secret set successfully, `$false` otherwise + +**Command:** `gh secret set {SecretName} --body {SecretValue}` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Usage Examples + +### Direct Execution with JSON + +```powershell +$creds = @' +{ + "clientId": "12345678-1234-1234-1234-123456789012", + "clientSecret": "mySecretValue123", + "subscriptionId": "12345678-1234-1234-1234-123456789012", + "tenantId": "12345678-1234-1234-1234-123456789012" +} +'@ + +.\createGitHubSecretAzureCredentials.ps1 -GhSecretBody $creds +``` + +### From Service Principal Creation + +```powershell +# Create service principal and capture output +$creds = az ad sp create-for-rbac --name "my-sp" --role Contributor --json-auth + +# Create GitHub secret +.\createGitHubSecretAzureCredentials.ps1 -GhSecretBody $creds +``` + +
+Expected Output + +``` +Creating GitHub secret for Azure credentials... +Checking GitHub authentication status... +Already authenticated to GitHub. +Setting GitHub secret: AZURE_CREDENTIALS +GitHub secret 'AZURE_CREDENTIALS' set successfully. + +GitHub secret 'AZURE_CREDENTIALS' created successfully. +You can now use this secret in your GitHub Actions workflows. +``` + +
+ +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Using the Secret in GitHub Actions + +After creating the secret, use it in your workflow: + +```yaml +name: Deploy to Azure +on: [push] + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Azure Login + uses: azure/login@v2 + with: + creds: ${{ secrets.AZURE_CREDENTIALS }} + + - name: Deploy resources + run: | + az group create --name my-rg --location eastus +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš ๏ธ Error Handling + +### Error Action Preference + +```powershell +$ErrorActionPreference = 'Stop' +$WarningPreference = 'Stop' +``` + +### Exit Codes + +| Code | Meaning | +|------|---------| +| `0` | Secret created successfully | +| `1` | Secret creation failed | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ› ๏ธ Troubleshooting + +### Common Issues + +| Issue | Cause | Solution | +|-------|-------|----------| +| "Failed to authenticate to GitHub" | gh login failed or cancelled | Run `gh auth login` manually | +| "Failed to set GitHub secret" | No repository context | Run from Git repository directory | +| "Secret name invalid" | Special characters in name | Use alphanumeric and underscore only | +| "Permission denied" | Insufficient repo permissions | Verify admin access | + +### Verify Secret Creation + +```powershell +# List repository secrets +gh secret list +``` + +### Check GitHub Authentication + +```powershell +# Verify authentication status +gh auth status + +# View authenticated scopes +gh auth token +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”’ Security Considerations + +### Secret Handling + +- Secret value is passed via `--body` parameter (not stdin) +- Value is encrypted before storage in GitHub +- Secret cannot be read after creation (only updated/deleted) + +### Audit Trail + +- GitHub audit logs record secret creation/modification +- Workflow runs log secret usage (value masked) + +### Secret Rotation + +When rotating credentials: + +1. Create new service principal credentials +2. Update secret with same command (overwrites existing) +3. Delete old service principal + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Related Scripts + +| Script | Purpose | Link | +|--------|---------|------| +| `deleteGitHubSecretAzureCredentials.ps1` | Remove GitHub secret | [delete-github-secret-azure-credentials.md](delete-github-secret-azure-credentials.md) | +| `generateDeploymentCredentials.ps1` | Create SP and call this script | [../azure/generate-deployment-credentials.md](../azure/generate-deployment-credentials.md) | +| `cleanSetUp.ps1` | Full environment cleanup | [../clean-setup.md](../clean-setup.md) | + +--- + +
+ +[โ† winget-update.ps1](../configuration/winget-update.md) | [โฌ†๏ธ Back to Top](#-table-of-contents) | [deleteGitHubSecretAzureCredentials.ps1 โ†’](delete-github-secret-azure-credentials.md) + +*DevExp-DevBox โ€ข createGitHubSecretAzureCredentials.ps1 Documentation* + +
diff --git a/docs/scripts/github/delete-github-secret-azure-credentials.md b/docs/scripts/github/delete-github-secret-azure-credentials.md new file mode 100644 index 00000000..28742a3f --- /dev/null +++ b/docs/scripts/github/delete-github-secret-azure-credentials.md @@ -0,0 +1,356 @@ +--- +title: "deleteGitHubSecretAzureCredentials.ps1 Script" +description: "Removes a GitHub repository secret" +author: "DevExp Team" +date: 2026-01-23 +version: "1.0.0" +tags: + - scripts + - github + - secrets + - cleanup +--- + +# ๐Ÿ—‘๏ธ deleteGitHubSecretAzureCredentials.ps1 + +> **Removes a GitHub repository secret** + +> [!WARNING] +> Deleting the secret will **immediately** affect any workflows using it. + +> [!NOTE] +> **Target Audience:** DevOps Engineers, Platform Engineers +> **Reading Time:** ~8 minutes + +
+๐Ÿ“ Navigation + +| Previous | Index | Next | +|:---------|:-----:|-----:| +| [โ† createGitHubSecretAzureCredentials.ps1](create-github-secret-azure-credentials.md) | [Scripts Index](../README.md) | โ€” | + +
+ +--- + +## ๐Ÿ“‘ Table of Contents + +- [๐ŸŽฏ Overview](#-overview) +- [๐Ÿ“Š Flow Visualization](#-flow-visualization) +- [๐Ÿ“ Parameters](#-parameters) +- [โš™๏ธ Prerequisites](#-prerequisites) +- [๐Ÿ”ง Functions Reference](#-functions-reference) +- [๐Ÿ“ Usage Examples](#-usage-examples) +- [โš ๏ธ Error Handling](#-error-handling) +- [๐Ÿ› ๏ธ Troubleshooting](#-troubleshooting) +- [๐Ÿ”’ Security Considerations](#-security-considerations) +- [๐Ÿ”— Related Scripts](#-related-scripts) + +--- + +## ๐ŸŽฏ Overview + +This script authenticates to GitHub using the GitHub CLI and removes a specified secret from the current repository. Typically used to remove the `AZURE_CREDENTIALS` secret during cleanup operations. + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“Š Flow Visualization + +```mermaid +--- +title: Delete GitHub Secret Flow +--- +flowchart TD + %% ===== SCRIPT ENTRY ===== + subgraph Entry["๐Ÿ“ฅ Script Entry"] + A(["๐Ÿš€ deleteGitHubSecretAzureCredentials.ps1 Start"]) + B[/"๐Ÿ“ Parse Parameters"/] + end + + %% ===== GITHUB AUTHENTICATION ===== + subgraph Auth["๐Ÿ” GitHub Authentication"] + C["โš™๏ธ Connect-GitHubCli"] + D[("๐Ÿ™ gh auth status")] + E{"โœ… Authenticated?"} + F[("๐Ÿ”‘ gh auth login")] + end + + %% ===== SECRET DELETION ===== + subgraph SecretDeletion["๐Ÿ—‘๏ธ Secret Deletion"] + G["โš™๏ธ Remove-GitHubRepositorySecret"] + H[("๐Ÿ—‘๏ธ gh secret remove")] + I{"๐Ÿ“‹ Secret existed?"} + end + + %% ===== SCRIPT EXIT ===== + subgraph Exit["๐Ÿ“ค Script Exit"] + J[\"๐ŸŽ‰ Secret Removed"\] + K[\"โญ๏ธ Secret Not Found - OK"\] + L{{"โŒ Error Handler"}} + end + + %% ===== CONNECTIONS ===== + A -->|parses| B -->|connects| C -->|checks| D -->|evaluates| E + E -->|Yes| G + E -->|No| F -->|authenticates| G + G -->|removes| H -->|evaluates| I + I -->|Yes| J + I -->|No| K + + %% ===== STYLES ===== + classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + classDef input fill:#F59E0B,stroke:#D97706,color:#000000 + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef external fill:#6B7280,stroke:#4B5563,color:#FFFFFF,stroke-dasharray:5 5 + classDef decision fill:#FFFBEB,stroke:#F59E0B,color:#000000 + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef failed fill:#F44336,stroke:#C62828,color:#FFFFFF + + class A trigger + class B input + class C,G primary + class D,F,H external + class E,I decision + class J,K secondary + class L failed + + %% ===== SUBGRAPH STYLES ===== + style Entry fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style Auth fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style SecretDeletion fill:#FEE2E2,stroke:#F44336,stroke-width:2px + style Exit fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Parameters + +| Parameter | Type | Required | Default | Validation | Description | +|-----------|------|----------|---------|------------|-------------| +| `-GhSecretName` | `string` | Yes | - | `ValidateNotNullOrEmpty` | Name of the GitHub secret to delete | + +**Aliases:** `ghSecretName` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Prerequisites + +### Required Tools + +| Tool | Purpose | Installation | +|------|---------|--------------| +| GitHub CLI (`gh`) | Manage repository secrets | [Install GitHub CLI](https://cli.github.com/) | +| PowerShell 5.1+ | Script execution | Pre-installed on Windows | + +### Required Permissions + +- **GitHub**: Repository admin or secrets delete permission +- Must be in a Git repository directory or specify repository + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Functions Reference + +### Function: `Connect-GitHubCli` + +**Purpose:** Ensures GitHub CLI is authenticated, prompting for login if needed. + +**Parameters:** None + +**Returns:** `[bool]` - `$true` if authenticated successfully, `$false` otherwise + +**Behavior:** + +1. Checks authentication status with `gh auth status` +2. If not authenticated, triggers `gh auth login` interactive flow +3. Returns success/failure status + +--- + +### Function: `Remove-GitHubRepositorySecret` + +**Purpose:** Removes a secret from the GitHub repository. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `SecretName` | `string` | Yes | Name of the secret to remove | + +**Returns:** `[bool]` - `$true` if secret removed or didn't exist, `$false` on error + +**Behavior:** + +1. Supports `-WhatIf` for dry run +2. Attempts to remove secret via `gh secret remove` +3. Non-zero exit code treated as warning (secret may not exist) +4. Returns `$true` even if secret didn't exist (idempotent) + +**Command:** `gh secret remove {SecretName}` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Usage Examples + +### Delete Default Azure Credentials Secret + +```powershell +.\deleteGitHubSecretAzureCredentials.ps1 -GhSecretName "AZURE_CREDENTIALS" +``` + +### Delete Custom Secret + +```powershell +.\deleteGitHubSecretAzureCredentials.ps1 -GhSecretName "MY_CUSTOM_SECRET" +``` + +### Dry Run (WhatIf) + +```powershell +.\deleteGitHubSecretAzureCredentials.ps1 -GhSecretName "AZURE_CREDENTIALS" -WhatIf +``` + +
+Expected Output + +``` +Starting GitHub secret deletion... +Checking GitHub authentication status... +Already authenticated to GitHub. +Removing GitHub secret: AZURE_CREDENTIALS +GitHub secret 'AZURE_CREDENTIALS' removed successfully. + +GitHub secret deletion completed. +``` + +
+ +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš ๏ธ Error Handling + +### Error Action Preference + +```powershell +$ErrorActionPreference = 'Stop' +$WarningPreference = 'Stop' +``` + +### Exit Codes + +| Code | Meaning | +|------|---------| +| `0` | Secret removed or didn't exist | +| `1` | Critical failure (authentication, etc.) | + +### Idempotency + +The script is **idempotent**: + +- If secret doesn't exist, returns success with warning +- Safe to run multiple times +- No error if already deleted + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ› ๏ธ Troubleshooting + +### Common Issues + +| Issue | Cause | Solution | +|-------|-------|----------| +| "Failed to authenticate to GitHub" | gh login failed | Run `gh auth login` manually | +| "Secret may not exist" | Secret already deleted | Expected - script continues | +| "Permission denied" | Insufficient repo permissions | Verify admin access | +| "Not a git repository" | Wrong working directory | Navigate to repository root | + +### Verify Secret Deletion + +```powershell +# List remaining repository secrets +gh secret list +``` + +### Check Before Deletion + +```powershell +# View existing secrets +gh secret list | findstr "AZURE_CREDENTIALS" +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”’ Security Considerations + +### Immediate Effect + +- Deleting the secret **immediately** affects workflow runs +- Any workflows using the secret will fail after deletion +- No grace period or rollback available + +### Before Deletion Checklist + +- [ ] Verify no workflows are actively using the secret +- [ ] Confirm CI/CD pipelines can tolerate temporary failures +- [ ] Have replacement credentials ready if needed + +### Audit Trail + +- GitHub audit logs record secret deletion +- Deletion cannot be undone - must recreate secret + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Related Scripts + +| Script | Purpose | Link | +|--------|---------|------| +| `createGitHubSecretAzureCredentials.ps1` | Create GitHub secret | [create-github-secret-azure-credentials.md](create-github-secret-azure-credentials.md) | +| `deleteDeploymentCredentials.ps1` | Remove service principal | [../azure/delete-deployment-credentials.md](../azure/delete-deployment-credentials.md) | +| `cleanSetUp.ps1` | Full environment cleanup | [../clean-setup.md](../clean-setup.md) | + +--- + +
+ +[โ† createGitHubSecretAzureCredentials.ps1](create-github-secret-azure-credentials.md) | [โฌ†๏ธ Back to Top](#-table-of-contents) + +*DevExp-DevBox โ€ข deleteGitHubSecretAzureCredentials.ps1 Documentation* + +
diff --git a/docs/scripts/setup.md b/docs/scripts/setup.md new file mode 100644 index 00000000..56911e0a --- /dev/null +++ b/docs/scripts/setup.md @@ -0,0 +1,586 @@ +--- +title: "setUp.ps1 Script" +description: "Azure Dev Box environment setup script with GitHub/Azure DevOps integration" +author: "DevExp Team" +date: 2026-01-23 +version: "1.0.0" +tags: + - scripts + - setup + - azure + - azd + - authentication +--- + +# โš™๏ธ setUp.ps1 + +> **Azure Dev Box environment setup with GitHub/Azure DevOps integration** + +> [!NOTE] +> **Target Audience:** DevOps Engineers, Platform Engineers +> **Reading Time:** ~15 minutes + +
+๐Ÿ“ Navigation + +| Previous | Index | Next | +|:---------|:-----:|-----:| +| [โ† Scripts Overview](README.md) | [Scripts Index](README.md) | [cleanSetUp.ps1 โ†’](clean-setup.md) | + +
+ +--- + +## ๐Ÿ“‘ Table of Contents + +- [๐ŸŽฏ Overview](#overview) +- [๐Ÿ“Š Flow Visualization](#flow-visualization) +- [๐Ÿ”’ Authentication Flow](#authentication-flow) +- [๐Ÿ“ Parameters](#parameters) +- [โš™๏ธ Prerequisites](#prerequisites) +- [๐Ÿ”ง Functions Reference](#functions-reference) +- [๐Ÿ“ Usage Examples](#usage-examples) +- [โš ๏ธ Error Handling](#error-handling) +- [๐Ÿ” Security Considerations](#security-considerations) +- [๐Ÿ”ง Troubleshooting](#troubleshooting) +- [๐Ÿ”— Related Scripts](#related-scripts) + +--- + +## ๐ŸŽฏ Overview + +This script automates the setup of an Azure Developer CLI (azd) environment for Dev Box, handles source control authentication (GitHub or Azure DevOps), and prepares the environment for Azure resource provisioning. Use this script when initializing a new DevExp-DevBox environment. + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“Š Flow Visualization + +```mermaid +--- +title: Setup Script Flow +--- +flowchart TD + %% ===== SCRIPT ENTRY ===== + subgraph Entry["๐Ÿ“ฅ Script Entry"] + A(["๐Ÿš€ setUp.ps1 Start"]) + B[/"๐Ÿ“ Parse Parameters"/] + C{"โ“ Help requested?"} + end + + %% ===== ARGUMENT VALIDATION ===== + subgraph Validation["โœ… Argument Validation"] + D["๐Ÿ” Test-Arguments"] + D1{"๐Ÿ“‹ EnvName provided?"} + D2{"๐Ÿ”— SourceControl provided?"} + D3["๐ŸŽฏ Select-SourceControlPlatform"] + D4["โœ”๏ธ Test-SourceControlValidation"] + end + + %% ===== TOOL VERIFICATION ===== + subgraph Tools["๐Ÿ”ง Tool Verification"] + E["๐Ÿงช Test-CommandAvailability"] + E1[("โ˜๏ธ az")] + E2[("๐Ÿš€ azd")] + E3[("๐Ÿ™ gh")] + end + + %% ===== AUTHENTICATION ===== + subgraph Auth["๐Ÿ” Authentication"] + F["๐Ÿ”‘ Test-AzureAuthentication"] + F1{"๐ŸŽ›๏ธ Platform?"} + F2["๐Ÿ™ Test-GitHubAuthentication"] + F3["๐Ÿ”ท Test-AdoAuthentication"] + end + + %% ===== TOKEN RETRIEVAL ===== + subgraph Token["๐ŸŽซ Token Retrieval"] + G{"๐ŸŽ›๏ธ Platform?"} + G1["๐Ÿ”’ Get-SecureGitHubToken"] + G2["๐Ÿ”’ Get-SecureAdoGitToken"] + end + + %% ===== ENVIRONMENT INIT ===== + subgraph Init["โš™๏ธ Environment Init"] + H["๐ŸŒ Initialize-AzdEnvironment"] + H1["๐Ÿ“ Create .azure directory"] + H2["๐Ÿ“ Write .env file"] + H3["โš™๏ธ Configure azd"] + end + + %% ===== SCRIPT EXIT ===== + subgraph Exit["๐Ÿ“ค Script Exit"] + I[\"โœ… Success"\] + J{{"โŒ Error Handler"}} + end + + %% ===== CONNECTIONS ===== + A -->|starts| B -->|checks| C + C -->|Yes| HELP["๐Ÿ“– Show-Help"] -->|exits| EXIT(["๐Ÿšช Exit 0"]) + C -->|No| D + D -->|validates| D1 + D1 -->|No| J + D1 -->|Yes| D2 + D2 -->|No| D3 + D2 -->|Yes| D4 + D3 -->|selects| D4 + D4 -->|checks| E + E -->|verifies| E1 & E2 + E -->|continues| F + F -->|determines| F1 + F1 -->|github| E3 -->|validates| F2 + F1 -->|adogit| F3 + F2 -->|retrieves| G + F3 -->|retrieves| G + G -->|github| G1 + G -->|adogit| G2 + G1 -->|initializes| H + G2 -->|initializes| H + H -->|creates| H1 -->|writes| H2 -->|configures| H3 -->|completes| I + + %% ===== STYLES ===== + classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF + classDef input fill:#F59E0B,stroke:#D97706,color:#000000 + classDef primary fill:#4F46E5,stroke:#3730A3,color:#FFFFFF + classDef secondary fill:#10B981,stroke:#059669,color:#FFFFFF + classDef external fill:#6B7280,stroke:#4B5563,color:#FFFFFF,stroke-dasharray:5 5 + classDef decision fill:#FFFBEB,stroke:#F59E0B,color:#000000 + classDef failed fill:#F44336,stroke:#C62828,color:#FFFFFF + + class A,EXIT trigger + class B input + class D,D4,E,F,F2,F3 primary + class E1,E2,E3 external + class C,D1,D2,F1,G decision + class D3,G1,G2,H,H1,H2,H3 secondary + class I secondary + class J,HELP failed + + %% ===== SUBGRAPH STYLES ===== + style Entry fill:#EEF2FF,stroke:#4F46E5,stroke-width:2px + style Validation fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style Tools fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Auth fill:#E0E7FF,stroke:#4F46E5,stroke-width:2px + style Token fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px + style Init fill:#ECFDF5,stroke:#10B981,stroke-width:2px + style Exit fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”’ Authentication Flow + +```mermaid +sequenceDiagram + participant User + participant Script as setUp.ps1 + participant AzCLI as Azure CLI + participant GhCLI as GitHub CLI + participant AdoCLI as Azure DevOps CLI + participant AzD as Azure Developer CLI + + User->>Script: Execute with parameters + Script->>AzCLI: az account show + AzCLI-->>Script: Subscription info + + alt GitHub Platform + Script->>GhCLI: gh auth status + GhCLI-->>Script: Auth status + Script->>GhCLI: gh auth token + GhCLI-->>Script: Personal Access Token + else Azure DevOps Platform + Script->>AdoCLI: az devops configure --list + AdoCLI-->>Script: Config status + Script->>User: Prompt for PAT + User-->>Script: Enter PAT securely + end + + Script->>Script: Store token in memory + Script->>AzD: Create environment directory + Script->>AzD: Write .env configuration + Script-->>User: Setup complete +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Parameters + +| Parameter | Type | Required | Default | Validation | Description | +|-----------|------|----------|---------|------------|-------------| +| `-EnvName` | `string` | Yes* | - | - | Name of the Azure environment to create | +| `-SourceControl` | `string` | No | - | `ValidateSet("github", "adogit", "")` | Source control platform | +| `-Help` | `switch` | No | `$false` | - | Show help message | + +*Required unless `-Help` is specified. + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Prerequisites + +### Required Tools + +| Tool | Purpose | Required For | Installation | +|------|---------|--------------|--------------| +| Azure CLI (`az`) | Azure authentication | All setups | [Install Azure CLI](https://docs.microsoft.com/cli/azure/install-azure-cli) | +| Azure Developer CLI (`azd`) | Environment management | All setups | [Install azd](https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd) | +| GitHub CLI (`gh`) | GitHub authentication | GitHub source control | [Install GitHub CLI](https://cli.github.com/) | + +### Required Permissions + +- **Azure**: Valid subscription with Enabled state +- **GitHub**: Authenticated with `repo` scope (for GitHub platform) +- **Azure DevOps**: Valid PAT with appropriate scopes (for ADO platform) + +### Environment Variables + +| Variable | Purpose | Set By | +|----------|---------|--------| +| `KEY_VAULT_SECRET` | Stores PAT for azd | Script (in `.env` file) | +| `SOURCE_CONTROL_PLATFORM` | Tracks selected platform | Script (in `.env` file) | +| `AZURE_DEVOPS_EXT_PAT` | Azure DevOps authentication | Script (for ADO platform) | + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Functions Reference + +### Function: `Write-LogMessage` + +**Purpose:** Outputs formatted log messages with timestamps and colored output based on severity. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `Message` | `string` | Yes | The message text to log | +| `Level` | `string` | No | Severity level: Info, Warning, Error, Success | + +**Output Format:** + +``` +โœ… [2025-01-23 10:30:45] Operation completed successfully +โŒ [2025-01-23 10:30:46] An error occurred +``` + +--- + +### Function: `Test-CommandAvailability` + +**Purpose:** Verifies that a required command-line tool is available in PATH. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `Command` | `string` | Yes | Name of the command to check | + +**Returns:** `[bool]` - `$true` if command exists, `$false` otherwise + +--- + +### Function: `Test-AzureAuthentication` + +**Purpose:** Validates Azure CLI authentication and subscription status. + +**Returns:** `[bool]` - `$true` if authenticated with enabled subscription + +**Checks:** + +- User is logged into Azure CLI +- Current subscription is in "Enabled" state +- Outputs subscription details for verification + +--- + +### Function: `Test-GitHubAuthentication` + +**Purpose:** Validates GitHub CLI authentication status. + +**Returns:** `[bool]` - `$true` if authenticated + +**Uses:** `gh auth status` + +--- + +### Function: `Test-AdoAuthentication` + +**Purpose:** Validates Azure DevOps CLI extension is configured. + +**Returns:** `[bool]` - `$true` if configured + +**Uses:** `az devops configure --list` + +--- + +### Function: `Get-SecureGitHubToken` + +**Purpose:** Retrieves GitHub Personal Access Token securely. + +**Returns:** `[bool]` - `$true` if token retrieved successfully + +**Token Sources (in order):** + +1. `KEY_VAULT_SECRET` environment variable +2. `gh auth token` command + +**Security:** Token stored in `$Script:GitHubToken` (script scope) + +--- + +### Function: `Get-SecureAdoGitToken` + +**Purpose:** Retrieves Azure DevOps PAT securely. + +**Returns:** `[bool]` - `$true` if token retrieved successfully + +**Token Sources (in order):** + +1. `KEY_VAULT_SECRET` environment variable +2. Secure prompt (`Read-Host -AsSecureString`) + +**Security:** + +- Token stored in `$Script:AdoToken` (script scope) +- Exported to `AZURE_DEVOPS_EXT_PAT` for Azure CLI + +--- + +### Function: `Initialize-AzdEnvironment` + +**Purpose:** Sets up the Azure Developer CLI environment with source control tokens. + +**Returns:** `[bool]` - `$true` if initialization succeeded + +**Creates:** + +- Directory: `.azure\{EnvName}\` +- File: `.azure\{EnvName}\.env` with: + + ``` + KEY_VAULT_SECRET='' + SOURCE_CONTROL_PLATFORM='' + ``` + +--- + +### Function: `Start-AzureProvisioning` + +**Purpose:** Initiates Azure resource provisioning using `azd provision`. + +**Returns:** `[bool]` - `$true` if provisioning succeeded + +**Command:** `azd provision -e {EnvName}` + +--- + +### Function: `Select-SourceControlPlatform` + +**Purpose:** Interactive prompt for source control platform selection. + +**Behavior:** + +1. Displays options (Azure DevOps Git, GitHub) +2. Validates selection (1 or 2) +3. Sets `$Script:SourceControl` variable + +--- + +### Function: `Invoke-Main` + +**Purpose:** Main orchestration function that coordinates the entire setup process. + +**Sequence:** + +1. Process and validate arguments +2. Display configuration summary +3. Verify required tools +4. Verify Azure authentication +5. Verify source control authentication +6. Initialize azd environment +7. Display success message + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Usage Examples + +### GitHub Setup + +```powershell +.\setUp.ps1 -EnvName "prod" -SourceControl "github" +``` + +### Azure DevOps Setup + +```powershell +.\setUp.ps1 -EnvName "dev" -SourceControl "adogit" +``` + +### Interactive Platform Selection + +```powershell +.\setUp.ps1 -EnvName "demo" +# Script prompts for platform selection +``` + +### Show Help + +```powershell +.\setUp.ps1 -Help +``` + +
+Expected Help Output + +``` +setUp.ps1 - Sets up Azure Dev Box environment with source control integration + +USAGE: + .\setUp.ps1 -EnvName ENV_NAME -SourceControl PLATFORM + +PARAMETERS: + -EnvName ENV_NAME Name of the Azure environment to create + -SourceControl PLATFORM Source control platform (github or adogit) + -Help Show this help message + +EXAMPLES: + .\setUp.ps1 -EnvName "prod" -SourceControl "github" + .\setUp.ps1 -EnvName "dev" -SourceControl "adogit" + +REQUIREMENTS: + - Azure CLI (az) + - Azure Developer CLI (azd) + - GitHub CLI (gh) [if using GitHub] + - Valid authentication for chosen platform +``` + +
+ +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš ๏ธ Error Handling + +### Error Action Preference + +```powershell +$ErrorActionPreference = 'Stop' +$ProgressPreference = 'SilentlyContinue' +``` + +### Exit Codes + +| Code | Meaning | +|------|---------| +| `0` | Setup completed successfully (or help displayed) | +| `1` | Setup failed due to error | +| `130` | Script interrupted by user (Ctrl+C) | + +### Trap Handler + +```powershell +trap { + Write-LogMessage "Script interrupted by user" "Warning" + exit 130 +} +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ” Security Considerations + +### Token Handling + +- Tokens are stored in script-scoped variables (`$Script:GitHubToken`, `$Script:AdoToken`) +- PAT values are masked in logs (first 4 + last 2 characters visible) +- Azure DevOps PAT can be entered via secure prompt (no echo) +- Tokens written to `.env` file (ensure proper .gitignore) + +### Credential Storage + +The script stores tokens in `.azure\{EnvName}\.env`: + +``` +KEY_VAULT_SECRET='ghp_xxxx****xx' +SOURCE_CONTROL_PLATFORM='github' +``` + +> โš ๏ธ **Warning:** Ensure `.azure/` is in `.gitignore` to prevent token exposure. + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Troubleshooting + +### Common Issues + +| Issue | Cause | Solution | +|-------|-------|----------| +| "Required command 'az' was not found" | Azure CLI not installed | Install Azure CLI | +| "Not logged into Azure" | Azure CLI not authenticated | Run `az login` | +| "Subscription not in 'Enabled' state" | Subscription suspended | Check Azure portal billing | +| "Not logged into GitHub" | GitHub CLI not authenticated | Run `gh auth login` | +| "Failed to retrieve GitHub token" | Token expired or revoked | Re-authenticate with `gh auth login` | + +### Verbose Output + +```powershell +# Set preference before running +$VerbosePreference = 'Continue' +.\setUp.ps1 -EnvName "debug-env" -SourceControl "github" +``` + +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Related Scripts + +| Script | Purpose | Link | +|--------|---------|------| +| `cleanSetUp.ps1` | Complete environment cleanup (opposite of setup) | [clean-setup.md](clean-setup.md) | +| `generateDeploymentCredentials.ps1` | Create service principal for CI/CD | [azure/generate-deployment-credentials.md](azure/generate-deployment-credentials.md) | +| `createUsersAndAssignRole.ps1` | Assign DevCenter roles | [azure/create-users-and-assign-role.md](azure/create-users-and-assign-role.md) | + +--- + +
+ +[โ† Scripts Overview](README.md) | [โฌ†๏ธ Back to Top](#-table-of-contents) | [cleanSetUp.ps1 โ†’](clean-setup.md) + +*DevExp-DevBox โ€ข setUp.ps1 Documentation* + +