From 61acc67ad6280b3b13bd7e0c280abb6749000fa0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 10:43:39 -0500 Subject: [PATCH 01/44] Add comprehensive DevOps documentation for CI/CD workflows - Created README.md for DevOps documentation, detailing CI/CD workflows, triggers, and architecture. - Added ci.md to document the Continuous Integration workflow, including triggers, jobs, and versioning strategy. - Introduced deploy.md for the Deploy to Azure workflow, outlining manual triggers, jobs, and prerequisites. - Developed release.md for the Branch-Based Release Strategy workflow, covering versioning, job conditions, and troubleshooting. --- .../07-deployment-architecture.md | 394 ++++++++++++++++++ docs/devops/README.md | 201 +++++++++ docs/devops/ci.md | 164 ++++++++ docs/devops/deploy.md | 235 +++++++++++ docs/devops/release.md | 357 ++++++++++++++++ 5 files changed, 1351 insertions(+) create mode 100644 docs/architecture/07-deployment-architecture.md create mode 100644 docs/devops/README.md create mode 100644 docs/devops/ci.md create mode 100644 docs/devops/deploy.md create mode 100644 docs/devops/release.md diff --git a/docs/architecture/07-deployment-architecture.md b/docs/architecture/07-deployment-architecture.md new file mode 100644 index 00000000..1ff1bf17 --- /dev/null +++ b/docs/architecture/07-deployment-architecture.md @@ -0,0 +1,394 @@ +# Deployment Architecture + +> ๐Ÿ“– This document describes the deployment architecture and CI/CD pipeline design for the Dev Box Accelerator project. + +## 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). + +## 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 +``` + +## 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 +``` + +## 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 +``` + +## 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 | + +## 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 +``` + +## 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` | + +## 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 + +## 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 + +## 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 diff --git a/docs/devops/README.md b/docs/devops/README.md new file mode 100644 index 00000000..249af983 --- /dev/null +++ b/docs/devops/README.md @@ -0,0 +1,201 @@ +# DevOps Documentation + +> ๐Ÿ“– Comprehensive documentation for GitHub Actions workflows in the Dev Box Accelerator project. + +## 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. + +## Master Pipeline Architecture + +The following diagram shows the complete CI/CD pipeline architecture and how all workflows relate to each other: + +```mermaid +flowchart TB + subgraph "๐ŸŽฏ Triggers" + direction LR + T1([Push: feature/**]) + T2([Push: fix/**]) + T3([PR to main]) + T4([Manual: Deploy]) + T5([Manual: Release]) + end + + subgraph "๐Ÿ”„ Continuous Integration" + direction TB + CI1["๐Ÿ“Š generate-tag-version"] + CI2["๐Ÿ”จ build"] + CI1 --> CI2 + end + + subgraph "๐Ÿš€ Deployment" + direction TB + D1["โœ… Validate Variables"] + D2["๐Ÿ”จ Build Bicep"] + D3["๐Ÿ” Azure OIDC Auth"] + D4["โ˜๏ธ azd provision"] + D1 --> D2 --> D3 --> D4 + end + + subgraph "๐Ÿท๏ธ Release" + direction TB + R1["๐Ÿ“Š generate-release"] + R2["๐Ÿ”จ build"] + R3["๐ŸŽ‰ publish-release"] + R4["๐Ÿ“‹ summary"] + R1 --> R2 --> R3 --> R4 + end + + subgraph "๐Ÿ“ฆ Outputs" + direction TB + O1[/"Versioned Artifacts"/] + O2[/"GitHub Release"/] + O3[(Azure Resources)] + end + + T1 & T2 & T3 --> CI1 + T4 --> D1 + T5 --> R1 + + CI2 --> O1 + R3 --> O1 + R3 --> O2 + D4 --> O3 + + classDef trigger fill:#2196F3,stroke:#1565C0,color:#fff + classDef ci fill:#FF9800,stroke:#EF6C00,color:#fff + classDef deploy fill:#4CAF50,stroke:#2E7D32,color:#fff + classDef release fill:#9C27B0,stroke:#6A1B9A,color:#fff + classDef output fill:#607D8B,stroke:#455A64,color:#fff + + class T1,T2,T3,T4,T5 trigger + class CI1,CI2 ci + class D1,D2,D3,D4 deploy + class R1,R2,R3,R4 release + class O1,O2,O3 output +``` + +## 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`) | + +## Quick Reference + +### Trigger Summary + +```mermaid +flowchart LR + subgraph "Automatic Triggers" + A1["Push to feature/**"] --> CI["CI Workflow"] + A2["Push to fix/**"] --> CI + A3["PR to main"] --> CI + end + + subgraph "Manual Triggers" + M1["workflow_dispatch"] --> DEPLOY["Deploy Workflow"] + M2["workflow_dispatch"] --> RELEASE["Release Workflow"] + end + + classDef auto fill:#4CAF50,stroke:#2E7D32,color:#fff + classDef manual fill:#2196F3,stroke:#1565C0,color:#fff + classDef workflow fill:#FF9800,stroke:#EF6C00,color:#fff + + class A1,A2,A3 auto + class M1,M2 manual + class CI,DEPLOY,RELEASE workflow +``` + +### 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 | + +## 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 +flowchart LR + subgraph "generate-release" + GR1["Get Branch Info"] + GR2["Get Latest Tag"] + GR3["Determine Release Type"] + GR4["Count Commits"] + GR5["Calculate Version"] + GR6["Create Tag"] + GR1 --> GR2 --> GR3 --> GR4 --> GR5 --> GR6 + end + + subgraph "bicep-standard-ci" + BC1["Build Bicep"] + BC2["Upload Artifacts"] + BC3["Generate Summary"] + BC1 --> BC2 --> BC3 + end + + classDef action fill:#9C27B0,stroke:#6A1B9A,color:#fff + class GR1,GR2,GR3,GR4,GR5,GR6,BC1,BC2,BC3 action +``` + +## 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 + +## Best Practices + +### Security + +- โœ… 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 + +## 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 diff --git a/docs/devops/ci.md b/docs/devops/ci.md new file mode 100644 index 00000000..be5ba5bd --- /dev/null +++ b/docs/devops/ci.md @@ -0,0 +1,164 @@ +# Continuous Integration Workflow + +## 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. + +## Pipeline Visualization + +```mermaid +flowchart TD + subgraph "๐ŸŽฏ Triggers" + T1([Push to feature/**]) + T2([Push to fix/**]) + T3([PR to main]) + end + + subgraph "๐Ÿ“Š generate-tag-version" + direction TB + GTV1["๐Ÿ”„ Checkout Repository"] + GTV2["๐Ÿท๏ธ Generate Release Information"] + GTV3[/"new_version, release_type, previous_tag"/] + GTV1 --> GTV2 --> GTV3 + end + + subgraph "๐Ÿ”จ build" + direction TB + B1["๐Ÿ”„ Checkout Repository"] + B2["๐Ÿ“ฆ Build Bicep Code"] + B3[/"Versioned Artifacts"/] + B1 --> B2 --> B3 + end + + T1 & T2 & T3 --> GTV1 + GTV3 --> |"success"| B1 + GTV3 -.-> |"failure"| SKIP((Skipped)) + + classDef trigger fill:#2196F3,stroke:#1565C0,color:#fff + classDef build fill:#FF9800,stroke:#EF6C00,color:#fff + classDef artifact fill:#4CAF50,stroke:#2E7D32,color:#fff + classDef skip fill:#9E9E9E,stroke:#616161,color:#fff + + class T1,T2,T3 trigger + class GTV1,GTV2,B1,B2 build + class GTV3,B3 artifact + class SKIP skip +``` + +## 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 | + +## 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 | + +## 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 | + +## Environment Variables + +This workflow does not use environment-specific variables. All configuration is derived from the branch name and commit history. + +## 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` | + +## Artifacts + +| Artifact Name | Contents | Retention | +| -------------------------- | ------------------------------- | --------- | +| `artifacts-{version}` | Compiled ARM templates | 30 days | + +## Troubleshooting + +### 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`) + +## Related Documentation + +- [Release Workflow](release.md) - Full release process with GitHub Releases +- [Deploy Workflow](deploy.md) - Azure deployment process diff --git a/docs/devops/deploy.md b/docs/devops/deploy.md new file mode 100644 index 00000000..9bb90f34 --- /dev/null +++ b/docs/devops/deploy.md @@ -0,0 +1,235 @@ +# Deploy to Azure Workflow + +## 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. + +## Pipeline Visualization + +```mermaid +flowchart TD + subgraph "๐ŸŽฏ Trigger" + T1([Manual Dispatch]) + end + + subgraph "๐Ÿ“ Inputs" + direction LR + I1[/"AZURE_ENV_NAME"/] + I2[/"AZURE_LOCATION"/] + end + + subgraph "๐Ÿš€ build-and-deploy-to-azure" + direction TB + V1["โœ… Validate Required Variables"] + V1 --> C1["๐Ÿ”„ Checkout Repository"] + C1 --> AZD["๐Ÿ“ฅ Install Azure Developer CLI"] + AZD --> B1["๐Ÿ”จ Build Bicep Templates"] + B1 --> U1["๐Ÿ“ค Upload Build Artifacts"] + U1 --> S1["๐Ÿ“Š Generate Build Summary"] + S1 --> AUTH["๐Ÿ” Authenticate with Azure (OIDC)"] + AUTH --> D1["๐Ÿš€ Deploy Infrastructure to Azure"] + D1 --> DS["๐Ÿ“‹ Generate Deployment Summary"] + end + + subgraph "โ˜๏ธ Azure Resources" + AZ1[(Azure Subscription)] + AZ2[Dev Center] + AZ3[Key Vault] + AZ4[Virtual Network] + end + + T1 --> I1 & I2 + I1 & I2 --> V1 + D1 --> AZ1 + AZ1 --> AZ2 & AZ3 & AZ4 + + classDef trigger fill:#2196F3,stroke:#1565C0,color:#fff + classDef input fill:#9C27B0,stroke:#6A1B9A,color:#fff + classDef build fill:#FF9800,stroke:#EF6C00,color:#fff + classDef deploy fill:#4CAF50,stroke:#2E7D32,color:#fff + classDef azure fill:#0078D4,stroke:#005A9E,color:#fff + + class T1 trigger + class I1,I2 input + class V1,C1,AZD,B1,U1,S1 build + class AUTH,D1,DS deploy + class AZ1,AZ2,AZ3,AZ4 azure +``` + +## 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 | + +## 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 | + +## 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 + +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}` + +> ๐Ÿ“– See [Azure OIDC Authentication Documentation](https://learn.microsoft.com/en-us/azure/developer/github/connect-from-azure) + +## 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` | + +## 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 + +## Artifacts + +| Artifact Name | Contents | Retention | +| --------------------------------------- | ----------------------- | --------- | +| `bicep-artifacts-{run_number}` | Compiled ARM templates | 7 days | + +## 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 +``` + +## Troubleshooting + +### 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 + ``` + +## Security Considerations + +- โœ… 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 + +## 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/) diff --git a/docs/devops/release.md b/docs/devops/release.md new file mode 100644 index 00000000..0e8795e9 --- /dev/null +++ b/docs/devops/release.md @@ -0,0 +1,357 @@ +# Branch-Based Release Strategy Workflow + +## 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. + +## Pipeline Visualization + +```mermaid +flowchart TD + subgraph "๐ŸŽฏ Trigger" + T1([Manual Dispatch]) + I1[/"force_release: boolean"/] + T1 --> I1 + end + + subgraph "๐Ÿ“Š generate-release" + direction TB + GR1["๐Ÿ”„ Checkout Repository"] + GR2["๐Ÿท๏ธ Generate Release Information"] + GR3["๐Ÿ“‹ Release Strategy Summary"] + GR4[/"new_version, release_type, should_release"/] + GR1 --> GR2 --> GR3 --> GR4 + end + + subgraph "๐Ÿ”จ build" + direction TB + B1["๐Ÿ”„ Checkout Repository"] + B2["๐Ÿ“ฆ Build Bicep Templates"] + B3["๐Ÿ“Š Build Summary"] + B1 --> B2 --> B3 + end + + subgraph "๐Ÿš€ publish-release" + direction TB + PR1["๐Ÿ”„ Checkout Repository"] + PR2["๐Ÿ“ฅ Download Build Artifacts"] + PR3["๐Ÿ“ Generate Release Notes"] + PR4["๐ŸŽ‰ Create GitHub Release"] + PR5["๐Ÿ“‹ Release Summary"] + PR1 --> PR2 --> PR3 --> PR4 --> PR5 + end + + subgraph "๐Ÿ“Š summary" + direction TB + S1["๐Ÿ“ˆ Workflow Summary"] + end + + I1 --> 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 --> S1 + SKIP1 --> S1 + SKIP2 --> S1 + + classDef trigger fill:#2196F3,stroke:#1565C0,color:#fff + classDef generate fill:#9C27B0,stroke:#6A1B9A,color:#fff + classDef build fill:#FF9800,stroke:#EF6C00,color:#fff + classDef publish fill:#4CAF50,stroke:#2E7D32,color:#fff + classDef summary fill:#607D8B,stroke:#455A64,color:#fff + classDef skip fill:#9E9E9E,stroke:#616161,color:#fff + + class T1,I1 trigger + class GR1,GR2,GR3,GR4 generate + class B1,B2,B3 build + class PR1,PR2,PR3,PR4,PR5 publish + class S1 summary + class SKIP1,SKIP2 skip +``` + +## 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 | + +## 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 | + +## 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 | + +## Versioning Strategy + +### 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 | + +## 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 + +## Artifacts + +| Artifact Name | Contents | Retention | +| -------------------------- | ------------------------------- | --------- | +| `artifacts-{version}` | Compiled ARM templates | 30 days | + +## 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 | + +## 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 + +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 +``` + +## Troubleshooting + +### 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 + ``` + +## Related Documentation + +- [CI Workflow](ci.md) - Continuous integration process +- [Deploy Workflow](deploy.md) - Azure deployment process From babd75d312bf9d9f364070f360de8234b7a57d6d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 11:14:27 -0500 Subject: [PATCH 02/44] Add setup script for Azure Dev Box environment with GitHub/Azure DevOps integration --- docs/scripts/clean-setup.md | 264 +++++++++++++++++++++ docs/scripts/setup.md | 442 ++++++++++++++++++++++++++++++++++++ 2 files changed, 706 insertions(+) create mode 100644 docs/scripts/clean-setup.md create mode 100644 docs/scripts/setup.md diff --git a/docs/scripts/clean-setup.md b/docs/scripts/clean-setup.md new file mode 100644 index 00000000..e0dfd515 --- /dev/null +++ b/docs/scripts/clean-setup.md @@ -0,0 +1,264 @@ +# cleanSetUp.ps1 + +> **Complete DevExp-DevBox infrastructure cleanup orchestrator** + +## 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. + +## Flow Visualization + +```mermaid +flowchart TD + subgraph Entry["Script Entry"] + A([cleanSetUp.ps1 Start]):::entry + B[/"Parse Parameters"/]:::input + end + + subgraph Main["Main Orchestration"] + C["Start-FullCleanup"]:::core + end + + subgraph Deployments["Subscription Deployments"] + D["Remove-SubscriptionDeployments"]:::core + D1{Deployments exist?}:::decision + D2["Delete each deployment"]:::core + D3[\Deployments removed\]:::output + end + + subgraph Users["User Cleanup"] + E["Invoke-CleanupScript"]:::core + E1["deleteUsersAndAssignedRoles.ps1"]:::external + end + + subgraph Credentials["Credentials Cleanup"] + F["Invoke-CleanupScript"]:::core + F1["deleteDeploymentCredentials.ps1"]:::external + end + + subgraph GitHub["GitHub Secret Cleanup"] + G["Invoke-CleanupScript"]:::core + G1["deleteGitHubSecretAzureCredentials.ps1"]:::external + end + + subgraph Resources["Resource Groups"] + H["Invoke-CleanupScript"]:::core + H1["cleanUp.ps1"]:::external + end + + subgraph Exit["Script Exit"] + I{All succeeded?}:::decision + J[\Success\]:::output + K{{Error Handler}}:::error + end + + A --> B --> C + C --> D + D --> D1 + D1 -->|Yes| D2 --> D3 + D1 -->|No| D3 + D3 --> E --> E1 + E1 --> F --> F1 + F1 --> G --> G1 + G1 --> H --> H1 + H1 --> I + I -->|Yes| J + I -->|No| K + + classDef entry fill:#2196F3,stroke:#1565C0,color:#fff + classDef input fill:#9C27B0,stroke:#6A1B9A,color:#fff + classDef core fill:#FF9800,stroke:#EF6C00,color:#fff + classDef external fill:#4CAF50,stroke:#2E7D32,color:#fff + classDef decision fill:#FFC107,stroke:#FFA000,color:#000 + classDef output fill:#2196F3,stroke:#1565C0,color:#fff + classDef error fill:#F44336,stroke:#C62828,color:#fff +``` + +## 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 | + +## 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. + +## 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 + +## 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. + +## 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 + +## 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 +``` + +## 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) | diff --git a/docs/scripts/setup.md b/docs/scripts/setup.md new file mode 100644 index 00000000..2c1c9646 --- /dev/null +++ b/docs/scripts/setup.md @@ -0,0 +1,442 @@ +# setUp.ps1 + +> **Azure Dev Box environment setup with GitHub/Azure DevOps integration** + +## 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. + +## Flow Visualization + +```mermaid +flowchart TD + subgraph Entry["Script Entry"] + A([setUp.ps1 Start]):::entry + B[/"Parse Parameters"/]:::input + C{Help requested?}:::decision + end + + subgraph Validation["Argument Validation"] + D["Test-Arguments"]:::validation + D1{EnvName provided?}:::decision + D2{SourceControl provided?}:::decision + D3["Select-SourceControlPlatform"]:::core + D4["Test-SourceControlValidation"]:::validation + end + + subgraph Tools["Tool Verification"] + E["Test-CommandAvailability"]:::validation + E1[(az)]:::external + E2[(azd)]:::external + E3[(gh)]:::external + end + + subgraph Auth["Authentication"] + F["Test-AzureAuthentication"]:::validation + F1{Platform?}:::decision + F2["Test-GitHubAuthentication"]:::validation + F3["Test-AdoAuthentication"]:::validation + end + + subgraph Token["Token Retrieval"] + G{Platform?}:::decision + G1["Get-SecureGitHubToken"]:::core + G2["Get-SecureAdoGitToken"]:::core + end + + subgraph Init["Environment Init"] + H["Initialize-AzdEnvironment"]:::core + H1["Create .azure directory"]:::core + H2["Write .env file"]:::core + H3["Configure azd"]:::core + end + + subgraph Exit["Script Exit"] + I[\Success\]:::output + J{{Error Handler}}:::error + end + + A --> B --> C + C -->|Yes| HELP[Show-Help] --> EXIT([Exit 0]):::entry + C -->|No| D + D --> D1 + D1 -->|No| J + D1 -->|Yes| D2 + D2 -->|No| D3 + D2 -->|Yes| D4 + D3 --> D4 + D4 --> E + E --> E1 & E2 + E --> F + F --> F1 + F1 -->|github| E3 --> F2 + F1 -->|adogit| F3 + F2 --> G + F3 --> G + G -->|github| G1 + G -->|adogit| G2 + G1 --> H + G2 --> H + H --> H1 --> H2 --> H3 --> I + + classDef entry fill:#2196F3,stroke:#1565C0,color:#fff + classDef input fill:#9C27B0,stroke:#6A1B9A,color:#fff + classDef core fill:#FF9800,stroke:#EF6C00,color:#fff + classDef validation fill:#9C27B0,stroke:#6A1B9A,color:#fff + classDef external fill:#4CAF50,stroke:#2E7D32,color:#fff + classDef decision fill:#FFC107,stroke:#FFA000,color:#000 + classDef output fill:#2196F3,stroke:#1565C0,color:#fff + classDef error fill:#F44336,stroke:#C62828,color:#fff +``` + +## 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 +``` + +## 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. + +## 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) | + +## 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 + +## 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 +``` + +
+ +## 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 +} +``` + +## 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. + +## 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" +``` + +## 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) | From 80bc5d0705d75f6d6a6c7399b5c1f11ae22bcf9e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 11:17:34 -0500 Subject: [PATCH 03/44] Add scripts for managing Azure DevCenter roles and GitHub secrets - Create `createUsersAndAssignRole.ps1` to assign DevCenter roles to the current signed-in user. - Create `deleteDeploymentCredentials.ps1` to remove Azure AD service principal and application registration for CI/CD cleanup. - Create `deleteUsersAndAssignedRoles.ps1` to remove DevCenter role assignments from the current signed-in user. - Create `generateDeploymentCredentials.ps1` to create Azure service principal and GitHub secret for CI/CD pipelines. - Create `createGitHubSecretAzureCredentials.ps1` to create a GitHub repository secret for Azure service principal credentials. - Add `delete-github-secret-azure-credentials.md` for future implementation. --- docs/scripts/azure/create-custom-role.md | 235 ++++++++++++++ .../azure/create-users-and-assign-role.md | 228 +++++++++++++ .../azure/delete-deployment-credentials.md | 204 ++++++++++++ .../azure/delete-users-and-assigned-roles.md | 249 ++++++++++++++ .../azure/generate-deployment-credentials.md | 305 ++++++++++++++++++ .../create-github-secret-azure-credentials.md | 260 +++++++++++++++ .../delete-github-secret-azure-credentials.md | 223 +++++++++++++ 7 files changed, 1704 insertions(+) create mode 100644 docs/scripts/azure/create-custom-role.md create mode 100644 docs/scripts/azure/create-users-and-assign-role.md create mode 100644 docs/scripts/azure/delete-deployment-credentials.md create mode 100644 docs/scripts/azure/delete-users-and-assigned-roles.md create mode 100644 docs/scripts/azure/generate-deployment-credentials.md create mode 100644 docs/scripts/github/create-github-secret-azure-credentials.md create mode 100644 docs/scripts/github/delete-github-secret-azure-credentials.md diff --git a/docs/scripts/azure/create-custom-role.md b/docs/scripts/azure/create-custom-role.md new file mode 100644 index 00000000..113a0702 --- /dev/null +++ b/docs/scripts/azure/create-custom-role.md @@ -0,0 +1,235 @@ +# createCustomRole.ps1 + +> **Creates a custom Azure RBAC role for role assignment management** + +## 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. + +## Flow Visualization + +```mermaid +flowchart TD + subgraph Entry["Script Entry"] + A([createCustomRole.ps1 Start]):::entry + B[/"Parse Parameters"/]:::input + end + + subgraph SubCheck["Subscription Resolution"] + C{SubscriptionId provided?}:::decision + D["Get-CurrentSubscriptionId"]:::core + E[(Azure CLI)]:::external + end + + subgraph RoleCreation["Role Definition Creation"] + F["New-CustomRoleDefinition"]:::core + F1["Build role definition JSON"]:::core + F2["Write to temp file"]:::core + F3{Force flag set?}:::decision + F4["Delete existing role"]:::core + F5[(az role definition create)]:::external + end + + subgraph Cleanup["Cleanup"] + G["Remove temp file"]:::core + end + + subgraph Exit["Script Exit"] + H{Success?}:::decision + I[\Role Created\]:::output + J{{Error Handler}}:::error + end + + A --> B --> C + C -->|No| D --> E + C -->|Yes| F + E --> F + F --> F1 --> F2 --> F3 + F3 -->|Yes| F4 --> F5 + F3 -->|No| F5 + F5 --> G --> H + H -->|Yes| I + H -->|No| J + + classDef entry fill:#2196F3,stroke:#1565C0,color:#fff + classDef input fill:#9C27B0,stroke:#6A1B9A,color:#fff + classDef core fill:#FF9800,stroke:#EF6C00,color:#fff + classDef external fill:#4CAF50,stroke:#2E7D32,color:#fff + classDef decision fill:#FFC107,stroke:#FFA000,color:#000 + classDef output fill:#2196F3,stroke:#1565C0,color:#fff + classDef error fill:#F44336,stroke:#C62828,color:#fff +``` + +## 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 | + +## 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 + +## 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}" + ] +} +``` + +## 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) + +## 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. + +## 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']" +``` + +## 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 + +## 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) | 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..1f5b6e3f --- /dev/null +++ b/docs/scripts/azure/create-users-and-assign-role.md @@ -0,0 +1,228 @@ +# createUsersAndAssignRole.ps1 + +> **Assigns Azure DevCenter roles to the current signed-in user** + +## 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. + +## Flow Visualization + +```mermaid +flowchart TD + subgraph Entry["Script Entry"] + A([createUsersAndAssignRole.ps1 Start]):::entry + B[/"Parse Parameters"/]:::input + end + + subgraph SubCheck["Subscription Resolution"] + C{SubscriptionId provided?}:::decision + D[(az account show)]:::external + end + + subgraph UserLookup["User Identification"] + E["New-UserRoleAssignments"]:::core + F[(az ad signed-in-user show)]:::external + G["Get current user Object ID"]:::core + end + + subgraph RoleLoop["Role Assignment Loop"] + H["For each DevCenter role"]:::core + I["Set-AzureRole"]:::core + I1{Role already assigned?}:::decision + I2["Skip - already assigned"]:::core + I3[(az role assignment create)]:::external + end + + subgraph Exit["Script Exit"] + J{All succeeded?}:::decision + K[\Roles Assigned\]:::output + L{{Error Handler}}:::error + end + + A --> B --> C + C -->|No| D --> E + C -->|Yes| E + E --> F --> G --> H + H --> I --> I1 + I1 -->|Yes| I2 --> H + I1 -->|No| I3 --> H + H -->|All roles processed| J + J -->|Yes| K + J -->|No| L + + classDef entry fill:#2196F3,stroke:#1565C0,color:#fff + classDef input fill:#9C27B0,stroke:#6A1B9A,color:#fff + classDef core fill:#FF9800,stroke:#EF6C00,color:#fff + classDef external fill:#4CAF50,stroke:#2E7D32,color:#fff + classDef decision fill:#FFC107,stroke:#FFA000,color:#000 + classDef output fill:#2196F3,stroke:#1565C0,color:#fff + classDef error fill:#F44336,stroke:#C62828,color:#fff +``` + +## Parameters + +| Parameter | Type | Required | Default | Validation | Description | +|-----------|------|----------|---------|------------|-------------| +| `-SubscriptionId` | `string` | No | Current subscription | `ValidatePattern` (GUID format) | Azure subscription ID for role scope | + +## 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 + +## 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 | + +## 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 + +## 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 +``` + +
+ +## 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 + +## 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 +``` + +## 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 + +## 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) | diff --git a/docs/scripts/azure/delete-deployment-credentials.md b/docs/scripts/azure/delete-deployment-credentials.md new file mode 100644 index 00000000..894485d8 --- /dev/null +++ b/docs/scripts/azure/delete-deployment-credentials.md @@ -0,0 +1,204 @@ +# deleteDeploymentCredentials.ps1 + +> **Removes Azure AD service principal and application registration for CI/CD cleanup** + +## 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. + +## Flow Visualization + +```mermaid +flowchart TD + subgraph Entry["Script Entry"] + A([deleteDeploymentCredentials.ps1 Start]):::entry + B[/"Parse Parameters"/]:::input + end + + subgraph Lookup["Application Lookup"] + C["Remove-AzureDeploymentCredentials"]:::core + D[(az ad app list)]:::external + E{App found?}:::decision + F["Get App ID"]:::core + end + + subgraph Delete["Credential Deletion"] + G[(az ad sp delete)]:::external + H["Delete service principal"]:::core + I[(az ad app delete)]:::external + J["Delete app registration"]:::core + end + + subgraph Exit["Script Exit"] + K{Success?}:::decision + L[\Credentials Deleted\]:::output + M[\Not Found - Skip\]:::output + N{{Error Handler}}:::error + end + + A --> B --> C --> D --> E + E -->|No| M + E -->|Yes| F --> G --> H --> I --> J --> K + K -->|Yes| L + K -->|No| N + + classDef entry fill:#2196F3,stroke:#1565C0,color:#fff + classDef input fill:#9C27B0,stroke:#6A1B9A,color:#fff + classDef core fill:#FF9800,stroke:#EF6C00,color:#fff + classDef external fill:#4CAF50,stroke:#2E7D32,color:#fff + classDef decision fill:#FFC107,stroke:#FFA000,color:#000 + classDef output fill:#2196F3,stroke:#1565C0,color:#fff + classDef error fill:#F44336,stroke:#C62828,color:#fff +``` + +## Parameters + +| Parameter | Type | Required | Default | Validation | Description | +|-----------|------|----------|---------|------------|-------------| +| `-AppDisplayName` | `string` | Yes | - | `ValidateNotNullOrEmpty` | Display name of the application registration to delete | + +## 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 + +## 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. + +## 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. +``` + +
+ +## 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 + +## 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 +``` + +## 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 + +## 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) | 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..aa7648fd --- /dev/null +++ b/docs/scripts/azure/delete-users-and-assigned-roles.md @@ -0,0 +1,249 @@ +# deleteUsersAndAssignedRoles.ps1 + +> **Removes DevCenter role assignments from the current signed-in user** + +## 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. + +## Flow Visualization + +```mermaid +flowchart TD + subgraph Entry["Script Entry"] + A([deleteUsersAndAssignedRoles.ps1 Start]):::entry + B[/"Parse Parameters"/]:::input + end + + subgraph SubCheck["Subscription Resolution"] + C{SubscriptionId provided?}:::decision + D[(az account show)]:::external + end + + subgraph UserLookup["User Identification"] + E["Remove-UserRoleAssignments"]:::core + F[(az ad signed-in-user show)]:::external + G["Get current user Object ID"]:::core + end + + subgraph RoleLoop["Role Removal Loop"] + H["For each DevCenter role"]:::core + I["Remove-UserRoleAssignment"]:::core + I1{Role assigned?}:::decision + I2["Skip - not assigned"]:::core + I3[(az role assignment delete)]:::external + end + + subgraph Exit["Script Exit"] + J{All succeeded?}:::decision + K[\Roles Removed\]:::output + L{{Error Handler}}:::error + end + + A --> B --> C + C -->|No| D --> E + C -->|Yes| E + E --> F --> G --> H + H --> I --> I1 + I1 -->|No| I2 --> H + I1 -->|Yes| I3 --> H + H -->|All roles processed| J + J -->|Yes| K + J -->|No| L + + classDef entry fill:#2196F3,stroke:#1565C0,color:#fff + classDef input fill:#9C27B0,stroke:#6A1B9A,color:#fff + classDef core fill:#FF9800,stroke:#EF6C00,color:#fff + classDef external fill:#4CAF50,stroke:#2E7D32,color:#fff + classDef decision fill:#FFC107,stroke:#FFA000,color:#000 + classDef output fill:#2196F3,stroke:#1565C0,color:#fff + classDef error fill:#F44336,stroke:#C62828,color:#fff +``` + +## 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 | + +## 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 + +## 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 | + +## 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 + +## 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. +``` + +
+ +## 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 + +## 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 +``` + +## 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 + +## 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) | diff --git a/docs/scripts/azure/generate-deployment-credentials.md b/docs/scripts/azure/generate-deployment-credentials.md new file mode 100644 index 00000000..39e3978b --- /dev/null +++ b/docs/scripts/azure/generate-deployment-credentials.md @@ -0,0 +1,305 @@ +# generateDeploymentCredentials.ps1 + +> **Creates Azure service principal and GitHub secret for CI/CD pipelines** + +## 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. + +## Flow Visualization + +```mermaid +flowchart TD + subgraph Entry["Script Entry"] + A([generateDeploymentCredentials.ps1 Start]):::entry + B[/"Parse Parameters"/]:::input + end + + subgraph SPCreation["Service Principal Creation"] + C["New-AzureDeploymentCredentials"]:::core + D[(az ad sp create-for-rbac)]:::external + E["Assign Contributor role"]:::core + F[(az role assignment create)]:::external + G["Assign User Access Administrator"]:::core + H["Assign Managed Identity Contributor"]:::core + end + + subgraph UserRoles["User Role Setup"] + I["Invoke-UserRoleAssignment"]:::core + J["createUsersAndAssignRole.ps1"]:::external + end + + subgraph GitHubSecret["GitHub Secret Creation"] + K["Invoke-GitHubSecretCreation"]:::core + L["createGitHubSecretAzureCredentials.ps1"]:::external + end + + subgraph Exit["Script Exit"] + M{All succeeded?}:::decision + N[\Credentials Created\]:::output + O{{Warning: Partial failure}}:::error + end + + A --> B --> C --> D --> E --> F --> G --> H + H --> I --> J + J --> K --> L --> M + M -->|Yes| N + M -->|No| O + + classDef entry fill:#2196F3,stroke:#1565C0,color:#fff + classDef input fill:#9C27B0,stroke:#6A1B9A,color:#fff + classDef core fill:#FF9800,stroke:#EF6C00,color:#fff + classDef external fill:#4CAF50,stroke:#2E7D32,color:#fff + classDef decision fill:#FFC107,stroke:#FFA000,color:#000 + classDef output fill:#2196F3,stroke:#1565C0,color:#fff + classDef error fill:#F44336,stroke:#C62828,color:#fff +``` + +## 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 +``` + +## 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 | + +## 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 + +## 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 | + +## 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` + +## 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. +``` + +
+ +## 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. + +## 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 + +## 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 +``` + +## 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) | 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..f8d41f04 --- /dev/null +++ b/docs/scripts/github/create-github-secret-azure-credentials.md @@ -0,0 +1,260 @@ +# createGitHubSecretAzureCredentials.ps1 + +> **Creates a GitHub repository secret for Azure service principal credentials** + +## 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. + +## Flow Visualization + +```mermaid +flowchart TD + subgraph Entry["Script Entry"] + A([createGitHubSecretAzureCredentials.ps1 Start]):::entry + B[/"Parse Parameters"/]:::input + end + + subgraph Auth["GitHub Authentication"] + C["Connect-GitHubCli"]:::core + D[(gh auth status)]:::external + E{Authenticated?}:::decision + F[(gh auth login)]:::external + end + + subgraph SecretCreation["Secret Creation"] + G["Set-GitHubRepositorySecret"]:::core + H[(gh secret set)]:::external + end + + subgraph Exit["Script Exit"] + I{Success?}:::decision + J[\Secret Created\]:::output + K{{Error Handler}}:::error + end + + A --> B --> C --> D --> E + E -->|Yes| G + E -->|No| F --> G + G --> H --> I + I -->|Yes| J + I -->|No| K + + classDef entry fill:#2196F3,stroke:#1565C0,color:#fff + classDef input fill:#9C27B0,stroke:#6A1B9A,color:#fff + classDef core fill:#FF9800,stroke:#EF6C00,color:#fff + classDef external fill:#4CAF50,stroke:#2E7D32,color:#fff + classDef decision fill:#FFC107,stroke:#FFA000,color:#000 + classDef output fill:#2196F3,stroke:#1565C0,color:#fff + classDef error fill:#F44336,stroke:#C62828,color:#fff +``` + +## Parameters + +| Parameter | Type | Required | Default | Validation | Description | +|-----------|------|----------|---------|------------|-------------| +| `-GhSecretBody` | `string` | Yes | - | `ValidateNotNullOrEmpty` | JSON body containing Azure credentials | + +**Aliases:** `ghSecretBody` + +## 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 + +## 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`. + +## 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}` + +## 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. +``` + +
+ +## 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 +``` + +## Error Handling + +### Error Action Preference + +```powershell +$ErrorActionPreference = 'Stop' +$WarningPreference = 'Stop' +``` + +### Exit Codes + +| Code | Meaning | +|------|---------| +| `0` | Secret created successfully | +| `1` | Secret creation failed | + +## 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 +``` + +## 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 + +## 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) | 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..930cb954 --- /dev/null +++ b/docs/scripts/github/delete-github-secret-azure-credentials.md @@ -0,0 +1,223 @@ +# deleteGitHubSecretAzureCredentials.ps1 + +> **Removes a GitHub repository secret** + +## 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. + +## Flow Visualization + +```mermaid +flowchart TD + subgraph Entry["Script Entry"] + A([deleteGitHubSecretAzureCredentials.ps1 Start]):::entry + B[/"Parse Parameters"/]:::input + end + + subgraph Auth["GitHub Authentication"] + C["Connect-GitHubCli"]:::core + D[(gh auth status)]:::external + E{Authenticated?}:::decision + F[(gh auth login)]:::external + end + + subgraph SecretDeletion["Secret Deletion"] + G["Remove-GitHubRepositorySecret"]:::core + H[(gh secret remove)]:::external + I{Secret existed?}:::decision + end + + subgraph Exit["Script Exit"] + J[\Secret Removed\]:::output + K[\Secret Not Found - OK\]:::output + L{{Error Handler}}:::error + end + + A --> B --> C --> D --> E + E -->|Yes| G + E -->|No| F --> G + G --> H --> I + I -->|Yes| J + I -->|No| K + + classDef entry fill:#2196F3,stroke:#1565C0,color:#fff + classDef input fill:#9C27B0,stroke:#6A1B9A,color:#fff + classDef core fill:#FF9800,stroke:#EF6C00,color:#fff + classDef external fill:#4CAF50,stroke:#2E7D32,color:#fff + classDef decision fill:#FFC107,stroke:#FFA000,color:#000 + classDef output fill:#2196F3,stroke:#1565C0,color:#fff + classDef error fill:#F44336,stroke:#C62828,color:#fff +``` + +## Parameters + +| Parameter | Type | Required | Default | Validation | Description | +|-----------|------|----------|---------|------------|-------------| +| `-GhSecretName` | `string` | Yes | - | `ValidateNotNullOrEmpty` | Name of the GitHub secret to delete | + +**Aliases:** `ghSecretName` + +## 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 + +## 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}` + +## 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. +``` + +
+ +## 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 + +## 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" +``` + +## 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 + +## 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) | From a364aff21694649106de63d39a338f0c016ddabb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 11:21:29 -0500 Subject: [PATCH 04/44] Add comprehensive documentation for PowerShell scripts in DevExp-DevBox --- docs/scripts/README.md | 271 ++++++++++++++ docs/scripts/configuration/clean-up.md | 291 +++++++++++++++ docs/scripts/configuration/winget-update.md | 380 ++++++++++++++++++++ 3 files changed, 942 insertions(+) create mode 100644 docs/scripts/README.md create mode 100644 docs/scripts/configuration/clean-up.md create mode 100644 docs/scripts/configuration/winget-update.md diff --git a/docs/scripts/README.md b/docs/scripts/README.md new file mode 100644 index 00000000..538ad8bd --- /dev/null +++ b/docs/scripts/README.md @@ -0,0 +1,271 @@ +# DevExp-DevBox PowerShell Scripts Documentation + +> Comprehensive documentation for all PowerShell automation scripts in the DevExp-DevBox project + +## 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. + +## Scripts Architecture + +```mermaid +flowchart TB + subgraph RootScripts["Root Scripts"] + setUp["setUp.ps1\n(Environment Setup)"]:::root + cleanSetUp["cleanSetUp.ps1\n(Full Cleanup)"]:::root + end + + subgraph AzureScripts["Azure Scripts"] + createRole["createCustomRole.ps1"]:::azure + createUsers["createUsersAndAssignRole.ps1"]:::azure + genCreds["generateDeploymentCredentials.ps1"]:::azure + deleteUsers["deleteUsersAndAssignedRoles.ps1"]:::azure + deleteCreds["deleteDeploymentCredentials.ps1"]:::azure + end + + subgraph GitHubScripts["GitHub Scripts"] + createSecret["createGitHubSecret\nAzureCredentials.ps1"]:::github + deleteSecret["deleteGitHubSecret\nAzureCredentials.ps1"]:::github + end + + subgraph UtilityScripts["Utility Scripts"] + cleanUp["cleanUp.ps1\n(Resource Groups)"]:::utility + wingetUpdate["winget-update.ps1\n(Store Apps)"]:::utility + end + + setUp -->|"Initializes"| genCreds + genCreds -->|"Calls"| createUsers + genCreds -->|"Calls"| createSecret + + cleanSetUp -->|"Orchestrates"| deleteUsers + cleanSetUp -->|"Orchestrates"| deleteCreds + cleanSetUp -->|"Orchestrates"| deleteSecret + cleanSetUp -->|"Orchestrates"| cleanUp + + classDef root fill:#2196F3,stroke:#1565C0,color:#fff + classDef azure fill:#FF9800,stroke:#EF6C00,color:#fff + classDef github fill:#4CAF50,stroke:#2E7D32,color:#fff + classDef utility fill:#9C27B0,stroke:#6A1B9A,color:#fff +``` + +## 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) | + +## 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) | + +## 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 | + +## Common Workflows + +### New Environment Setup + +```mermaid +flowchart LR + A[az login] --> B[setUp.ps1] + B --> C[generateDeploymentCredentials.ps1] + C --> D[azd provision] + + style A fill:#4CAF50 + style B fill:#2196F3 + style C fill:#FF9800 + style D fill:#4CAF50 +``` + +```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" +``` + +## 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)] +``` + +## 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 +``` + +## 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 | + +## 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.) diff --git a/docs/scripts/configuration/clean-up.md b/docs/scripts/configuration/clean-up.md new file mode 100644 index 00000000..da0b66be --- /dev/null +++ b/docs/scripts/configuration/clean-up.md @@ -0,0 +1,291 @@ +# cleanUp.ps1 + +> **Removes Azure resource groups for DevExp-DevBox environment** + +## 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. + +## Flow Visualization + +```mermaid +flowchart TD + subgraph Entry["Script Entry"] + A([cleanUp.ps1 Start]):::entry + B[/"Parse Parameters"/]:::input + end + + subgraph Main["Main Orchestration"] + C["Remove-AllResourceGroups"]:::core + D["Build resource group names"]:::core + end + + subgraph RGLoop["Resource Group Deletion Loop"] + E["For each resource group"]:::core + F["Remove-AzureResourceGroup"]:::core + F1[(az group exists)]:::external + F2{RG exists?}:::decision + F3[(az deployment group list)]:::external + F4["Delete deployments"]:::core + F5[(az group delete --no-wait)]:::external + end + + subgraph Exit["Script Exit"] + G{All succeeded?}:::decision + H[\Deletions Initiated\]:::output + I{{Partial Failure}}:::error + end + + A --> B --> C --> D --> E + E --> F --> F1 --> F2 + F2 -->|No| E + F2 -->|Yes| F3 --> F4 --> F5 --> E + E -->|All processed| G + G -->|Yes| H + G -->|No| I + + classDef entry fill:#2196F3,stroke:#1565C0,color:#fff + classDef input fill:#9C27B0,stroke:#6A1B9A,color:#fff + classDef core fill:#FF9800,stroke:#EF6C00,color:#fff + classDef external fill:#4CAF50,stroke:#2E7D32,color:#fff + classDef decision fill:#FFC107,stroke:#FFA000,color:#000 + classDef output fill:#2196F3,stroke:#1565C0,color:#fff + classDef error fill:#F44336,stroke:#C62828,color:#fff +``` + +## 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 | + +## 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 + +## 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 +``` + +## 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` + +## 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. +``` + +
+ +## 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 + +## 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} +``` + +## 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 + +## 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) | diff --git a/docs/scripts/configuration/winget-update.md b/docs/scripts/configuration/winget-update.md new file mode 100644 index 00000000..58dadff1 --- /dev/null +++ b/docs/scripts/configuration/winget-update.md @@ -0,0 +1,380 @@ +# winget-update.ps1 + +> **Silently updates all Microsoft Store applications using Windows Package Manager** + +## 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. + +## Flow Visualization + +```mermaid +flowchart TD + subgraph Entry["Script Entry"] + A([winget-update.ps1 Start]):::entry + B["Configure logging"]:::core + C["Set ExecutionPolicy Bypass"]:::core + end + + subgraph Preflight["Preflight Checks"] + D["Resolve-WinGetExecutable"]:::core + E["Test-WinGetAvailability"]:::validation + F{WinGet available?}:::decision + end + + subgraph Services["Service Preparation"] + G["Start-StoreInstallService"]:::core + H["Initialize-WinGetSources"]:::core + end + + subgraph Updates["Update Passes"] + I["Update-MicrosoftStoreApps"]:::core + I1["Pass 1: Standard upgrade"]:::core + I2["Pass 2: Forced upgrade"]:::core + I3["Pass 3: Safety net pass"]:::core + I4["Summary check"]:::core + end + + subgraph Exit["Script Exit"] + J[\Updates Complete\]:::output + K{{Error Exit}}:::error + end + + A --> B --> C --> D --> E --> F + F -->|No| K + F -->|Yes| G --> H --> I + I --> I1 --> I2 --> I3 --> I4 --> J + + classDef entry fill:#2196F3,stroke:#1565C0,color:#fff + classDef core fill:#FF9800,stroke:#EF6C00,color:#fff + classDef validation fill:#9C27B0,stroke:#6A1B9A,color:#fff + classDef external fill:#4CAF50,stroke:#2E7D32,color:#fff + classDef decision fill:#FFC107,stroke:#FFA000,color:#000 + classDef output fill:#2196F3,stroke:#1565C0,color:#fff + classDef error fill:#F44336,stroke:#C62828,color:#fff +``` + +## Update Process Flow + +```mermaid +sequenceDiagram + 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 +``` + +## Parameters + +This script has no parameters. All configuration is handled internally. + +## 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 + +## 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]` + +## 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` + +## 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 +``` + +
+ +## 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 + +## 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 +``` + +## 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 | + +## 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). + +## 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 | From b0479abf2368151d1203e3fa72ed1e2bc6070e5f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 11:25:17 -0500 Subject: [PATCH 05/44] Add initial documentation for Business Architecture of DevExp-DevBox --- docs/architecture/01-business-architecture.md | 429 ++++++++++++++++++ 1 file changed, 429 insertions(+) create mode 100644 docs/architecture/01-business-architecture.md diff --git a/docs/architecture/01-business-architecture.md b/docs/architecture/01-business-architecture.md new file mode 100644 index 00000000..bc9bb760 --- /dev/null +++ b/docs/architecture/01-business-architecture.md @@ -0,0 +1,429 @@ +# Business Architecture + +> **DevExp-DevBox Landing Zone Accelerator** + +| 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) + +--- + +## Business Context + +### Problem Statement + +Modern software development organizations face significant challenges in providing consistent, secure, and rapidly deployable development environments: + +```mermaid +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 + +--- + +## Stakeholder Analysis + +### Stakeholder Map + +```mermaid +flowchart TB + subgraph Executive["Executive Stakeholders"] + CTO["CTO/VP Engineering"] + CISO["CISO/Security Director"] + CFO["CFO/Finance Director"] + end + + subgraph Technical["Technical Stakeholders"] + PE["Platform Engineers"] + SA["Solution Architects"] + SEC["Security Engineers"] + OPS["Operations Team"] + end + + subgraph Users["End Users"] + DEV["Developers"] + LEAD["Tech Leads"] + PM["Project Managers"] + end + + subgraph External["External"] + MS["Microsoft Support"] + AUD["Auditors"] + end + + CTO --> PE + CISO --> SEC + CFO --> OPS + + PE --> DEV + SA --> LEAD + SEC --> DEV + + AUD -.-> SEC + MS -.-> PE + + style Executive fill:#2196F3,color:#fff + style Technical fill:#FF9800,color:#fff + style Users fill:#4CAF50,color:#fff + style External fill:#9C27B0,color:#fff +``` + +### 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 | + +--- + +## Business Capabilities + +### Capability Model + +```mermaid +flowchart TB + subgraph L1["Developer Platform Capabilities"] + subgraph L2A["Environment Management"] + C1["Dev Box Provisioning"] + C2["Environment Configuration"] + C3["Image Management"] + C4["Pool Management"] + end + + subgraph L2B["Security & Governance"] + C5["Identity Management"] + C6["Access Control"] + C7["Secrets Management"] + C8["Compliance Enforcement"] + end + + subgraph L2C["Operations & Monitoring"] + C9["Resource Monitoring"] + C10["Cost Management"] + C11["Diagnostics & Logging"] + C12["Alerting"] + end + + subgraph L2D["Network & Connectivity"] + C13["Network Provisioning"] + C14["Network Security"] + C15["Hybrid Connectivity"] + end + end + + style L2A fill:#FF9800,color:#fff + style L2B fill:#F44336,color:#fff + style L2C fill:#4CAF50,color:#fff + style L2D fill:#2196F3,color:#fff +``` + +### 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 | + +--- + +## Value Streams + +### Primary Value Stream: Developer Onboarding + +```mermaid +flowchart LR + subgraph Trigger["Trigger"] + T1["New Developer Joins"] + end + + subgraph Request["Request Phase"] + R1["Request Dev Box Access"] + R2["Assign to Project"] + R3["Select Dev Box Pool"] + end + + subgraph Provision["Provisioning Phase"] + P1["Create Dev Box Instance"] + P2["Apply DSC Configuration"] + P3["Clone Repositories"] + end + + subgraph Validate["Validation Phase"] + V1["Verify Tools Installed"] + V2["Test Connectivity"] + V3["Confirm Access"] + end + + subgraph Outcome["Outcome"] + O1["Developer Productive"] + end + + T1 --> R1 --> R2 --> R3 + R3 --> P1 --> P2 --> P3 + P3 --> V1 --> V2 --> V3 + V3 --> O1 + + style Trigger fill:#9C27B0,color:#fff + style Request fill:#2196F3,color:#fff + style Provision fill:#FF9800,color:#fff + style Validate fill:#4CAF50,color:#fff + style Outcome fill:#4CAF50,color:#fff +``` + +### 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 +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 --> [*] +``` + +--- + +## 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 | + +--- + +## Success Metrics + +### Key Performance Indicators (KPIs) + +```mermaid +flowchart TB + subgraph Developer["Developer Productivity"] + KPI1["Time to First Commit"] + KPI2["Environment Setup Time"] + KPI3["Self-Service Success Rate"] + end + + subgraph Operations["Operational Efficiency"] + KPI4["Deployment Success Rate"] + KPI5["Mean Time to Provision"] + KPI6["Configuration Drift %"] + end + + subgraph Security["Security Posture"] + KPI7["Compliance Score"] + KPI8["Secret Rotation Rate"] + KPI9["Access Review Completion"] + end + + subgraph Cost["Cost Management"] + KPI10["Cost per Developer"] + KPI11["Resource Utilization"] + KPI12["Budget Variance"] + end + + style Developer fill:#4CAF50,color:#fff + style Operations fill:#FF9800,color:#fff + style Security fill:#F44336,color:#fff + style Cost fill:#2196F3,color:#fff +``` + +### 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 | + +--- + +## 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 | + +--- + +## 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) From cff91d80cb4a919763d55ccba2d23a41660230d4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 11:28:37 -0500 Subject: [PATCH 06/44] Add comprehensive documentation for Data Architecture in DevExp-DevBox --- docs/architecture/02-data-architecture.md | 695 ++++++++++++++++ .../03-application-architecture.md | 741 ++++++++++++++++++ 2 files changed, 1436 insertions(+) create mode 100644 docs/architecture/02-data-architecture.md create mode 100644 docs/architecture/03-application-architecture.md diff --git a/docs/architecture/02-data-architecture.md b/docs/architecture/02-data-architecture.md new file mode 100644 index 00000000..9d66da2c --- /dev/null +++ b/docs/architecture/02-data-architecture.md @@ -0,0 +1,695 @@ +# Data Architecture + +> **DevExp-DevBox Landing Zone Accelerator** + +| 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 +flowchart TB + subgraph DataCategories["Data Categories"] + subgraph Config["Configuration Data"] + C1["Resource Organization"] + C2["Security Settings"] + C3["Workload Definitions"] + end + + subgraph Secrets["Secrets & Credentials"] + S1["GitHub PAT Tokens"] + S2["Azure DevOps PATs"] + S3["Service Principal Credentials"] + end + + subgraph Telemetry["Telemetry & Diagnostics"] + T1["Resource Logs"] + T2["Metrics"] + T3["Activity Logs"] + end + + subgraph State["Deployment State"] + ST1["azd Environment"] + ST2["Bicep Outputs"] + ST3["Resource IDs"] + end + end + + style Config fill:#2196F3,color:#fff + style Secrets fill:#F44336,color:#fff + style Telemetry fill:#4CAF50,color:#fff + style State fill:#FF9800,color:#fff +``` + +### 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 | + +--- + +## 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 +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" +``` + +--- + +## Secrets Management + +### Secret Types and Lifecycle + +```mermaid +flowchart TB + subgraph Sources["Secret Sources"] + GH["GitHub CLI\n(gh auth token)"] + ADO["Azure DevOps CLI\nManual Entry"] + SP["Service Principal\n(az ad sp create-for-rbac)"] + end + + subgraph Storage["Secret Storage"] + KV["Azure Key Vault\n(gha-token secret)"] + GHS["GitHub Secrets\n(AZURE_CREDENTIALS)"] + ENV["azd Environment\n(.azure/.env)"] + end + + subgraph Consumers["Secret Consumers"] + CAT["DevCenter Catalogs\n(Private Repos)"] + WF["GitHub Actions\n(OIDC Auth)"] + DEP["azd Provision\n(Key Vault)"] + end + + GH --> ENV --> KV + ADO --> ENV --> KV + SP --> GHS + + KV --> CAT + GHS --> WF + KV --> DEP + + style Sources fill:#FF9800,color:#fff + style Storage fill:#F44336,color:#fff + style Consumers fill:#4CAF50,color:#fff +``` + +### 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 +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 +``` + +--- + +## Telemetry & Diagnostics + +### Log Analytics Data Collection + +All resources send diagnostic data to a centralized Log Analytics workspace for unified monitoring and analysis. + +```mermaid +flowchart LR + subgraph Resources["Azure Resources"] + DC["DevCenter"] + KV["Key Vault"] + VN["Virtual Network"] + LA["Log Analytics"] + end + + subgraph LAW["Log Analytics Workspace"] + LOGS["Diagnostic Logs"] + MET["Metrics"] + ACT["Activity Logs"] + end + + subgraph Solutions["Solutions"] + AA["AzureActivity"] + end + + DC -->|DiagnosticSettings| LOGS + KV -->|DiagnosticSettings| LOGS + VN -->|DiagnosticSettings| LOGS + LA -->|DiagnosticSettings| LOGS + + DC -->|AllMetrics| MET + KV -->|AllMetrics| MET + VN -->|AllMetrics| MET + + LOGS --> AA + ACT --> AA + + style Resources fill:#2196F3,color:#fff + style LAW fill:#4CAF50,color:#fff + style Solutions fill:#FF9800,color:#fff +``` + +### 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) | + +--- + +## Data Flow Diagrams + +### Configuration Loading Flow + +```mermaid +flowchart TB + subgraph Source["Git Repository"] + Y1["azureResources.yaml"] + Y2["security.yaml"] + Y3["devcenter.yaml"] + end + + subgraph Bicep["Bicep Compilation"] + LOAD["loadYamlContent()"] + MAIN["main.bicep"] + SEC["security.bicep"] + WL["workload.bicep"] + end + + subgraph Deploy["Deployment"] + ARM["ARM Template"] + AZ["Azure Resource Manager"] + end + + subgraph Resources["Azure Resources"] + RG["Resource Groups"] + KVRES["Key Vault"] + DCRES["DevCenter"] + end + + Y1 --> LOAD + Y2 --> LOAD + Y3 --> LOAD + + LOAD --> MAIN + MAIN --> SEC + MAIN --> WL + + SEC --> ARM + WL --> ARM + + ARM --> AZ + AZ --> RG + AZ --> KVRES + AZ --> DCRES + + style Source fill:#9C27B0,color:#fff + style Bicep fill:#FF9800,color:#fff + style Deploy fill:#2196F3,color:#fff + style Resources fill:#4CAF50,color:#fff +``` + +### Secrets Flow Diagram + +```mermaid +flowchart TB + subgraph Setup["Setup Phase"] + CLI["gh auth token\nOR\nManual PAT Entry"] + PS["setUp.ps1 / setUp.sh"] + end + + subgraph AZD["azd Environment"] + ENV[".azure/{env}/.env\nKEY_VAULT_SECRET='...'"] + end + + subgraph Deploy["Deployment"] + PARAMS["main.parameters.json\n${KEY_VAULT_SECRET}"] + BICEP["security.bicep"] + end + + subgraph Azure["Azure Resources"] + KV["Key Vault\ngha-token secret"] + DC["DevCenter\nsecretIdentifier reference"] + end + + subgraph Access["Runtime Access"] + CAT["Private Catalog\n(GitHub/ADO)"] + end + + CLI --> PS --> ENV + ENV --> PARAMS --> BICEP + BICEP --> KV + KV --> DC + DC --> CAT + + style Setup fill:#FF9800,color:#fff + style AZD fill:#9C27B0,color:#fff + style Deploy fill:#2196F3,color:#fff + style Azure fill:#4CAF50,color:#fff + style Access fill:#F44336,color:#fff +``` + +--- + +## 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 | + +--- + +## 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 +``` + +--- + +## 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 | + +--- + +## 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) diff --git a/docs/architecture/03-application-architecture.md b/docs/architecture/03-application-architecture.md new file mode 100644 index 00000000..3cf0f892 --- /dev/null +++ b/docs/architecture/03-application-architecture.md @@ -0,0 +1,741 @@ +# Application Architecture + +> **DevExp-DevBox Landing Zone Accelerator** + +| 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 +flowchart TB + subgraph Orchestration["Orchestration Layer"] + MAIN["main.bicep\n(Subscription Scope)"] + end + + subgraph LandingZones["Landing Zone Modules"] + SEC["security.bicep"] + MON["logAnalytics.bicep"] + WL["workload.bicep"] + CONN["connectivity.bicep"] + end + + subgraph CoreResources["Core Resource Modules"] + KV["keyVault.bicep"] + LA["logAnalytics.bicep"] + DC["devCenter.bicep"] + VN["vnet.bicep"] + end + + subgraph ProjectResources["Project Modules"] + PROJ["project.bicep"] + POOL["projectPool.bicep"] + PCAT["projectCatalog.bicep"] + PENV["projectEnvironmentType.bicep"] + end + + subgraph Identity["Identity Modules"] + DCRA["devCenterRoleAssignment.bicep"] + ORA["orgRoleAssignment.bicep"] + PIRA["projectIdentityRoleAssignment.bicep"] + KVA["keyVaultAccess.bicep"] + end + + MAIN --> SEC + MAIN --> MON + MAIN --> WL + + SEC --> KV + MON --> LA + WL --> DC + WL --> CONN + + CONN --> VN + DC --> PROJ + PROJ --> POOL + PROJ --> PCAT + PROJ --> PENV + + DC --> DCRA + DC --> ORA + PROJ --> PIRA + SEC --> KVA + + style Orchestration fill:#E91E63,color:#fff + style LandingZones fill:#9C27B0,color:#fff + style CoreResources fill:#2196F3,color:#fff + style ProjectResources fill:#4CAF50,color:#fff + style Identity fill:#FF9800,color:#fff +``` + +### 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 | + +--- + +## 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 +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 +``` + +--- + +## Module Dependency Graph + +### Complete Dependency Tree + +```mermaid +flowchart TB + subgraph L0["Layer 0: Orchestration"] + MAIN["main.bicep\n(targetScope: subscription)"] + end + + subgraph L1["Layer 1: Resource Groups"] + RG_SEC["Resource Group\n(Security)"] + RG_MON["Resource Group\n(Monitoring)"] + RG_WL["Resource Group\n(Workload)"] + end + + subgraph L2["Layer 2: Landing Zone Modules"] + SEC["security.bicep"] + LA["logAnalytics.bicep"] + WL["workload.bicep"] + end + + subgraph L3["Layer 3: Core Resources"] + KV["keyVault.bicep"] + LOG["Log Analytics\nWorkspace"] + DC["devCenter.bicep"] + CONN["connectivity.bicep"] + end + + subgraph L4["Layer 4: Child Resources"] + SECRET["secret.bicep"] + CAT["catalog.bicep"] + ENV["environmentType.bicep"] + VN["vnet.bicep"] + NC["networkConnection.bicep"] + end + + subgraph L5["Layer 5: Project Resources"] + PROJ["project.bicep"] + end + + subgraph L6["Layer 6: Project Child Resources"] + POOL["projectPool.bicep"] + PCAT["projectCatalog.bicep"] + PENV["projectEnvironmentType.bicep"] + end + + subgraph L7["Layer 7: Identity"] + DCRA["devCenterRoleAssignment"] + ORA["orgRoleAssignment"] + PIRA["projectIdentityRoleAssignment"] + KVA["keyVaultAccess"] + end + + MAIN --> RG_SEC + MAIN --> RG_MON + MAIN --> RG_WL + + RG_SEC --> SEC + RG_MON --> LA + RG_WL --> WL + + SEC --> KV + LA --> LOG + WL --> DC + WL --> CONN + + KV --> SECRET + KV --> KVA + DC --> CAT + DC --> ENV + DC --> DCRA + DC --> ORA + CONN --> VN + CONN --> NC + + DC --> PROJ + PROJ --> POOL + PROJ --> PCAT + PROJ --> PENV + PROJ --> PIRA + + LOG -.->|logAnalyticsId| KV + LOG -.->|logAnalyticsId| DC + LOG -.->|logAnalyticsId| VN + KV -.->|secretIdentifier| CAT + + style L0 fill:#E91E63,color:#fff + style L1 fill:#9C27B0,color:#fff + style L2 fill:#673AB7,color:#fff + style L3 fill:#3F51B5,color:#fff + style L4 fill:#2196F3,color:#fff + style L5 fill:#4CAF50,color:#fff + style L6 fill:#8BC34A,color:#fff + style L7 fill:#FF9800,color:#fff +``` + +### 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 | + +--- + +## 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 +``` + +--- + +## Deployment Orchestration + +### Deployment Sequence Diagram + +```mermaid +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 +flowchart LR + subgraph Phase1["Phase 1: Foundation"] + RG["Resource Groups"] + LA["Log Analytics"] + end + + subgraph Phase2["Phase 2: Security"] + KV["Key Vault"] + SEC["Secrets"] + end + + subgraph Phase3["Phase 3: Network"] + VN["Virtual Network"] + NC["Network Connection"] + end + + subgraph Phase4["Phase 4: Workload"] + DC["DevCenter"] + CAT["Catalogs"] + ENV["Environment Types"] + end + + subgraph Phase5["Phase 5: Projects"] + PROJ["Projects"] + POOL["Pools"] + PCAT["Project Catalogs"] + end + + subgraph Phase6["Phase 6: Identity"] + RBAC["RBAC Assignments"] + end + + Phase1 --> Phase2 + Phase1 --> Phase3 + Phase2 --> Phase4 + Phase3 --> Phase4 + Phase4 --> Phase5 + Phase5 --> Phase6 + + style Phase1 fill:#E91E63,color:#fff + style Phase2 fill:#9C27B0,color:#fff + style Phase3 fill:#3F51B5,color:#fff + style Phase4 fill:#2196F3,color:#fff + style Phase5 fill:#4CAF50,color:#fff + style Phase6 fill:#FF9800,color:#fff +``` + +--- + +## 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 +flowchart TB + subgraph Input["Input Configuration"] + PC["project config object"] + NCI["networkConnectionId"] + SID["secretIdentifier"] + end + + subgraph Project["Project Resource"] + PR["Microsoft.DevCenter/devcenters/projects"] + end + + subgraph Children["Child Resources"] + PO["Pools\n(projectPool.bicep)"] + CA["Catalogs\n(projectCatalog.bicep)"] + ET["Environment Types\n(projectEnvironmentType.bicep)"] + end + + subgraph Identity["Identity"] + MI["SystemAssigned Identity"] + RA["Role Assignments"] + end + + Input --> Project + Project --> Children + Project --> MI + MI --> RA + + style Input fill:#FF9800,color:#fff + style Project fill:#2196F3,color:#fff + style Children fill:#4CAF50,color:#fff + style Identity fill:#9C27B0,color:#fff +``` + +--- + +## Integration Patterns + +### Configuration Integration Pattern + +The accelerator uses the **Configuration as Data** pattern where all deployment parameters are externalized to YAML files. + +```mermaid +flowchart LR + subgraph Config["Configuration Layer"] + YAML["YAML Files\n(infra/settings/)"] + SCHEMA["JSON Schemas\n(validation)"] + end + + subgraph Bicep["Bicep Layer"] + LOAD["loadYamlContent()"] + PARAM["Parameters"] + MOD["Modules"] + end + + subgraph ARM["ARM Layer"] + TEMPLATE["ARM Template"] + DEPLOY["Deployment"] + end + + SCHEMA -->|validates| YAML + YAML --> LOAD + LOAD --> PARAM + PARAM --> MOD + MOD --> TEMPLATE + TEMPLATE --> DEPLOY + + style Config fill:#FF9800,color:#fff + style Bicep fill:#2196F3,color:#fff + style ARM fill:#4CAF50,color:#fff +``` + +### Hierarchical Module Pattern + +Modules follow a parent-child pattern where parent modules orchestrate child resources: + +```mermaid +flowchart TB + 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 + + subgraph Example["Example: devCenter.bicep"] + DC["devCenter.bicep"] + CAT["catalog.bicep\n(for each catalog)"] + ENV["environmentType.bicep\n(for each type)"] + PROJ["project.bicep\n(for each project)"] + end + + DC -->|"module catalogs"| CAT + DC -->|"module envTypes"| ENV + DC -->|"module projects"| PROJ +``` + +### 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 + } +} +``` + +--- + +## 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 +``` + +--- + +## 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) From c4ad47286f7fd1c43a98cf72729a43c8f6db8abb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 11:28:48 -0500 Subject: [PATCH 07/44] Add missing line breaks in Application Architecture documentation for improved readability --- docs/architecture/03-application-architecture.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/architecture/03-application-architecture.md b/docs/architecture/03-application-architecture.md index 3cf0f892..d0fc6b93 100644 --- a/docs/architecture/03-application-architecture.md +++ b/docs/architecture/03-application-architecture.md @@ -472,6 +472,7 @@ flowchart LR **Scope:** `targetScope = 'subscription'` **Responsibilities:** + - Load YAML configuration files - Create landing zone resource groups - Orchestrate module deployments with dependencies @@ -510,6 +511,7 @@ module security 'src/security/security.bicep' = if (securityConfig.create) { **Scope:** Resource Group **Resources Created:** + - Microsoft.DevCenter/devcenters - Diagnostic Settings - Catalogs (via child module) @@ -517,6 +519,7 @@ module security 'src/security/security.bicep' = if (securityConfig.create) { - Role Assignments (via child module) **Key Features:** + - SystemAssigned managed identity - Microsoft-hosted network support - Azure Monitor agent installation @@ -548,6 +551,7 @@ resource devCenter 'Microsoft.DevCenter/devcenters@2024-08-01-preview' = { **Scope:** DevCenter **Resources Created:** + - Microsoft.DevCenter/devcenters/projects - Project Pools (via child module) - Project Catalogs (via child module) From 3d99786e6becb5176bdc8be4e9ee5eedbb7ea88f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 11:31:10 -0500 Subject: [PATCH 08/44] Add comprehensive Technology Architecture documentation for DevExp-DevBox --- .../04-technology-architecture.md | 671 ++++++++++++++++++ 1 file changed, 671 insertions(+) create mode 100644 docs/architecture/04-technology-architecture.md diff --git a/docs/architecture/04-technology-architecture.md b/docs/architecture/04-technology-architecture.md new file mode 100644 index 00000000..bc08ff00 --- /dev/null +++ b/docs/architecture/04-technology-architecture.md @@ -0,0 +1,671 @@ +# Technology Architecture + +> **DevExp-DevBox Landing Zone Accelerator** + +| 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 +flowchart TB + subgraph Developer["Developer Tooling"] + VSC["VS Code"] + GH["GitHub"] + AZD["Azure Developer CLI"] + end + + subgraph IaC["Infrastructure as Code"] + BICEP["Azure Bicep"] + YAML["YAML Configuration"] + PS["PowerShell/Bash"] + end + + subgraph CI/CD["CI/CD Platform"] + GHA["GitHub Actions"] + OIDC["OIDC Federation"] + end + + 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 + + Developer --> IaC + IaC --> CI/CD + CI/CD --> Azure + + style Developer fill:#2196F3,color:#fff + style IaC fill:#FF9800,color:#fff + style CI/CD fill:#9C27B0,color:#fff + style Azure fill:#4CAF50,color:#fff +``` + +### 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 | + +--- + +## 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 +flowchart TB + subgraph Management["Management Plane"] + ARM["Azure Resource Manager"] + SUB["Subscription"] + end + + subgraph ResourceGroups["Resource Groups"] + RG_SEC["rg-security"] + RG_MON["rg-monitoring"] + RG_WL["rg-workload"] + end + + subgraph SecurityZone["Security Landing Zone"] + KV["Key Vault"] + SEC["Secrets"] + end + + subgraph MonitoringZone["Monitoring Landing Zone"] + LA["Log Analytics\nWorkspace"] + SOL["Solutions"] + end + + subgraph WorkloadZone["Workload Landing Zone"] + DC["DevCenter"] + PROJ["Projects"] + POOL["Pools"] + CAT["Catalogs"] + end + + subgraph NetworkZone["Network"] + VNET["Virtual Network"] + SUBNET["Subnets"] + NC["Network Connection"] + end + + ARM --> SUB + SUB --> ResourceGroups + + RG_SEC --> SecurityZone + RG_MON --> MonitoringZone + RG_WL --> WorkloadZone + RG_WL --> NetworkZone + + KV -.->|secretIdentifier| CAT + LA -.->|diagnostics| KV + LA -.->|diagnostics| DC + LA -.->|diagnostics| VNET + + NC --> VNET + DC --> PROJ + PROJ --> POOL + + style Management fill:#E91E63,color:#fff + style ResourceGroups fill:#9C27B0,color:#fff + style SecurityZone fill:#F44336,color:#fff + style MonitoringZone fill:#4CAF50,color:#fff + style WorkloadZone fill:#2196F3,color:#fff + style NetworkZone fill:#FF9800,color:#fff +``` + +### 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 | + +--- + +## Landing Zone Design + +### Azure Landing Zone Alignment + +The accelerator implements a simplified Azure Landing Zone pattern with three primary zones plus networking. + +```mermaid +flowchart TB + subgraph Subscription["Azure Subscription"] + subgraph Security["Security Landing Zone"] + direction TB + RG_S["Resource Group:\ndevexp-security-{env}"] + KV_R["Key Vault"] + SEC_R["Secrets"] + end + + subgraph Monitoring["Monitoring Landing Zone"] + direction TB + RG_M["Resource Group:\ndevexp-monitoring-{env}"] + LA_R["Log Analytics"] + SOL_R["Solutions"] + end + + subgraph Workload["Workload Landing Zone"] + direction TB + RG_W["Resource Group:\ndevexp-workload-{env}"] + DC_R["DevCenter"] + PROJ_R["Projects"] + POOL_R["Pools"] + end + + subgraph Network["Connectivity"] + direction TB + VNET_R["Virtual Network"] + NC_R["Network Connection"] + end + end + + Security --> Monitoring + Monitoring --> Workload + Network --> Workload + + style Security fill:#F44336,color:#fff + style Monitoring fill:#4CAF50,color:#fff + style Workload fill:#2196F3,color:#fff + style Network fill:#FF9800,color:#fff +``` + +### 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` | + +--- + +## Network Architecture + +### Network Topology + +```mermaid +flowchart TB + subgraph Internet["Internet"] + DEV["Developer\n(Remote)"] + GH["GitHub.com"] + ADO["Azure DevOps"] + end + + 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\n(Managed/Unmanaged)"] + DC["DevCenter"] + end + + subgraph MSHosted["Microsoft-Hosted Network"] + MHN["Microsoft Managed\nNetwork"] + end + + DEV -->|"RDP/HTTPS"| DB1 + DEV -->|"RDP/HTTPS"| DB2 + + DB1 -->|"HTTPS"| GH + DB1 -->|"HTTPS"| ADO + + DC -->|"networkConnectionId"| NC + NC -->|"subnetId"| Subnet + + DC -.->|"Alternative"| MHN + + style Internet fill:#E91E63,color:#fff + style VNet fill:#2196F3,color:#fff + style MSHosted fill:#9C27B0,color:#fff +``` + +### 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 | + +--- + +## Compute Architecture + +### Dev Box Architecture + +```mermaid +flowchart TB + subgraph DevCenter["Azure DevCenter"] + DC["DevCenter Resource"] + + subgraph Images["Image Definitions"] + IMG1["eShop-backend-engineer"] + IMG2["eShop-frontend-engineer"] + end + + subgraph Projects["Projects"] + PROJ["eShop Project"] + end + + subgraph Pools["Dev Box Pools"] + P1["backend-engineer\ngeneral_i_32c128gb512ssd_v2"] + P2["frontend-engineer\ngeneral_i_16c64gb256ssd_v2"] + end + end + + subgraph Runtime["Runtime Environment"] + DB1["Dev Box Instance\n(Windows 11)"] + DB2["Dev Box Instance\n(Windows 11)"] + end + + DC --> Images + DC --> Projects + Projects --> Pools + P1 --> DB1 + P2 --> DB2 + + IMG1 -->|imageDefinition| P1 + IMG2 -->|imageDefinition| P2 + + style DevCenter fill:#2196F3,color:#fff + style Runtime fill:#4CAF50,color:#fff +``` + +### 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 +flowchart LR + subgraph Catalog["DevCenter Catalog"] + GIT["Git Repository"] + IMG_DEF["Image Definitions\n(YAML/JSON)"] + DSC["DSC Configurations\n(Optional)"] + end + + subgraph DevCenter["DevCenter"] + CAT["Catalog Sync"] + IMG["Image Gallery"] + end + + subgraph Pool["Dev Box Pool"] + VM["Dev Box VMs"] + end + + GIT --> CAT + CAT --> IMG_DEF + IMG_DEF --> IMG + IMG --> VM + DSC --> IMG + + style Catalog fill:#FF9800,color:#fff + style DevCenter fill:#2196F3,color:#fff + style Pool fill:#4CAF50,color:#fff +``` + +--- + +## CI/CD Infrastructure + +### GitHub Actions Architecture + +```mermaid +flowchart TB + subgraph GitHub["GitHub"] + REPO["Repository"] + + subgraph Actions["GitHub Actions"] + WF_BUILD["build.yml"] + WF_DEPLOY["deploy.yml"] + WF_RELEASE["release.yml"] + end + + subgraph Secrets["GitHub Configuration"] + VARS["Variables:\n- AZURE_CLIENT_ID\n- AZURE_TENANT_ID\n- AZURE_SUBSCRIPTION_ID"] + SECS["Secrets:\n- AZURE_CREDENTIALS"] + end + end + + subgraph Azure["Azure"] + OIDC["OIDC Provider\n(Microsoft Entra ID)"] + ARM["Azure Resource Manager"] + SUB["Subscription"] + end + + REPO --> Actions + Actions --> OIDC + OIDC -->|"Token Exchange"| ARM + ARM --> SUB + + VARS --> Actions + SECS --> Actions + + style GitHub fill:#9C27B0,color:#fff + style Azure fill:#2196F3,color:#fff +``` + +### Workflow Pipeline Structure + +```mermaid +flowchart LR + subgraph Build["build.yml"] + B1["Checkout"] + B2["Setup azd"] + B3["Login (OIDC)"] + B4["azd provision"] + end + + subgraph Deploy["deploy.yml"] + D1["Checkout"] + D2["Setup azd"] + D3["Login (OIDC)"] + D4["Download Artifacts"] + D5["azd deploy"] + end + + subgraph Release["release.yml"] + R1["Get Version"] + R2["Create Tag"] + R3["Create Release"] + R4["Generate Notes"] + end + + Build -->|"artifacts"| Deploy + Deploy -->|"on success"| Release + + style Build fill:#FF9800,color:#fff + style Deploy fill:#4CAF50,color:#fff + style Release fill:#2196F3,color:#fff +``` + +### 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 }} +``` + +--- + +## Monitoring Infrastructure + +### Log Analytics Architecture + +```mermaid +flowchart TB + subgraph Sources["Telemetry Sources"] + DC["DevCenter\nLogs & Metrics"] + KV["Key Vault\nLogs & Metrics"] + VN["Virtual Network\nLogs & Metrics"] + DB["Dev Box\nAgent Metrics"] + end + + subgraph Collection["Collection Layer"] + DS["Diagnostic Settings"] + AMA["Azure Monitor Agent"] + end + + subgraph LAW["Log Analytics Workspace"] + subgraph Tables["Tables"] + DIAG["AzureDiagnostics"] + MET["AzureMetrics"] + ACT["AzureActivity"] + end + + subgraph Solutions["Solutions"] + AA["AzureActivity Solution"] + end + end + + subgraph Consumers["Consumers"] + DASH["Dashboards"] + ALERT["Alerts"] + WB["Workbooks"] + end + + DC --> DS + KV --> DS + VN --> DS + DB --> AMA + + DS --> Tables + AMA --> Tables + + Tables --> Solutions + Tables --> Consumers + + style Sources fill:#FF9800,color:#fff + style Collection fill:#9C27B0,color:#fff + style LAW fill:#2196F3,color:#fff + style Consumers fill:#4CAF50,color:#fff +``` + +### 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) | + +--- + +## 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 | + +--- + +## 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 | + +--- + +## 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) From f2f1678dfb0508f6c321fcd701f8e509a3325057 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 11:32:35 -0500 Subject: [PATCH 09/44] Add comprehensive Security Architecture documentation for DevExp-DevBox --- docs/architecture/05-security-architecture.md | 696 ++++++++++++++++++ 1 file changed, 696 insertions(+) create mode 100644 docs/architecture/05-security-architecture.md diff --git a/docs/architecture/05-security-architecture.md b/docs/architecture/05-security-architecture.md new file mode 100644 index 00000000..625c1ac6 --- /dev/null +++ b/docs/architecture/05-security-architecture.md @@ -0,0 +1,696 @@ +# Security Architecture + +> **DevExp-DevBox Landing Zone Accelerator** + +| 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 +flowchart TB + subgraph External["External Boundary"] + DEV["Developers"] + GH["GitHub"] + ADO["Azure DevOps"] + end + + subgraph Identity["Identity Layer"] + AAD["Microsoft Entra ID"] + MI["Managed Identities"] + OIDC["OIDC Federation"] + end + + subgraph Access["Access Control Layer"] + RBAC["Azure RBAC"] + KVA["Key Vault Access"] + DCA["DevCenter Access"] + end + + subgraph Network["Network Layer"] + NSG["Network Security Groups"] + VNET["Virtual Network"] + PE["Private Endpoints"] + end + + subgraph Data["Data Layer"] + KV["Key Vault\n(Secrets)"] + LA["Log Analytics\n(Telemetry)"] + DC["DevCenter\n(Workloads)"] + end + + External --> Identity + Identity --> Access + Access --> Network + Network --> Data + + style External fill:#F44336,color:#fff + style Identity fill:#9C27B0,color:#fff + style Access fill:#FF9800,color:#fff + style Network fill:#2196F3,color:#fff + style Data fill:#4CAF50,color:#fff +``` + +### 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 | + +--- + +## Threat Model + +### STRIDE Analysis + +```mermaid +flowchart TB + subgraph Assets["Protected Assets"] + A1["GitHub PAT Tokens"] + A2["Azure Credentials"] + A3["Dev Box VMs"] + A4["Source Code"] + A5["Configuration Data"] + end + + subgraph Threats["STRIDE Threats"] + T1["Spoofing"] + T2["Tampering"] + T3["Repudiation"] + T4["Information Disclosure"] + T5["Denial of Service"] + T6["Elevation of Privilege"] + end + + 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 + + T1 --> M1 + T2 --> M2 + T3 --> M3 + T4 --> M4 + T5 --> M5 + T6 --> M6 + + style Assets fill:#F44336,color:#fff + style Threats fill:#FF9800,color:#fff + style Mitigations fill:#4CAF50,color:#fff +``` + +### 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 +flowchart LR + subgraph External["External Attack Surface"] + A1["GitHub Repository"] + A2["GitHub Actions"] + A3["Developer Endpoints"] + end + + subgraph Internal["Internal Attack Surface"] + B1["Azure Portal"] + B2["Key Vault API"] + B3["DevCenter API"] + B4["Dev Box RDP"] + end + + subgraph Data["Data at Risk"] + C1["PAT Tokens"] + C2["Source Code"] + C3["Dev Box Data"] + end + + A1 --> B1 + A2 --> B2 + A3 --> B4 + + B1 --> C1 + B2 --> C1 + B3 --> C2 + B4 --> C3 + + style External fill:#F44336,color:#fff + style Internal fill:#FF9800,color:#fff + style Data fill:#9C27B0,color:#fff +``` + +--- + +## Identity & Access Management + +### Identity Types + +```mermaid +flowchart TB + subgraph UserIdentities["User Identities"] + AAD_USER["Azure AD Users"] + AAD_GROUP["Azure AD Groups"] + end + + subgraph ServiceIdentities["Service Identities"] + MI_SYS["SystemAssigned\nManaged Identity"] + MI_USER["UserAssigned\nManaged Identity"] + SP["Service Principal\n(OIDC Federation)"] + end + + subgraph Resources["Resources"] + DC["DevCenter"] + PROJ["Projects"] + KV["Key Vault"] + end + + AAD_USER --> AAD_GROUP + AAD_GROUP -->|"RBAC"| DC + AAD_GROUP -->|"RBAC"| PROJ + + MI_SYS --> DC + MI_SYS --> PROJ + + SP -->|"GitHub Actions"| Resources + MI_SYS -->|"DevCenter โ†’ Key Vault"| KV + + style UserIdentities fill:#2196F3,color:#fff + style ServiceIdentities fill:#4CAF50,color:#fff + style Resources fill:#FF9800,color:#fff +``` + +### 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) | + +--- + +## RBAC Hierarchy + +### Role Assignment Model + +```mermaid +flowchart TB + subgraph Subscription["Subscription Scope"] + R1["Contributor"] + R2["Key Vault Administrator"] + R3["Key Vault Secrets User"] + end + + subgraph ResourceGroup["Resource Group Scope"] + R4["DevCenter Project Admin"] + R5["Log Analytics Contributor"] + end + + subgraph Resource["Resource Scope"] + R6["Dev Box User"] + R7["Deployment Environments User"] + end + + subgraph Principals["Principals"] + P1["DevCenter MI"] + P2["Platform Engineering Team"] + P3["Project Developers"] + end + + P1 --> R1 + P1 --> R2 + P1 --> R3 + + P2 --> R4 + P2 --> R5 + + P3 --> R6 + P3 --> R7 + + style Subscription fill:#E91E63,color:#fff + style ResourceGroup fill:#9C27B0,color:#fff + style Resource fill:#2196F3,color:#fff + style Principals fill:#4CAF50,color:#fff +``` + +### 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 +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 +``` + +--- + +## Secrets Management + +### Secrets Architecture + +```mermaid +flowchart TB + subgraph Sources["Secret Sources"] + GH_CLI["gh auth token"] + MANUAL["Manual Entry"] + AZD_ENV[".azure/.env"] + end + + 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\n(GitHub PAT)"] + end + end + + subgraph Access["Secret Access"] + MI["DevCenter\nManaged Identity"] + CAT["Catalog\n(Private Repo)"] + end + + GH_CLI --> AZD_ENV + MANUAL --> AZD_ENV + AZD_ENV -->|"provision"| KV + + KV --> Secrets + + MI -->|"Key Vault Secrets User"| PAT + PAT -->|"secretIdentifier"| CAT + + style Sources fill:#FF9800,color:#fff + style KeyVault fill:#F44336,color:#fff + style Access fill:#4CAF50,color:#fff +``` + +### 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 +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 +``` + +--- + +## Network Security + +### Network Security Architecture + +```mermaid +flowchart TB + subgraph Internet["Internet"] + DEV["Developer"] + GH["GitHub.com"] + end + + subgraph AzureNetwork["Azure Network Security"] + subgraph NSG["Network Security Group"] + RULE1["Allow RDP (3389)\nfrom Corporate"] + RULE2["Allow HTTPS (443)\nOutbound"] + RULE3["Deny All\nDefault"] + end + + subgraph VNet["Virtual Network"] + SUBNET["Dev Box Subnet\n10.0.1.0/24"] + end + + subgraph PE["Private Endpoints"] + KV_PE["Key Vault PE\n(Optional)"] + LA_PE["Log Analytics PE\n(Optional)"] + end + end + + subgraph Resources["Azure Resources"] + DB["Dev Box"] + KV["Key Vault"] + LA["Log Analytics"] + end + + DEV -->|"RDP"| NSG + NSG --> SUBNET + SUBNET --> DB + + DB -->|"HTTPS"| GH + DB --> PE + PE --> KV + PE --> LA + + style Internet fill:#F44336,color:#fff + style AzureNetwork fill:#2196F3,color:#fff + style Resources fill:#4CAF50,color:#fff +``` + +### 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 +``` + +--- + +## 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 | + +--- + +## 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) | + +--- + +## Security Operations + +### Security Monitoring + +```mermaid +flowchart TB + subgraph Sources["Audit Sources"] + KV_AUDIT["Key Vault\nAuditEvent"] + AAD_AUDIT["Azure AD\nSign-in Logs"] + ACT_LOG["Activity Log"] + DC_LOG["DevCenter\nDiagnostics"] + end + + subgraph Collection["Log Analytics"] + LA["Workspace"] + TABLES["Security Tables"] + end + + subgraph Detection["Detection"] + RULES["Alert Rules"] + SENT["Microsoft Sentinel\n(Optional)"] + end + + subgraph Response["Response"] + EMAIL["Email Notifications"] + TICKET["Service Tickets"] + AUTO["Automation"] + end + + Sources --> Collection + Collection --> Detection + Detection --> Response + + style Sources fill:#FF9800,color:#fff + style Collection fill:#2196F3,color:#fff + style Detection fill:#9C27B0,color:#fff + style Response fill:#4CAF50,color:#fff +``` + +### 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 | + +--- + +## 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 | + +--- + +## 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) From 23f773ef0037040ab7deba15a2d9648c567a4b0d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 11:36:44 -0500 Subject: [PATCH 10/44] Enhance documentation consistency and readability across architecture and DevOps files by adding emojis, improving table formatting, and updating section titles for better clarity. --- docs/architecture/01-business-architecture.md | 78 ++++++++---- docs/architecture/02-data-architecture.md | 78 ++++++++---- .../03-application-architecture.md | 78 ++++++++---- .../04-technology-architecture.md | 86 ++++++++++---- docs/architecture/05-security-architecture.md | 94 ++++++++++----- .../07-deployment-architecture.md | 93 +++++++++++++-- docs/devops/README.md | 75 ++++++++++-- docs/devops/ci.md | 92 +++++++++++++-- docs/devops/deploy.md | 111 ++++++++++++++++-- 9 files changed, 620 insertions(+), 165 deletions(-) diff --git a/docs/architecture/01-business-architecture.md b/docs/architecture/01-business-architecture.md index bc9bb760..5c0bf70a 100644 --- a/docs/architecture/01-business-architecture.md +++ b/docs/architecture/01-business-architecture.md @@ -1,9 +1,9 @@ -# Business Architecture +# ๐Ÿข Business Architecture > **DevExp-DevBox Landing Zone Accelerator** | Property | Value | -|----------|-------| +|:---------|:------| | **Version** | 1.0.0 | | **Last Updated** | 2026-01-23 | | **Author** | DevExp Team | @@ -11,21 +11,21 @@ --- -## Table of Contents +## ๐Ÿ“‘ Table of Contents -- [Executive Summary](#executive-summary) -- [Business Context](#business-context) -- [Stakeholder Analysis](#stakeholder-analysis) -- [Business Capabilities](#business-capabilities) -- [Value Streams](#value-streams) -- [Business Requirements](#business-requirements) -- [Success Metrics](#success-metrics) -- [Glossary](#glossary) -- [References](#references) +- [๐Ÿ“‹ 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 +## ๐Ÿ“‹ 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. @@ -48,7 +48,11 @@ The **DevExp-DevBox Landing Zone Accelerator** is an enterprise-grade infrastruc --- -## Business Context +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐ŸŽฏ Business Context ### Problem Statement @@ -97,7 +101,11 @@ The DevExp-DevBox accelerator serves organizations that: --- -## Stakeholder Analysis +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ‘ฅ Stakeholder Analysis ### Stakeholder Map @@ -163,7 +171,11 @@ flowchart TB --- -## Business Capabilities +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Business Capabilities ### Capability Model @@ -235,7 +247,11 @@ flowchart TB --- -## Value Streams +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”„ Value Streams ### Primary Value Stream: Developer Onboarding @@ -308,7 +324,11 @@ stateDiagram-v2 --- -## Business Requirements +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Business Requirements ### Functional Requirements @@ -344,7 +364,11 @@ stateDiagram-v2 --- -## Success Metrics +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“Š Success Metrics ### Key Performance Indicators (KPIs) @@ -397,7 +421,11 @@ flowchart TB --- -## Glossary +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“– Glossary | Term | Definition | |------|------------| @@ -412,16 +440,20 @@ flowchart TB --- -## References +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— References -### External 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 +### ๐Ÿ“š Related Documents - [Data Architecture](02-data-architecture.md) - [Application Architecture](03-application-architecture.md) diff --git a/docs/architecture/02-data-architecture.md b/docs/architecture/02-data-architecture.md index 9d66da2c..975178c3 100644 --- a/docs/architecture/02-data-architecture.md +++ b/docs/architecture/02-data-architecture.md @@ -1,9 +1,9 @@ -# Data Architecture +# ๐Ÿ—„๏ธ Data Architecture > **DevExp-DevBox Landing Zone Accelerator** | Property | Value | -|----------|-------| +|:---------|:------| | **Version** | 1.0.0 | | **Last Updated** | 2026-01-23 | | **Author** | DevExp Team | @@ -11,21 +11,21 @@ --- -## Table of Contents +## ๐Ÿ“‘ Table of Contents -- [Data Overview](#data-overview) -- [Configuration Data Model](#configuration-data-model) -- [Secrets Management](#secrets-management) -- [Telemetry & Diagnostics](#telemetry--diagnostics) -- [Data Flow Diagrams](#data-flow-diagrams) -- [Data Governance](#data-governance) -- [Schema Documentation](#schema-documentation) -- [Glossary](#glossary) -- [References](#references) +- [๐Ÿ“Š 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 +## ๐Ÿ“Š Data Overview The DevExp-DevBox accelerator manages four primary categories of data, each with distinct lifecycle, sensitivity, and storage requirements. @@ -83,7 +83,11 @@ flowchart TB --- -## Configuration Data Model +[โฌ†๏ธ 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. @@ -328,7 +332,11 @@ projects: --- -## Secrets Management +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ” Secrets Management ### Secret Types and Lifecycle @@ -396,7 +404,11 @@ sequenceDiagram --- -## Telemetry & Diagnostics +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ถ Telemetry & Diagnostics ### Log Analytics Data Collection @@ -475,7 +487,11 @@ resource diagnosticSettings 'Microsoft.Insights/diagnosticSettings@2021-05-01-pr --- -## Data Flow Diagrams +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”„ Data Flow Diagrams ### Configuration Loading Flow @@ -569,7 +585,11 @@ flowchart TB --- -## Data Governance +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ›ก๏ธ Data Governance ### Data Ownership @@ -606,7 +626,11 @@ All resources must include the following tags for governance: --- -## Schema Documentation +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Schema Documentation ### JSON Schema Files @@ -662,7 +686,11 @@ Configure VS Code to validate YAML files: --- -## Glossary +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“– Glossary | Term | Definition | |------|------------| @@ -678,16 +706,20 @@ Configure VS Code to validate YAML files: --- -## References +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— References -### Internal 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 +### ๐ŸŒ 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) diff --git a/docs/architecture/03-application-architecture.md b/docs/architecture/03-application-architecture.md index d0fc6b93..c680e8b5 100644 --- a/docs/architecture/03-application-architecture.md +++ b/docs/architecture/03-application-architecture.md @@ -1,9 +1,9 @@ -# Application Architecture +# ๐Ÿ“ฆ Application Architecture > **DevExp-DevBox Landing Zone Accelerator** | Property | Value | -|----------|-------| +|:---------|:------| | **Version** | 1.0.0 | | **Last Updated** | 2026-01-23 | | **Author** | DevExp Team | @@ -11,21 +11,21 @@ --- -## Table of Contents +## ๐Ÿ“‘ 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](#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 +## ๐Ÿ“Š 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. @@ -106,7 +106,11 @@ flowchart TB --- -## Bicep Module Catalog +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“‹ Bicep Module Catalog ### Module Inventory @@ -161,7 +165,11 @@ mindmap --- -## Module Dependency Graph +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Module Dependency Graph ### Complete Dependency Tree @@ -273,7 +281,11 @@ flowchart TB --- -## Interface Contracts +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“œ Interface Contracts ### main.bicep Parameters @@ -369,7 +381,11 @@ output devCenterProjects array = devCenter.outputs.devCenterProjects --- -## Deployment Orchestration +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿš€ Deployment Orchestration ### Deployment Sequence Diagram @@ -465,7 +481,11 @@ flowchart LR --- -## Component Details +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Component Details ### main.bicep - Subscription Orchestrator @@ -596,7 +616,11 @@ flowchart TB --- -## Integration Patterns +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”„ Integration Patterns ### Configuration Integration Pattern @@ -677,7 +701,11 @@ module workload 'src/workload/workload.bicep' = { --- -## Extension Points +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”Œ Extension Points ### Adding a New Landing Zone @@ -728,16 +756,20 @@ output resourceName string = childResource.name --- -## References +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“š References -### Internal 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 +### ๐ŸŒ 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/) diff --git a/docs/architecture/04-technology-architecture.md b/docs/architecture/04-technology-architecture.md index bc08ff00..83ae6b19 100644 --- a/docs/architecture/04-technology-architecture.md +++ b/docs/architecture/04-technology-architecture.md @@ -1,9 +1,9 @@ -# Technology Architecture +# โ˜๏ธ Technology Architecture > **DevExp-DevBox Landing Zone Accelerator** | Property | Value | -|----------|-------| +|:---------|:------| | **Version** | 1.0.0 | | **Last Updated** | 2026-01-23 | | **Author** | DevExp Team | @@ -11,22 +11,22 @@ --- -## Table of Contents +## ๐Ÿ“‘ 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](#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 +## ๐Ÿ“Š 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. @@ -98,7 +98,11 @@ flowchart TB --- -## Azure Service Catalog +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ฆ Azure Service Catalog ### Primary Azure Services @@ -192,7 +196,11 @@ flowchart TB --- -## Landing Zone Design +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ—๏ธ Landing Zone Design ### Azure Landing Zone Alignment @@ -260,7 +268,11 @@ flowchart TB --- -## Network Architecture +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐ŸŒ Network Architecture ### Network Topology @@ -339,7 +351,11 @@ network: --- -## Compute Architecture +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ’ป Compute Architecture ### Dev Box Architecture @@ -425,7 +441,11 @@ flowchart LR --- -## CI/CD Infrastructure +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”„ CI/CD Infrastructure ### GitHub Actions Architecture @@ -524,7 +544,11 @@ steps: --- -## Monitoring Infrastructure +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ถ Monitoring Infrastructure ### Log Analytics Architecture @@ -596,7 +620,11 @@ flowchart TB --- -## Infrastructure Sizing +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Infrastructure Sizing ### Resource Sizing Guidelines @@ -620,7 +648,11 @@ flowchart TB --- -## Technology Standards +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“œ Technology Standards ### Bicep Coding Standards @@ -653,16 +685,20 @@ flowchart TB --- -## References +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— References -### Internal 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 +### ๐ŸŒ 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/) diff --git a/docs/architecture/05-security-architecture.md b/docs/architecture/05-security-architecture.md index 625c1ac6..94e66e03 100644 --- a/docs/architecture/05-security-architecture.md +++ b/docs/architecture/05-security-architecture.md @@ -1,9 +1,9 @@ -# Security Architecture +# ๐Ÿ”’ Security Architecture > **DevExp-DevBox Landing Zone Accelerator** | Property | Value | -|----------|-------| +|:---------|:------| | **Version** | 1.0.0 | | **Last Updated** | 2026-01-23 | | **Author** | DevExp Team | @@ -11,23 +11,23 @@ --- -## Table of Contents +## ๐Ÿ“‘ 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](#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 +## ๐Ÿ“Š 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. @@ -90,7 +90,11 @@ flowchart TB --- -## Threat Model +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš ๏ธ Threat Model ### STRIDE Analysis @@ -189,7 +193,11 @@ flowchart LR --- -## Identity & Access Management +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”‘ Identity & Access Management ### Identity Types @@ -256,7 +264,11 @@ identity: --- -## RBAC Hierarchy +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ‘ฅ RBAC Hierarchy ### Role Assignment Model @@ -348,7 +360,11 @@ sequenceDiagram --- -## Secrets Management +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ” Secrets Management ### Secrets Architecture @@ -442,7 +458,11 @@ sequenceDiagram --- -## Network Security +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐ŸŒ Network Security ### Network Security Architecture @@ -515,7 +535,11 @@ network: --- -## Data Protection +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ›ก๏ธ Data Protection ### Encryption Model @@ -539,7 +563,11 @@ network: --- -## Compliance & Governance +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โœ… Compliance & Governance ### Tagging for Governance @@ -577,7 +605,11 @@ tags: --- -## Security Operations +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ถ Security Operations ### Security Monitoring @@ -639,7 +671,11 @@ flowchart TB --- -## Security Controls Matrix +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“‹ Security Controls Matrix ### Control Implementation Summary @@ -677,16 +713,20 @@ flowchart TB --- -## References +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— References -### Internal 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 +### ๐ŸŒ 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) diff --git a/docs/architecture/07-deployment-architecture.md b/docs/architecture/07-deployment-architecture.md index 1ff1bf17..2ded4c76 100644 --- a/docs/architecture/07-deployment-architecture.md +++ b/docs/architecture/07-deployment-architecture.md @@ -1,12 +1,35 @@ -# Deployment Architecture +# ๐Ÿš€ Deployment Architecture > ๐Ÿ“– This document describes the deployment architecture and CI/CD pipeline design for the Dev Box Accelerator project. -## Overview +--- + +## ๐Ÿ“‘ 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). -## High-Level Architecture +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ—๏ธ High-Level Architecture ```mermaid flowchart TB @@ -60,7 +83,13 @@ flowchart TB class SUB,RG,DC,KV,VNET azure ``` -## Pipeline Architecture +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”„ Pipeline Architecture ### Workflow Relationships @@ -151,7 +180,13 @@ sequenceDiagram end ``` -## Deployment Environments +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐ŸŒ Deployment Environments ### Environment Strategy @@ -190,7 +225,13 @@ flowchart TB class SUB1,SUB2,SUB3 azure ``` -## Security Architecture +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”’ Security Architecture ### Authentication Flow @@ -236,7 +277,13 @@ flowchart LR | Concurrency Control | Job grouping | Prevent race conditions | | Environment Protection | GitHub Environments | Approval gates | -## Infrastructure Components +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ฆ Infrastructure Components ### Bicep Module Structure @@ -290,7 +337,13 @@ flowchart TB class I1,I2 identity ``` -## Artifact Management +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ’พ Artifact Management ### Artifact Flow @@ -337,7 +390,13 @@ flowchart LR | 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` | -## Deployment Process +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ› ๏ธ Deployment Process ### Pre-Deployment Checklist @@ -369,7 +428,13 @@ flowchart LR - Creates/updates Azure resources - Generates deployment summary -## Monitoring & Observability +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ถ Monitoring & Observability ### Workflow Monitoring @@ -386,7 +451,13 @@ flowchart LR - Long-running deployment alerts - Azure resource health monitoring -## Related Documentation +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Related Documentation - [DevOps Workflows](../devops/README.md) - Detailed workflow documentation - [CI Workflow](../devops/ci.md) - Continuous integration details diff --git a/docs/devops/README.md b/docs/devops/README.md index 249af983..17d347a6 100644 --- a/docs/devops/README.md +++ b/docs/devops/README.md @@ -1,12 +1,33 @@ -# DevOps Documentation +# ๐Ÿ”„ DevOps Documentation > ๐Ÿ“– Comprehensive documentation for GitHub Actions workflows in the Dev Box Accelerator project. -## Overview +--- + +## ๐Ÿ“‘ Table of Contents + +- [๐ŸŽฏ Overview](#overview) +- [๐Ÿ—๏ธ Master Pipeline Architecture](#master-pipeline-architecture) +- [๐Ÿ“š Workflow Documentation](#workflow-documentation) +- [โšก Quick Reference](#quick-reference) +- [๐Ÿ”„ Reusable Components](#reusable-components) +- [๐Ÿท๏ธ Versioning Strategy](#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. -## Master Pipeline Architecture +--- + +[โฌ†๏ธ 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: @@ -75,7 +96,13 @@ flowchart TB class O1,O2,O3 output ``` -## Workflow Documentation +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“š Workflow Documentation | Workflow | File | Purpose | Trigger | |----------|------|---------|---------| @@ -83,7 +110,13 @@ flowchart TB | [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`) | -## Quick Reference +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โšก Quick Reference ### Trigger Summary @@ -129,7 +162,13 @@ flowchart LR | `id-token: write` | โŒ | โœ… | โŒ | OIDC authentication | | `actions: read` | โŒ | โŒ | โœ… | Workflow introspection | -## Reusable Components +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”„ Reusable Components ### Composite Actions @@ -163,7 +202,13 @@ flowchart LR class GR1,GR2,GR3,GR4,GR5,GR6,BC1,BC2,BC3 action ``` -## Versioning Strategy +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿท๏ธ Versioning Strategy The project uses a **branch-based semantic versioning** strategy: @@ -178,7 +223,13 @@ The project uses a **branch-based semantic versioning** strategy: - **Patch > 99**: Resets to 0, increments minor - **Minor > 99**: Resets to 0, increments major -## Best Practices +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โœ… Best Practices ### Security @@ -194,7 +245,13 @@ The project uses a **branch-based semantic versioning** strategy: - โœ… Step summaries for visibility into workflow execution - โœ… Artifact retention policies configured -## Related Documentation +--- + +[โฌ†๏ธ 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 diff --git a/docs/devops/ci.md b/docs/devops/ci.md index be5ba5bd..f05e9a3d 100644 --- a/docs/devops/ci.md +++ b/docs/devops/ci.md @@ -1,10 +1,32 @@ -# Continuous Integration Workflow +# ๐Ÿ”„ Continuous Integration Workflow -## Overview +--- + +## ๐Ÿ“‘ Table of Contents + +- [๐ŸŽฏ Overview](#overview) +- [๐Ÿ“Š Pipeline Visualization](#pipeline-visualization) +- [๐ŸŽฏ Triggers](#triggers) +- [โš™๏ธ Jobs & Steps](#jobs--steps) +- [๐Ÿ” Prerequisites](#prerequisites) +- [๐Ÿท๏ธ Versioning Strategy](#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. -## Pipeline Visualization +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“Š Pipeline Visualization ```mermaid flowchart TD @@ -45,14 +67,26 @@ flowchart TD class SKIP skip ``` -## Triggers +--- + +[โฌ†๏ธ 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 | -## Jobs & Steps +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Jobs & Steps ### Job: `generate-tag-version` @@ -102,7 +136,13 @@ flowchart TD | 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 | -## Prerequisites +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ” Prerequisites ### Permissions @@ -121,11 +161,23 @@ This workflow depends on the following composite actions: | `.github/actions/ci/generate-release` | Generates semantic version and release metadata | | `.github/actions/ci/bicep-standard-ci` | Builds Bicep templates and uploads artifacts | -## Environment Variables +--- + +[โฌ†๏ธ 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. -## Versioning Strategy +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿท๏ธ Versioning Strategy The CI workflow implements a **branch-based versioning strategy**: @@ -136,13 +188,25 @@ The CI workflow implements a **branch-based versioning strategy**: | `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` | -## Artifacts +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ฆ Artifacts | Artifact Name | Contents | Retention | | -------------------------- | ------------------------------- | --------- | | `artifacts-{version}` | Compiled ARM templates | 30 days | -## Troubleshooting +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Troubleshooting ### Common Issues @@ -158,7 +222,13 @@ The CI workflow implements a **branch-based versioning strategy**: 2. Review the `generate-tag-version` job outputs for version information 3. Verify branch name follows supported patterns (`feature/**`, `fix/**`, or `main`) -## Related Documentation +--- + +[โฌ†๏ธ 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 diff --git a/docs/devops/deploy.md b/docs/devops/deploy.md index 9bb90f34..dbb92cce 100644 --- a/docs/devops/deploy.md +++ b/docs/devops/deploy.md @@ -1,10 +1,35 @@ -# Deploy to Azure Workflow +# ๐Ÿš€ Deploy to Azure Workflow -## Overview +--- + +## ๐Ÿ“‘ Table of Contents + +- [๐ŸŽฏ Overview](#overview) +- [๐Ÿ“Š Pipeline Visualization](#pipeline-visualization) +- [๐ŸŽฏ Triggers](#triggers) +- [โš™๏ธ Jobs & Steps](#jobs--steps) +- [๐Ÿ” Prerequisites](#prerequisites) +- [๐ŸŒ Environment Variables](#environment-variables) +- [๐Ÿ”’ Concurrency Control](#concurrency-control) +- [๐Ÿ“ฆ Artifacts](#artifacts) +- [๐Ÿ“ Usage Examples](#usage-examples) +- [๐Ÿ”ง Troubleshooting](#troubleshooting) +- [๐Ÿ›ก๏ธ Security Considerations](#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. -## Pipeline Visualization +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“Š Pipeline Visualization ```mermaid flowchart TD @@ -56,7 +81,13 @@ flowchart TD class AZ1,AZ2,AZ3,AZ4 azure ``` -## Triggers +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐ŸŽฏ Triggers | Trigger Type | Description | | ------------------- | ----------------------------------------------------- | @@ -69,7 +100,13 @@ flowchart TD | `AZURE_ENV_NAME` | `string` | Yes | `demo` | Azure environment name (e.g., dev, staging, prod) | | `AZURE_LOCATION` | `string` | Yes | `eastus2` | Azure region for deployment | -## Jobs & Steps +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Jobs & Steps ### Job: `build-and-deploy-to-azure` @@ -96,7 +133,13 @@ flowchart TD | 8 | Deploy Infrastructure to Azure | Runs `azd provision` to deploy resources | | 9 | Generate Deployment Summary | Creates a summary of the deployment result | -## Prerequisites +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ” Prerequisites ### Permissions @@ -137,7 +180,13 @@ This workflow uses **OpenID Connect (OIDC)** for secure, secretless authenticati > ๐Ÿ“– See [Azure OIDC Authentication Documentation](https://learn.microsoft.com/en-us/azure/developer/github/connect-from-azure) -## Environment Variables +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐ŸŒ Environment Variables | Variable | Source | Description | | ----------------------- | ----------------------------------- | ------------------------------------- | @@ -149,7 +198,13 @@ This workflow uses **OpenID Connect (OIDC)** for secure, secretless authenticati | `KEY_VAULT_SECRET` | Repository secret | Key Vault secret value | | `SOURCE_CONTROL_PLATFORM`| Hardcoded | Set to `github` | -## Concurrency Control +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”’ Concurrency Control ```yaml concurrency: @@ -161,13 +216,25 @@ concurrency: - **Behavior:** Only one deployment can run per environment at a time - **Cancellation:** Running deployments are NOT cancelled if a new one is triggered -## Artifacts +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ฆ Artifacts | Artifact Name | Contents | Retention | | --------------------------------------- | ----------------------- | --------- | | `bicep-artifacts-{run_number}` | Compiled ARM templates | 7 days | -## Usage Examples +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Usage Examples ### Manual Trigger via GitHub UI @@ -187,7 +254,13 @@ gh workflow run deploy.yml \ -f AZURE_LOCATION=eastus2 ``` -## Troubleshooting +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Troubleshooting ### Common Issues @@ -221,14 +294,26 @@ gh workflow run deploy.yml \ az bicep build --file ./infra/main.bicep --outdir ./test-output ``` -## Security Considerations +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ›ก๏ธ Security Considerations - โœ… 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 -## Related Documentation +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Related Documentation - [CI Workflow](ci.md) - Continuous integration process - [Release Workflow](release.md) - GitHub release creation From a993d66ec01a219fad6b7e5827f7c371d1f0e4bf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 11:37:39 -0500 Subject: [PATCH 11/44] Enhance documentation for release, setup, and cleanup scripts by adding table of contents, improving section titles, and incorporating emojis for better clarity and navigation. --- docs/devops/release.md | 110 ++++++++++++++++++++--- docs/scripts/README.md | 95 +++++++++++++++++--- docs/scripts/azure/create-custom-role.md | 75 ++++++++++++++-- docs/scripts/clean-setup.md | 88 +++++++++++++++--- docs/scripts/setup.md | 102 ++++++++++++++++++--- 5 files changed, 414 insertions(+), 56 deletions(-) diff --git a/docs/devops/release.md b/docs/devops/release.md index 0e8795e9..faa6b6bd 100644 --- a/docs/devops/release.md +++ b/docs/devops/release.md @@ -1,10 +1,34 @@ -# Branch-Based Release Strategy Workflow +# ๐Ÿท๏ธ Branch-Based Release Strategy Workflow -## Overview +--- + +## ๐Ÿ“‘ Table of Contents + +- [๐ŸŽฏ Overview](#overview) +- [๐Ÿ“Š Pipeline Visualization](#pipeline-visualization) +- [๐ŸŽฏ Triggers](#triggers) +- [โš™๏ธ Jobs & Steps](#jobs--steps) +- [๐Ÿ” Prerequisites](#prerequisites) +- [๐Ÿท๏ธ Versioning Strategy](#versioning-strategy) +- [๐Ÿ”’ Concurrency Control](#concurrency-control) +- [๐Ÿ“ฆ Artifacts](#artifacts) +- [๐Ÿ“ 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. -## Pipeline Visualization +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“Š Pipeline Visualization ```mermaid flowchart TD @@ -71,7 +95,13 @@ flowchart TD class SKIP1,SKIP2 skip ``` -## Triggers +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐ŸŽฏ Triggers | Trigger Type | Description | | ------------------- | ----------------------------------------------------- | @@ -83,7 +113,13 @@ flowchart TD | --------------- | --------- | -------- | ------- | ------------------------------------------------ | | `force_release` | `boolean` | No | `false` | Force create a release even for non-main branches | -## Jobs & Steps +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Jobs & Steps ### Job: `generate-release` @@ -188,7 +224,13 @@ This job runs when: | **Dependencies** | `generate-release`, `build`, `publish-release` | | **Condition** | `always()` - runs regardless of previous job results | -## Prerequisites +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ” Prerequisites ### Permissions @@ -207,7 +249,13 @@ permissions: | `.github/actions/ci/bicep-standard-ci` | Builds Bicep templates and uploads artifacts | | `softprops/action-gh-release@v2.3.2` | Creates GitHub Releases | -## Versioning Strategy +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿท๏ธ Versioning Strategy ### Branch-Based Version Calculation @@ -268,7 +316,13 @@ For the `main` branch, the version increment follows this rule: | Fix branch | `-fix.{branch-name}` | | Pull Request | Additional `-pr{number}` suffix | -## Concurrency Control +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”’ Concurrency Control ```yaml concurrency: @@ -280,13 +334,25 @@ concurrency: - **Behavior:** Only one release workflow can run per branch at a time - **Cancellation:** Running releases are NOT cancelled if a new one is triggered -## Artifacts +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ฆ Artifacts | Artifact Name | Contents | Retention | | -------------------------- | ------------------------------- | --------- | | `artifacts-{version}` | Compiled ARM templates | 30 days | -## GitHub Release Contents +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐ŸŽ‰ GitHub Release Contents Each published release includes: @@ -298,7 +364,13 @@ Each published release includes: | **Artifacts** | Compiled ARM templates from `./artifacts/` | | **Pre-release Flag** | Set for non-main branches | -## Usage Examples +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Usage Examples ### Trigger Release from Main Branch @@ -328,7 +400,13 @@ gh workflow run release.yml -r main gh workflow run release.yml -r feature/my-feature -f force_release=true ``` -## Troubleshooting +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Troubleshooting ### Common Issues @@ -351,7 +429,13 @@ gh workflow run release.yml -r feature/my-feature -f force_release=true git tag --list 'v*' | sort -V | tail -10 ``` -## Related Documentation +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Related Documentation - [CI Workflow](ci.md) - Continuous integration process - [Deploy Workflow](deploy.md) - Azure deployment process diff --git a/docs/scripts/README.md b/docs/scripts/README.md index 538ad8bd..34cdb730 100644 --- a/docs/scripts/README.md +++ b/docs/scripts/README.md @@ -1,12 +1,35 @@ -# DevExp-DevBox PowerShell Scripts Documentation +# ๐Ÿ“œ DevExp-DevBox PowerShell Scripts Documentation -> Comprehensive documentation for all PowerShell automation scripts in the DevExp-DevBox project +> ๐Ÿ“– Comprehensive documentation for all PowerShell automation scripts in the DevExp-DevBox project. -## Overview +--- + +## ๐Ÿ“‘ 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. -## Scripts Architecture +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ—๏ธ Scripts Architecture ```mermaid flowchart TB @@ -48,7 +71,13 @@ flowchart TB classDef utility fill:#9C27B0,stroke:#6A1B9A,color:#fff ``` -## Quick Reference +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โšก Quick Reference ### Setup Scripts (Execute in Order) @@ -75,7 +104,13 @@ flowchart TB |--------|---------| | [winget-update.ps1](configuration/winget-update.md) | Update Microsoft Store apps (Dev Box workloads) | -## Scripts by Category +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“‚ Scripts by Category ### Root Scripts @@ -116,7 +151,13 @@ Scripts for resource management and Dev Box configuration. | `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) | -## Prerequisites Summary +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Prerequisites Summary ### Required Tools @@ -136,7 +177,13 @@ Scripts for resource management and Dev Box configuration. | Azure AD | Application Administrator | Credential scripts | | GitHub Repository | Admin | Secret scripts | -## Common Workflows +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”„ Common Workflows ### New Environment Setup @@ -193,7 +240,13 @@ Or step-by-step: .\.configuration\powershell\cleanUp.ps1 -EnvName "prod" -Location "eastus2" ``` -## Error Handling Patterns +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš ๏ธ Error Handling Patterns All scripts follow consistent error handling: @@ -210,7 +263,13 @@ $WarningPreference = 'Stop' [CmdletBinding(SupportsShouldProcess)] ``` -## File Structure +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ File Structure ``` DevExp-DevBox/ @@ -252,7 +311,13 @@ DevExp-DevBox/ โ””โ”€โ”€ winget-update.md ``` -## Related Documentation +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Related Documentation | Document | Description | |----------|-------------| @@ -260,7 +325,13 @@ DevExp-DevBox/ | [CI/CD Overview](../devops/README.md) | DevOps pipeline documentation | | [Deployment Guide](../devops/deploy.md) | Deployment instructions | -## Contributing +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿค Contributing When adding new PowerShell scripts: diff --git a/docs/scripts/azure/create-custom-role.md b/docs/scripts/azure/create-custom-role.md index 113a0702..6789ea69 100644 --- a/docs/scripts/azure/create-custom-role.md +++ b/docs/scripts/azure/create-custom-role.md @@ -1,12 +1,33 @@ -# createCustomRole.ps1 +# ๐Ÿ”‘ createCustomRole.ps1 > **Creates a custom Azure RBAC role for role assignment management** -## Overview +--- + +## ๐Ÿ“‘ 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) + +--- + +## ๐ŸŽฏ 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. -## Flow Visualization +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“Š Flow Visualization ```mermaid flowchart TD @@ -60,7 +81,13 @@ flowchart TD classDef error fill:#F44336,stroke:#C62828,color:#fff ``` -## Parameters +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Parameters | Parameter | Type | Required | Default | Validation | Description | |-----------|------|----------|---------|------------|-------------| @@ -69,7 +96,13 @@ flowchart TD | `-Description` | `string` | No | `"Allows creating role assignments."` | - | Description for the custom role | | `-Force` | `switch` | No | `$false` | - | Delete existing role before creating | -## Prerequisites +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Prerequisites ### Required Tools @@ -83,7 +116,13 @@ flowchart TD - **Azure**: `Microsoft.Authorization/roleDefinitions/write` at subscription scope - Typically requires **Owner** or **User Access Administrator** role -## Role Definition +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“œ Role Definition The created role includes these permissions: @@ -106,7 +145,13 @@ The created role includes these permissions: } ``` -## Functions Reference +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Functions Reference ### Function: `Get-CurrentSubscriptionId` @@ -143,7 +188,13 @@ The created role includes these permissions: 4. Creates role via `az role definition create` 5. Cleans up temp file (in finally block) -## Usage Examples +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Usage Examples ### Basic Usage (Current Subscription) @@ -181,7 +232,13 @@ Deletes any existing role with the same name before creating. Shows what would be created without making changes. -## Error Handling +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš ๏ธ Error Handling ### Error Action Preference diff --git a/docs/scripts/clean-setup.md b/docs/scripts/clean-setup.md index e0dfd515..5ba58771 100644 --- a/docs/scripts/clean-setup.md +++ b/docs/scripts/clean-setup.md @@ -1,12 +1,34 @@ -# cleanSetUp.ps1 +# ๐Ÿงน cleanSetUp.ps1 > **Complete DevExp-DevBox infrastructure cleanup orchestrator** -## Overview +--- + +## ๐Ÿ“‘ 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. -## Flow Visualization +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“Š Flow Visualization ```mermaid flowchart TD @@ -74,7 +96,13 @@ flowchart TD classDef error fill:#F44336,stroke:#C62828,color:#fff ``` -## Parameters +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Parameters | Parameter | Type | Required | Default | Validation | Description | |-----------|------|----------|---------|------------|-------------| @@ -83,7 +111,13 @@ flowchart TD | `-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 | -## Prerequisites +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Prerequisites ### Required Tools @@ -103,7 +137,13 @@ flowchart TD None required - all configuration via parameters. -## Functions Reference +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Functions Reference ### Function: `Remove-SubscriptionDeployments` @@ -114,6 +154,7 @@ None required - all configuration via parameters. **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` @@ -147,6 +188,7 @@ Deployment 'main-deployment-20240115' deleted. **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 @@ -170,13 +212,20 @@ Deployment 'main-deployment-20240115' deleted. **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 -## Usage Examples +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Usage Examples ### Basic Cleanup (Default Parameters) @@ -185,6 +234,7 @@ Deployment 'main-deployment-20240115' deleted. ``` Cleans up the environment using: + - Environment: `gitHub` - Location: `eastus2` - App: `ContosoDevEx GitHub Actions Enterprise App` @@ -210,7 +260,13 @@ Cleans up the environment using: Shows what would be deleted without making changes. -## Error Handling +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš ๏ธ Error Handling ### Error Action Preference @@ -234,7 +290,13 @@ The script uses strict error handling - any unhandled error terminates execution - The script tracks success/failure of each operation - Final status reflects whether all operations succeeded -## Troubleshooting +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Troubleshooting ### Common Issues @@ -253,7 +315,13 @@ Enable verbose output: .\cleanSetUp.ps1 -Verbose ``` -## Related Scripts +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Related Scripts | Script | Purpose | Link | |--------|---------|------| diff --git a/docs/scripts/setup.md b/docs/scripts/setup.md index 2c1c9646..65a1588d 100644 --- a/docs/scripts/setup.md +++ b/docs/scripts/setup.md @@ -1,12 +1,36 @@ -# setUp.ps1 +# โš™๏ธ setUp.ps1 > **Azure Dev Box environment setup with GitHub/Azure DevOps integration** -## Overview +--- + +## ๐Ÿ“‘ 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. -## Flow Visualization +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“Š Flow Visualization ```mermaid flowchart TD @@ -89,7 +113,13 @@ flowchart TD classDef error fill:#F44336,stroke:#C62828,color:#fff ``` -## Authentication Flow +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”’ Authentication Flow ```mermaid sequenceDiagram @@ -122,7 +152,13 @@ sequenceDiagram Script-->>User: Setup complete ``` -## Parameters +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Parameters | Parameter | Type | Required | Default | Validation | Description | |-----------|------|----------|---------|------------|-------------| @@ -132,7 +168,13 @@ sequenceDiagram *Required unless `-Help` is specified. -## Prerequisites +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Prerequisites ### Required Tools @@ -156,7 +198,13 @@ sequenceDiagram | `SOURCE_CONTROL_PLATFORM` | Tracks selected platform | Script (in `.env` file) | | `AZURE_DEVOPS_EXT_PAT` | Azure DevOps authentication | Script (for ADO platform) | -## Functions Reference +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Functions Reference ### Function: `Write-LogMessage` @@ -313,7 +361,13 @@ sequenceDiagram 6. Initialize azd environment 7. Display success message -## Usage Examples +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Usage Examples ### GitHub Setup @@ -367,7 +421,13 @@ REQUIREMENTS: -## Error Handling +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš ๏ธ Error Handling ### Error Action Preference @@ -393,7 +453,13 @@ trap { } ``` -## Security Considerations +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ” Security Considerations ### Token Handling @@ -413,7 +479,13 @@ SOURCE_CONTROL_PLATFORM='github' > โš ๏ธ **Warning:** Ensure `.azure/` is in `.gitignore` to prevent token exposure. -## Troubleshooting +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Troubleshooting ### Common Issues @@ -433,7 +505,13 @@ $VerbosePreference = 'Continue' .\setUp.ps1 -EnvName "debug-env" -SourceControl "github" ``` -## Related Scripts +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Related Scripts | Script | Purpose | Link | |--------|---------|------| From bb800f9d7d6a517a46c0c1c175d557068186ee72 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 11:38:21 -0500 Subject: [PATCH 12/44] Enhance documentation for createUsersAndAssignRole.ps1 and deleteDeploymentCredentials.ps1 by adding table of contents, improving section titles, and incorporating emojis for better clarity and navigation. --- .../azure/create-users-and-assign-role.md | 84 +++++++++++++++-- .../azure/delete-deployment-credentials.md | 93 ++++++++++++++++--- .../azure/delete-users-and-assigned-roles.md | 75 +++++++++++++-- 3 files changed, 222 insertions(+), 30 deletions(-) diff --git a/docs/scripts/azure/create-users-and-assign-role.md b/docs/scripts/azure/create-users-and-assign-role.md index 1f5b6e3f..b5fa1f31 100644 --- a/docs/scripts/azure/create-users-and-assign-role.md +++ b/docs/scripts/azure/create-users-and-assign-role.md @@ -1,12 +1,34 @@ -# createUsersAndAssignRole.ps1 +# ๐Ÿ‘ฅ createUsersAndAssignRole.ps1 > **Assigns Azure DevCenter roles to the current signed-in user** -## Overview +--- + +## ๐Ÿ“‘ 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) + +--- + +## ๐ŸŽฏ 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. -## Flow Visualization +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“Š Flow Visualization ```mermaid flowchart TD @@ -60,13 +82,25 @@ flowchart TD classDef error fill:#F44336,stroke:#C62828,color:#fff ``` -## Parameters +--- + +[โฌ†๏ธ 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 | -## Prerequisites +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Prerequisites ### Required Tools @@ -80,7 +114,13 @@ flowchart TD - **Azure**: `Microsoft.Authorization/roleAssignments/write` at subscription scope - Typically requires **Owner** or **User Access Administrator** role -## Assigned Roles +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”‘ Assigned Roles The script assigns these DevCenter-specific roles: @@ -91,7 +131,13 @@ The script assigns these DevCenter-specific roles: | `Deployment Environments Reader` | View deployment environments | | `Deployment Environments User` | Use deployment environments | -## Functions Reference +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Functions Reference ### Function: `Set-AzureRole` @@ -135,7 +181,13 @@ The script assigns these DevCenter-specific roles: 3. Calls `Set-AzureRole` for each role 4. Tracks success/failure of each assignment -## Usage Examples +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Usage Examples ### Basic Usage (Current Subscription) @@ -169,7 +221,13 @@ All role assignments completed successfully for user: a1b2c3d4-e5f6-7890-abcd-ef -## Error Handling +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš ๏ธ Error Handling ### Error Action Preference @@ -193,7 +251,13 @@ The script is **idempotent** - running it multiple times will: - Only attempt to assign missing roles - Not cause errors for existing assignments -## Troubleshooting +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Troubleshooting ### Common Issues diff --git a/docs/scripts/azure/delete-deployment-credentials.md b/docs/scripts/azure/delete-deployment-credentials.md index 894485d8..fa860851 100644 --- a/docs/scripts/azure/delete-deployment-credentials.md +++ b/docs/scripts/azure/delete-deployment-credentials.md @@ -1,12 +1,35 @@ -# deleteDeploymentCredentials.ps1 +# ๐Ÿ—‘๏ธ deleteDeploymentCredentials.ps1 > **Removes Azure AD service principal and application registration for CI/CD cleanup** -## Overview +--- + +## ๐Ÿ“‘ 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. -## Flow Visualization +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“Š Flow Visualization ```mermaid flowchart TD @@ -51,13 +74,25 @@ flowchart TD classDef error fill:#F44336,stroke:#C62828,color:#fff ``` -## Parameters +--- + +[โฌ†๏ธ 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 | -## Prerequisites +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Prerequisites ### Required Tools @@ -71,7 +106,13 @@ flowchart TD - **Azure AD**: `Application.ReadWrite.All` or **Application Administrator** role - Permission to delete service principals in the tenant -## Functions Reference +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Functions Reference ### Function: `Remove-AzureDeploymentCredentials` @@ -94,7 +135,13 @@ flowchart TD **Important:** Service principal must be deleted before the application registration. -## Usage Examples +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Usage Examples ### Delete Default CI/CD Credentials @@ -141,7 +188,13 @@ Cleanup completed successfully. -## Error Handling +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš ๏ธ Error Handling ### Error Action Preference @@ -164,7 +217,13 @@ The script is **idempotent**: - If application doesn't exist, returns success with warning - Safe to run multiple times -## Troubleshooting +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Troubleshooting ### Common Issues @@ -182,7 +241,13 @@ The script is **idempotent**: az ad app list --display-name "ContosoDevEx GitHub Actions Enterprise App" --query "[].appId" --output tsv ``` -## Security Considerations +--- + +[โฌ†๏ธ 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 @@ -195,7 +260,13 @@ az ad app list --display-name "ContosoDevEx GitHub Actions Enterprise App" --que - [ ] Update or disable CI/CD workflows that use `AZURE_CREDENTIALS` - [ ] Confirm you have permission to recreate if needed -## Related Scripts +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Related Scripts | Script | Purpose | Link | |--------|---------|------| diff --git a/docs/scripts/azure/delete-users-and-assigned-roles.md b/docs/scripts/azure/delete-users-and-assigned-roles.md index aa7648fd..4d68fcb1 100644 --- a/docs/scripts/azure/delete-users-and-assigned-roles.md +++ b/docs/scripts/azure/delete-users-and-assigned-roles.md @@ -1,12 +1,33 @@ -# deleteUsersAndAssignedRoles.ps1 +# ๐Ÿ‘ฅ deleteUsersAndAssignedRoles.ps1 > **Removes DevCenter role assignments from the current signed-in user** -## Overview +--- + +## ๐Ÿ“‘ 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) + +--- + +## ๐ŸŽฏ 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. -## Flow Visualization +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“Š Flow Visualization ```mermaid flowchart TD @@ -60,14 +81,26 @@ flowchart TD classDef error fill:#F44336,stroke:#C62828,color:#fff ``` -## Parameters +--- + +[โฌ†๏ธ 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 | -## Prerequisites +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Prerequisites ### Required Tools @@ -81,7 +114,13 @@ flowchart TD - **Azure**: `Microsoft.Authorization/roleAssignments/delete` at subscription scope - Typically requires **Owner** or **User Access Administrator** role -## Removed Roles +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”‘ Removed Roles The script removes these DevCenter-specific roles: @@ -92,7 +131,13 @@ The script removes these DevCenter-specific roles: | `Deployment Environments Reader` | View deployment environments | | `Deployment Environments User` | Use deployment environments | -## Functions Reference +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Functions Reference ### Function: `Remove-UserRoleAssignment` @@ -136,7 +181,13 @@ The script removes these DevCenter-specific roles: 3. Calls `Remove-UserRoleAssignment` for each role 4. Tracks success/failure of each removal -## Usage Examples +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Usage Examples ### Basic Usage (Current Subscription) @@ -184,7 +235,13 @@ User role assignments cleanup completed successfully. -## Error Handling +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš ๏ธ Error Handling ### Error Action Preference From c09ec628aab763743b5000d44543f845aab1a8ef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 11:39:52 -0500 Subject: [PATCH 13/44] Enhance documentation for generateDeploymentCredentials.ps1 by adding a table of contents, improving section titles, and incorporating emojis for better clarity and navigation. --- .../azure/generate-deployment-credentials.md | 111 ++++++++++++++++-- 1 file changed, 98 insertions(+), 13 deletions(-) diff --git a/docs/scripts/azure/generate-deployment-credentials.md b/docs/scripts/azure/generate-deployment-credentials.md index 39e3978b..6bd20c22 100644 --- a/docs/scripts/azure/generate-deployment-credentials.md +++ b/docs/scripts/azure/generate-deployment-credentials.md @@ -1,12 +1,37 @@ -# generateDeploymentCredentials.ps1 +# ๐Ÿ”‘ generateDeploymentCredentials.ps1 > **Creates Azure service principal and GitHub secret for CI/CD pipelines** -## Overview +--- + +## ๐Ÿ“‘ 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. -## Flow Visualization +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“Š Flow Visualization ```mermaid flowchart TD @@ -55,7 +80,13 @@ flowchart TD classDef error fill:#F44336,stroke:#C62828,color:#fff ``` -## Service Principal Creation Flow +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”„ Service Principal Creation Flow ```mermaid sequenceDiagram @@ -84,14 +115,26 @@ sequenceDiagram GhRepo-->>Script: Secret created ``` -## Parameters +--- + +[โฌ†๏ธ 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 | -## Prerequisites +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Prerequisites ### Required Tools @@ -107,7 +150,13 @@ sequenceDiagram - **Azure AD**: `Application.ReadWrite.All` or Application Administrator - **GitHub**: Repository admin access to create secrets -## Assigned Roles +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ‘ฅ Assigned Roles The created service principal receives these roles at subscription scope: @@ -117,7 +166,13 @@ The created service principal receives these roles at subscription scope: | `User Access Administrator` | Create role assignments for deployed resources | | `Managed Identity Contributor` | Create and manage managed identities | -## Functions Reference +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Functions Reference ### Function: `New-AzureDeploymentCredentials` @@ -169,7 +224,13 @@ The created service principal receives these roles at subscription scope: **Called Script:** `..\GitHub\createGitHubSecretAzureCredentials.ps1` -## Usage Examples +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Usage Examples ### Create Deployment Credentials @@ -215,7 +276,13 @@ Deployment credentials generation completed. -## Error Handling +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš ๏ธ Error Handling ### Error Action Preference @@ -240,7 +307,13 @@ The script continues with warnings if: Credentials are displayed on console if GitHub secret creation fails. -## Security Considerations +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”’ Security Considerations ### Credential Exposure @@ -270,7 +343,13 @@ Consider if these are necessary for your workflow. - Secret value cannot be read after creation - Audit logs track secret usage -## Troubleshooting +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ› ๏ธ Troubleshooting ### Common Issues @@ -295,7 +374,13 @@ az ad sp list --display-name "Contoso DevBox CI/CD" --query "[].{appId:appId, di gh secret list ``` -## Related Scripts +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Related Scripts | Script | Purpose | Link | |--------|---------|------| From 68d5911a059bc5920aa8e551d219c3631b983919 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 11:40:42 -0500 Subject: [PATCH 14/44] Enhance documentation for cleanUp.ps1 and winget-update.ps1 by adding a table of contents, improving section titles, and incorporating emojis for better clarity and navigation. --- docs/scripts/configuration/clean-up.md | 102 +++++++++++++-- docs/scripts/configuration/winget-update.md | 120 ++++++++++++++++-- .../create-github-secret-azure-credentials.md | 111 ++++++++++++++-- .../delete-github-secret-azure-credentials.md | 93 ++++++++++++-- 4 files changed, 376 insertions(+), 50 deletions(-) diff --git a/docs/scripts/configuration/clean-up.md b/docs/scripts/configuration/clean-up.md index da0b66be..6ca3c865 100644 --- a/docs/scripts/configuration/clean-up.md +++ b/docs/scripts/configuration/clean-up.md @@ -1,12 +1,36 @@ -# cleanUp.ps1 +# ๐Ÿงน cleanUp.ps1 > **Removes Azure resource groups for DevExp-DevBox environment** -## Overview +--- + +## ๐Ÿ“‘ 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. -## Flow Visualization +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“Š Flow Visualization ```mermaid flowchart TD @@ -53,7 +77,13 @@ flowchart TD classDef error fill:#F44336,stroke:#C62828,color:#fff ``` -## Parameters +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Parameters | Parameter | Type | Required | Default | Validation | Description | |-----------|------|----------|---------|------------|-------------| @@ -61,7 +91,13 @@ flowchart TD | `-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 | -## Prerequisites +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Prerequisites ### Required Tools @@ -75,7 +111,13 @@ flowchart TD - **Azure**: Contributor or Owner on the subscription - Permission to delete resource groups and deployments -## Resource Groups Deleted +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ—‚๏ธ Resource Groups Deleted Based on the naming convention `{WorkloadName}-{type}-{EnvName}-{Location}-rg`: @@ -98,7 +140,13 @@ devexp-monitoring-demo-eastus2-rg devexp-security-demo-eastus2-rg ``` -## Functions Reference +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Functions Reference ### Function: `Remove-AzureResourceGroup` @@ -147,7 +195,13 @@ devexp-security-demo-eastus2-rg - `Default-ActivityLogAlerts` - `DefaultResourceGroup-WUS2` -## Usage Examples +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Usage Examples ### Default Cleanup @@ -201,7 +255,13 @@ All resource group deletions initiated successfully. -## Error Handling +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš ๏ธ Error Handling ### Error Action Preference @@ -233,7 +293,13 @@ The script is **idempotent**: - Safe to run multiple times - No error if already deleted -## Troubleshooting +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ› ๏ธ Troubleshooting ### Common Issues @@ -261,7 +327,13 @@ az group list --query "[?contains(name, 'devexp')]" --output table az lock delete --name {lock-name} --resource-group {rg-name} ``` -## Security Considerations +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”’ Security Considerations ### Destructive Operation @@ -283,7 +355,13 @@ Azure resource locks can prevent accidental deletion: - Remove locks before running cleanup - Or use Azure portal to delete locked resources -## Related Scripts +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Related Scripts | Script | Purpose | Link | |--------|---------|------| diff --git a/docs/scripts/configuration/winget-update.md b/docs/scripts/configuration/winget-update.md index 58dadff1..7545d37d 100644 --- a/docs/scripts/configuration/winget-update.md +++ b/docs/scripts/configuration/winget-update.md @@ -1,12 +1,38 @@ -# winget-update.ps1 +# ๐Ÿ“ฆ winget-update.ps1 > **Silently updates all Microsoft Store applications using Windows Package Manager** -## Overview +--- + +## ๐Ÿ“‘ 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. -## Flow Visualization +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“Š Flow Visualization ```mermaid flowchart TD @@ -54,7 +80,13 @@ flowchart TD classDef error fill:#F44336,stroke:#C62828,color:#fff ``` -## Update Process Flow +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”„ Update Process Flow ```mermaid sequenceDiagram @@ -90,11 +122,23 @@ sequenceDiagram Script->>Log: Complete - log file path ``` -## Parameters +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Parameters This script has no parameters. All configuration is handled internally. -## Prerequisites +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Prerequisites ### Required Tools @@ -108,7 +152,13 @@ This script has no parameters. All configuration is handled internally. - **Elevated (Administrator)**: Required for machine-wide app updates - **Standard User**: Will update user-scoped apps only -## Configuration +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ› ๏ธ Configuration ### Environment Variables Set @@ -130,7 +180,13 @@ This script has no parameters. All configuration is handled internally. - **Log File Format:** `upgrade-YYYYMMDD-HHMMSS.log` - **Log Levels:** `[INFO ]`, `[WARN ]`, `[ERROR]` -## Functions Reference +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Functions Reference ### Function: `Write-LogInfo` @@ -235,7 +291,13 @@ This script has no parameters. All configuration is handled internally. - `--accept-package-agreements` - `--disable-interactivity` -## Usage Examples +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Usage Examples ### Standard Execution @@ -287,7 +349,13 @@ No applicable upgrade found. -## Error Handling +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš ๏ธ Error Handling ### Exit Codes @@ -302,7 +370,13 @@ No applicable upgrade found. - Individual app update failures don't stop the process - Service start failures are logged as warnings -## Troubleshooting +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ” Troubleshooting ### Common Issues @@ -333,7 +407,13 @@ winget source reset --force winget source update ``` -## DSC Integration +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”„ DSC Integration This script is designed to work with Windows Desired State Configuration (DSC). Related DSC files: @@ -342,7 +422,13 @@ This script is designed to work with Windows Desired State Configuration (DSC). | `winget-upgrade-packages.dsc.yaml` | DSC configuration for package updates | | `common-config.dsc.yaml` | Common DSC configuration | -## Security Considerations +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”’ Security Considerations ### Execution Policy @@ -371,7 +457,13 @@ The script automatically accepts: Review these agreements at [Microsoft Store Terms](https://www.microsoft.com/store/b/terms-of-use). -## Related Files +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Related Files | File | Purpose | Location | |------|---------|----------| diff --git a/docs/scripts/github/create-github-secret-azure-credentials.md b/docs/scripts/github/create-github-secret-azure-credentials.md index f8d41f04..6214d249 100644 --- a/docs/scripts/github/create-github-secret-azure-credentials.md +++ b/docs/scripts/github/create-github-secret-azure-credentials.md @@ -1,12 +1,37 @@ -# createGitHubSecretAzureCredentials.ps1 +# ๐Ÿ” createGitHubSecretAzureCredentials.ps1 > **Creates a GitHub repository secret for Azure service principal credentials** -## Overview +--- + +## ๐Ÿ“‘ 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. -## Flow Visualization +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“Š Flow Visualization ```mermaid flowchart TD @@ -49,7 +74,13 @@ flowchart TD classDef error fill:#F44336,stroke:#C62828,color:#fff ``` -## Parameters +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Parameters | Parameter | Type | Required | Default | Validation | Description | |-----------|------|----------|---------|------------|-------------| @@ -57,7 +88,13 @@ flowchart TD **Aliases:** `ghSecretBody` -## Prerequisites +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Prerequisites ### Required Tools @@ -71,7 +108,13 @@ flowchart TD - **GitHub**: Repository admin or secrets write permission - Must be in a Git repository directory or specify repository -## Expected Input Format +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ฅ Expected Input Format The `GhSecretBody` parameter should contain Azure service principal credentials in this JSON format: @@ -86,7 +129,13 @@ The `GhSecretBody` parameter should contain Azure service principal credentials This format is output by `az ad sp create-for-rbac --json-auth`. -## Functions Reference +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Functions Reference ### Function: `Connect-GitHubCli` @@ -119,7 +168,13 @@ This format is output by `az ad sp create-for-rbac --json-auth`. **Command:** `gh secret set {SecretName} --body {SecretValue}` -## Usage Examples +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Usage Examples ### Direct Execution with JSON @@ -162,7 +217,13 @@ You can now use this secret in your GitHub Actions workflows. -## Using the Secret in GitHub Actions +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Using the Secret in GitHub Actions After creating the secret, use it in your workflow: @@ -186,7 +247,13 @@ jobs: az group create --name my-rg --location eastus ``` -## Error Handling +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš ๏ธ Error Handling ### Error Action Preference @@ -202,7 +269,13 @@ $WarningPreference = 'Stop' | `0` | Secret created successfully | | `1` | Secret creation failed | -## Troubleshooting +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ› ๏ธ Troubleshooting ### Common Issues @@ -230,7 +303,13 @@ gh auth status gh auth token ``` -## Security Considerations +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”’ Security Considerations ### Secret Handling @@ -251,7 +330,13 @@ When rotating credentials: 2. Update secret with same command (overwrites existing) 3. Delete old service principal -## Related Scripts +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Related Scripts | Script | Purpose | Link | |--------|---------|------| diff --git a/docs/scripts/github/delete-github-secret-azure-credentials.md b/docs/scripts/github/delete-github-secret-azure-credentials.md index 930cb954..6d49ba25 100644 --- a/docs/scripts/github/delete-github-secret-azure-credentials.md +++ b/docs/scripts/github/delete-github-secret-azure-credentials.md @@ -1,12 +1,35 @@ -# deleteGitHubSecretAzureCredentials.ps1 +# ๐Ÿ—‘๏ธ deleteGitHubSecretAzureCredentials.ps1 > **Removes a GitHub repository secret** -## Overview +--- + +## ๐Ÿ“‘ 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. -## Flow Visualization +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“Š Flow Visualization ```mermaid flowchart TD @@ -50,7 +73,13 @@ flowchart TD classDef error fill:#F44336,stroke:#C62828,color:#fff ``` -## Parameters +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Parameters | Parameter | Type | Required | Default | Validation | Description | |-----------|------|----------|---------|------------|-------------| @@ -58,7 +87,13 @@ flowchart TD **Aliases:** `ghSecretName` -## Prerequisites +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš™๏ธ Prerequisites ### Required Tools @@ -72,7 +107,13 @@ flowchart TD - **GitHub**: Repository admin or secrets delete permission - Must be in a Git repository directory or specify repository -## Functions Reference +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Functions Reference ### Function: `Connect-GitHubCli` @@ -111,7 +152,13 @@ flowchart TD **Command:** `gh secret remove {SecretName}` -## Usage Examples +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ“ Usage Examples ### Delete Default Azure Credentials Secret @@ -146,7 +193,13 @@ GitHub secret deletion completed. -## Error Handling +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## โš ๏ธ Error Handling ### Error Action Preference @@ -170,7 +223,13 @@ The script is **idempotent**: - Safe to run multiple times - No error if already deleted -## Troubleshooting +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ› ๏ธ Troubleshooting ### Common Issues @@ -195,7 +254,13 @@ gh secret list gh secret list | findstr "AZURE_CREDENTIALS" ``` -## Security Considerations +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”’ Security Considerations ### Immediate Effect @@ -214,7 +279,13 @@ gh secret list | findstr "AZURE_CREDENTIALS" - GitHub audit logs record secret deletion - Deletion cannot be undone - must recreate secret -## Related Scripts +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Related Scripts | Script | Purpose | Link | |--------|---------|------| From 0018156353b2505ef311747383a97d74a57be4ab Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 11:43:46 -0500 Subject: [PATCH 15/44] Enhance documentation for architecture files by adding navigation details, target audience notes, and improving section titles for better clarity and accessibility. --- docs/architecture/01-business-architecture.md | 37 +++++++++++++++++++ docs/architecture/02-data-architecture.md | 37 +++++++++++++++++++ .../03-application-architecture.md | 37 +++++++++++++++++++ .../04-technology-architecture.md | 37 +++++++++++++++++++ docs/architecture/05-security-architecture.md | 37 +++++++++++++++++++ .../07-deployment-architecture.md | 37 +++++++++++++++++++ 6 files changed, 222 insertions(+) diff --git a/docs/architecture/01-business-architecture.md b/docs/architecture/01-business-architecture.md index 5c0bf70a..b9778afc 100644 --- a/docs/architecture/01-business-architecture.md +++ b/docs/architecture/01-business-architecture.md @@ -1,7 +1,34 @@ +--- +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 | @@ -459,3 +486,13 @@ flowchart TB - [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 index 975178c3..4edd879d 100644 --- a/docs/architecture/02-data-architecture.md +++ b/docs/architecture/02-data-architecture.md @@ -1,7 +1,34 @@ +--- +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 | @@ -725,3 +752,13 @@ Configure VS Code to validate YAML files: - [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 index c680e8b5..fcb5e541 100644 --- a/docs/architecture/03-application-architecture.md +++ b/docs/architecture/03-application-architecture.md @@ -1,7 +1,34 @@ +--- +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 | @@ -775,3 +802,13 @@ output resourceName string = childResource.name - [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 index 83ae6b19..4f8bfcf4 100644 --- a/docs/architecture/04-technology-architecture.md +++ b/docs/architecture/04-technology-architecture.md @@ -1,7 +1,34 @@ +--- +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 | @@ -705,3 +732,13 @@ flowchart TB - [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 index 94e66e03..7965fe9d 100644 --- a/docs/architecture/05-security-architecture.md +++ b/docs/architecture/05-security-architecture.md @@ -1,7 +1,34 @@ +--- +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 | @@ -734,3 +761,13 @@ flowchart TB - [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 index 2ded4c76..ccefaecb 100644 --- a/docs/architecture/07-deployment-architecture.md +++ b/docs/architecture/07-deployment-architecture.md @@ -1,7 +1,34 @@ +--- +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 @@ -463,3 +490,13 @@ flowchart LR - [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* + +
From 63e969f19e58e85201545b957e1e43905c9a0aae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 11:48:00 -0500 Subject: [PATCH 16/44] Enhance documentation for various scripts by adding descriptions, target audience notes, reading times, and navigation details for improved clarity and accessibility. --- docs/devops/README.md | 36 +++++++++++++++++ docs/devops/ci.md | 36 +++++++++++++++++ docs/devops/deploy.md | 37 +++++++++++++++++ docs/devops/release.md | 36 +++++++++++++++++ docs/scripts/README.md | 37 +++++++++++++++++ docs/scripts/azure/create-custom-role.md | 39 ++++++++++++++++++ .../azure/create-users-and-assign-role.md | 36 +++++++++++++++++ .../azure/delete-deployment-credentials.md | 39 ++++++++++++++++++ .../azure/delete-users-and-assigned-roles.md | 36 +++++++++++++++++ .../azure/generate-deployment-credentials.md | 40 +++++++++++++++++++ docs/scripts/clean-setup.md | 39 ++++++++++++++++++ docs/scripts/configuration/clean-up.md | 39 ++++++++++++++++++ docs/scripts/configuration/winget-update.md | 40 +++++++++++++++++++ .../create-github-secret-azure-credentials.md | 37 +++++++++++++++++ .../delete-github-secret-azure-credentials.md | 39 ++++++++++++++++++ docs/scripts/setup.md | 37 +++++++++++++++++ 16 files changed, 603 insertions(+) diff --git a/docs/devops/README.md b/docs/devops/README.md index 17d347a6..242b2357 100644 --- a/docs/devops/README.md +++ b/docs/devops/README.md @@ -1,7 +1,33 @@ +--- +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 > ๐Ÿ“– Comprehensive documentation for GitHub Actions workflows in the Dev Box Accelerator project. +> [!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 @@ -256,3 +282,13 @@ The project uses a **branch-based semantic versioning** strategy: - [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](#-table-of-contents) | [CI Workflow โ†’](ci.md) + +*DevExp-DevBox โ€ข DevOps Documentation* + +
diff --git a/docs/devops/ci.md b/docs/devops/ci.md index f05e9a3d..8e9d6062 100644 --- a/docs/devops/ci.md +++ b/docs/devops/ci.md @@ -1,5 +1,31 @@ +--- +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 @@ -232,3 +258,13 @@ The CI workflow implements a **branch-based versioning strategy**: - [Release Workflow](release.md) - Full release process with GitHub Releases - [Deploy Workflow](deploy.md) - Azure deployment process + +--- + +
+ +[โ† DevOps Overview](README.md) | [โฌ†๏ธ Back to Top](#-table-of-contents) | [Deploy Workflow โ†’](deploy.md) + +*DevExp-DevBox โ€ข CI Workflow Documentation* + +
diff --git a/docs/devops/deploy.md b/docs/devops/deploy.md index dbb92cce..b51d7d48 100644 --- a/docs/devops/deploy.md +++ b/docs/devops/deploy.md @@ -1,5 +1,32 @@ +--- +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 @@ -318,3 +345,13 @@ gh workflow run deploy.yml \ - [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](#-table-of-contents) | [Release Workflow โ†’](release.md) + +*DevExp-DevBox โ€ข Deploy Workflow Documentation* + +
diff --git a/docs/devops/release.md b/docs/devops/release.md index faa6b6bd..d8595f0d 100644 --- a/docs/devops/release.md +++ b/docs/devops/release.md @@ -1,5 +1,31 @@ +--- +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 @@ -439,3 +465,13 @@ gh workflow run release.yml -r feature/my-feature -f force_release=true - [CI Workflow](ci.md) - Continuous integration process - [Deploy Workflow](deploy.md) - Azure deployment process + +--- + +
+ +[โ† Deploy Workflow](deploy.md) | [โฌ†๏ธ Back to Top](#-table-of-contents) + +*DevExp-DevBox โ€ข Release Workflow Documentation* + +
diff --git a/docs/scripts/README.md b/docs/scripts/README.md index 34cdb730..dacf0d54 100644 --- a/docs/scripts/README.md +++ b/docs/scripts/README.md @@ -1,7 +1,34 @@ +--- +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 @@ -340,3 +367,13 @@ When adding new PowerShell scripts: 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/create-custom-role.md b/docs/scripts/azure/create-custom-role.md index 6789ea69..c5ee74d6 100644 --- a/docs/scripts/azure/create-custom-role.md +++ b/docs/scripts/azure/create-custom-role.md @@ -1,7 +1,36 @@ +--- +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 @@ -290,3 +319,13 @@ az role definition list --custom-role-only true --query "[?roleName=='Contoso De | `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) | + +--- + +
+ +[โ† 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 index b5fa1f31..17aabe21 100644 --- a/docs/scripts/azure/create-users-and-assign-role.md +++ b/docs/scripts/azure/create-users-and-assign-role.md @@ -1,7 +1,33 @@ +--- +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 @@ -290,3 +316,13 @@ az role assignment list --assignee $userId --query "[].roleDefinitionName" --out | `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) | + +--- + +
+ +[โ† 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 index fa860851..f9d89228 100644 --- a/docs/scripts/azure/delete-deployment-credentials.md +++ b/docs/scripts/azure/delete-deployment-credentials.md @@ -1,7 +1,36 @@ +--- +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 @@ -273,3 +302,13 @@ az ad app list --display-name "ContosoDevEx GitHub Actions Enterprise App" --que | `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) | + +--- + +
+ +[โ† 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 index 4d68fcb1..180b3888 100644 --- a/docs/scripts/azure/delete-users-and-assigned-roles.md +++ b/docs/scripts/azure/delete-users-and-assigned-roles.md @@ -1,7 +1,33 @@ +--- +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 @@ -304,3 +330,13 @@ az role assignment list --assignee $userId --query "[].roleDefinitionName" --out | `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) | + +--- + +
+ +[โ† 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 index 6bd20c22..79843d2f 100644 --- a/docs/scripts/azure/generate-deployment-credentials.md +++ b/docs/scripts/azure/generate-deployment-credentials.md @@ -1,7 +1,37 @@ +--- +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 @@ -388,3 +418,13 @@ gh secret list | `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) | + +--- + +
+ +[โ† 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 index 5ba58771..088467a2 100644 --- a/docs/scripts/clean-setup.md +++ b/docs/scripts/clean-setup.md @@ -1,7 +1,36 @@ +--- +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 @@ -330,3 +359,13 @@ Enable verbose output: | `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/clean-up.md b/docs/scripts/configuration/clean-up.md index 6ca3c865..86c9c6a4 100644 --- a/docs/scripts/configuration/clean-up.md +++ b/docs/scripts/configuration/clean-up.md @@ -1,7 +1,36 @@ +--- +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 @@ -367,3 +396,13 @@ Azure resource locks can prevent accidental deletion: |--------|---------|------| | `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 index 7545d37d..cc97641f 100644 --- a/docs/scripts/configuration/winget-update.md +++ b/docs/scripts/configuration/winget-update.md @@ -1,7 +1,37 @@ +--- +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 @@ -470,3 +500,13 @@ Review these agreements at [Microsoft Store Terms](https://www.microsoft.com/sto | `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/create-github-secret-azure-credentials.md b/docs/scripts/github/create-github-secret-azure-credentials.md index 6214d249..8032365a 100644 --- a/docs/scripts/github/create-github-secret-azure-credentials.md +++ b/docs/scripts/github/create-github-secret-azure-credentials.md @@ -1,7 +1,34 @@ +--- +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 @@ -343,3 +370,13 @@ When rotating credentials: | `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 index 6d49ba25..657882a1 100644 --- a/docs/scripts/github/delete-github-secret-azure-credentials.md +++ b/docs/scripts/github/delete-github-secret-azure-credentials.md @@ -1,7 +1,36 @@ +--- +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 @@ -292,3 +321,13 @@ gh secret list | findstr "AZURE_CREDENTIALS" | `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 index 65a1588d..3ab51007 100644 --- a/docs/scripts/setup.md +++ b/docs/scripts/setup.md @@ -1,7 +1,34 @@ +--- +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 @@ -518,3 +545,13 @@ $VerbosePreference = 'Continue' | `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* + +
From 25c241bd2088dfd41d52ea25dcdddc943fc9e6cc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 11:57:10 -0500 Subject: [PATCH 17/44] Enhance documentation for architecture files by adding titles to diagrams, improving section titles, and incorporating emojis for better clarity and navigation. --- docs/architecture/01-business-architecture.md | 182 ++++++++---- docs/architecture/02-data-architecture.md | 268 ++++++++++++------ .../03-application-architecture.md | 134 +++++---- 3 files changed, 380 insertions(+), 204 deletions(-) diff --git a/docs/architecture/01-business-architecture.md b/docs/architecture/01-business-architecture.md index b9778afc..4359eb94 100644 --- a/docs/architecture/01-business-architecture.md +++ b/docs/architecture/01-business-architecture.md @@ -86,6 +86,9 @@ The **DevExp-DevBox Landing Zone Accelerator** is an enterprise-grade infrastruc 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 @@ -137,13 +140,18 @@ The DevExp-DevBox accelerator serves organizations that: ### 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"] @@ -151,32 +159,47 @@ flowchart TB 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 - CTO --> PE - CISO --> SEC - CFO --> OPS + %% ===== RELATIONSHIPS ===== + CTO -->|"oversees"| PE + CISO -->|"directs"| SEC + CFO -->|"manages"| OPS - PE --> DEV - SA --> LEAD - SEC --> DEV + PE -->|"supports"| DEV + SA -->|"guides"| LEAD + SEC -->|"enables"| DEV - AUD -.-> SEC - MS -.-> PE + AUD -.->|"audits"| SEC + MS -.->|"assists"| PE - style Executive fill:#2196F3,color:#fff - style Technical fill:#FF9800,color:#fff - style Users fill:#4CAF50,color:#fff - style External fill:#9C27B0,color:#fff + %% ===== 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 @@ -207,40 +230,58 @@ flowchart TB ### 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"] + 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"] + 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"] + 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"] + C13["๐ŸŒ Network Provisioning"] + C14["๐Ÿ”’ Network Security"] + C15["๐Ÿ”— Hybrid Connectivity"] end end - style L2A fill:#FF9800,color:#fff - style L2B fill:#F44336,color:#fff - style L2C fill:#4CAF50,color:#fff - style L2D fill:#2196F3,color:#fff + %% ===== 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 @@ -283,43 +324,69 @@ flowchart TB ### Primary Value Stream: Developer Onboarding ```mermaid +--- +title: Developer Onboarding Value Stream +--- flowchart LR - subgraph Trigger["Trigger"] - T1["New Developer Joins"] + %% ===== TRIGGER ===== + subgraph Trigger["๐ŸŽฏ Trigger"] + T1["๐Ÿ‘ค New Developer Joins"] end - subgraph Request["Request Phase"] - R1["Request Dev Box Access"] - R2["Assign to Project"] - R3["Select Dev Box Pool"] + %% ===== REQUEST PHASE ===== + subgraph Request["๐Ÿ“ Request Phase"] + R1["๐Ÿ“‹ Request Dev Box Access"] + R2["๐Ÿ“ Assign to Project"] + R3["๐ŸŠ Select Dev Box Pool"] end - subgraph Provision["Provisioning Phase"] - P1["Create Dev Box Instance"] - P2["Apply DSC Configuration"] - P3["Clone Repositories"] + %% ===== PROVISIONING PHASE ===== + subgraph Provision["โš™๏ธ Provisioning Phase"] + P1["๐Ÿ–ฅ๏ธ Create Dev Box Instance"] + P2["๐Ÿ”ง Apply DSC Configuration"] + P3["๐Ÿ“‚ Clone Repositories"] end - subgraph Validate["Validation Phase"] - V1["Verify Tools Installed"] - V2["Test Connectivity"] - V3["Confirm Access"] + %% ===== VALIDATION PHASE ===== + subgraph Validate["โœ… Validation Phase"] + V1["๐Ÿ” Verify Tools Installed"] + V2["๐ŸŒ Test Connectivity"] + V3["๐Ÿ” Confirm Access"] end - subgraph Outcome["Outcome"] - O1["Developer Productive"] + %% ===== OUTCOME ===== + subgraph Outcome["๐Ÿ† Outcome"] + O1["๐Ÿš€ Developer Productive"] end - T1 --> R1 --> R2 --> R3 - R3 --> P1 --> P2 --> P3 - P3 --> V1 --> V2 --> V3 - V3 --> O1 + %% ===== 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 - style Trigger fill:#9C27B0,color:#fff - style Request fill:#2196F3,color:#fff - style Provision fill:#FF9800,color:#fff - style Validate fill:#4CAF50,color:#fff - style Outcome fill:#4CAF50,color:#fff + %% ===== 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 @@ -334,6 +401,9 @@ flowchart LR ### Secondary Value Stream: Environment Lifecycle ```mermaid +--- +title: Environment Lifecycle States +--- stateDiagram-v2 [*] --> Requested: Developer Request Requested --> Provisioning: Auto-Approved diff --git a/docs/architecture/02-data-architecture.md b/docs/architecture/02-data-architecture.md index 4edd879d..bab71e8a 100644 --- a/docs/architecture/02-data-architecture.md +++ b/docs/architecture/02-data-architecture.md @@ -59,37 +59,56 @@ The DevExp-DevBox accelerator manages four primary categories of data, each with ### Data Categories ```mermaid +--- +title: Data Categories Overview +--- flowchart TB - subgraph DataCategories["Data Categories"] - subgraph Config["Configuration Data"] - C1["Resource Organization"] - C2["Security Settings"] - C3["Workload Definitions"] + %% ===== DATA CATEGORIES ===== + subgraph DataCategories["๐Ÿ“Š Data Categories"] + %% ===== CONFIGURATION DATA ===== + subgraph Config["โš™๏ธ Configuration Data"] + C1["๐Ÿ“ Resource Organization"] + C2["๐Ÿ”’ Security Settings"] + C3["๐Ÿ“ฆ Workload Definitions"] end - subgraph Secrets["Secrets & Credentials"] - S1["GitHub PAT Tokens"] - S2["Azure DevOps PATs"] - S3["Service Principal Credentials"] + %% ===== SECRETS & CREDENTIALS ===== + subgraph Secrets["๐Ÿ” Secrets & Credentials"] + S1["๐Ÿ”‘ GitHub PAT Tokens"] + S2["๐ŸŽซ Azure DevOps PATs"] + S3["๐Ÿ‘ค Service Principal Credentials"] end - subgraph Telemetry["Telemetry & Diagnostics"] - T1["Resource Logs"] - T2["Metrics"] - T3["Activity Logs"] + %% ===== TELEMETRY & DIAGNOSTICS ===== + subgraph Telemetry["๐Ÿ“ถ Telemetry & Diagnostics"] + T1["๐Ÿ“ Resource Logs"] + T2["๐Ÿ“Š Metrics"] + T3["๐Ÿ“‹ Activity Logs"] end - subgraph State["Deployment State"] - ST1["azd Environment"] - ST2["Bicep Outputs"] - ST3["Resource IDs"] + %% ===== DEPLOYMENT STATE ===== + subgraph State["๐Ÿ’พ Deployment State"] + ST1["๐ŸŒ azd Environment"] + ST2["๐Ÿ“„ Bicep Outputs"] + ST3["๐Ÿ†” Resource IDs"] end end - style Config fill:#2196F3,color:#fff - style Secrets fill:#F44336,color:#fff - style Telemetry fill:#4CAF50,color:#fff - style State fill:#FF9800,color:#fff + %% ===== 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 @@ -121,6 +140,9 @@ The accelerator uses YAML-based configuration files with JSON Schema validation. ### Entity Relationship Diagram ```mermaid +--- +title: Configuration Data Entity Relationships +--- erDiagram LANDING_ZONES ||--o{ RESOURCE_GROUP : contains LANDING_ZONES { @@ -368,36 +390,53 @@ projects: ### Secret Types and Lifecycle ```mermaid +--- +title: Secret Types and Lifecycle +--- flowchart TB - subgraph Sources["Secret Sources"] - GH["GitHub CLI\n(gh auth token)"] - ADO["Azure DevOps CLI\nManual Entry"] - SP["Service Principal\n(az ad sp create-for-rbac)"] + %% ===== 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 - subgraph Storage["Secret Storage"] - KV["Azure Key Vault\n(gha-token secret)"] - GHS["GitHub Secrets\n(AZURE_CREDENTIALS)"] - ENV["azd Environment\n(.azure/.env)"] + %% ===== SECRET STORAGE ===== + subgraph Storage["๐Ÿ” Secret Storage"] + KV["๐Ÿ›๏ธ Azure Key Vault
(gha-token secret)"] + GHS["๐Ÿ“ฆ GitHub Secrets
(AZURE_CREDENTIALS)"] + ENV["๐Ÿ“„ azd Environment
(.azure/.env)"] end - subgraph Consumers["Secret Consumers"] - CAT["DevCenter Catalogs\n(Private Repos)"] - WF["GitHub Actions\n(OIDC Auth)"] - DEP["azd Provision\n(Key Vault)"] + %% ===== SECRET CONSUMERS ===== + subgraph Consumers["โšก Secret Consumers"] + CAT["๐Ÿ“š DevCenter Catalogs
(Private Repos)"] + WF["๐Ÿ”„ GitHub Actions
(OIDC Auth)"] + DEP["๐Ÿš€ azd Provision
(Key Vault)"] end - GH --> ENV --> KV - ADO --> ENV --> KV - SP --> GHS + %% ===== 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 - KV --> CAT - GHS --> WF - KV --> DEP + class GH,ADO,SP datastore + class KV,GHS,ENV failed + class CAT,WF,DEP secondary - style Sources fill:#FF9800,color:#fff - style Storage fill:#F44336,color:#fff - style Consumers fill:#4CAF50,color:#fff + 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 @@ -414,11 +453,14 @@ flowchart TB ### 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) + 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 @@ -442,39 +484,55 @@ sequenceDiagram All resources send diagnostic data to a centralized Log Analytics workspace for unified monitoring and analysis. ```mermaid +--- +title: Log Analytics Data Collection +--- flowchart LR - subgraph Resources["Azure Resources"] - DC["DevCenter"] - KV["Key Vault"] - VN["Virtual Network"] - LA["Log Analytics"] + %% ===== AZURE RESOURCES ===== + subgraph Resources["๐Ÿข Azure Resources"] + DC["๐Ÿ–ฅ๏ธ DevCenter"] + KV["๐Ÿ” Key Vault"] + VN["๐ŸŒ Virtual Network"] + LA["๐Ÿ“Š Log Analytics"] end - subgraph LAW["Log Analytics Workspace"] - LOGS["Diagnostic Logs"] - MET["Metrics"] - ACT["Activity Logs"] + %% ===== LOG ANALYTICS WORKSPACE ===== + subgraph LAW["๐Ÿ“ˆ Log Analytics Workspace"] + LOGS["๐Ÿ“ Diagnostic Logs"] + MET["๐Ÿ“Š Metrics"] + ACT["๐Ÿ“‹ Activity Logs"] end - subgraph Solutions["Solutions"] - AA["AzureActivity"] + %% ===== SOLUTIONS ===== + subgraph Solutions["๐Ÿ”ง Solutions"] + AA["โ˜๏ธ AzureActivity"] end - DC -->|DiagnosticSettings| LOGS - KV -->|DiagnosticSettings| LOGS - VN -->|DiagnosticSettings| LOGS - LA -->|DiagnosticSettings| LOGS + %% ===== 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 - DC -->|AllMetrics| MET - KV -->|AllMetrics| MET - VN -->|AllMetrics| MET + %% ===== 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 - LOGS --> AA - ACT --> AA + class DC,KV,VN,LA primary + class LOGS,MET,ACT secondary + class AA datastore - style Resources fill:#2196F3,color:#fff - style LAW fill:#4CAF50,color:#fff - style Solutions fill:#FF9800,color:#fff + 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 @@ -573,41 +631,65 @@ flowchart TB ### Secrets Flow Diagram ```mermaid +--- +title: Secrets Flow Diagram +--- flowchart TB - subgraph Setup["Setup Phase"] - CLI["gh auth token\nOR\nManual PAT Entry"] - PS["setUp.ps1 / setUp.sh"] + %% ===== SETUP PHASE ===== + subgraph Setup["๐Ÿ”ง Setup Phase"] + CLI["๐Ÿ”‘ gh auth token
OR
Manual PAT Entry"] + PS["๐Ÿ“œ setUp.ps1 / setUp.sh"] end - subgraph AZD["azd Environment"] - ENV[".azure/{env}/.env\nKEY_VAULT_SECRET='...'"] + %% ===== AZD ENVIRONMENT ===== + subgraph AZD["๐ŸŒ azd Environment"] + ENV["๐Ÿ“„ .azure/{env}/.env
KEY_VAULT_SECRET='...'"] end - subgraph Deploy["Deployment"] - PARAMS["main.parameters.json\n${KEY_VAULT_SECRET}"] - BICEP["security.bicep"] + %% ===== DEPLOYMENT ===== + subgraph Deploy["๐Ÿš€ Deployment"] + PARAMS["๐Ÿ“‹ main.parameters.json
${KEY_VAULT_SECRET}"] + BICEP["โš™๏ธ security.bicep"] end - subgraph Azure["Azure Resources"] - KV["Key Vault\ngha-token secret"] - DC["DevCenter\nsecretIdentifier reference"] + %% ===== AZURE RESOURCES ===== + subgraph Azure["โ˜๏ธ Azure Resources"] + KV["๐Ÿ›๏ธ Key Vault
gha-token secret"] + DC["๐Ÿ–ฅ๏ธ DevCenter
secretIdentifier reference"] end - subgraph Access["Runtime Access"] - CAT["Private Catalog\n(GitHub/ADO)"] + %% ===== RUNTIME ACCESS ===== + subgraph Access["๐Ÿ”“ Runtime Access"] + CAT["๐Ÿ“š Private Catalog
(GitHub/ADO)"] end - CLI --> PS --> ENV - ENV --> PARAMS --> BICEP - BICEP --> KV - KV --> DC - DC --> CAT - - style Setup fill:#FF9800,color:#fff - style AZD fill:#9C27B0,color:#fff - style Deploy fill:#2196F3,color:#fff - style Azure fill:#4CAF50,color:#fff - style Access fill:#F44336,color:#fff + %% ===== 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 ``` --- diff --git a/docs/architecture/03-application-architecture.md b/docs/architecture/03-application-architecture.md index fcb5e541..950946ca 100644 --- a/docs/architecture/03-application-architecture.md +++ b/docs/architecture/03-application-architecture.md @@ -59,64 +59,85 @@ The DevExp-DevBox accelerator is an Infrastructure as Code (IaC) application bui ### Solution Architecture ```mermaid +--- +title: Solution Architecture Overview +--- flowchart TB - subgraph Orchestration["Orchestration Layer"] - MAIN["main.bicep\n(Subscription Scope)"] + %% ===== ORCHESTRATION LAYER ===== + subgraph Orchestration["๐ŸŽฏ Orchestration Layer"] + MAIN["๐Ÿ“„ main.bicep
(Subscription Scope)"] end - subgraph LandingZones["Landing Zone Modules"] - SEC["security.bicep"] - MON["logAnalytics.bicep"] - WL["workload.bicep"] - CONN["connectivity.bicep"] + %% ===== LANDING ZONE MODULES ===== + subgraph LandingZones["๐Ÿ—๏ธ Landing Zone Modules"] + SEC["๐Ÿ” security.bicep"] + MON["๐Ÿ“Š logAnalytics.bicep"] + WL["๐Ÿ“ฆ workload.bicep"] + CONN["๐ŸŒ connectivity.bicep"] end - subgraph CoreResources["Core Resource Modules"] - KV["keyVault.bicep"] - LA["logAnalytics.bicep"] - DC["devCenter.bicep"] - VN["vnet.bicep"] + %% ===== CORE RESOURCE MODULES ===== + subgraph CoreResources["โš™๏ธ Core Resource Modules"] + KV["๐Ÿ”‘ keyVault.bicep"] + LA["๐Ÿ“ˆ logAnalytics.bicep"] + DC["๐Ÿ–ฅ๏ธ devCenter.bicep"] + VN["๐Ÿ”— vnet.bicep"] end - subgraph ProjectResources["Project Modules"] - PROJ["project.bicep"] - POOL["projectPool.bicep"] - PCAT["projectCatalog.bicep"] - PENV["projectEnvironmentType.bicep"] + %% ===== PROJECT MODULES ===== + subgraph ProjectResources["๐Ÿ“ Project Modules"] + PROJ["๐Ÿ“‹ project.bicep"] + POOL["๐ŸŠ projectPool.bicep"] + PCAT["๐Ÿ“š projectCatalog.bicep"] + PENV["๐ŸŒ projectEnvironmentType.bicep"] end - subgraph Identity["Identity Modules"] - DCRA["devCenterRoleAssignment.bicep"] - ORA["orgRoleAssignment.bicep"] - PIRA["projectIdentityRoleAssignment.bicep"] - KVA["keyVaultAccess.bicep"] + %% ===== IDENTITY MODULES ===== + subgraph Identity["๐Ÿ‘ค Identity Modules"] + DCRA["๐Ÿ” devCenterRoleAssignment.bicep"] + ORA["๐Ÿข orgRoleAssignment.bicep"] + PIRA["๐Ÿ‘ฅ projectIdentityRoleAssignment.bicep"] + KVA["๐Ÿ”‘ keyVaultAccess.bicep"] end - MAIN --> SEC - MAIN --> MON - MAIN --> WL - - SEC --> KV - MON --> LA - WL --> DC - WL --> CONN - - CONN --> VN - DC --> PROJ - PROJ --> POOL - PROJ --> PCAT - PROJ --> PENV - - DC --> DCRA - DC --> ORA - PROJ --> PIRA - SEC --> KVA - - style Orchestration fill:#E91E63,color:#fff - style LandingZones fill:#9C27B0,color:#fff - style CoreResources fill:#2196F3,color:#fff - style ProjectResources fill:#4CAF50,color:#fff - style Identity fill:#FF9800,color:#fff + %% ===== 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 @@ -156,32 +177,35 @@ flowchart TB ### Module Classification ```mermaid +--- +title: Bicep Module Classification +--- mindmap - root((Bicep Modules)) - Orchestration + root((๐Ÿ“ฆ Bicep Modules)) + ๐ŸŽฏ Orchestration main.bicep - Landing Zones + ๐Ÿ—๏ธ Landing Zones security.bicep workload.bicep - Infrastructure + ๐ŸŒ Infrastructure connectivity.bicep vnet.bicep networkConnection.bicep resourceGroup.bicep - Resources + โš™๏ธ Resources keyVault.bicep secret.bicep logAnalytics.bicep - Workload + ๐Ÿ“ฆ Workload devCenter.bicep catalog.bicep environmentType.bicep - Projects + ๐Ÿ“ Projects project.bicep projectPool.bicep projectCatalog.bicep projectEnvironmentType.bicep - Identity + ๐Ÿ‘ค Identity devCenterRoleAssignment.bicep devCenterRoleAssignmentRG.bicep orgRoleAssignment.bicep From 2c39a016c6299e8ec3480ed98a242a943bae8b13 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 11:58:29 -0500 Subject: [PATCH 18/44] Enhance documentation for application architecture by adding titles, improving section titles, and incorporating emojis for better clarity and navigation. --- .../03-application-architecture.md | 427 +++++++++++------- 1 file changed, 265 insertions(+), 162 deletions(-) diff --git a/docs/architecture/03-application-architecture.md b/docs/architecture/03-application-architecture.md index 950946ca..381938f1 100644 --- a/docs/architecture/03-application-architecture.md +++ b/docs/architecture/03-application-architecture.md @@ -225,96 +225,123 @@ mindmap ### Complete Dependency Tree ```mermaid +--- +title: Complete Module Dependency Tree +--- flowchart TB - subgraph L0["Layer 0: Orchestration"] - MAIN["main.bicep\n(targetScope: subscription)"] + %% ===== LAYER 0: ORCHESTRATION ===== + subgraph L0["๐ŸŽฏ Layer 0: Orchestration"] + MAIN["๐Ÿ“„ main.bicep
(targetScope: subscription)"] end - subgraph L1["Layer 1: Resource Groups"] - RG_SEC["Resource Group\n(Security)"] - RG_MON["Resource Group\n(Monitoring)"] - RG_WL["Resource Group\n(Workload)"] + %% ===== 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 - subgraph L2["Layer 2: Landing Zone Modules"] - SEC["security.bicep"] - LA["logAnalytics.bicep"] - WL["workload.bicep"] + %% ===== LAYER 2: LANDING ZONE MODULES ===== + subgraph L2["๐Ÿ—๏ธ Layer 2: Landing Zone Modules"] + SEC["๐Ÿ”’ security.bicep"] + LA["๐Ÿ“ˆ logAnalytics.bicep"] + WL["๐Ÿ“ฆ workload.bicep"] end - subgraph L3["Layer 3: Core Resources"] - KV["keyVault.bicep"] - LOG["Log Analytics\nWorkspace"] - DC["devCenter.bicep"] - CONN["connectivity.bicep"] + %% ===== LAYER 3: CORE RESOURCES ===== + subgraph L3["โš™๏ธ Layer 3: Core Resources"] + KV["๐Ÿ”‘ keyVault.bicep"] + LOG["๐Ÿ“Š Log Analytics
Workspace"] + DC["๐Ÿ–ฅ๏ธ devCenter.bicep"] + CONN["๐ŸŒ connectivity.bicep"] end - subgraph L4["Layer 4: Child Resources"] - SECRET["secret.bicep"] - CAT["catalog.bicep"] - ENV["environmentType.bicep"] - VN["vnet.bicep"] - NC["networkConnection.bicep"] + %% ===== 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 - subgraph L5["Layer 5: Project Resources"] - PROJ["project.bicep"] + %% ===== LAYER 5: PROJECT RESOURCES ===== + subgraph L5["๐Ÿ“ Layer 5: Project Resources"] + PROJ["๐Ÿ“‹ project.bicep"] end - subgraph L6["Layer 6: Project Child Resources"] - POOL["projectPool.bicep"] - PCAT["projectCatalog.bicep"] - PENV["projectEnvironmentType.bicep"] + %% ===== LAYER 6: PROJECT CHILD RESOURCES ===== + subgraph L6["๐Ÿ“ฆ Layer 6: Project Child Resources"] + POOL["๐ŸŠ projectPool.bicep"] + PCAT["๐Ÿ“š projectCatalog.bicep"] + PENV["๐ŸŒ projectEnvironmentType.bicep"] end - subgraph L7["Layer 7: Identity"] - DCRA["devCenterRoleAssignment"] - ORA["orgRoleAssignment"] - PIRA["projectIdentityRoleAssignment"] - KVA["keyVaultAccess"] + %% ===== LAYER 7: IDENTITY ===== + subgraph L7["๐Ÿ‘ค Layer 7: Identity"] + DCRA["๐Ÿ” devCenterRoleAssignment"] + ORA["๐Ÿข orgRoleAssignment"] + PIRA["๐Ÿ‘ฅ projectIdentityRoleAssignment"] + KVA["๐Ÿ”‘ keyVaultAccess"] end - MAIN --> RG_SEC - MAIN --> RG_MON - MAIN --> RG_WL - - RG_SEC --> SEC - RG_MON --> LA - RG_WL --> WL - - SEC --> KV - LA --> LOG - WL --> DC - WL --> CONN - - KV --> SECRET - KV --> KVA - DC --> CAT - DC --> ENV - DC --> DCRA - DC --> ORA - CONN --> VN - CONN --> NC - - DC --> PROJ - PROJ --> POOL - PROJ --> PCAT - PROJ --> PENV - PROJ --> PIRA + %% ===== 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 - style L0 fill:#E91E63,color:#fff - style L1 fill:#9C27B0,color:#fff - style L2 fill:#673AB7,color:#fff - style L3 fill:#3F51B5,color:#fff - style L4 fill:#2196F3,color:#fff - style L5 fill:#4CAF50,color:#fff - style L6 fill:#8BC34A,color:#fff - style L7 fill:#FF9800,color:#fff + %% ===== 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 @@ -441,14 +468,17 @@ output devCenterProjects array = devCenter.outputs.devCenterProjects ### 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 + 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) @@ -483,51 +513,74 @@ sequenceDiagram ### Deployment Dependencies ```mermaid +--- +title: Deployment Dependencies +--- flowchart LR - subgraph Phase1["Phase 1: Foundation"] - RG["Resource Groups"] - LA["Log Analytics"] + %% ===== PHASE 1: FOUNDATION ===== + subgraph Phase1["๐Ÿ—๏ธ Phase 1: Foundation"] + RG["๐Ÿ“ Resource Groups"] + LA["๐Ÿ“Š Log Analytics"] end - subgraph Phase2["Phase 2: Security"] - KV["Key Vault"] - SEC["Secrets"] + %% ===== PHASE 2: SECURITY ===== + subgraph Phase2["๐Ÿ” Phase 2: Security"] + KV["๐Ÿ”‘ Key Vault"] + SEC["๐Ÿ”’ Secrets"] end - subgraph Phase3["Phase 3: Network"] - VN["Virtual Network"] - NC["Network Connection"] + %% ===== PHASE 3: NETWORK ===== + subgraph Phase3["๐ŸŒ Phase 3: Network"] + VN["๐Ÿ”— Virtual Network"] + NC["๐Ÿ“ถ Network Connection"] end - subgraph Phase4["Phase 4: Workload"] - DC["DevCenter"] - CAT["Catalogs"] - ENV["Environment Types"] + %% ===== PHASE 4: WORKLOAD ===== + subgraph Phase4["๐Ÿ“ฆ Phase 4: Workload"] + DC["๐Ÿ–ฅ๏ธ DevCenter"] + CAT["๐Ÿ“š Catalogs"] + ENV["๐ŸŒ Environment Types"] end - subgraph Phase5["Phase 5: Projects"] - PROJ["Projects"] - POOL["Pools"] - PCAT["Project Catalogs"] + %% ===== PHASE 5: PROJECTS ===== + subgraph Phase5["๐Ÿ“ Phase 5: Projects"] + PROJ["๐Ÿ“‹ Projects"] + POOL["๐ŸŠ Pools"] + PCAT["๐Ÿ“– Project Catalogs"] end - subgraph Phase6["Phase 6: Identity"] - RBAC["RBAC Assignments"] + %% ===== PHASE 6: IDENTITY ===== + subgraph Phase6["๐Ÿ‘ค Phase 6: Identity"] + RBAC["๐Ÿ” RBAC Assignments"] end - Phase1 --> Phase2 - Phase1 --> Phase3 - Phase2 --> Phase4 - Phase3 --> Phase4 - Phase4 --> Phase5 - Phase5 --> Phase6 - - style Phase1 fill:#E91E63,color:#fff - style Phase2 fill:#9C27B0,color:#fff - style Phase3 fill:#3F51B5,color:#fff - style Phase4 fill:#2196F3,color:#fff - style Phase5 fill:#4CAF50,color:#fff - style Phase6 fill:#FF9800,color:#fff + %% ===== 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 ``` --- @@ -632,37 +685,56 @@ resource devCenter 'Microsoft.DevCenter/devcenters@2024-08-01-preview' = { **Configuration Flow:** ```mermaid +--- +title: Project Configuration Flow +--- flowchart TB - subgraph Input["Input Configuration"] - PC["project config object"] - NCI["networkConnectionId"] - SID["secretIdentifier"] + %% ===== INPUT CONFIGURATION ===== + subgraph Input["๐Ÿ“ฅ Input Configuration"] + PC["โš™๏ธ project config object"] + NCI["๐Ÿ”— networkConnectionId"] + SID["๐Ÿ”‘ secretIdentifier"] end - subgraph Project["Project Resource"] - PR["Microsoft.DevCenter/devcenters/projects"] + %% ===== PROJECT RESOURCE ===== + subgraph Project["๐Ÿ“‹ Project Resource"] + PR["๐Ÿข Microsoft.DevCenter/devcenters/projects"] end - subgraph Children["Child Resources"] - PO["Pools\n(projectPool.bicep)"] - CA["Catalogs\n(projectCatalog.bicep)"] - ET["Environment Types\n(projectEnvironmentType.bicep)"] + %% ===== CHILD RESOURCES ===== + subgraph Children["๐Ÿ“ฆ Child Resources"] + PO["๐ŸŠ Pools
(projectPool.bicep)"] + CA["๐Ÿ“š Catalogs
(projectCatalog.bicep)"] + ET["๐ŸŒ Environment Types
(projectEnvironmentType.bicep)"] end - subgraph Identity["Identity"] - MI["SystemAssigned Identity"] - RA["Role Assignments"] + %% ===== IDENTITY ===== + subgraph Identity["๐Ÿ‘ค Identity"] + MI["๐Ÿ” SystemAssigned Identity"] + RA["๐Ÿ›ก๏ธ Role Assignments"] end - Input --> Project - Project --> Children - Project --> MI - MI --> RA + %% ===== 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:#FF9800,color:#fff - style Project fill:#2196F3,color:#fff - style Children fill:#4CAF50,color:#fff - style Identity fill:#9C27B0,color:#fff + 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 ``` --- @@ -678,33 +750,49 @@ flowchart TB The accelerator uses the **Configuration as Data** pattern where all deployment parameters are externalized to YAML files. ```mermaid +--- +title: Configuration Integration Pattern +--- flowchart LR - subgraph Config["Configuration Layer"] - YAML["YAML Files\n(infra/settings/)"] - SCHEMA["JSON Schemas\n(validation)"] + %% ===== CONFIGURATION LAYER ===== + subgraph Config["๐Ÿ“ Configuration Layer"] + YAML["๐Ÿ“„ YAML Files
(infra/settings/)"] + SCHEMA["๐Ÿ“‹ JSON Schemas
(validation)"] end - subgraph Bicep["Bicep Layer"] - LOAD["loadYamlContent()"] - PARAM["Parameters"] - MOD["Modules"] + %% ===== BICEP LAYER ===== + subgraph Bicep["โš™๏ธ Bicep Layer"] + LOAD["๐Ÿ”„ loadYamlContent()"] + PARAM["๐Ÿ“ฅ Parameters"] + MOD["๐Ÿ“ฆ Modules"] end - subgraph ARM["ARM Layer"] - TEMPLATE["ARM Template"] - DEPLOY["Deployment"] + %% ===== ARM LAYER ===== + subgraph ARM["โ˜๏ธ ARM Layer"] + TEMPLATE["๐Ÿ“‹ ARM Template"] + DEPLOY["๐Ÿš€ Deployment"] end + %% ===== CONNECTIONS ===== SCHEMA -->|validates| YAML - YAML --> LOAD - LOAD --> PARAM - PARAM --> MOD - MOD --> TEMPLATE - TEMPLATE --> DEPLOY - - style Config fill:#FF9800,color:#fff - style Bicep fill:#2196F3,color:#fff - style ARM fill:#4CAF50,color:#fff + 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 @@ -712,28 +800,43 @@ flowchart LR Modules follow a parent-child pattern where parent modules orchestrate child resources: ```mermaid +--- +title: Hierarchical Module Pattern +--- flowchart TB - subgraph Pattern["Hierarchical Module Pattern"] - P["Parent Module"] - C1["Child Module 1"] - C2["Child Module 2"] - C3["Child Module 3"] + %% ===== 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 + P -->|for loop| C1 + P -->|for loop| C2 + P -->|for loop| C3 - subgraph Example["Example: devCenter.bicep"] - DC["devCenter.bicep"] - CAT["catalog.bicep\n(for each catalog)"] - ENV["environmentType.bicep\n(for each type)"] - PROJ["project.bicep\n(for each project)"] + %% ===== 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 + 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 From 9c1bc14a478e20177f94f22318d7cfa42dddc21a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 12:01:32 -0500 Subject: [PATCH 19/44] Enhance documentation for technology architecture by adding emojis, improving section titles, and refining diagram styles for better clarity and navigation. --- .../04-technology-architecture.md | 255 +++++++++++------- 1 file changed, 159 insertions(+), 96 deletions(-) diff --git a/docs/architecture/04-technology-architecture.md b/docs/architecture/04-technology-architecture.md index 4f8bfcf4..695cc2e3 100644 --- a/docs/architecture/04-technology-architecture.md +++ b/docs/architecture/04-technology-architecture.md @@ -60,55 +60,74 @@ The DevExp-DevBox accelerator leverages Azure's Platform as a Service (PaaS) off ### Technology Stack Overview ```mermaid +--- +title: Technology Stack Overview +--- flowchart TB - subgraph Developer["Developer Tooling"] - VSC["VS Code"] - GH["GitHub"] - AZD["Azure Developer CLI"] + %% ===== DEVELOPER TOOLING ===== + subgraph Developer["๐Ÿ‘จโ€๐Ÿ’ป Developer Tooling"] + VSC["๐Ÿ’ป VS Code"] + GH["๐Ÿ™ GitHub"] + AZD["๐Ÿš€ Azure Developer CLI"] end - subgraph IaC["Infrastructure as Code"] - BICEP["Azure Bicep"] - YAML["YAML Configuration"] - PS["PowerShell/Bash"] + %% ===== INFRASTRUCTURE AS CODE ===== + subgraph IaC["๐Ÿ“œ Infrastructure as Code"] + BICEP["โš™๏ธ Azure Bicep"] + YAML["๐Ÿ“„ YAML Configuration"] + PS["๐Ÿ“ PowerShell/Bash"] end - subgraph CI/CD["CI/CD Platform"] - GHA["GitHub Actions"] - OIDC["OIDC Federation"] + %% ===== CI/CD PLATFORM ===== + subgraph CI_CD["๐Ÿ”„ CI/CD Platform"] + GHA["๐Ÿ”„ GitHub Actions"] + OIDC["๐Ÿ” OIDC Federation"] end - subgraph Azure["Azure Platform"] - subgraph Compute["Compute Services"] - DC["Azure DevCenter"] - DB["Dev Boxes"] + %% ===== 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"] + subgraph Security["๐Ÿ” Security Services"] + KV["๐Ÿ”‘ Key Vault"] + RBAC["๐Ÿ›ก๏ธ Azure RBAC"] + MI["๐Ÿ‘ค Managed Identities"] end - subgraph Network["Network Services"] - VNET["Virtual Network"] - NC["Network Connections"] + subgraph Network["๐ŸŒ Network Services"] + VNET["๐Ÿ”— Virtual Network"] + NC["๐Ÿ“ถ Network Connections"] end - subgraph Monitor["Monitoring Services"] - LA["Log Analytics"] - MON["Azure Monitor"] + subgraph Monitor["๐Ÿ“Š Monitoring Services"] + LA["๐Ÿ“ˆ Log Analytics"] + MON["๐Ÿ“Š Azure Monitor"] end end - Developer --> IaC - IaC --> CI/CD - CI/CD --> Azure - - style Developer fill:#2196F3,color:#fff - style IaC fill:#FF9800,color:#fff - style CI/CD fill:#9C27B0,color:#fff - style Azure fill:#4CAF50,color:#fff + %% ===== 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 @@ -146,64 +165,88 @@ flowchart TB ### Service Relationships ```mermaid +--- +title: Azure Service Relationships +--- flowchart TB - subgraph Management["Management Plane"] - ARM["Azure Resource Manager"] - SUB["Subscription"] + %% ===== MANAGEMENT PLANE ===== + subgraph Management["๐ŸŽฏ Management Plane"] + ARM["โ˜๏ธ Azure Resource Manager"] + SUB["๐Ÿ“‹ Subscription"] end - subgraph ResourceGroups["Resource Groups"] - RG_SEC["rg-security"] - RG_MON["rg-monitoring"] - RG_WL["rg-workload"] + %% ===== RESOURCE GROUPS ===== + subgraph ResourceGroups["๐Ÿ“ Resource Groups"] + RG_SEC["๐Ÿ” rg-security"] + RG_MON["๐Ÿ“Š rg-monitoring"] + RG_WL["๐Ÿ“ฆ rg-workload"] end - subgraph SecurityZone["Security Landing Zone"] - KV["Key Vault"] - SEC["Secrets"] + %% ===== SECURITY ZONE ===== + subgraph SecurityZone["๐Ÿ” Security Landing Zone"] + KV["๐Ÿ”‘ Key Vault"] + SEC["๐Ÿ”’ Secrets"] end - subgraph MonitoringZone["Monitoring Landing Zone"] - LA["Log Analytics\nWorkspace"] - SOL["Solutions"] + %% ===== MONITORING ZONE ===== + subgraph MonitoringZone["๐Ÿ“Š Monitoring Landing Zone"] + LA["๐Ÿ“ˆ Log Analytics
Workspace"] + SOL["๐Ÿ”ง Solutions"] end - subgraph WorkloadZone["Workload Landing Zone"] - DC["DevCenter"] - PROJ["Projects"] - POOL["Pools"] - CAT["Catalogs"] + %% ===== WORKLOAD ZONE ===== + subgraph WorkloadZone["๐Ÿ“ฆ Workload Landing Zone"] + DC["๐Ÿ–ฅ๏ธ DevCenter"] + PROJ["๐Ÿ“ Projects"] + POOL["๐ŸŠ Pools"] + CAT["๐Ÿ“š Catalogs"] end - subgraph NetworkZone["Network"] - VNET["Virtual Network"] - SUBNET["Subnets"] - NC["Network Connection"] + %% ===== NETWORK ZONE ===== + subgraph NetworkZone["๐ŸŒ Network"] + VNET["๐Ÿ”— Virtual Network"] + SUBNET["๐Ÿ“ถ Subnets"] + NC["๐Ÿ”Œ Network Connection"] end - ARM --> SUB - SUB --> ResourceGroups + %% ===== CONNECTIONS ===== + ARM -->|manages| SUB + SUB -->|contains| ResourceGroups - RG_SEC --> SecurityZone - RG_MON --> MonitoringZone - RG_WL --> WorkloadZone - RG_WL --> NetworkZone + 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 --> VNET - DC --> PROJ - PROJ --> POOL - - style Management fill:#E91E63,color:#fff - style ResourceGroups fill:#9C27B0,color:#fff - style SecurityZone fill:#F44336,color:#fff - style MonitoringZone fill:#4CAF50,color:#fff - style WorkloadZone fill:#2196F3,color:#fff - style NetworkZone fill:#FF9800,color:#fff + 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 @@ -234,45 +277,65 @@ flowchart TB The accelerator implements a simplified Azure Landing Zone pattern with three primary zones plus networking. ```mermaid +--- +title: Azure Landing Zone Design +--- flowchart TB - subgraph Subscription["Azure Subscription"] - subgraph Security["Security Landing Zone"] + %% ===== SUBSCRIPTION ===== + subgraph Subscription["โ˜๏ธ Azure Subscription"] + %% ===== SECURITY ===== + subgraph Security["๐Ÿ” Security Landing Zone"] direction TB - RG_S["Resource Group:\ndevexp-security-{env}"] - KV_R["Key Vault"] - SEC_R["Secrets"] + RG_S["๐Ÿ“ Resource Group:
devexp-security-{env}"] + KV_R["๐Ÿ”‘ Key Vault"] + SEC_R["๐Ÿ”’ Secrets"] end - subgraph Monitoring["Monitoring Landing Zone"] + %% ===== MONITORING ===== + subgraph Monitoring["๐Ÿ“Š Monitoring Landing Zone"] direction TB - RG_M["Resource Group:\ndevexp-monitoring-{env}"] - LA_R["Log Analytics"] - SOL_R["Solutions"] + RG_M["๐Ÿ“ Resource Group:
devexp-monitoring-{env}"] + LA_R["๐Ÿ“ˆ Log Analytics"] + SOL_R["๐Ÿ”ง Solutions"] end - subgraph Workload["Workload Landing Zone"] + %% ===== WORKLOAD ===== + subgraph Workload["๐Ÿ“ฆ Workload Landing Zone"] direction TB - RG_W["Resource Group:\ndevexp-workload-{env}"] - DC_R["DevCenter"] - PROJ_R["Projects"] - POOL_R["Pools"] + RG_W["๐Ÿ“ Resource Group:
devexp-workload-{env}"] + DC_R["๐Ÿ–ฅ๏ธ DevCenter"] + PROJ_R["๐Ÿ“‹ Projects"] + POOL_R["๐ŸŠ Pools"] end - subgraph Network["Connectivity"] + %% ===== CONNECTIVITY ===== + subgraph Network["๐ŸŒ Connectivity"] direction TB - VNET_R["Virtual Network"] - NC_R["Network Connection"] + VNET_R["๐Ÿ”— Virtual Network"] + NC_R["๐Ÿ“ถ Network Connection"] end end - Security --> Monitoring - Monitoring --> Workload - Network --> Workload - - style Security fill:#F44336,color:#fff - style Monitoring fill:#4CAF50,color:#fff - style Workload fill:#2196F3,color:#fff - style Network fill:#FF9800,color:#fff + %% ===== 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 From 73919704be2147bb8f464514178e8f14dab1a8cf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 12:01:44 -0500 Subject: [PATCH 20/44] Enhance documentation for network and Dev Box architecture by adding emojis, improving diagram styles, and refining connections for better clarity and navigation. --- .../04-technology-architecture.md | 170 +++++++++++------- 1 file changed, 109 insertions(+), 61 deletions(-) diff --git a/docs/architecture/04-technology-architecture.md b/docs/architecture/04-technology-architecture.md index 695cc2e3..5b904383 100644 --- a/docs/architecture/04-technology-architecture.md +++ b/docs/architecture/04-technology-architecture.md @@ -367,44 +367,60 @@ flowchart TB ### Network Topology ```mermaid +--- +title: Network Topology +--- flowchart TB - subgraph Internet["Internet"] - DEV["Developer\n(Remote)"] - GH["GitHub.com"] - ADO["Azure DevOps"] + %% ===== INTERNET ===== + subgraph Internet["๐ŸŒ Internet"] + DEV["๐Ÿ‘จโ€๐Ÿ’ป Developer
(Remote)"] + GH["๐Ÿ™ GitHub.com"] + ADO["๐Ÿ”ท Azure DevOps"] end - 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"] + %% ===== 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\n(Managed/Unmanaged)"] - DC["DevCenter"] + NC["๐Ÿ“ถ Network Connection
(Managed/Unmanaged)"] + DC["๐Ÿ–ฅ๏ธ DevCenter"] end - subgraph MSHosted["Microsoft-Hosted Network"] - MHN["Microsoft Managed\nNetwork"] + %% ===== MS HOSTED ===== + subgraph MSHosted["๐Ÿข Microsoft-Hosted Network"] + MHN["โ˜๏ธ Microsoft Managed
Network"] end - DEV -->|"RDP/HTTPS"| DB1 - DEV -->|"RDP/HTTPS"| DB2 + %% ===== CONNECTIONS ===== + DEV -->|RDP/HTTPS| DB1 + DEV -->|RDP/HTTPS| DB2 + + DB1 -->|HTTPS| GH + DB1 -->|HTTPS| ADO + + DC -->|networkConnectionId| NC + NC -->|subnetId| Subnet - DB1 -->|"HTTPS"| GH - DB1 -->|"HTTPS"| ADO + DC -.->|Alternative| MHN - DC -->|"networkConnectionId"| NC - NC -->|"subnetId"| Subnet + %% ===== 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 - DC -.->|"Alternative"| MHN + class DEV,GH,ADO external + class DB1,DB2,DB3,NC,DC primary + class MHN trigger - style Internet fill:#E91E63,color:#fff - style VNet fill:#2196F3,color:#fff - style MSHosted fill:#9C27B0,color:#fff + 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 @@ -450,41 +466,57 @@ network: ### Dev Box Architecture ```mermaid +--- +title: Dev Box Architecture +--- flowchart TB - subgraph DevCenter["Azure DevCenter"] - DC["DevCenter Resource"] + %% ===== DEVCENTER ===== + subgraph DevCenter["๐Ÿข Azure DevCenter"] + DC["๐Ÿ–ฅ๏ธ DevCenter Resource"] - subgraph Images["Image Definitions"] - IMG1["eShop-backend-engineer"] - IMG2["eShop-frontend-engineer"] + %% ===== IMAGES ===== + subgraph Images["๐Ÿ“ฆ Image Definitions"] + IMG1["๐Ÿ’ป eShop-backend-engineer"] + IMG2["๐ŸŽจ eShop-frontend-engineer"] end - subgraph Projects["Projects"] - PROJ["eShop Project"] + %% ===== PROJECTS ===== + subgraph Projects["๐Ÿ“ Projects"] + PROJ["๐Ÿ“‹ eShop Project"] end - subgraph Pools["Dev Box Pools"] - P1["backend-engineer\ngeneral_i_32c128gb512ssd_v2"] - P2["frontend-engineer\ngeneral_i_16c64gb256ssd_v2"] + %% ===== POOLS ===== + subgraph Pools["๐ŸŠ Dev Box Pools"] + P1["โš™๏ธ backend-engineer
general_i_32c128gb512ssd_v2"] + P2["๐ŸŽจ frontend-engineer
general_i_16c64gb256ssd_v2"] end end - subgraph Runtime["Runtime Environment"] - DB1["Dev Box Instance\n(Windows 11)"] - DB2["Dev Box Instance\n(Windows 11)"] + %% ===== RUNTIME ===== + subgraph Runtime["๐Ÿš€ Runtime Environment"] + DB1["๐Ÿ–ฅ๏ธ Dev Box Instance
(Windows 11)"] + DB2["๐Ÿ–ฅ๏ธ Dev Box Instance
(Windows 11)"] end - DC --> Images - DC --> Projects - Projects --> Pools - P1 --> DB1 - P2 --> DB2 + %% ===== CONNECTIONS ===== + DC -->|manages| Images + DC -->|contains| Projects + Projects -->|deploys| Pools + P1 -->|provisions| DB1 + P2 -->|provisions| DB2 IMG1 -->|imageDefinition| P1 IMG2 -->|imageDefinition| P2 - style DevCenter fill:#2196F3,color:#fff - style Runtime fill:#4CAF50,color:#fff + %% ===== 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 @@ -502,31 +534,47 @@ flowchart TB Dev Box images are managed through DevCenter catalogs containing image definitions: ```mermaid +--- +title: Image Management Flow +--- flowchart LR - subgraph Catalog["DevCenter Catalog"] - GIT["Git Repository"] - IMG_DEF["Image Definitions\n(YAML/JSON)"] - DSC["DSC Configurations\n(Optional)"] + %% ===== CATALOG ===== + subgraph Catalog["๐Ÿ“š DevCenter Catalog"] + GIT["๐Ÿ™ Git Repository"] + IMG_DEF["๐Ÿ“„ Image Definitions
(YAML/JSON)"] + DSC["โš™๏ธ DSC Configurations
(Optional)"] end - subgraph DevCenter["DevCenter"] - CAT["Catalog Sync"] - IMG["Image Gallery"] + %% ===== DEVCENTER ===== + subgraph DevCenter["๐Ÿข DevCenter"] + CAT["๐Ÿ”„ Catalog Sync"] + IMG["๐Ÿ“ฆ Image Gallery"] end - subgraph Pool["Dev Box Pool"] - VM["Dev Box VMs"] + %% ===== POOL ===== + subgraph Pool["๐ŸŠ Dev Box Pool"] + VM["๐Ÿ–ฅ๏ธ Dev Box VMs"] end - GIT --> CAT - CAT --> IMG_DEF - IMG_DEF --> IMG - IMG --> VM - DSC --> IMG + %% ===== 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:#FF9800,color:#fff - style DevCenter fill:#2196F3,color:#fff - style Pool fill:#4CAF50,color:#fff + 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 ``` --- From 1cce332beef4ed960ae1bf2a54cdeda233fe8606 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 12:04:00 -0500 Subject: [PATCH 21/44] Enhance documentation for GitHub Actions and Log Analytics architecture by adding emojis, improving diagram styles, and refining connections for better clarity and navigation. --- .../04-technology-architecture.md | 200 +++++++++++------- 1 file changed, 127 insertions(+), 73 deletions(-) diff --git a/docs/architecture/04-technology-architecture.md b/docs/architecture/04-technology-architecture.md index 5b904383..719ca9da 100644 --- a/docs/architecture/04-technology-architecture.md +++ b/docs/architecture/04-technology-architecture.md @@ -588,72 +588,107 @@ flowchart LR ### GitHub Actions Architecture ```mermaid +--- +title: GitHub Actions Architecture +--- flowchart TB - subgraph GitHub["GitHub"] - REPO["Repository"] + %% ===== GITHUB ===== + subgraph GitHub["๐Ÿ™ GitHub"] + REPO["๐Ÿ“ Repository"] - subgraph Actions["GitHub Actions"] - WF_BUILD["build.yml"] - WF_DEPLOY["deploy.yml"] - WF_RELEASE["release.yml"] + %% ===== ACTIONS ===== + subgraph Actions["๐Ÿ”„ GitHub Actions"] + WF_BUILD["๐Ÿ”จ build.yml"] + WF_DEPLOY["๐Ÿš€ deploy.yml"] + WF_RELEASE["๐Ÿ“ฆ release.yml"] end - subgraph Secrets["GitHub Configuration"] - VARS["Variables:\n- AZURE_CLIENT_ID\n- AZURE_TENANT_ID\n- AZURE_SUBSCRIPTION_ID"] - SECS["Secrets:\n- AZURE_CREDENTIALS"] + %% ===== SECRETS ===== + subgraph Secrets["๐Ÿ” GitHub Configuration"] + VARS["๐Ÿ“‹ Variables:
- AZURE_CLIENT_ID
- AZURE_TENANT_ID
- AZURE_SUBSCRIPTION_ID"] + SECS["๐Ÿ”‘ Secrets:
- AZURE_CREDENTIALS"] end end - subgraph Azure["Azure"] - OIDC["OIDC Provider\n(Microsoft Entra ID)"] - ARM["Azure Resource Manager"] - SUB["Subscription"] + %% ===== AZURE ===== + subgraph Azure["โ˜๏ธ Azure"] + OIDC["๐Ÿ” OIDC Provider
(Microsoft Entra ID)"] + ARM["โ˜๏ธ Azure Resource Manager"] + SUB["๐Ÿ“‹ Subscription"] end - REPO --> Actions - Actions --> OIDC - OIDC -->|"Token Exchange"| ARM - ARM --> SUB + %% ===== CONNECTIONS ===== + REPO -->|triggers| Actions + Actions -->|authenticates| OIDC + OIDC -->|Token Exchange| ARM + ARM -->|deploys| SUB - VARS --> Actions - SECS --> Actions + VARS -->|configures| Actions + SECS -->|configures| Actions - style GitHub fill:#9C27B0,color:#fff - style Azure fill:#2196F3,color:#fff + %% ===== 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 - subgraph Build["build.yml"] - B1["Checkout"] - B2["Setup azd"] - B3["Login (OIDC)"] - B4["azd provision"] + %% ===== BUILD ===== + subgraph Build["๐Ÿ”จ build.yml"] + B1["๐Ÿ“ฅ Checkout"] + B2["โš™๏ธ Setup azd"] + B3["๐Ÿ” Login (OIDC)"] + B4["๐Ÿš€ azd provision"] end - subgraph Deploy["deploy.yml"] - D1["Checkout"] - D2["Setup azd"] - D3["Login (OIDC)"] - D4["Download Artifacts"] - D5["azd deploy"] + %% ===== DEPLOY ===== + subgraph Deploy["๐Ÿš€ deploy.yml"] + D1["๐Ÿ“ฅ Checkout"] + D2["โš™๏ธ Setup azd"] + D3["๐Ÿ” Login (OIDC)"] + D4["๐Ÿ“ฆ Download Artifacts"] + D5["๐Ÿš€ azd deploy"] end - subgraph Release["release.yml"] - R1["Get Version"] - R2["Create Tag"] - R3["Create Release"] - R4["Generate Notes"] + %% ===== RELEASE ===== + subgraph Release["๐Ÿ“ฆ release.yml"] + R1["๐Ÿท๏ธ Get Version"] + R2["๐Ÿ”– Create Tag"] + R3["๐Ÿ“ฆ Create Release"] + R4["๐Ÿ“ Generate Notes"] end - Build -->|"artifacts"| Deploy - Deploy -->|"on success"| Release + %% ===== CONNECTIONS ===== + Build -->|artifacts| Deploy + Deploy -->|on success| Release - style Build fill:#FF9800,color:#fff - style Deploy fill:#4CAF50,color:#fff - style Release fill:#2196F3,color:#fff + %% ===== 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 @@ -691,52 +726,71 @@ steps: ### Log Analytics Architecture ```mermaid +--- +title: Log Analytics Architecture +--- flowchart TB - subgraph Sources["Telemetry Sources"] - DC["DevCenter\nLogs & Metrics"] - KV["Key Vault\nLogs & Metrics"] - VN["Virtual Network\nLogs & Metrics"] - DB["Dev Box\nAgent Metrics"] + %% ===== 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 - subgraph Collection["Collection Layer"] - DS["Diagnostic Settings"] - AMA["Azure Monitor Agent"] + %% ===== COLLECTION LAYER ===== + subgraph Collection["๐Ÿ”„ Collection Layer"] + DS["โš™๏ธ Diagnostic Settings"] + AMA["๐Ÿ“Š Azure Monitor Agent"] end - subgraph LAW["Log Analytics Workspace"] - subgraph Tables["Tables"] - DIAG["AzureDiagnostics"] - MET["AzureMetrics"] - ACT["AzureActivity"] + %% ===== LOG ANALYTICS WORKSPACE ===== + subgraph LAW["๐Ÿ“ˆ Log Analytics Workspace"] + subgraph Tables["๐Ÿ“‹ Tables"] + DIAG["๐Ÿ“ AzureDiagnostics"] + MET["๐Ÿ“Š AzureMetrics"] + ACT["๐Ÿ“‹ AzureActivity"] end - subgraph Solutions["Solutions"] - AA["AzureActivity Solution"] + subgraph Solutions["๐Ÿ”ง Solutions"] + AA["โ˜๏ธ AzureActivity Solution"] end end - subgraph Consumers["Consumers"] - DASH["Dashboards"] - ALERT["Alerts"] - WB["Workbooks"] + %% ===== CONSUMERS ===== + subgraph Consumers["๐Ÿ‘ฅ Consumers"] + DASH["๐Ÿ“Š Dashboards"] + ALERT["๐Ÿ”” Alerts"] + WB["๐Ÿ“– Workbooks"] end - DC --> DS - KV --> DS - VN --> DS - DB --> AMA + %% ===== CONNECTIONS ===== + DC -->|sends| DS + KV -->|sends| DS + VN -->|sends| DS + DB -->|sends| AMA + + DS -->|ingests| Tables + AMA -->|ingests| Tables - DS --> Tables - AMA --> 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 - Tables --> Solutions - Tables --> Consumers + class DC,KV,VN,DB datastore + class DS,AMA trigger + class DIAG,MET,ACT,AA primary + class DASH,ALERT,WB secondary - style Sources fill:#FF9800,color:#fff - style Collection fill:#9C27B0,color:#fff - style LAW fill:#2196F3,color:#fff - style Consumers fill:#4CAF50,color:#fff + 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 From f7b34f8c16197886ef87bb4576f99bc777cbc848 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 12:05:25 -0500 Subject: [PATCH 22/44] Enhance security architecture documentation by adding emojis, improving diagram styles, and refining connections for better clarity and navigation. --- docs/architecture/05-security-architecture.md | 361 +++++++++++------- 1 file changed, 226 insertions(+), 135 deletions(-) diff --git a/docs/architecture/05-security-architecture.md b/docs/architecture/05-security-architecture.md index 7965fe9d..3f3d14c0 100644 --- a/docs/architecture/05-security-architecture.md +++ b/docs/architecture/05-security-architecture.md @@ -61,47 +61,69 @@ The DevExp-DevBox accelerator implements defense-in-depth security principles ac ### Security Architecture Overview ```mermaid +--- +title: Security Architecture Overview +--- flowchart TB - subgraph External["External Boundary"] - DEV["Developers"] - GH["GitHub"] - ADO["Azure DevOps"] + %% ===== EXTERNAL BOUNDARY ===== + subgraph External["๐ŸŒ External Boundary"] + DEV["๐Ÿ‘จโ€๐Ÿ’ป Developers"] + GH["๐Ÿ™ GitHub"] + ADO["๐Ÿ”ท Azure DevOps"] end - subgraph Identity["Identity Layer"] - AAD["Microsoft Entra ID"] - MI["Managed Identities"] - OIDC["OIDC Federation"] + %% ===== IDENTITY LAYER ===== + subgraph Identity["๐Ÿ” Identity Layer"] + AAD["๐Ÿข Microsoft Entra ID"] + MI["๐Ÿ‘ค Managed Identities"] + OIDC["๐Ÿ”— OIDC Federation"] end - subgraph Access["Access Control Layer"] - RBAC["Azure RBAC"] - KVA["Key Vault Access"] - DCA["DevCenter Access"] + %% ===== ACCESS CONTROL LAYER ===== + subgraph Access["๐Ÿ›ก๏ธ Access Control Layer"] + RBAC["๐Ÿ“‹ Azure RBAC"] + KVA["๐Ÿ”‘ Key Vault Access"] + DCA["๐Ÿ–ฅ๏ธ DevCenter Access"] end - subgraph Network["Network Layer"] - NSG["Network Security Groups"] - VNET["Virtual Network"] - PE["Private Endpoints"] + %% ===== NETWORK LAYER ===== + subgraph Network["๐ŸŒ Network Layer"] + NSG["๐Ÿ›ก๏ธ Network Security Groups"] + VNET["๐Ÿ”— Virtual Network"] + PE["๐Ÿ”’ Private Endpoints"] end - subgraph Data["Data Layer"] - KV["Key Vault\n(Secrets)"] - LA["Log Analytics\n(Telemetry)"] - DC["DevCenter\n(Workloads)"] + %% ===== DATA LAYER ===== + subgraph Data["๐Ÿ’พ Data Layer"] + KV["๐Ÿ”‘ Key Vault
(Secrets)"] + LA["๐Ÿ“Š Log Analytics
(Telemetry)"] + DC["๐Ÿ–ฅ๏ธ DevCenter
(Workloads)"] end - External --> Identity - Identity --> Access - Access --> Network - Network --> Data - - style External fill:#F44336,color:#fff - style Identity fill:#9C27B0,color:#fff - style Access fill:#FF9800,color:#fff - style Network fill:#2196F3,color:#fff - style Data fill:#4CAF50,color:#fff + %% ===== 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 @@ -126,43 +148,59 @@ flowchart TB ### STRIDE Analysis ```mermaid +--- +title: STRIDE Threat Analysis +--- flowchart TB - subgraph Assets["Protected Assets"] - A1["GitHub PAT Tokens"] - A2["Azure Credentials"] - A3["Dev Box VMs"] - A4["Source Code"] - A5["Configuration Data"] + %% ===== PROTECTED ASSETS ===== + subgraph Assets["๐ŸŽฏ Protected Assets"] + A1["๐Ÿ”‘ GitHub PAT Tokens"] + A2["๐Ÿ” Azure Credentials"] + A3["๐Ÿ–ฅ๏ธ Dev Box VMs"] + A4["๐Ÿ“‚ Source Code"] + A5["โš™๏ธ Configuration Data"] end - subgraph Threats["STRIDE Threats"] - T1["Spoofing"] - T2["Tampering"] - T3["Repudiation"] - T4["Information Disclosure"] - T5["Denial of Service"] - T6["Elevation of Privilege"] + %% ===== STRIDE THREATS ===== + subgraph Threats["โš ๏ธ STRIDE Threats"] + T1["๐Ÿ‘ค Spoofing"] + T2["โœ๏ธ Tampering"] + T3["โŒ Repudiation"] + T4["๐Ÿ‘๏ธ Information Disclosure"] + T5["๐Ÿšซ Denial of Service"] + T6["โฌ†๏ธ Elevation of Privilege"] end - 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"] + %% ===== 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 - T1 --> M1 - T2 --> M2 - T3 --> M3 - T4 --> M4 - T5 --> M5 - T6 --> M6 - - style Assets fill:#F44336,color:#fff - style Threats fill:#FF9800,color:#fff - style Mitigations fill:#4CAF50,color:#fff + %% ===== 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 @@ -184,38 +222,54 @@ flowchart TB ### Attack Surface Diagram ```mermaid +--- +title: Attack Surface Diagram +--- flowchart LR - subgraph External["External Attack Surface"] - A1["GitHub Repository"] - A2["GitHub Actions"] - A3["Developer Endpoints"] + %% ===== EXTERNAL ATTACK SURFACE ===== + subgraph External["๐ŸŒ External Attack Surface"] + A1["๐Ÿ™ GitHub Repository"] + A2["๐Ÿ”„ GitHub Actions"] + A3["๐Ÿ‘จโ€๐Ÿ’ป Developer Endpoints"] end - subgraph Internal["Internal Attack Surface"] - B1["Azure Portal"] - B2["Key Vault API"] - B3["DevCenter API"] - B4["Dev Box RDP"] + %% ===== INTERNAL ATTACK SURFACE ===== + subgraph Internal["๐Ÿข Internal Attack Surface"] + B1["๐ŸŒ Azure Portal"] + B2["๐Ÿ”‘ Key Vault API"] + B3["๐Ÿ–ฅ๏ธ DevCenter API"] + B4["๐Ÿ–ฅ๏ธ Dev Box RDP"] end - subgraph Data["Data at Risk"] - C1["PAT Tokens"] - C2["Source Code"] - C3["Dev Box Data"] + %% ===== DATA AT RISK ===== + subgraph Data["๐ŸŽฏ Data at Risk"] + C1["๐Ÿ”‘ PAT Tokens"] + C2["๐Ÿ“‚ Source Code"] + C3["๐Ÿ’พ Dev Box Data"] end - A1 --> B1 - A2 --> B2 - A3 --> B4 + %% ===== CONNECTIONS ===== + A1 -->|targets| B1 + A2 -->|targets| B2 + A3 -->|targets| B4 + + B1 -->|accesses| C1 + B2 -->|accesses| C1 + B3 -->|accesses| C2 + B4 -->|accesses| C3 - B1 --> C1 - B2 --> C1 - B3 --> C2 - B4 --> 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 - style External fill:#F44336,color:#fff - style Internal fill:#FF9800,color:#fff - style Data fill:#9C27B0,color:#fff + 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 ``` --- @@ -229,37 +283,53 @@ flowchart LR ### Identity Types ```mermaid +--- +title: Identity Types +--- flowchart TB - subgraph UserIdentities["User Identities"] - AAD_USER["Azure AD Users"] - AAD_GROUP["Azure AD Groups"] + %% ===== USER IDENTITIES ===== + subgraph UserIdentities["๐Ÿ‘ฅ User Identities"] + AAD_USER["๐Ÿ‘ค Azure AD Users"] + AAD_GROUP["๐Ÿ‘ฅ Azure AD Groups"] end - subgraph ServiceIdentities["Service Identities"] - MI_SYS["SystemAssigned\nManaged Identity"] - MI_USER["UserAssigned\nManaged Identity"] - SP["Service Principal\n(OIDC Federation)"] + %% ===== SERVICE IDENTITIES ===== + subgraph ServiceIdentities["โš™๏ธ Service Identities"] + MI_SYS["๐Ÿ” SystemAssigned
Managed Identity"] + MI_USER["๐Ÿ‘ค UserAssigned
Managed Identity"] + SP["๐Ÿ”— Service Principal
(OIDC Federation)"] end - subgraph Resources["Resources"] - DC["DevCenter"] - PROJ["Projects"] - KV["Key Vault"] + %% ===== RESOURCES ===== + subgraph Resources["๐Ÿข Resources"] + DC["๐Ÿ–ฅ๏ธ DevCenter"] + PROJ["๐Ÿ“ Projects"] + KV["๐Ÿ”‘ Key Vault"] end - AAD_USER --> AAD_GROUP - AAD_GROUP -->|"RBAC"| DC - AAD_GROUP -->|"RBAC"| PROJ + %% ===== 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 - MI_SYS --> DC - MI_SYS --> PROJ + SP -->|GitHub Actions| Resources + MI_SYS -->|DevCenter โ†’ Key Vault| KV - 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 - style UserIdentities fill:#2196F3,color:#fff - style ServiceIdentities fill:#4CAF50,color:#fff - style Resources fill:#FF9800,color:#fff + 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) @@ -300,43 +370,61 @@ identity: ### Role Assignment Model ```mermaid +--- +title: RBAC Role Assignment Model +--- flowchart TB - subgraph Subscription["Subscription Scope"] - R1["Contributor"] - R2["Key Vault Administrator"] - R3["Key Vault Secrets User"] + %% ===== SUBSCRIPTION SCOPE ===== + subgraph Subscription["๐Ÿ“‹ Subscription Scope"] + R1["๐Ÿ”ง Contributor"] + R2["๐Ÿ”‘ Key Vault Administrator"] + R3["๐Ÿ” Key Vault Secrets User"] end - subgraph ResourceGroup["Resource Group Scope"] - R4["DevCenter Project Admin"] - R5["Log Analytics Contributor"] + %% ===== RESOURCE GROUP SCOPE ===== + subgraph ResourceGroup["๐Ÿ“ Resource Group Scope"] + R4["๐Ÿ–ฅ๏ธ DevCenter Project Admin"] + R5["๐Ÿ“Š Log Analytics Contributor"] end - subgraph Resource["Resource Scope"] - R6["Dev Box User"] - R7["Deployment Environments User"] + %% ===== RESOURCE SCOPE ===== + subgraph Resource["๐ŸŽฏ Resource Scope"] + R6["๐Ÿ’ป Dev Box User"] + R7["๐ŸŒ Deployment Environments User"] end - subgraph Principals["Principals"] - P1["DevCenter MI"] - P2["Platform Engineering Team"] - P3["Project Developers"] + %% ===== PRINCIPALS ===== + subgraph Principals["๐Ÿ‘ฅ Principals"] + P1["๐Ÿ” DevCenter MI"] + P2["๐Ÿ‘ท Platform Engineering Team"] + P3["๐Ÿ‘จโ€๐Ÿ’ป Project Developers"] end - P1 --> R1 - P1 --> R2 - P1 --> R3 + %% ===== CONNECTIONS ===== + P1 -->|assigned| R1 + P1 -->|assigned| R2 + P1 -->|assigned| R3 - P2 --> R4 - P2 --> R5 + P2 -->|assigned| R4 + P2 -->|assigned| R5 - P3 --> R6 - P3 --> R7 + P3 -->|assigned| R6 + P3 -->|assigned| R7 - style Subscription fill:#E91E63,color:#fff - style ResourceGroup fill:#9C27B0,color:#fff - style Resource fill:#2196F3,color:#fff - style Principals fill:#4CAF50,color:#fff + %% ===== 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 @@ -368,13 +456,16 @@ orgRoleTypes: ### 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 + 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 From 31ed2b5f49b3803cddb944bf8c0cc83ab97ebfe7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 12:06:37 -0500 Subject: [PATCH 23/44] Enhance security architecture documentation by adding emojis, improving diagram styles, and refining connections for better clarity and navigation. --- docs/architecture/05-security-architecture.md | 212 +++++++++++------- 1 file changed, 133 insertions(+), 79 deletions(-) diff --git a/docs/architecture/05-security-architecture.md b/docs/architecture/05-security-architecture.md index 3f3d14c0..e22b3748 100644 --- a/docs/architecture/05-security-architecture.md +++ b/docs/architecture/05-security-architecture.md @@ -487,45 +487,61 @@ sequenceDiagram ### Secrets Architecture ```mermaid +--- +title: Secrets Architecture +--- flowchart TB - subgraph Sources["Secret Sources"] - GH_CLI["gh auth token"] - MANUAL["Manual Entry"] - AZD_ENV[".azure/.env"] + %% ===== SECRET SOURCES ===== + subgraph Sources["๐Ÿ”‘ Secret Sources"] + GH_CLI["๐Ÿ™ gh auth token"] + MANUAL["โœ๏ธ Manual Entry"] + AZD_ENV["๐Ÿ“„ .azure/.env"] end - subgraph KeyVault["Azure Key Vault"] - KV["Key Vault Resource"] + %% ===== 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"] + 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\n(GitHub PAT)"] + subgraph Secrets["๐Ÿ”’ Secrets"] + PAT["๐Ÿ”‘ gha-token
(GitHub PAT)"] end end - subgraph Access["Secret Access"] - MI["DevCenter\nManaged Identity"] - CAT["Catalog\n(Private Repo)"] + %% ===== SECRET ACCESS ===== + subgraph Access["๐Ÿ”“ Secret Access"] + MI["๐Ÿ” DevCenter
Managed Identity"] + CAT["๐Ÿ“š Catalog
(Private Repo)"] end - GH_CLI --> AZD_ENV - MANUAL --> AZD_ENV - AZD_ENV -->|"provision"| KV + %% ===== CONNECTIONS ===== + GH_CLI -->|extracts| AZD_ENV + MANUAL -->|inputs| AZD_ENV + AZD_ENV -->|provision| KV + + KV -->|stores| Secrets - KV --> 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 - MI -->|"Key Vault Secrets User"| PAT - PAT -->|"secretIdentifier"| CAT + class GH_CLI,MANUAL,AZD_ENV datastore + class KV,PP,SD,RET,RBAC,PAT failed + class MI,CAT secondary - style Sources fill:#FF9800,color:#fff - style KeyVault fill:#F44336,color:#fff - style Access fill:#4CAF50,color:#fff + 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 @@ -553,12 +569,15 @@ keyVault: ### 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) + 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) @@ -585,47 +604,63 @@ sequenceDiagram ### Network Security Architecture ```mermaid +--- +title: Network Security Architecture +--- flowchart TB - subgraph Internet["Internet"] - DEV["Developer"] - GH["GitHub.com"] + %% ===== INTERNET ===== + subgraph Internet["๐ŸŒ Internet"] + DEV["๐Ÿ‘จโ€๐Ÿ’ป Developer"] + GH["๐Ÿ™ GitHub.com"] end - subgraph AzureNetwork["Azure Network Security"] - subgraph NSG["Network Security Group"] - RULE1["Allow RDP (3389)\nfrom Corporate"] - RULE2["Allow HTTPS (443)\nOutbound"] - RULE3["Deny All\nDefault"] + %% ===== 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\n10.0.1.0/24"] + subgraph VNet["๐Ÿ”— Virtual Network"] + SUBNET["๐Ÿ“ถ Dev Box Subnet
10.0.1.0/24"] end - subgraph PE["Private Endpoints"] - KV_PE["Key Vault PE\n(Optional)"] - LA_PE["Log Analytics PE\n(Optional)"] + subgraph PE["๐Ÿ”’ Private Endpoints"] + KV_PE["๐Ÿ”‘ Key Vault PE
(Optional)"] + LA_PE["๐Ÿ“Š Log Analytics PE
(Optional)"] end end - subgraph Resources["Azure Resources"] - DB["Dev Box"] - KV["Key Vault"] - LA["Log Analytics"] + %% ===== RESOURCES ===== + subgraph Resources["๐Ÿข Azure Resources"] + DB["๐Ÿ–ฅ๏ธ Dev Box"] + KV["๐Ÿ”‘ Key Vault"] + LA["๐Ÿ“Š Log Analytics"] end - DEV -->|"RDP"| NSG - NSG --> SUBNET - SUBNET --> DB + %% ===== 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 - DB -->|"HTTPS"| GH - DB --> PE - PE --> KV - PE --> LA + class DEV,GH external + class RULE1,RULE2,RULE3,SUBNET,KV_PE,LA_PE primary + class DB,KV,LA secondary - style Internet fill:#F44336,color:#fff - style AzureNetwork fill:#2196F3,color:#fff - style Resources fill:#4CAF50,color:#fff + 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 @@ -732,38 +767,57 @@ tags: ### Security Monitoring ```mermaid +--- +title: Security Monitoring Architecture +--- flowchart TB - subgraph Sources["Audit Sources"] - KV_AUDIT["Key Vault\nAuditEvent"] - AAD_AUDIT["Azure AD\nSign-in Logs"] - ACT_LOG["Activity Log"] - DC_LOG["DevCenter\nDiagnostics"] + %% ===== 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 - subgraph Collection["Log Analytics"] - LA["Workspace"] - TABLES["Security Tables"] + %% ===== LOG ANALYTICS ===== + subgraph Collection["๐Ÿ“Š Log Analytics"] + LA["๐Ÿ“ˆ Workspace"] + TABLES["๐Ÿ“‹ Security Tables"] end - subgraph Detection["Detection"] - RULES["Alert Rules"] - SENT["Microsoft Sentinel\n(Optional)"] + %% ===== DETECTION ===== + subgraph Detection["๐Ÿ” Detection"] + RULES["๐Ÿ”” Alert Rules"] + SENT["๐Ÿ›ก๏ธ Microsoft Sentinel
(Optional)"] end - subgraph Response["Response"] - EMAIL["Email Notifications"] - TICKET["Service Tickets"] - AUTO["Automation"] + %% ===== RESPONSE ===== + subgraph Response["๐Ÿšจ Response"] + EMAIL["๐Ÿ“ง Email Notifications"] + TICKET["๐ŸŽซ Service Tickets"] + AUTO["โšก Automation"] end - Sources --> Collection - Collection --> Detection - Detection --> Response + %% ===== 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:#FF9800,color:#fff - style Collection fill:#2196F3,color:#fff - style Detection fill:#9C27B0,color:#fff - style Response fill:#4CAF50,color:#fff + 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 From 3727733694a55f26a921253e95c28caea8e9ca75 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 10:04:52 -0800 Subject: [PATCH 24/44] Add comprehensive documentation for DevExp-DevBox, including architecture, DevOps, scripts, and quick start guides for Azure deployment. --- docs/README.md | 206 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 206 insertions(+) create mode 100644 docs/README.md 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)** + +
From 9d7d4ba696337ce29137ff2aac4d1da59e634464 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 10:12:54 -0800 Subject: [PATCH 25/44] Enhance Key Performance Indicators documentation by adding emojis for better visualization and improving diagram styles for clarity. --- docs/architecture/01-business-architecture.md | 51 +++++++---- docs/architecture/02-data-architecture.md | 84 ++++++++++++------- 2 files changed, 87 insertions(+), 48 deletions(-) diff --git a/docs/architecture/01-business-architecture.md b/docs/architecture/01-business-architecture.md index 4359eb94..da4852d3 100644 --- a/docs/architecture/01-business-architecture.md +++ b/docs/architecture/01-business-architecture.md @@ -470,35 +470,54 @@ stateDiagram-v2 ### 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"] + 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 %"] + 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"] + 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"] + KPI10["๐Ÿ’ฐ Cost per Developer"] + KPI11["๐Ÿ“Š Resource Utilization"] + KPI12["๐Ÿ“‹ Budget Variance"] end - style Developer fill:#4CAF50,color:#fff - style Operations fill:#FF9800,color:#fff - style Security fill:#F44336,color:#fff - style Cost fill:#2196F3,color:#fff + %% ===== 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 diff --git a/docs/architecture/02-data-architecture.md b/docs/architecture/02-data-architecture.md index bab71e8a..bf46f76d 100644 --- a/docs/architecture/02-data-architecture.md +++ b/docs/architecture/02-data-architecture.md @@ -581,51 +581,71 @@ resource diagnosticSettings 'Microsoft.Insights/diagnosticSettings@2021-05-01-pr ### Configuration Loading Flow ```mermaid +--- +title: Configuration Loading Flow +--- flowchart TB - subgraph Source["Git Repository"] - Y1["azureResources.yaml"] - Y2["security.yaml"] - Y3["devcenter.yaml"] + %% ===== SOURCE LAYER ===== + subgraph Source["๐Ÿ“ Git Repository"] + Y1["๐Ÿ“„ azureResources.yaml"] + Y2["๐Ÿ” security.yaml"] + Y3["๐Ÿ–ฅ๏ธ devcenter.yaml"] end - subgraph Bicep["Bicep Compilation"] - LOAD["loadYamlContent()"] - MAIN["main.bicep"] - SEC["security.bicep"] - WL["workload.bicep"] + %% ===== BICEP COMPILATION LAYER ===== + subgraph Bicep["โš™๏ธ Bicep Compilation"] + LOAD["๐Ÿ”„ loadYamlContent()"] + MAIN["๐Ÿ“„ main.bicep"] + SEC["๐Ÿ” security.bicep"] + WL["๐Ÿ“ฆ workload.bicep"] end - subgraph Deploy["Deployment"] - ARM["ARM Template"] - AZ["Azure Resource Manager"] + %% ===== DEPLOYMENT LAYER ===== + subgraph Deploy["๐Ÿš€ Deployment"] + ARM["๐Ÿ“‹ ARM Template"] + AZ["โ˜๏ธ Azure Resource Manager"] end - subgraph Resources["Azure Resources"] - RG["Resource Groups"] - KVRES["Key Vault"] - DCRES["DevCenter"] + %% ===== RESOURCES LAYER ===== + subgraph Resources["๐Ÿข Azure Resources"] + RG["๐Ÿ“ Resource Groups"] + KVRES["๐Ÿ”‘ Key Vault"] + DCRES["๐Ÿ–ฅ๏ธ DevCenter"] end - Y1 --> LOAD - Y2 --> LOAD - Y3 --> LOAD + %% ===== CONNECTIONS ===== + Y1 -->|loads| LOAD + Y2 -->|loads| LOAD + Y3 -->|loads| LOAD + + LOAD -->|configures| MAIN + MAIN -->|invokes| SEC + MAIN -->|invokes| WL - LOAD --> MAIN - MAIN --> SEC - MAIN --> WL + SEC -->|compiles| ARM + WL -->|compiles| ARM - SEC --> ARM - WL --> 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 - ARM --> AZ - AZ --> RG - AZ --> KVRES - AZ --> DCRES + class Y1,Y2,Y3 datastore + class LOAD,MAIN,SEC,WL primary + class ARM,AZ trigger + class RG,KVRES,DCRES secondary - style Source fill:#9C27B0,color:#fff - style Bicep fill:#FF9800,color:#fff - style Deploy fill:#2196F3,color:#fff - style Resources fill:#4CAF50,color:#fff + %% ===== 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 From c246e90d98d4901687dd00d31f799b2956541580 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 10:14:12 -0800 Subject: [PATCH 26/44] Enhance CI, Deploy, and Release documentation by improving pipeline visualizations with clearer labels, emojis, and refined connections for better clarity and navigation. --- docs/devops/ci.md | 54 +++++++++++++++++----------- docs/devops/deploy.md | 77 +++++++++++++++++++++++---------------- docs/devops/release.md | 82 +++++++++++++++++++++++++----------------- 3 files changed, 129 insertions(+), 84 deletions(-) diff --git a/docs/devops/ci.md b/docs/devops/ci.md index 8e9d6062..11bfe26e 100644 --- a/docs/devops/ci.md +++ b/docs/devops/ci.md @@ -55,42 +55,56 @@ The **Continuous Integration (CI)** workflow validates and builds Bicep template ## ๐Ÿ“Š Pipeline Visualization ```mermaid +--- +title: CI Pipeline Visualization +--- flowchart TD - subgraph "๐ŸŽฏ Triggers" - T1([Push to feature/**]) - T2([Push to fix/**]) - T3([PR to main]) + %% ===== TRIGGERS ===== + subgraph Triggers["๐ŸŽฏ Triggers"] + T1(["๐ŸŒฟ Push to feature/**"]) + T2(["๐Ÿ”ง Push to fix/**"]) + T3(["๐Ÿ“ PR to main"]) end - subgraph "๐Ÿ“Š generate-tag-version" + %% ===== 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 --> GTV2 --> GTV3 + GTV3[/"๐Ÿ“ฆ new_version, release_type, previous_tag"/] + GTV1 -->|clones| GTV2 -->|outputs| GTV3 end - subgraph "๐Ÿ”จ build" + %% ===== BUILD JOB ===== + subgraph Build["๐Ÿ”จ build"] direction TB B1["๐Ÿ”„ Checkout Repository"] B2["๐Ÿ“ฆ Build Bicep Code"] - B3[/"Versioned Artifacts"/] - B1 --> B2 --> B3 + B3[/"โœ… Versioned Artifacts"/] + B1 -->|clones| B2 -->|produces| B3 end - T1 & T2 & T3 --> GTV1 - GTV3 --> |"success"| B1 - GTV3 -.-> |"failure"| SKIP((Skipped)) + %% ===== CONNECTIONS ===== + T1 & T2 & T3 -->|triggers| GTV1 + GTV3 -->|success| B1 + GTV3 -.->|failure| SKIP((โญ๏ธ Skipped)) - classDef trigger fill:#2196F3,stroke:#1565C0,color:#fff - classDef build fill:#FF9800,stroke:#EF6C00,color:#fff - classDef artifact fill:#4CAF50,stroke:#2E7D32,color:#fff - classDef skip fill:#9E9E9E,stroke:#616161,color:#fff + %% ===== 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 build - class GTV3,B3 artifact - class SKIP skip + 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 ``` --- diff --git a/docs/devops/deploy.md b/docs/devops/deploy.md index b51d7d48..5be2284d 100644 --- a/docs/devops/deploy.md +++ b/docs/devops/deploy.md @@ -59,53 +59,68 @@ The **Deploy to Azure** workflow provisions infrastructure to Azure using the Az ## ๐Ÿ“Š Pipeline Visualization ```mermaid +--- +title: Deploy to Azure Pipeline Visualization +--- flowchart TD - subgraph "๐ŸŽฏ Trigger" - T1([Manual Dispatch]) + %% ===== TRIGGER ===== + subgraph Trigger["๐ŸŽฏ Trigger"] + T1(["๐Ÿ–ฑ๏ธ Manual Dispatch"]) end - subgraph "๐Ÿ“ Inputs" + %% ===== INPUTS ===== + subgraph Inputs["๐Ÿ“ Inputs"] direction LR - I1[/"AZURE_ENV_NAME"/] - I2[/"AZURE_LOCATION"/] + I1[/"๐ŸŒ AZURE_ENV_NAME"/] + I2[/"๐Ÿ“ AZURE_LOCATION"/] end - subgraph "๐Ÿš€ build-and-deploy-to-azure" + %% ===== BUILD AND DEPLOY JOB ===== + subgraph BuildDeploy["๐Ÿš€ build-and-deploy-to-azure"] direction TB V1["โœ… Validate Required Variables"] - V1 --> C1["๐Ÿ”„ Checkout Repository"] - C1 --> AZD["๐Ÿ“ฅ Install Azure Developer CLI"] - AZD --> B1["๐Ÿ”จ Build Bicep Templates"] - B1 --> U1["๐Ÿ“ค Upload Build Artifacts"] - U1 --> S1["๐Ÿ“Š Generate Build Summary"] - S1 --> AUTH["๐Ÿ” Authenticate with Azure (OIDC)"] - AUTH --> D1["๐Ÿš€ Deploy Infrastructure to Azure"] - D1 --> DS["๐Ÿ“‹ Generate Deployment Summary"] + 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 - subgraph "โ˜๏ธ Azure Resources" - AZ1[(Azure Subscription)] - AZ2[Dev Center] - AZ3[Key Vault] - AZ4[Virtual Network] + %% ===== AZURE RESOURCES ===== + subgraph AzureResources["โ˜๏ธ Azure Resources"] + AZ1[("๐Ÿ”‘ Azure Subscription")] + AZ2["๐Ÿ–ฅ๏ธ Dev Center"] + AZ3["๐Ÿ” Key Vault"] + AZ4["๐ŸŒ Virtual Network"] end - T1 --> I1 & I2 - I1 & I2 --> V1 - D1 --> AZ1 - AZ1 --> AZ2 & AZ3 & AZ4 + %% ===== CONNECTIONS ===== + T1 -->|provides| I1 & I2 + I1 & I2 -->|configures| V1 + D1 -->|creates| AZ1 + AZ1 -->|provisions| AZ2 & AZ3 & AZ4 - classDef trigger fill:#2196F3,stroke:#1565C0,color:#fff - classDef input fill:#9C27B0,stroke:#6A1B9A,color:#fff - classDef build fill:#FF9800,stroke:#EF6C00,color:#fff - classDef deploy fill:#4CAF50,stroke:#2E7D32,color:#fff - classDef azure fill:#0078D4,stroke:#005A9E,color:#fff + %% ===== 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 build - class AUTH,D1,DS deploy - class AZ1,AZ2,AZ3,AZ4 azure + 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 ``` --- diff --git a/docs/devops/release.md b/docs/devops/release.md index d8595f0d..5b069d6b 100644 --- a/docs/devops/release.md +++ b/docs/devops/release.md @@ -57,68 +57,84 @@ The **Branch-Based Release Strategy** workflow generates semantic versions and p ## ๐Ÿ“Š Pipeline Visualization ```mermaid +--- +title: Release Pipeline Visualization +--- flowchart TD - subgraph "๐ŸŽฏ Trigger" - T1([Manual Dispatch]) - I1[/"force_release: boolean"/] - T1 --> I1 + %% ===== TRIGGER ===== + subgraph Trigger["๐ŸŽฏ Trigger"] + T1(["๐Ÿ–ฑ๏ธ Manual Dispatch"]) + I1[/"๐Ÿ”„ force_release: boolean"/] + T1 -->|configures| I1 end - subgraph "๐Ÿ“Š generate-release" + %% ===== 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 --> GR2 --> GR3 --> GR4 + GR4[/"๐Ÿ“ฆ new_version, release_type, should_release"/] + GR1 -->|clones| GR2 -->|summarizes| GR3 -->|outputs| GR4 end - subgraph "๐Ÿ”จ build" + %% ===== BUILD JOB ===== + subgraph Build["๐Ÿ”จ build"] direction TB B1["๐Ÿ”„ Checkout Repository"] B2["๐Ÿ“ฆ Build Bicep Templates"] B3["๐Ÿ“Š Build Summary"] - B1 --> B2 --> B3 + B1 -->|compiles| B2 -->|reports| B3 end - subgraph "๐Ÿš€ publish-release" + %% ===== 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 --> PR2 --> PR3 --> PR4 --> PR5 + PR1 -->|downloads| PR2 -->|generates| PR3 -->|publishes| PR4 -->|summarizes| PR5 end - subgraph "๐Ÿ“Š summary" + %% ===== SUMMARY JOB ===== + subgraph Summary["๐Ÿ“Š summary"] direction TB S1["๐Ÿ“ˆ Workflow Summary"] end - I1 --> 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 --> S1 - SKIP1 --> S1 - SKIP2 --> S1 - - classDef trigger fill:#2196F3,stroke:#1565C0,color:#fff - classDef generate fill:#9C27B0,stroke:#6A1B9A,color:#fff - classDef build fill:#FF9800,stroke:#EF6C00,color:#fff - classDef publish fill:#4CAF50,stroke:#2E7D32,color:#fff - classDef summary fill:#607D8B,stroke:#455A64,color:#fff - classDef skip fill:#9E9E9E,stroke:#616161,color:#fff + %% ===== 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 generate - class B1,B2,B3 build - class PR1,PR2,PR3,PR4,PR5 publish - class S1 summary - class SKIP1,SKIP2 skip + 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 ``` --- From cc8aa6dae994d3f693595e899512f99b6f018445 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 10:15:13 -0800 Subject: [PATCH 27/44] Enhance setup script documentation by improving flow visualizations with clearer labels, emojis, and refined connections for better clarity and navigation. --- docs/scripts/README.md | 95 +++++++++++++++--------- docs/scripts/clean-setup.md | 115 ++++++++++++++++++----------- docs/scripts/setup.md | 139 ++++++++++++++++++++++-------------- 3 files changed, 218 insertions(+), 131 deletions(-) diff --git a/docs/scripts/README.md b/docs/scripts/README.md index dacf0d54..da3cb013 100644 --- a/docs/scripts/README.md +++ b/docs/scripts/README.md @@ -59,43 +59,63 @@ This documentation covers the PowerShell scripts used to set up, manage, and cle ## ๐Ÿ—๏ธ Scripts Architecture ```mermaid +--- +title: Scripts Architecture +--- flowchart TB - subgraph RootScripts["Root Scripts"] - setUp["setUp.ps1\n(Environment Setup)"]:::root - cleanSetUp["cleanSetUp.ps1\n(Full Cleanup)"]:::root + %% ===== ROOT SCRIPTS ===== + subgraph RootScripts["๐Ÿš€ Root Scripts"] + setUp["๐Ÿ“ฅ setUp.ps1
(Environment Setup)"] + cleanSetUp["๐Ÿ—‘๏ธ cleanSetUp.ps1
(Full Cleanup)"] end - subgraph AzureScripts["Azure Scripts"] - createRole["createCustomRole.ps1"]:::azure - createUsers["createUsersAndAssignRole.ps1"]:::azure - genCreds["generateDeploymentCredentials.ps1"]:::azure - deleteUsers["deleteUsersAndAssignedRoles.ps1"]:::azure - deleteCreds["deleteDeploymentCredentials.ps1"]:::azure + %% ===== AZURE SCRIPTS ===== + subgraph AzureScripts["โ˜๏ธ Azure Scripts"] + createRole["๐Ÿ” createCustomRole.ps1"] + createUsers["๐Ÿ‘ฅ createUsersAndAssignRole.ps1"] + genCreds["๐Ÿ”‘ generateDeploymentCredentials.ps1"] + deleteUsers["๐Ÿ‘ค deleteUsersAndAssignedRoles.ps1"] + deleteCreds["๐Ÿ”’ deleteDeploymentCredentials.ps1"] end - subgraph GitHubScripts["GitHub Scripts"] - createSecret["createGitHubSecret\nAzureCredentials.ps1"]:::github - deleteSecret["deleteGitHubSecret\nAzureCredentials.ps1"]:::github + %% ===== GITHUB SCRIPTS ===== + subgraph GitHubScripts["๐Ÿ™ GitHub Scripts"] + createSecret["๐Ÿ“ createGitHubSecret
AzureCredentials.ps1"] + deleteSecret["โŒ deleteGitHubSecret
AzureCredentials.ps1"] end - subgraph UtilityScripts["Utility Scripts"] - cleanUp["cleanUp.ps1\n(Resource Groups)"]:::utility - wingetUpdate["winget-update.ps1\n(Store Apps)"]:::utility + %% ===== UTILITY SCRIPTS ===== + subgraph UtilityScripts["๐Ÿ”ง Utility Scripts"] + cleanUp["๐Ÿ—‘๏ธ cleanUp.ps1
(Resource Groups)"] + wingetUpdate["๐Ÿ“ฆ winget-update.ps1
(Store Apps)"] end - setUp -->|"Initializes"| genCreds - genCreds -->|"Calls"| createUsers - genCreds -->|"Calls"| createSecret + %% ===== 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 - cleanSetUp -->|"Orchestrates"| deleteUsers - cleanSetUp -->|"Orchestrates"| deleteCreds - cleanSetUp -->|"Orchestrates"| deleteSecret - cleanSetUp -->|"Orchestrates"| cleanUp - - classDef root fill:#2196F3,stroke:#1565C0,color:#fff - classDef azure fill:#FF9800,stroke:#EF6C00,color:#fff - classDef github fill:#4CAF50,stroke:#2E7D32,color:#fff - classDef utility fill:#9C27B0,stroke:#6A1B9A,color:#fff + %% ===== 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 ``` --- @@ -215,15 +235,22 @@ Scripts for resource management and Dev Box configuration. ### New Environment Setup ```mermaid +--- +title: New Environment Setup Flow +--- flowchart LR - A[az login] --> B[setUp.ps1] - B --> C[generateDeploymentCredentials.ps1] - C --> D[azd provision] + 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 - style A fill:#4CAF50 - style B fill:#2196F3 - style C fill:#FF9800 - style D fill:#4CAF50 + class A,D secondary + class B trigger + class C datastore ``` ```powershell diff --git a/docs/scripts/clean-setup.md b/docs/scripts/clean-setup.md index 088467a2..6d4675ab 100644 --- a/docs/scripts/clean-setup.md +++ b/docs/scripts/clean-setup.md @@ -60,69 +60,100 @@ This script orchestrates the complete cleanup of DevExp-DevBox infrastructure, i ## ๐Ÿ“Š Flow Visualization ```mermaid +--- +title: Clean Setup Script Flow +--- flowchart TD - subgraph Entry["Script Entry"] - A([cleanSetUp.ps1 Start]):::entry - B[/"Parse Parameters"/]:::input + %% ===== SCRIPT ENTRY ===== + subgraph Entry["๐Ÿ“ฅ Script Entry"] + A(["๐Ÿš€ cleanSetUp.ps1 Start"]) + B[/"๐Ÿ“ Parse Parameters"/] end - subgraph Main["Main Orchestration"] - C["Start-FullCleanup"]:::core + %% ===== MAIN ORCHESTRATION ===== + subgraph Main["๐ŸŽฏ Main Orchestration"] + C["โš™๏ธ Start-FullCleanup"] end - subgraph Deployments["Subscription Deployments"] - D["Remove-SubscriptionDeployments"]:::core - D1{Deployments exist?}:::decision - D2["Delete each deployment"]:::core - D3[\Deployments removed\]:::output + %% ===== SUBSCRIPTION DEPLOYMENTS ===== + subgraph Deployments["๐Ÿ“‹ Subscription Deployments"] + D["๐Ÿ—‘๏ธ Remove-SubscriptionDeployments"] + D1{"๐Ÿ“Š Deployments exist?"} + D2["๐Ÿ”„ Delete each deployment"] + D3[\"โœ… Deployments removed"\] end - subgraph Users["User Cleanup"] - E["Invoke-CleanupScript"]:::core - E1["deleteUsersAndAssignedRoles.ps1"]:::external + %% ===== USER CLEANUP ===== + subgraph Users["๐Ÿ‘ฅ User Cleanup"] + E["โš™๏ธ Invoke-CleanupScript"] + E1[("๐Ÿ”ง deleteUsersAndAssignedRoles.ps1")] end - subgraph Credentials["Credentials Cleanup"] - F["Invoke-CleanupScript"]:::core - F1["deleteDeploymentCredentials.ps1"]:::external + %% ===== CREDENTIALS CLEANUP ===== + subgraph Credentials["๐Ÿ”‘ Credentials Cleanup"] + F["โš™๏ธ Invoke-CleanupScript"] + F1[("๐Ÿ”ง deleteDeploymentCredentials.ps1")] end - subgraph GitHub["GitHub Secret Cleanup"] - G["Invoke-CleanupScript"]:::core - G1["deleteGitHubSecretAzureCredentials.ps1"]:::external + %% ===== GITHUB SECRET CLEANUP ===== + subgraph GitHub["๐Ÿ™ GitHub Secret Cleanup"] + G["โš™๏ธ Invoke-CleanupScript"] + G1[("๐Ÿ”ง deleteGitHubSecretAzureCredentials.ps1")] end - subgraph Resources["Resource Groups"] - H["Invoke-CleanupScript"]:::core - H1["cleanUp.ps1"]:::external + %% ===== RESOURCE GROUPS ===== + subgraph Resources["๐Ÿข Resource Groups"] + H["โš™๏ธ Invoke-CleanupScript"] + H1[("๐Ÿ”ง cleanUp.ps1")] end - subgraph Exit["Script Exit"] - I{All succeeded?}:::decision - J[\Success\]:::output - K{{Error Handler}}:::error + %% ===== SCRIPT EXIT ===== + subgraph Exit["๐Ÿ“ค Script Exit"] + I{"โœ… All succeeded?"} + J[\"๐ŸŽ‰ Success"\] + K{{"โŒ Error Handler"}} end - A --> B --> C - C --> D - D --> D1 - D1 -->|Yes| D2 --> D3 + %% ===== CONNECTIONS ===== + A -->|parses| B -->|orchestrates| C + C -->|removes| D + D -->|checks| D1 + D1 -->|Yes| D2 -->|completes| D3 D1 -->|No| D3 - D3 --> E --> E1 - E1 --> F --> F1 - F1 --> G --> G1 - G1 --> H --> H1 - H1 --> I + 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 - classDef entry fill:#2196F3,stroke:#1565C0,color:#fff - classDef input fill:#9C27B0,stroke:#6A1B9A,color:#fff - classDef core fill:#FF9800,stroke:#EF6C00,color:#fff - classDef external fill:#4CAF50,stroke:#2E7D32,color:#fff - classDef decision fill:#FFC107,stroke:#FFA000,color:#000 - classDef output fill:#2196F3,stroke:#1565C0,color:#fff - classDef error fill:#F44336,stroke:#C62828,color:#fff + %% ===== 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 ``` --- diff --git a/docs/scripts/setup.md b/docs/scripts/setup.md index 3ab51007..56911e0a 100644 --- a/docs/scripts/setup.md +++ b/docs/scripts/setup.md @@ -60,84 +60,113 @@ This script automates the setup of an Azure Developer CLI (azd) environment for ## ๐Ÿ“Š Flow Visualization ```mermaid +--- +title: Setup Script Flow +--- flowchart TD - subgraph Entry["Script Entry"] - A([setUp.ps1 Start]):::entry - B[/"Parse Parameters"/]:::input - C{Help requested?}:::decision + %% ===== SCRIPT ENTRY ===== + subgraph Entry["๐Ÿ“ฅ Script Entry"] + A(["๐Ÿš€ setUp.ps1 Start"]) + B[/"๐Ÿ“ Parse Parameters"/] + C{"โ“ Help requested?"} end - subgraph Validation["Argument Validation"] - D["Test-Arguments"]:::validation - D1{EnvName provided?}:::decision - D2{SourceControl provided?}:::decision - D3["Select-SourceControlPlatform"]:::core - D4["Test-SourceControlValidation"]:::validation + %% ===== ARGUMENT VALIDATION ===== + subgraph Validation["โœ… Argument Validation"] + D["๐Ÿ” Test-Arguments"] + D1{"๐Ÿ“‹ EnvName provided?"} + D2{"๐Ÿ”— SourceControl provided?"} + D3["๐ŸŽฏ Select-SourceControlPlatform"] + D4["โœ”๏ธ Test-SourceControlValidation"] end - subgraph Tools["Tool Verification"] - E["Test-CommandAvailability"]:::validation - E1[(az)]:::external - E2[(azd)]:::external - E3[(gh)]:::external + %% ===== TOOL VERIFICATION ===== + subgraph Tools["๐Ÿ”ง Tool Verification"] + E["๐Ÿงช Test-CommandAvailability"] + E1[("โ˜๏ธ az")] + E2[("๐Ÿš€ azd")] + E3[("๐Ÿ™ gh")] end - subgraph Auth["Authentication"] - F["Test-AzureAuthentication"]:::validation - F1{Platform?}:::decision - F2["Test-GitHubAuthentication"]:::validation - F3["Test-AdoAuthentication"]:::validation + %% ===== AUTHENTICATION ===== + subgraph Auth["๐Ÿ” Authentication"] + F["๐Ÿ”‘ Test-AzureAuthentication"] + F1{"๐ŸŽ›๏ธ Platform?"} + F2["๐Ÿ™ Test-GitHubAuthentication"] + F3["๐Ÿ”ท Test-AdoAuthentication"] end - subgraph Token["Token Retrieval"] - G{Platform?}:::decision - G1["Get-SecureGitHubToken"]:::core - G2["Get-SecureAdoGitToken"]:::core + %% ===== TOKEN RETRIEVAL ===== + subgraph Token["๐ŸŽซ Token Retrieval"] + G{"๐ŸŽ›๏ธ Platform?"} + G1["๐Ÿ”’ Get-SecureGitHubToken"] + G2["๐Ÿ”’ Get-SecureAdoGitToken"] end - subgraph Init["Environment Init"] - H["Initialize-AzdEnvironment"]:::core - H1["Create .azure directory"]:::core - H2["Write .env file"]:::core - H3["Configure azd"]:::core + %% ===== ENVIRONMENT INIT ===== + subgraph Init["โš™๏ธ Environment Init"] + H["๐ŸŒ Initialize-AzdEnvironment"] + H1["๐Ÿ“ Create .azure directory"] + H2["๐Ÿ“ Write .env file"] + H3["โš™๏ธ Configure azd"] end - subgraph Exit["Script Exit"] - I[\Success\]:::output - J{{Error Handler}}:::error + %% ===== SCRIPT EXIT ===== + subgraph Exit["๐Ÿ“ค Script Exit"] + I[\"โœ… Success"\] + J{{"โŒ Error Handler"}} end - A --> B --> C - C -->|Yes| HELP[Show-Help] --> EXIT([Exit 0]):::entry + %% ===== CONNECTIONS ===== + A -->|starts| B -->|checks| C + C -->|Yes| HELP["๐Ÿ“– Show-Help"] -->|exits| EXIT(["๐Ÿšช Exit 0"]) C -->|No| D - D --> D1 + D -->|validates| D1 D1 -->|No| J D1 -->|Yes| D2 D2 -->|No| D3 D2 -->|Yes| D4 - D3 --> D4 - D4 --> E - E --> E1 & E2 - E --> F - F --> F1 - F1 -->|github| E3 --> F2 + 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 --> G - F3 --> G + F2 -->|retrieves| G + F3 -->|retrieves| G G -->|github| G1 G -->|adogit| G2 - G1 --> H - G2 --> H - H --> H1 --> H2 --> H3 --> I - - classDef entry fill:#2196F3,stroke:#1565C0,color:#fff - classDef input fill:#9C27B0,stroke:#6A1B9A,color:#fff - classDef core fill:#FF9800,stroke:#EF6C00,color:#fff - classDef validation fill:#9C27B0,stroke:#6A1B9A,color:#fff - classDef external fill:#4CAF50,stroke:#2E7D32,color:#fff - classDef decision fill:#FFC107,stroke:#FFA000,color:#000 - classDef output fill:#2196F3,stroke:#1565C0,color:#fff - classDef error fill:#F44336,stroke:#C62828,color:#fff + 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 ``` --- From f8eb1c57ef73d22e339aea3501cb6a41d8810e61 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 10:16:12 -0800 Subject: [PATCH 28/44] Enhance CI/CD pipeline documentation by adding emojis, improving diagram styles, and refining connections for better clarity and navigation. --- docs/devops/README.md | 162 ++++++++++++++++++++++++++---------------- 1 file changed, 101 insertions(+), 61 deletions(-) diff --git a/docs/devops/README.md b/docs/devops/README.md index 242b2357..f1f86930 100644 --- a/docs/devops/README.md +++ b/docs/devops/README.md @@ -58,68 +58,85 @@ This folder contains detailed documentation for all CI/CD workflows that automat 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 - subgraph "๐ŸŽฏ Triggers" + %% ===== TRIGGERS ===== + subgraph Triggers["๐ŸŽฏ Triggers"] direction LR - T1([Push: feature/**]) - T2([Push: fix/**]) - T3([PR to main]) - T4([Manual: Deploy]) - T5([Manual: Release]) + T1(["๐ŸŒฟ Push: feature/**"]) + T2(["๐Ÿ”ง Push: fix/**"]) + T3(["๐Ÿ“ PR to main"]) + T4(["๐Ÿ–ฑ๏ธ Manual: Deploy"]) + T5(["๐Ÿ–ฑ๏ธ Manual: Release"]) end - subgraph "๐Ÿ”„ Continuous Integration" + %% ===== CONTINUOUS INTEGRATION ===== + subgraph CI["๐Ÿ”„ Continuous Integration"] direction TB CI1["๐Ÿ“Š generate-tag-version"] CI2["๐Ÿ”จ build"] - CI1 --> CI2 + CI1 -->|calculates| CI2 end - subgraph "๐Ÿš€ Deployment" + %% ===== DEPLOYMENT ===== + subgraph Deployment["๐Ÿš€ Deployment"] direction TB D1["โœ… Validate Variables"] D2["๐Ÿ”จ Build Bicep"] D3["๐Ÿ” Azure OIDC Auth"] D4["โ˜๏ธ azd provision"] - D1 --> D2 --> D3 --> D4 + D1 -->|validates| D2 -->|authenticates| D3 -->|provisions| D4 end - subgraph "๐Ÿท๏ธ Release" + %% ===== RELEASE ===== + subgraph Release["๐Ÿท๏ธ Release"] direction TB R1["๐Ÿ“Š generate-release"] R2["๐Ÿ”จ build"] R3["๐ŸŽ‰ publish-release"] R4["๐Ÿ“‹ summary"] - R1 --> R2 --> R3 --> R4 + R1 -->|prepares| R2 -->|publishes| R3 -->|summarizes| R4 end - subgraph "๐Ÿ“ฆ Outputs" + %% ===== OUTPUTS ===== + subgraph Outputs["๐Ÿ“ฆ Outputs"] direction TB - O1[/"Versioned Artifacts"/] - O2[/"GitHub Release"/] - O3[(Azure Resources)] + O1[/"โœ… Versioned Artifacts"/] + O2[/"๐Ÿท๏ธ GitHub Release"/] + O3[("โ˜๏ธ Azure Resources")] end - T1 & T2 & T3 --> CI1 - T4 --> D1 - T5 --> R1 + %% ===== CONNECTIONS ===== + T1 & T2 & T3 -->|triggers| CI1 + T4 -->|triggers| D1 + T5 -->|triggers| R1 - CI2 --> O1 - R3 --> O1 - R3 --> O2 - D4 --> O3 + CI2 -->|produces| O1 + R3 -->|creates| O1 + R3 -->|creates| O2 + D4 -->|provisions| O3 - classDef trigger fill:#2196F3,stroke:#1565C0,color:#fff - classDef ci fill:#FF9800,stroke:#EF6C00,color:#fff - classDef deploy fill:#4CAF50,stroke:#2E7D32,color:#fff - classDef release fill:#9C27B0,stroke:#6A1B9A,color:#fff - classDef output fill:#607D8B,stroke:#455A64,color:#fff + %% ===== 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 ci - class D1,D2,D3,D4 deploy - class R1,R2,R3,R4 release - class O1,O2,O3 output + 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 ``` --- @@ -147,25 +164,35 @@ flowchart TB ### Trigger Summary ```mermaid +--- +title: Trigger Summary +--- flowchart LR - subgraph "Automatic Triggers" - A1["Push to feature/**"] --> CI["CI Workflow"] - A2["Push to fix/**"] --> CI - A3["PR to main"] --> CI + %% ===== 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 - subgraph "Manual Triggers" - M1["workflow_dispatch"] --> DEPLOY["Deploy Workflow"] - M2["workflow_dispatch"] --> RELEASE["Release Workflow"] + %% ===== MANUAL TRIGGERS ===== + subgraph ManualTriggers["๐Ÿ–ฑ๏ธ Manual Triggers"] + M1["๐Ÿ–ฑ๏ธ workflow_dispatch"] -->|triggers| DEPLOY["๐Ÿš€ Deploy Workflow"] + M2["๐Ÿ–ฑ๏ธ workflow_dispatch"] -->|triggers| RELEASE["๐Ÿท๏ธ Release Workflow"] end - classDef auto fill:#4CAF50,stroke:#2E7D32,color:#fff - classDef manual fill:#2196F3,stroke:#1565C0,color:#fff - classDef workflow fill:#FF9800,stroke:#EF6C00,color:#fff - - class A1,A2,A3 auto - class M1,M2 manual - class CI,DEPLOY,RELEASE workflow + %% ===== 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 @@ -206,26 +233,39 @@ flowchart LR ### Action Flow ```mermaid +--- +title: Reusable Actions Flow +--- flowchart LR - subgraph "generate-release" - GR1["Get Branch Info"] - GR2["Get Latest Tag"] - GR3["Determine Release Type"] - GR4["Count Commits"] - GR5["Calculate Version"] - GR6["Create Tag"] - GR1 --> GR2 --> GR3 --> GR4 --> GR5 --> GR6 + %% ===== 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 - subgraph "bicep-standard-ci" - BC1["Build Bicep"] - BC2["Upload Artifacts"] - BC3["Generate Summary"] - BC1 --> BC2 --> BC3 + %% ===== BICEP STANDARD CI ACTION ===== + subgraph BicepCI["๐Ÿ”จ bicep-standard-ci"] + BC1["๐Ÿ“ฆ Build Bicep"] + BC2["๐Ÿ“ค Upload Artifacts"] + BC3["๐Ÿ“Š Generate Summary"] + BC1 -->|uploads| BC2 -->|summarizes| BC3 end - classDef action fill:#9C27B0,stroke:#6A1B9A,color:#fff - class GR1,GR2,GR3,GR4,GR5,GR6,BC1,BC2,BC3 action + %% ===== 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 ``` --- From fb7f9d36391da59d73469183a67f0d0535f0ce09 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 10:17:03 -0800 Subject: [PATCH 29/44] Enhance flow visualization documentation for createCustomRole.ps1 and createUsersAndAssignRole.ps1 scripts by adding emojis, improving diagram styles, and refining connections for better clarity and navigation. --- docs/scripts/azure/create-custom-role.md | 91 ++++++++++++------- .../azure/create-users-and-assign-role.md | 91 ++++++++++++------- 2 files changed, 116 insertions(+), 66 deletions(-) diff --git a/docs/scripts/azure/create-custom-role.md b/docs/scripts/azure/create-custom-role.md index c5ee74d6..c481e23c 100644 --- a/docs/scripts/azure/create-custom-role.md +++ b/docs/scripts/azure/create-custom-role.md @@ -59,55 +59,80 @@ This script creates a custom Azure RBAC role definition that grants permissions ## ๐Ÿ“Š Flow Visualization ```mermaid +--- +title: Create Custom Role Flow +--- flowchart TD - subgraph Entry["Script Entry"] - A([createCustomRole.ps1 Start]):::entry - B[/"Parse Parameters"/]:::input + %% ===== SCRIPT ENTRY ===== + subgraph Entry["๐Ÿ“ฅ Script Entry"] + A(["๐Ÿš€ createCustomRole.ps1 Start"]) + B[/"๐Ÿ“ Parse Parameters"/] end - subgraph SubCheck["Subscription Resolution"] - C{SubscriptionId provided?}:::decision - D["Get-CurrentSubscriptionId"]:::core - E[(Azure CLI)]:::external + %% ===== SUBSCRIPTION RESOLUTION ===== + subgraph SubCheck["๐Ÿ” Subscription Resolution"] + C{"๐Ÿ“‹ SubscriptionId provided?"} + D["โš™๏ธ Get-CurrentSubscriptionId"] + E[("โ˜๏ธ Azure CLI")] end - subgraph RoleCreation["Role Definition Creation"] - F["New-CustomRoleDefinition"]:::core - F1["Build role definition JSON"]:::core - F2["Write to temp file"]:::core - F3{Force flag set?}:::decision - F4["Delete existing role"]:::core - F5[(az role definition create)]:::external + %% ===== 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 - subgraph Cleanup["Cleanup"] - G["Remove temp file"]:::core + %% ===== CLEANUP ===== + subgraph Cleanup["๐Ÿงน Cleanup"] + G["๐Ÿ—‘๏ธ Remove temp file"] end - subgraph Exit["Script Exit"] - H{Success?}:::decision - I[\Role Created\]:::output - J{{Error Handler}}:::error + %% ===== SCRIPT EXIT ===== + subgraph Exit["๐Ÿ“ค Script Exit"] + H{"โœ… Success?"} + I[\"๐ŸŽ‰ Role Created"\] + J{{"โŒ Error Handler"}} end - A --> B --> C - C -->|No| D --> E + %% ===== CONNECTIONS ===== + A -->|parses| B -->|checks| C + C -->|No| D -->|calls| E C -->|Yes| F - E --> F - F --> F1 --> F2 --> F3 - F3 -->|Yes| F4 --> F5 + E -->|provides| F + F -->|builds| F1 -->|writes| F2 -->|checks| F3 + F3 -->|Yes| F4 -->|creates| F5 F3 -->|No| F5 - F5 --> G --> H + F5 -->|cleans| G -->|evaluates| H H -->|Yes| I H -->|No| J - classDef entry fill:#2196F3,stroke:#1565C0,color:#fff - classDef input fill:#9C27B0,stroke:#6A1B9A,color:#fff - classDef core fill:#FF9800,stroke:#EF6C00,color:#fff - classDef external fill:#4CAF50,stroke:#2E7D32,color:#fff - classDef decision fill:#FFC107,stroke:#FFA000,color:#000 - classDef output fill:#2196F3,stroke:#1565C0,color:#fff - classDef error fill:#F44336,stroke:#C62828,color:#fff + %% ===== 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 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 ``` --- diff --git a/docs/scripts/azure/create-users-and-assign-role.md b/docs/scripts/azure/create-users-and-assign-role.md index 17aabe21..5dfa67ba 100644 --- a/docs/scripts/azure/create-users-and-assign-role.md +++ b/docs/scripts/azure/create-users-and-assign-role.md @@ -57,55 +57,80 @@ This script retrieves the current Azure AD signed-in user and assigns DevCenter- ## ๐Ÿ“Š Flow Visualization ```mermaid +--- +title: Create Users and Assign Role Flow +--- flowchart TD - subgraph Entry["Script Entry"] - A([createUsersAndAssignRole.ps1 Start]):::entry - B[/"Parse Parameters"/]:::input + %% ===== SCRIPT ENTRY ===== + subgraph Entry["๐Ÿ“ฅ Script Entry"] + A(["๐Ÿš€ createUsersAndAssignRole.ps1 Start"]) + B[/"๐Ÿ“ Parse Parameters"/] end - subgraph SubCheck["Subscription Resolution"] - C{SubscriptionId provided?}:::decision - D[(az account show)]:::external + %% ===== SUBSCRIPTION RESOLUTION ===== + subgraph SubCheck["๐Ÿ” Subscription Resolution"] + C{"๐Ÿ“‹ SubscriptionId provided?"} + D[("โ˜๏ธ az account show")] end - subgraph UserLookup["User Identification"] - E["New-UserRoleAssignments"]:::core - F[(az ad signed-in-user show)]:::external - G["Get current user Object ID"]:::core + %% ===== USER IDENTIFICATION ===== + subgraph UserLookup["๐Ÿ‘ค User Identification"] + E["โš™๏ธ New-UserRoleAssignments"] + F[("๐Ÿ” az ad signed-in-user show")] + G["๐Ÿ†” Get current user Object ID"] end - subgraph RoleLoop["Role Assignment Loop"] - H["For each DevCenter role"]:::core - I["Set-AzureRole"]:::core - I1{Role already assigned?}:::decision - I2["Skip - already assigned"]:::core - I3[(az role assignment create)]:::external + %% ===== 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 - subgraph Exit["Script Exit"] - J{All succeeded?}:::decision - K[\Roles Assigned\]:::output - L{{Error Handler}}:::error + %% ===== SCRIPT EXIT ===== + subgraph Exit["๐Ÿ“ค Script Exit"] + J{"โœ… All succeeded?"} + K[\"๐ŸŽ‰ Roles Assigned"\] + L{{"โŒ Error Handler"}} end - A --> B --> C - C -->|No| D --> E + %% ===== CONNECTIONS ===== + A -->|parses| B -->|checks| C + C -->|No| D -->|continues| E C -->|Yes| E - E --> F --> G --> H - H --> I --> I1 - I1 -->|Yes| I2 --> H - I1 -->|No| I3 --> H + 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 - classDef entry fill:#2196F3,stroke:#1565C0,color:#fff - classDef input fill:#9C27B0,stroke:#6A1B9A,color:#fff - classDef core fill:#FF9800,stroke:#EF6C00,color:#fff - classDef external fill:#4CAF50,stroke:#2E7D32,color:#fff - classDef decision fill:#FFC107,stroke:#FFA000,color:#000 - classDef output fill:#2196F3,stroke:#1565C0,color:#fff - classDef error fill:#F44336,stroke:#C62828,color:#fff + %% ===== 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 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 ``` --- From 417e02deac80f248069d5e8135f8d4ecd120d918 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 10:18:09 -0800 Subject: [PATCH 30/44] Enhance flow visualization documentation for deleteDeploymentCredentials.ps1, deleteUsersAndAssignedRoles.ps1, and generateDeploymentCredentials.ps1 scripts by adding emojis, improving diagram styles, and refining connections for better clarity and navigation. --- .../azure/delete-deployment-credentials.md | 77 ++++++++++------ .../azure/delete-users-and-assigned-roles.md | 91 ++++++++++++------- .../azure/generate-deployment-credentials.md | 85 +++++++++++------ 3 files changed, 163 insertions(+), 90 deletions(-) diff --git a/docs/scripts/azure/delete-deployment-credentials.md b/docs/scripts/azure/delete-deployment-credentials.md index f9d89228..40cea9e2 100644 --- a/docs/scripts/azure/delete-deployment-credentials.md +++ b/docs/scripts/azure/delete-deployment-credentials.md @@ -61,46 +61,69 @@ This script removes an Azure AD service principal and its associated application ## ๐Ÿ“Š Flow Visualization ```mermaid +--- +title: Delete Deployment Credentials Flow +--- flowchart TD - subgraph Entry["Script Entry"] - A([deleteDeploymentCredentials.ps1 Start]):::entry - B[/"Parse Parameters"/]:::input + %% ===== SCRIPT ENTRY ===== + subgraph Entry["๐Ÿ“ฅ Script Entry"] + A(["๐Ÿš€ deleteDeploymentCredentials.ps1 Start"]) + B[/"๐Ÿ“ Parse Parameters"/] end - subgraph Lookup["Application Lookup"] - C["Remove-AzureDeploymentCredentials"]:::core - D[(az ad app list)]:::external - E{App found?}:::decision - F["Get App ID"]:::core + %% ===== APPLICATION LOOKUP ===== + subgraph Lookup["๐Ÿ” Application Lookup"] + C["โš™๏ธ Remove-AzureDeploymentCredentials"] + D[("๐Ÿ” az ad app list")] + E{"๐Ÿ“‹ App found?"} + F["๐Ÿ†” Get App ID"] end - subgraph Delete["Credential Deletion"] - G[(az ad sp delete)]:::external - H["Delete service principal"]:::core - I[(az ad app delete)]:::external - J["Delete app registration"]:::core + %% ===== 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 - subgraph Exit["Script Exit"] - K{Success?}:::decision - L[\Credentials Deleted\]:::output - M[\Not Found - Skip\]:::output - N{{Error Handler}}:::error + %% ===== SCRIPT EXIT ===== + subgraph Exit["๐Ÿ“ค Script Exit"] + K{"โœ… Success?"} + L[\"๐ŸŽ‰ Credentials Deleted"\] + M[\"โญ๏ธ Not Found - Skip"\] + N{{"โŒ Error Handler"}} end - A --> B --> C --> D --> E + %% ===== CONNECTIONS ===== + A -->|parses| B -->|invokes| C -->|queries| D -->|checks| E E -->|No| M - E -->|Yes| F --> G --> H --> I --> J --> K + E -->|Yes| F -->|deletes| G -->|continues| H -->|deletes| I -->|completes| J -->|evaluates| K K -->|Yes| L K -->|No| N - classDef entry fill:#2196F3,stroke:#1565C0,color:#fff - classDef input fill:#9C27B0,stroke:#6A1B9A,color:#fff - classDef core fill:#FF9800,stroke:#EF6C00,color:#fff - classDef external fill:#4CAF50,stroke:#2E7D32,color:#fff - classDef decision fill:#FFC107,stroke:#FFA000,color:#000 - classDef output fill:#2196F3,stroke:#1565C0,color:#fff - classDef error fill:#F44336,stroke:#C62828,color:#fff + %% ===== 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,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 ``` --- diff --git a/docs/scripts/azure/delete-users-and-assigned-roles.md b/docs/scripts/azure/delete-users-and-assigned-roles.md index 180b3888..c0547c5a 100644 --- a/docs/scripts/azure/delete-users-and-assigned-roles.md +++ b/docs/scripts/azure/delete-users-and-assigned-roles.md @@ -56,55 +56,80 @@ This script removes Azure RBAC role assignments that were created for DevCenter ## ๐Ÿ“Š Flow Visualization ```mermaid +--- +title: Delete Users and Assigned Roles Flow +--- flowchart TD - subgraph Entry["Script Entry"] - A([deleteUsersAndAssignedRoles.ps1 Start]):::entry - B[/"Parse Parameters"/]:::input + %% ===== SCRIPT ENTRY ===== + subgraph Entry["๐Ÿ“ฅ Script Entry"] + A(["๐Ÿš€ deleteUsersAndAssignedRoles.ps1 Start"]) + B[/"๐Ÿ“ Parse Parameters"/] end - subgraph SubCheck["Subscription Resolution"] - C{SubscriptionId provided?}:::decision - D[(az account show)]:::external + %% ===== SUBSCRIPTION RESOLUTION ===== + subgraph SubCheck["๐Ÿ” Subscription Resolution"] + C{"๐Ÿ“‹ SubscriptionId provided?"} + D[("โ˜๏ธ az account show")] end - subgraph UserLookup["User Identification"] - E["Remove-UserRoleAssignments"]:::core - F[(az ad signed-in-user show)]:::external - G["Get current user Object ID"]:::core + %% ===== USER IDENTIFICATION ===== + subgraph UserLookup["๐Ÿ‘ค User Identification"] + E["โš™๏ธ Remove-UserRoleAssignments"] + F[("๐Ÿ” az ad signed-in-user show")] + G["๐Ÿ†” Get current user Object ID"] end - subgraph RoleLoop["Role Removal Loop"] - H["For each DevCenter role"]:::core - I["Remove-UserRoleAssignment"]:::core - I1{Role assigned?}:::decision - I2["Skip - not assigned"]:::core - I3[(az role assignment delete)]:::external + %% ===== 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 - subgraph Exit["Script Exit"] - J{All succeeded?}:::decision - K[\Roles Removed\]:::output - L{{Error Handler}}:::error + %% ===== SCRIPT EXIT ===== + subgraph Exit["๐Ÿ“ค Script Exit"] + J{"โœ… All succeeded?"} + K[\"๐ŸŽ‰ Roles Removed"\] + L{{"โŒ Error Handler"}} end - A --> B --> C - C -->|No| D --> E + %% ===== CONNECTIONS ===== + A -->|parses| B -->|checks| C + C -->|No| D -->|continues| E C -->|Yes| E - E --> F --> G --> H - H --> I --> I1 - I1 -->|No| I2 --> H - I1 -->|Yes| I3 --> H + 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 - classDef entry fill:#2196F3,stroke:#1565C0,color:#fff - classDef input fill:#9C27B0,stroke:#6A1B9A,color:#fff - classDef core fill:#FF9800,stroke:#EF6C00,color:#fff - classDef external fill:#4CAF50,stroke:#2E7D32,color:#fff - classDef decision fill:#FFC107,stroke:#FFA000,color:#000 - classDef output fill:#2196F3,stroke:#1565C0,color:#fff - classDef error fill:#F44336,stroke:#C62828,color:#fff + %% ===== 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 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 ``` --- diff --git a/docs/scripts/azure/generate-deployment-credentials.md b/docs/scripts/azure/generate-deployment-credentials.md index 79843d2f..1651d6c6 100644 --- a/docs/scripts/azure/generate-deployment-credentials.md +++ b/docs/scripts/azure/generate-deployment-credentials.md @@ -64,50 +64,75 @@ This script creates an Azure AD service principal with required roles for CI/CD ## ๐Ÿ“Š Flow Visualization ```mermaid +--- +title: Generate Deployment Credentials Flow +--- flowchart TD - subgraph Entry["Script Entry"] - A([generateDeploymentCredentials.ps1 Start]):::entry - B[/"Parse Parameters"/]:::input + %% ===== SCRIPT ENTRY ===== + subgraph Entry["๐Ÿ“ฅ Script Entry"] + A(["๐Ÿš€ generateDeploymentCredentials.ps1 Start"]) + B[/"๐Ÿ“ Parse Parameters"/] end - subgraph SPCreation["Service Principal Creation"] - C["New-AzureDeploymentCredentials"]:::core - D[(az ad sp create-for-rbac)]:::external - E["Assign Contributor role"]:::core - F[(az role assignment create)]:::external - G["Assign User Access Administrator"]:::core - H["Assign Managed Identity Contributor"]:::core + %% ===== 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 - subgraph UserRoles["User Role Setup"] - I["Invoke-UserRoleAssignment"]:::core - J["createUsersAndAssignRole.ps1"]:::external + %% ===== USER ROLE SETUP ===== + subgraph UserRoles["๐Ÿ‘ฅ User Role Setup"] + I["โš™๏ธ Invoke-UserRoleAssignment"] + J[("๐Ÿ”ง createUsersAndAssignRole.ps1")] end - subgraph GitHubSecret["GitHub Secret Creation"] - K["Invoke-GitHubSecretCreation"]:::core - L["createGitHubSecretAzureCredentials.ps1"]:::external + %% ===== GITHUB SECRET CREATION ===== + subgraph GitHubSecret["๐Ÿ™ GitHub Secret Creation"] + K["โš™๏ธ Invoke-GitHubSecretCreation"] + L[("๐Ÿ“ createGitHubSecretAzureCredentials.ps1")] end - subgraph Exit["Script Exit"] - M{All succeeded?}:::decision - N[\Credentials Created\]:::output - O{{Warning: Partial failure}}:::error + %% ===== SCRIPT EXIT ===== + subgraph Exit["๐Ÿ“ค Script Exit"] + M{"โœ… All succeeded?"} + N[\"๐ŸŽ‰ Credentials Created"\] + O{{"โš ๏ธ Warning: Partial failure"}} end - A --> B --> C --> D --> E --> F --> G --> H - H --> I --> J - J --> K --> L --> M + %% ===== 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 - classDef entry fill:#2196F3,stroke:#1565C0,color:#fff - classDef input fill:#9C27B0,stroke:#6A1B9A,color:#fff - classDef core fill:#FF9800,stroke:#EF6C00,color:#fff - classDef external fill:#4CAF50,stroke:#2E7D32,color:#fff - classDef decision fill:#FFC107,stroke:#FFA000,color:#000 - classDef output fill:#2196F3,stroke:#1565C0,color:#fff - classDef error fill:#F44336,stroke:#C62828,color:#fff + %% ===== 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,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 ``` --- From 4c61939b7958c05beb656f8cb95610348221b690 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 10:18:53 -0800 Subject: [PATCH 31/44] Enhance flow visualization documentation for createGitHubSecretAzureCredentials.ps1 and deleteGitHubSecretAzureCredentials.ps1 scripts by adding emojis, improving diagram styles, and refining connections for better clarity and navigation. --- .../create-github-secret-azure-credentials.md | 73 +++++++++++------- .../delete-github-secret-azure-credentials.md | 75 ++++++++++++------- 2 files changed, 97 insertions(+), 51 deletions(-) diff --git a/docs/scripts/github/create-github-secret-azure-credentials.md b/docs/scripts/github/create-github-secret-azure-credentials.md index 8032365a..dbec78a9 100644 --- a/docs/scripts/github/create-github-secret-azure-credentials.md +++ b/docs/scripts/github/create-github-secret-azure-credentials.md @@ -61,44 +61,67 @@ This script authenticates to GitHub using the GitHub CLI and creates a repositor ## ๐Ÿ“Š Flow Visualization ```mermaid +--- +title: Create GitHub Secret Flow +--- flowchart TD - subgraph Entry["Script Entry"] - A([createGitHubSecretAzureCredentials.ps1 Start]):::entry - B[/"Parse Parameters"/]:::input + %% ===== SCRIPT ENTRY ===== + subgraph Entry["๐Ÿ“ฅ Script Entry"] + A(["๐Ÿš€ createGitHubSecretAzureCredentials.ps1 Start"]) + B[/"๐Ÿ“ Parse Parameters"/] end - subgraph Auth["GitHub Authentication"] - C["Connect-GitHubCli"]:::core - D[(gh auth status)]:::external - E{Authenticated?}:::decision - F[(gh auth login)]:::external + %% ===== GITHUB AUTHENTICATION ===== + subgraph Auth["๐Ÿ” GitHub Authentication"] + C["โš™๏ธ Connect-GitHubCli"] + D[("๐Ÿ™ gh auth status")] + E{"โœ… Authenticated?"} + F[("๐Ÿ”‘ gh auth login")] end - subgraph SecretCreation["Secret Creation"] - G["Set-GitHubRepositorySecret"]:::core - H[(gh secret set)]:::external + %% ===== SECRET CREATION ===== + subgraph SecretCreation["๐Ÿ“ Secret Creation"] + G["โš™๏ธ Set-GitHubRepositorySecret"] + H[("๐Ÿ”’ gh secret set")] end - subgraph Exit["Script Exit"] - I{Success?}:::decision - J[\Secret Created\]:::output - K{{Error Handler}}:::error + %% ===== SCRIPT EXIT ===== + subgraph Exit["๐Ÿ“ค Script Exit"] + I{"โœ… Success?"} + J[\"๐ŸŽ‰ Secret Created"\] + K{{"โŒ Error Handler"}} end - A --> B --> C --> D --> E + %% ===== CONNECTIONS ===== + A -->|parses| B -->|connects| C -->|checks| D -->|evaluates| E E -->|Yes| G - E -->|No| F --> G - G --> H --> I + E -->|No| F -->|authenticates| G + G -->|creates| H -->|evaluates| I I -->|Yes| J I -->|No| K - classDef entry fill:#2196F3,stroke:#1565C0,color:#fff - classDef input fill:#9C27B0,stroke:#6A1B9A,color:#fff - classDef core fill:#FF9800,stroke:#EF6C00,color:#fff - classDef external fill:#4CAF50,stroke:#2E7D32,color:#fff - classDef decision fill:#FFC107,stroke:#FFA000,color:#000 - classDef output fill:#2196F3,stroke:#1565C0,color:#fff - classDef error fill:#F44336,stroke:#C62828,color:#fff + %% ===== 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 ``` --- diff --git a/docs/scripts/github/delete-github-secret-azure-credentials.md b/docs/scripts/github/delete-github-secret-azure-credentials.md index 657882a1..b8a3a490 100644 --- a/docs/scripts/github/delete-github-secret-azure-credentials.md +++ b/docs/scripts/github/delete-github-secret-azure-credentials.md @@ -61,45 +61,68 @@ This script authenticates to GitHub using the GitHub CLI and removes a specified ## ๐Ÿ“Š Flow Visualization ```mermaid +--- +title: Delete GitHub Secret Flow +--- flowchart TD - subgraph Entry["Script Entry"] - A([deleteGitHubSecretAzureCredentials.ps1 Start]):::entry - B[/"Parse Parameters"/]:::input + %% ===== SCRIPT ENTRY ===== + subgraph Entry["๐Ÿ“ฅ Script Entry"] + A(["๐Ÿš€ deleteGitHubSecretAzureCredentials.ps1 Start"]) + B[/"๐Ÿ“ Parse Parameters"/] end - subgraph Auth["GitHub Authentication"] - C["Connect-GitHubCli"]:::core - D[(gh auth status)]:::external - E{Authenticated?}:::decision - F[(gh auth login)]:::external + %% ===== GITHUB AUTHENTICATION ===== + subgraph Auth["๐Ÿ” GitHub Authentication"] + C["โš™๏ธ Connect-GitHubCli"] + D[("๐Ÿ™ gh auth status")] + E{"โœ… Authenticated?"} + F[("๐Ÿ”‘ gh auth login")] end - subgraph SecretDeletion["Secret Deletion"] - G["Remove-GitHubRepositorySecret"]:::core - H[(gh secret remove)]:::external - I{Secret existed?}:::decision + %% ===== SECRET DELETION ===== + subgraph SecretDeletion["๐Ÿ—‘๏ธ Secret Deletion"] + G["โš™๏ธ Remove-GitHubRepositorySecret"] + H[("๐Ÿ—‘๏ธ gh secret remove")] + I{"๐Ÿ“‹ Secret existed?"} end - subgraph Exit["Script Exit"] - J[\Secret Removed\]:::output - K[\Secret Not Found - OK\]:::output - L{{Error Handler}}:::error + %% ===== SCRIPT EXIT ===== + subgraph Exit["๐Ÿ“ค Script Exit"] + J[\"๐ŸŽ‰ Secret Removed"\] + K[\"โญ๏ธ Secret Not Found - OK"\] + L{{"โŒ Error Handler"}} end - A --> B --> C --> D --> E + %% ===== CONNECTIONS ===== + A -->|parses| B -->|connects| C -->|checks| D -->|evaluates| E E -->|Yes| G - E -->|No| F --> G - G --> H --> I + E -->|No| F -->|authenticates| G + G -->|removes| H -->|evaluates| I I -->|Yes| J I -->|No| K - classDef entry fill:#2196F3,stroke:#1565C0,color:#fff - classDef input fill:#9C27B0,stroke:#6A1B9A,color:#fff - classDef core fill:#FF9800,stroke:#EF6C00,color:#fff - classDef external fill:#4CAF50,stroke:#2E7D32,color:#fff - classDef decision fill:#FFC107,stroke:#FFA000,color:#000 - classDef output fill:#2196F3,stroke:#1565C0,color:#fff - classDef error fill:#F44336,stroke:#C62828,color:#fff + %% ===== 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 ``` --- From 5c466bbeba34771cb9ff40e5e6c4c8b6cd630476 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 10:20:48 -0800 Subject: [PATCH 32/44] Enhance flow visualization documentation for cleanUp.ps1 and winget-update.ps1 scripts by adding emojis, improving diagram styles, and refining connections for better clarity and navigation. --- docs/scripts/configuration/clean-up.md | 79 ++++++++++++------- docs/scripts/configuration/winget-update.md | 85 +++++++++++++-------- 2 files changed, 105 insertions(+), 59 deletions(-) diff --git a/docs/scripts/configuration/clean-up.md b/docs/scripts/configuration/clean-up.md index 86c9c6a4..9f0d79ef 100644 --- a/docs/scripts/configuration/clean-up.md +++ b/docs/scripts/configuration/clean-up.md @@ -62,48 +62,71 @@ This script deletes Azure resource groups and their associated deployments for t ## ๐Ÿ“Š Flow Visualization ```mermaid +--- +title: Resource Group Cleanup Flow +--- flowchart TD - subgraph Entry["Script Entry"] - A([cleanUp.ps1 Start]):::entry - B[/"Parse Parameters"/]:::input + %% ===== SCRIPT ENTRY ===== + subgraph Entry["๐Ÿ“ฅ Script Entry"] + A(["๐Ÿš€ cleanUp.ps1 Start"]) + B[/"๐Ÿ“ Parse Parameters"/] end - subgraph Main["Main Orchestration"] - C["Remove-AllResourceGroups"]:::core - D["Build resource group names"]:::core + %% ===== MAIN ORCHESTRATION ===== + subgraph Main["๐ŸŽฏ Main Orchestration"] + C["โš™๏ธ Remove-AllResourceGroups"] + D["๐Ÿ“‹ Build resource group names"] end - subgraph RGLoop["Resource Group Deletion Loop"] - E["For each resource group"]:::core - F["Remove-AzureResourceGroup"]:::core - F1[(az group exists)]:::external - F2{RG exists?}:::decision - F3[(az deployment group list)]:::external - F4["Delete deployments"]:::core - F5[(az group delete --no-wait)]:::external + %% ===== 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 - subgraph Exit["Script Exit"] - G{All succeeded?}:::decision - H[\Deletions Initiated\]:::output - I{{Partial Failure}}:::error + %% ===== SCRIPT EXIT ===== + subgraph Exit["๐Ÿ“ค Script Exit"] + G{"โœ… All succeeded?"} + H[\"๐ŸŽ‰ Deletions Initiated"\] + I{{"โš ๏ธ Partial Failure"}} end - A --> B --> C --> D --> E - E --> F --> F1 --> F2 + %% ===== CONNECTIONS ===== + A -->|parses| B -->|invokes| C -->|builds| D -->|iterates| E + E -->|processes| F -->|checks| F1 -->|evaluates| F2 F2 -->|No| E - F2 -->|Yes| F3 --> F4 --> F5 --> E + F2 -->|Yes| F3 -->|clears| F4 -->|deletes| F5 -->|next| E E -->|All processed| G G -->|Yes| H G -->|No| I - classDef entry fill:#2196F3,stroke:#1565C0,color:#fff - classDef input fill:#9C27B0,stroke:#6A1B9A,color:#fff - classDef core fill:#FF9800,stroke:#EF6C00,color:#fff - classDef external fill:#4CAF50,stroke:#2E7D32,color:#fff - classDef decision fill:#FFC107,stroke:#FFA000,color:#000 - classDef output fill:#2196F3,stroke:#1565C0,color:#fff - classDef error fill:#F44336,stroke:#C62828,color:#fff + %% ===== 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,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 ``` --- diff --git a/docs/scripts/configuration/winget-update.md b/docs/scripts/configuration/winget-update.md index cc97641f..878ced54 100644 --- a/docs/scripts/configuration/winget-update.md +++ b/docs/scripts/configuration/winget-update.md @@ -65,49 +65,72 @@ This script performs a comprehensive, non-interactive update of all Microsoft St ## ๐Ÿ“Š Flow Visualization ```mermaid +--- +title: WinGet Update Flow +--- flowchart TD - subgraph Entry["Script Entry"] - A([winget-update.ps1 Start]):::entry - B["Configure logging"]:::core - C["Set ExecutionPolicy Bypass"]:::core + %% ===== SCRIPT ENTRY ===== + subgraph Entry["๐Ÿ“ฅ Script Entry"] + A(["๐Ÿš€ winget-update.ps1 Start"]) + B["๐Ÿ“ Configure logging"] + C["๐Ÿ” Set ExecutionPolicy Bypass"] end - subgraph Preflight["Preflight Checks"] - D["Resolve-WinGetExecutable"]:::core - E["Test-WinGetAvailability"]:::validation - F{WinGet available?}:::decision + %% ===== PREFLIGHT CHECKS ===== + subgraph Preflight["โœ… Preflight Checks"] + D["๐Ÿ” Resolve-WinGetExecutable"] + E["๐Ÿงช Test-WinGetAvailability"] + F{"๐Ÿ“‹ WinGet available?"} end - subgraph Services["Service Preparation"] - G["Start-StoreInstallService"]:::core - H["Initialize-WinGetSources"]:::core + %% ===== SERVICE PREPARATION ===== + subgraph Services["โš™๏ธ Service Preparation"] + G["๐Ÿš€ Start-StoreInstallService"] + H["๐Ÿ”„ Initialize-WinGetSources"] end - subgraph Updates["Update Passes"] - I["Update-MicrosoftStoreApps"]:::core - I1["Pass 1: Standard upgrade"]:::core - I2["Pass 2: Forced upgrade"]:::core - I3["Pass 3: Safety net pass"]:::core - I4["Summary check"]:::core + %% ===== 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 - subgraph Exit["Script Exit"] - J[\Updates Complete\]:::output - K{{Error Exit}}:::error + %% ===== SCRIPT EXIT ===== + subgraph Exit["๐Ÿ“ค Script Exit"] + J[\"๐ŸŽ‰ Updates Complete"\] + K{{"โŒ Error Exit"}} end - A --> B --> C --> D --> E --> F + %% ===== CONNECTIONS ===== + A -->|configures| B -->|sets| C -->|resolves| D -->|tests| E -->|evaluates| F F -->|No| K - F -->|Yes| G --> H --> I - I --> I1 --> I2 --> I3 --> I4 --> J - - classDef entry fill:#2196F3,stroke:#1565C0,color:#fff - classDef core fill:#FF9800,stroke:#EF6C00,color:#fff - classDef validation fill:#9C27B0,stroke:#6A1B9A,color:#fff - classDef external fill:#4CAF50,stroke:#2E7D32,color:#fff - classDef decision fill:#FFC107,stroke:#FFA000,color:#000 - classDef output fill:#2196F3,stroke:#1565C0,color:#fff - classDef error fill:#F44336,stroke:#C62828,color:#fff + 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 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,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 ``` --- From 4309ed86fd9f134510186415acc376779c2dd7d6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 10:23:03 -0800 Subject: [PATCH 33/44] Enhance flow visualization documentation for createGitHubSecretAzureCredentials.ps1 and deleteGitHubSecretAzureCredentials.ps1 scripts by improving link formatting for better navigation. --- .../create-github-secret-azure-credentials.md | 48 +++++++++---------- .../delete-github-secret-azure-credentials.md | 40 ++++++++-------- 2 files changed, 44 insertions(+), 44 deletions(-) diff --git a/docs/scripts/github/create-github-secret-azure-credentials.md b/docs/scripts/github/create-github-secret-azure-credentials.md index dbec78a9..fa477637 100644 --- a/docs/scripts/github/create-github-secret-azure-credentials.md +++ b/docs/scripts/github/create-github-secret-azure-credentials.md @@ -33,18 +33,18 @@ tags: ## ๐Ÿ“‘ 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](#-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) --- @@ -54,7 +54,7 @@ This script authenticates to GitHub using the GitHub CLI and creates a repositor --- -[โฌ†๏ธ Back to Top](#-table-of-contents) +[โฌ†๏ธ Back to Top](#-creategithubsecretazurecredentialsps1) --- @@ -126,7 +126,7 @@ flowchart TD --- -[โฌ†๏ธ Back to Top](#-table-of-contents) +[โฌ†๏ธ Back to Top](#-creategithubsecretazurecredentialsps1) --- @@ -140,7 +140,7 @@ flowchart TD --- -[โฌ†๏ธ Back to Top](#-table-of-contents) +[โฌ†๏ธ Back to Top](#-creategithubsecretazurecredentialsps1) --- @@ -160,7 +160,7 @@ flowchart TD --- -[โฌ†๏ธ Back to Top](#-table-of-contents) +[โฌ†๏ธ Back to Top](#-creategithubsecretazurecredentialsps1) --- @@ -181,7 +181,7 @@ This format is output by `az ad sp create-for-rbac --json-auth`. --- -[โฌ†๏ธ Back to Top](#-table-of-contents) +[โฌ†๏ธ Back to Top](#-creategithubsecretazurecredentialsps1) --- @@ -220,7 +220,7 @@ This format is output by `az ad sp create-for-rbac --json-auth`. --- -[โฌ†๏ธ Back to Top](#-table-of-contents) +[โฌ†๏ธ Back to Top](#-creategithubsecretazurecredentialsps1) --- @@ -269,7 +269,7 @@ You can now use this secret in your GitHub Actions workflows. --- -[โฌ†๏ธ Back to Top](#-table-of-contents) +[โฌ†๏ธ Back to Top](#-creategithubsecretazurecredentialsps1) --- @@ -299,7 +299,7 @@ jobs: --- -[โฌ†๏ธ Back to Top](#-table-of-contents) +[โฌ†๏ธ Back to Top](#-creategithubsecretazurecredentialsps1) --- @@ -321,7 +321,7 @@ $WarningPreference = 'Stop' --- -[โฌ†๏ธ Back to Top](#-table-of-contents) +[โฌ†๏ธ Back to Top](#-creategithubsecretazurecredentialsps1) --- @@ -355,7 +355,7 @@ gh auth token --- -[โฌ†๏ธ Back to Top](#-table-of-contents) +[โฌ†๏ธ Back to Top](#-creategithubsecretazurecredentialsps1) --- @@ -382,7 +382,7 @@ When rotating credentials: --- -[โฌ†๏ธ Back to Top](#-table-of-contents) +[โฌ†๏ธ Back to Top](#-creategithubsecretazurecredentialsps1) --- @@ -398,7 +398,7 @@ When rotating credentials:
-[โ† winget-update.ps1](../configuration/winget-update.md) | [โฌ†๏ธ Back to Top](#-table-of-contents) | [deleteGitHubSecretAzureCredentials.ps1 โ†’](delete-github-secret-azure-credentials.md) +[โ† winget-update.ps1](../configuration/winget-update.md) | [โฌ†๏ธ Back to Top](#-creategithubsecretazurecredentialsps1) | [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 index b8a3a490..32908f43 100644 --- a/docs/scripts/github/delete-github-secret-azure-credentials.md +++ b/docs/scripts/github/delete-github-secret-azure-credentials.md @@ -35,16 +35,16 @@ tags: ## ๐Ÿ“‘ 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](#-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) --- @@ -54,7 +54,7 @@ This script authenticates to GitHub using the GitHub CLI and removes a specified --- -[โฌ†๏ธ Back to Top](#-table-of-contents) +[โฌ†๏ธ Back to Top](#๏ธ-deleteGitHubSecretAzureCredentialsps1) --- @@ -127,7 +127,7 @@ flowchart TD --- -[โฌ†๏ธ Back to Top](#-table-of-contents) +[โฌ†๏ธ Back to Top](#๏ธ-deleteGitHubSecretAzureCredentialsps1) --- @@ -141,7 +141,7 @@ flowchart TD --- -[โฌ†๏ธ Back to Top](#-table-of-contents) +[โฌ†๏ธ Back to Top](#๏ธ-deleteGitHubSecretAzureCredentialsps1) --- @@ -161,7 +161,7 @@ flowchart TD --- -[โฌ†๏ธ Back to Top](#-table-of-contents) +[โฌ†๏ธ Back to Top](#๏ธ-deleteGitHubSecretAzureCredentialsps1) --- @@ -206,7 +206,7 @@ flowchart TD --- -[โฌ†๏ธ Back to Top](#-table-of-contents) +[โฌ†๏ธ Back to Top](#๏ธ-deleteGitHubSecretAzureCredentialsps1) --- @@ -247,7 +247,7 @@ GitHub secret deletion completed. --- -[โฌ†๏ธ Back to Top](#-table-of-contents) +[โฌ†๏ธ Back to Top](#๏ธ-deleteGitHubSecretAzureCredentialsps1) --- @@ -277,7 +277,7 @@ The script is **idempotent**: --- -[โฌ†๏ธ Back to Top](#-table-of-contents) +[โฌ†๏ธ Back to Top](#๏ธ-deleteGitHubSecretAzureCredentialsps1) --- @@ -308,7 +308,7 @@ gh secret list | findstr "AZURE_CREDENTIALS" --- -[โฌ†๏ธ Back to Top](#-table-of-contents) +[โฌ†๏ธ Back to Top](#๏ธ-deleteGitHubSecretAzureCredentialsps1) --- @@ -333,7 +333,7 @@ gh secret list | findstr "AZURE_CREDENTIALS" --- -[โฌ†๏ธ Back to Top](#-table-of-contents) +[โฌ†๏ธ Back to Top](#๏ธ-deleteGitHubSecretAzureCredentialsps1) --- @@ -349,7 +349,7 @@ gh secret list | findstr "AZURE_CREDENTIALS"
-[โ† createGitHubSecretAzureCredentials.ps1](create-github-secret-azure-credentials.md) | [โฌ†๏ธ Back to Top](#-table-of-contents) +[โ† createGitHubSecretAzureCredentials.ps1](create-github-secret-azure-credentials.md) | [โฌ†๏ธ Back to Top](#๏ธ-deleteGitHubSecretAzureCredentialsps1) *DevExp-DevBox โ€ข deleteGitHubSecretAzureCredentials.ps1 Documentation* From 5edc8fc142063b8fde58363f82a0fea194db3d53 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 10:24:34 -0800 Subject: [PATCH 34/44] Fix link formatting in deleteGitHubSecretAzureCredentials.ps1 documentation for consistent navigation --- .../delete-github-secret-azure-credentials.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/scripts/github/delete-github-secret-azure-credentials.md b/docs/scripts/github/delete-github-secret-azure-credentials.md index 32908f43..074d2d16 100644 --- a/docs/scripts/github/delete-github-secret-azure-credentials.md +++ b/docs/scripts/github/delete-github-secret-azure-credentials.md @@ -54,7 +54,7 @@ This script authenticates to GitHub using the GitHub CLI and removes a specified --- -[โฌ†๏ธ Back to Top](#๏ธ-deleteGitHubSecretAzureCredentialsps1) +[โฌ†๏ธ Back to Top](#๏ธ-deletegithubsecretazurecredentialsps1) --- @@ -127,7 +127,7 @@ flowchart TD --- -[โฌ†๏ธ Back to Top](#๏ธ-deleteGitHubSecretAzureCredentialsps1) +[โฌ†๏ธ Back to Top](#๏ธ-deletegithubsecretazurecredentialsps1) --- @@ -141,7 +141,7 @@ flowchart TD --- -[โฌ†๏ธ Back to Top](#๏ธ-deleteGitHubSecretAzureCredentialsps1) +[โฌ†๏ธ Back to Top](#๏ธ-deletegithubsecretazurecredentialsps1) --- @@ -161,7 +161,7 @@ flowchart TD --- -[โฌ†๏ธ Back to Top](#๏ธ-deleteGitHubSecretAzureCredentialsps1) +[โฌ†๏ธ Back to Top](#๏ธ-deletegithubsecretazurecredentialsps1) --- @@ -206,7 +206,7 @@ flowchart TD --- -[โฌ†๏ธ Back to Top](#๏ธ-deleteGitHubSecretAzureCredentialsps1) +[โฌ†๏ธ Back to Top](#๏ธ-deletegithubsecretazurecredentialsps1) --- @@ -247,7 +247,7 @@ GitHub secret deletion completed. --- -[โฌ†๏ธ Back to Top](#๏ธ-deleteGitHubSecretAzureCredentialsps1) +[โฌ†๏ธ Back to Top](#๏ธ-deletegithubsecretazurecredentialsps1) --- @@ -277,7 +277,7 @@ The script is **idempotent**: --- -[โฌ†๏ธ Back to Top](#๏ธ-deleteGitHubSecretAzureCredentialsps1) +[โฌ†๏ธ Back to Top](#๏ธ-deletegithubsecretazurecredentialsps1) --- @@ -308,7 +308,7 @@ gh secret list | findstr "AZURE_CREDENTIALS" --- -[โฌ†๏ธ Back to Top](#๏ธ-deleteGitHubSecretAzureCredentialsps1) +[โฌ†๏ธ Back to Top](#๏ธ-deletegithubsecretazurecredentialsps1) --- @@ -333,7 +333,7 @@ gh secret list | findstr "AZURE_CREDENTIALS" --- -[โฌ†๏ธ Back to Top](#๏ธ-deleteGitHubSecretAzureCredentialsps1) +[โฌ†๏ธ Back to Top](#๏ธ-deletegithubsecretazurecredentialsps1) --- @@ -349,7 +349,7 @@ gh secret list | findstr "AZURE_CREDENTIALS"
-[โ† createGitHubSecretAzureCredentials.ps1](create-github-secret-azure-credentials.md) | [โฌ†๏ธ Back to Top](#๏ธ-deleteGitHubSecretAzureCredentialsps1) +[โ† createGitHubSecretAzureCredentials.ps1](create-github-secret-azure-credentials.md) | [โฌ†๏ธ Back to Top](#๏ธ-deletegithubsecretazurecredentialsps1) *DevExp-DevBox โ€ข deleteGitHubSecretAzureCredentials.ps1 Documentation* From 3bb1bc615c1d6c7aa931870143a63151d59c0759 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 10:28:36 -0800 Subject: [PATCH 35/44] Fix link formatting in cleanUp.ps1 and winget-update.ps1 documentation for consistent navigation --- docs/scripts/configuration/clean-up.md | 38 ++++++++--------- docs/scripts/configuration/winget-update.md | 46 ++++++++++----------- 2 files changed, 42 insertions(+), 42 deletions(-) diff --git a/docs/scripts/configuration/clean-up.md b/docs/scripts/configuration/clean-up.md index 9f0d79ef..1cc847a8 100644 --- a/docs/scripts/configuration/clean-up.md +++ b/docs/scripts/configuration/clean-up.md @@ -35,17 +35,17 @@ tags: ## ๐Ÿ“‘ 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](#-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) --- @@ -138,7 +138,7 @@ flowchart TD ## ๐Ÿ“ 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 | @@ -154,7 +154,7 @@ flowchart TD ### 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 | @@ -174,7 +174,7 @@ flowchart TD 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 | @@ -207,7 +207,7 @@ devexp-security-demo-eastus2-rg **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 @@ -230,7 +230,7 @@ devexp-security-demo-eastus2-rg **Parameters:** | Name | Type | Required | Description | -|------|------|----------|-------------| +|:-----|:-----|:--------:|:------------| | `WorkloadName` | `string` | Yes | Workload name prefix | | `Environment` | `string` | Yes | Environment name | | `Location` | `string` | Yes | Azure region | @@ -325,7 +325,7 @@ $WarningPreference = 'Stop' ### Exit Codes | Code | Meaning | -|------|---------| +|:----:|:--------| | `0` | All deletions initiated successfully | | `1` | One or more deletions failed | @@ -356,7 +356,7 @@ The script is **idempotent**: ### 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 | @@ -416,7 +416,7 @@ Azure resource locks can prevent accidental deletion: ## ๐Ÿ”— 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) | diff --git a/docs/scripts/configuration/winget-update.md b/docs/scripts/configuration/winget-update.md index 878ced54..2160a477 100644 --- a/docs/scripts/configuration/winget-update.md +++ b/docs/scripts/configuration/winget-update.md @@ -36,19 +36,19 @@ tags: ## ๐Ÿ“‘ 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](#-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) --- @@ -196,7 +196,7 @@ This script has no parameters. All configuration is handled internally. ### 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 | @@ -216,13 +216,13 @@ This script has no parameters. All configuration is handled internally. ### 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 | @@ -248,7 +248,7 @@ This script has no parameters. All configuration is handled internally. **Parameters:** | Name | Type | Description | -|------|------|-------------| +|:-----|:-----|:------------| | `Message` | `string` | Message to write | --- @@ -285,7 +285,7 @@ This script has no parameters. All configuration is handled internally. **Parameters:** | Name | Type | Required | Description | -|------|------|----------|-------------| +|:-----|:-----|:--------:|:------------| | `CommandArgs` | `string[]` | Yes | Arguments to pass to winget | | `RetryOnSelfUpdate` | `switch` | No | Retry if winget updated itself | @@ -333,7 +333,7 @@ This script has no parameters. All configuration is handled internally. **Update Passes:** | Pass | Purpose | Flags | -|------|---------|-------| +|:----:|:--------|:------| | 1 | Standard upgrade | `--include-unknown --silent` | | 2 | Forced upgrade | `--force --silent` | | 3 | Safety net | Unfiltered (all sources) | @@ -413,7 +413,7 @@ No applicable upgrade found. ### Exit Codes | Code | Meaning | -|------|---------| +|:----:|:--------| | `0` | Updates completed (may include skipped apps) | | `1` | Critical failure (winget not found, etc.) | @@ -434,7 +434,7 @@ No applicable upgrade found. ### 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 | @@ -471,7 +471,7 @@ winget source update 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 | @@ -519,7 +519,7 @@ Review these agreements at [Microsoft Store Terms](https://www.microsoft.com/sto ## ๐Ÿ”— 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 | From 91c8fb93800746d061d2a1732f92f919fce3a8a9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 10:33:20 -0800 Subject: [PATCH 36/44] Enhance flow visualization documentation for cleanUp.ps1 and winget-update.ps1 scripts by refining class definitions and adding new styles for better clarity and navigation. --- docs/scripts/configuration/clean-up.md | 8 +++++--- docs/scripts/configuration/winget-update.md | 9 ++++++++- 2 files changed, 13 insertions(+), 4 deletions(-) diff --git a/docs/scripts/configuration/clean-up.md b/docs/scripts/configuration/clean-up.md index 1cc847a8..10c8e2d8 100644 --- a/docs/scripts/configuration/clean-up.md +++ b/docs/scripts/configuration/clean-up.md @@ -107,12 +107,14 @@ flowchart TD %% ===== 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 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 diff --git a/docs/scripts/configuration/winget-update.md b/docs/scripts/configuration/winget-update.md index 2160a477..cf5a6c1b 100644 --- a/docs/scripts/configuration/winget-update.md +++ b/docs/scripts/configuration/winget-update.md @@ -114,9 +114,12 @@ flowchart TD 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 decision fill:#FFFBEB,stroke:#F59E0B,color:#000000 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 @@ -142,7 +145,11 @@ flowchart TD ## ๐Ÿ”„ 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 From 53b137dae3d94614ba3f1707a76307db71e0dce0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 10:36:45 -0800 Subject: [PATCH 37/44] Enhance documentation for Azure scripts by improving link formatting, adding new sections, and ensuring consistent navigation across createCustomRole.ps1, createUsersAndAssignRole.ps1, deleteDeploymentCredentials.ps1, deleteUsersAndAssignedRoles.ps1, and generateDeploymentCredentials.ps1. --- docs/scripts/azure/create-custom-role.md | 43 ++++++++++++----- .../azure/create-users-and-assign-role.md | 40 +++++++++++----- .../azure/delete-deployment-credentials.md | 24 ++++++---- .../azure/delete-users-and-assigned-roles.md | 47 ++++++++++++++----- .../azure/generate-deployment-credentials.md | 28 ++++++----- 5 files changed, 127 insertions(+), 55 deletions(-) diff --git a/docs/scripts/azure/create-custom-role.md b/docs/scripts/azure/create-custom-role.md index c481e23c..e043e186 100644 --- a/docs/scripts/azure/create-custom-role.md +++ b/docs/scripts/azure/create-custom-role.md @@ -35,14 +35,17 @@ tags: ## ๐Ÿ“‘ 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) +- [๐ŸŽฏ Overview](#-overview) +- [๐Ÿ“Š Flow Visualization](#-flow-visualization) +- [๐Ÿ“ Parameters](#-parameters) +- [โš™๏ธ Prerequisites](#%EF%B8%8F-prerequisites) +- [๐Ÿ“œ Role Definition](#-role-definition) +- [๐Ÿ”ง Functions Reference](#-functions-reference) +- [๐Ÿ“ Usage Examples](#-usage-examples) +- [โš ๏ธ Error Handling](#%EF%B8%8F-error-handling) +- [๐Ÿ”ง Troubleshooting](#-troubleshooting) +- [๐Ÿ” Security Considerations](#-security-considerations) +- [๐Ÿ”— Related Scripts](#-related-scripts) --- @@ -312,7 +315,7 @@ $ProgressPreference = 'SilentlyContinue' The temporary JSON file is always cleaned up via `finally` block, even if creation fails. -## Troubleshooting +## ๐Ÿ”ง Troubleshooting ### Common Issues @@ -323,6 +326,8 @@ The temporary JSON file is always cleaned up via `finally` block, even if creati | 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 @@ -330,14 +335,26 @@ The temporary JSON file is always cleaned up via `finally` block, even if creati az role definition list --custom-role-only true --query "[?roleName=='Contoso DevBox - Role Assignment Writer']" ``` -## Security Considerations +--- + +[โฌ†๏ธ 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 -## Related Scripts +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Related Scripts | Script | Purpose | Link | |--------|---------|------| @@ -347,6 +364,10 @@ az role definition list --custom-role-only true --query "[?roleName=='Contoso De --- +[โฌ†๏ธ 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) diff --git a/docs/scripts/azure/create-users-and-assign-role.md b/docs/scripts/azure/create-users-and-assign-role.md index 5dfa67ba..c6e16add 100644 --- a/docs/scripts/azure/create-users-and-assign-role.md +++ b/docs/scripts/azure/create-users-and-assign-role.md @@ -32,15 +32,17 @@ tags: ## ๐Ÿ“‘ 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) +- [๐ŸŽฏ Overview](#-overview) +- [๐Ÿ“Š Flow Visualization](#-flow-visualization) +- [๐Ÿ“ Parameters](#-parameters) +- [โš™๏ธ Prerequisites](#%EF%B8%8F-prerequisites) +- [๐Ÿ”‘ Assigned Roles](#-assigned-roles) +- [๐Ÿ”ง Functions Reference](#-functions-reference) +- [๐Ÿ“ Usage Examples](#-usage-examples) +- [โš ๏ธ Error Handling](#%EF%B8%8F-error-handling) +- [๐Ÿ”ง Troubleshooting](#-troubleshooting) +- [๐Ÿ” Security Considerations](#-security-considerations) +- [๐Ÿ”— Related Scripts](#-related-scripts) --- @@ -327,14 +329,26 @@ $userId = az ad signed-in-user show --query id --output tsv az role assignment list --assignee $userId --query "[].roleDefinitionName" --output table ``` -## Security Considerations +--- + +[โฌ†๏ธ 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 -## Related Scripts +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Related Scripts | Script | Purpose | Link | |--------|---------|------| @@ -344,6 +358,10 @@ az role assignment list --assignee $userId --query "[].roleDefinitionName" --out --- +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- +
[โ† createCustomRole.ps1](create-custom-role.md) | [โฌ†๏ธ Back to Top](#-table-of-contents) | [deleteDeploymentCredentials.ps1 โ†’](delete-deployment-credentials.md) diff --git a/docs/scripts/azure/delete-deployment-credentials.md b/docs/scripts/azure/delete-deployment-credentials.md index 40cea9e2..cf3b6997 100644 --- a/docs/scripts/azure/delete-deployment-credentials.md +++ b/docs/scripts/azure/delete-deployment-credentials.md @@ -35,16 +35,16 @@ tags: ## ๐Ÿ“‘ 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](#-overview) +- [๐Ÿ“Š Flow Visualization](#-flow-visualization) +- [๐Ÿ“ Parameters](#-parameters) +- [โš™๏ธ Prerequisites](#%EF%B8%8F-prerequisites) +- [๐Ÿ”ง Functions Reference](#-functions-reference) +- [๐Ÿ“ Usage Examples](#-usage-examples) +- [โš ๏ธ Error Handling](#%EF%B8%8F-error-handling) +- [๐Ÿ”ง Troubleshooting](#-troubleshooting) +- [๐Ÿ” Security Considerations](#-security-considerations) +- [๐Ÿ”— Related Scripts](#-related-scripts) --- @@ -328,6 +328,10 @@ az ad app list --display-name "ContosoDevEx GitHub Actions Enterprise App" --que --- +[โฌ†๏ธ 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) diff --git a/docs/scripts/azure/delete-users-and-assigned-roles.md b/docs/scripts/azure/delete-users-and-assigned-roles.md index c0547c5a..905d360b 100644 --- a/docs/scripts/azure/delete-users-and-assigned-roles.md +++ b/docs/scripts/azure/delete-users-and-assigned-roles.md @@ -32,14 +32,17 @@ tags: ## ๐Ÿ“‘ 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) +- [๐ŸŽฏ Overview](#-overview) +- [๐Ÿ“Š Flow Visualization](#-flow-visualization) +- [๐Ÿ“ Parameters](#-parameters) +- [โš™๏ธ Prerequisites](#%EF%B8%8F-prerequisites) +- [๐Ÿ”‘ Removed Roles](#-removed-roles) +- [๐Ÿ”ง Functions Reference](#-functions-reference) +- [๐Ÿ“ Usage Examples](#-usage-examples) +- [โš ๏ธ Error Handling](#%EF%B8%8F-error-handling) +- [๐Ÿ”ง Troubleshooting](#-troubleshooting) +- [๐Ÿ” Security Considerations](#-security-considerations) +- [๐Ÿ”— Related Scripts](#-related-scripts) --- @@ -316,7 +319,13 @@ The script is **idempotent** - running it multiple times will: - Not cause errors for missing assignments - Only attempt to remove existing assignments -## Troubleshooting +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”ง Troubleshooting ### Common Issues @@ -335,7 +344,13 @@ $userId = az ad signed-in-user show --query id --output tsv az role assignment list --assignee $userId --query "[].roleDefinitionName" --output table ``` -## Security Considerations +--- + +[โฌ†๏ธ 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 @@ -348,7 +363,13 @@ az role assignment list --assignee $userId --query "[].roleDefinitionName" --out - [ ] Confirm role removal aligns with access policy - [ ] Document reason for access revocation -## Related Scripts +--- + +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- + +## ๐Ÿ”— Related Scripts | Script | Purpose | Link | |--------|---------|------| @@ -358,6 +379,10 @@ az role assignment list --assignee $userId --query "[].roleDefinitionName" --out --- +[โฌ†๏ธ Back to Top](#-table-of-contents) + +--- +
[โ† deleteDeploymentCredentials.ps1](delete-deployment-credentials.md) | [โฌ†๏ธ Back to Top](#-table-of-contents) | [generateDeploymentCredentials.ps1 โ†’](generate-deployment-credentials.md) diff --git a/docs/scripts/azure/generate-deployment-credentials.md b/docs/scripts/azure/generate-deployment-credentials.md index 1651d6c6..2a9ebf00 100644 --- a/docs/scripts/azure/generate-deployment-credentials.md +++ b/docs/scripts/azure/generate-deployment-credentials.md @@ -36,18 +36,18 @@ tags: ## ๐Ÿ“‘ 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](#-overview) +- [๐Ÿ“Š Flow Visualization](#-flow-visualization) +- [๐Ÿ”„ Service Principal Creation Flow](#-service-principal-creation-flow) +- [๐Ÿ“ Parameters](#-parameters) +- [โš™๏ธ Prerequisites](#%EF%B8%8F-prerequisites) +- [๐Ÿ‘ฅ Assigned Roles](#-assigned-roles) +- [๐Ÿ”ง Functions Reference](#-functions-reference) +- [๐Ÿ“ Usage Examples](#-usage-examples) +- [โš ๏ธ Error Handling](#%EF%B8%8F-error-handling) +- [๐Ÿ”’ Security Considerations](#-security-considerations) +- [๐Ÿ› ๏ธ Troubleshooting](#%EF%B8%8F-troubleshooting) +- [๐Ÿ”— Related Scripts](#-related-scripts) --- @@ -446,6 +446,10 @@ gh secret list --- +[โฌ†๏ธ 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) From 07d52b5b1c523ac5d655e32c5aef5b198a8ff17a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 10:39:14 -0800 Subject: [PATCH 38/44] Add comprehensive documentation for Azure PowerShell scripts, including setup, cleanup, and prerequisites sections, along with a workflow diagram and scripts inventory. --- docs/scripts/azure/README.md | 194 +++++++++++++++++++++++++++++++++++ 1 file changed, 194 insertions(+) create mode 100644 docs/scripts/azure/README.md diff --git a/docs/scripts/azure/README.md b/docs/scripts/azure/README.md new file mode 100644 index 00000000..ec15c2e2 --- /dev/null +++ b/docs/scripts/azure/README.md @@ -0,0 +1,194 @@ +--- +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) | [Docs 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 + subgraph Setup["๐Ÿš€ Setup Phase"] + A["๐Ÿ”‘ createCustomRole.ps1"] + B["๐Ÿ”‘ generateDeploymentCredentials.ps1"] + C["๐Ÿ‘ฅ createUsersAndAssignRole.ps1"] + end + + subgraph Cleanup["๐Ÿ—‘๏ธ Cleanup Phase"] + D["๐Ÿ‘ฅ deleteUsersAndAssignedRoles.ps1"] + E["๐Ÿ—‘๏ธ deleteDeploymentCredentials.ps1"] + end + + A --> B + B --> C + D --> E + + Setup -.->|"Reverse"| Cleanup + + %% Styles + classDef setup fill:#10B981,stroke:#059669,color:#FFFFFF + classDef cleanup fill:#F44336,stroke:#C62828,color:#FFFFFF + + class A,B,C setup + class D,E cleanup +``` + +--- + +[โฌ†๏ธ 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* + +
From 6d167a8c7243081eb8e40eba651517efd26a9795 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 10:43:53 -0800 Subject: [PATCH 39/44] Enhance workflow diagram in README.md by adding setup and cleanup phases, refining connections, and updating node styles for better clarity. --- docs/scripts/azure/README.md | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/docs/scripts/azure/README.md b/docs/scripts/azure/README.md index ec15c2e2..f63686eb 100644 --- a/docs/scripts/azure/README.md +++ b/docs/scripts/azure/README.md @@ -75,29 +75,39 @@ This folder contains PowerShell scripts for managing Azure Role-Based Access Con 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 - A --> B - B --> C - D --> E + %% ===== CONNECTIONS ===== + A -->|"creates RBAC role"| B + B -->|"configures credentials"| C + D -->|"removes roles"| E - Setup -.->|"Reverse"| Cleanup + Setup -.->|"Reverse Operations"| Cleanup - %% Styles - classDef setup fill:#10B981,stroke:#059669,color:#FFFFFF - classDef cleanup fill:#F44336,stroke:#C62828,color:#FFFFFF + %% ===== 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 setup - class D,E cleanup + 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 ``` --- From 47b1954ec7e967edfa3a4e6bae24d120e13cb470 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 10:45:19 -0800 Subject: [PATCH 40/44] Refine input styles in flowcharts across multiple Azure script documentation for improved clarity and consistency. --- docs/scripts/azure/create-custom-role.md | 2 +- docs/scripts/azure/create-users-and-assign-role.md | 2 +- docs/scripts/azure/delete-deployment-credentials.md | 2 +- docs/scripts/azure/delete-users-and-assigned-roles.md | 2 +- docs/scripts/azure/generate-deployment-credentials.md | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/scripts/azure/create-custom-role.md b/docs/scripts/azure/create-custom-role.md index e043e186..984d6906 100644 --- a/docs/scripts/azure/create-custom-role.md +++ b/docs/scripts/azure/create-custom-role.md @@ -115,7 +115,7 @@ flowchart TD %% ===== STYLES ===== classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF - classDef input fill:#F59E0B,stroke:#D97706,color:#000000 + 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 diff --git a/docs/scripts/azure/create-users-and-assign-role.md b/docs/scripts/azure/create-users-and-assign-role.md index c6e16add..e4a62229 100644 --- a/docs/scripts/azure/create-users-and-assign-role.md +++ b/docs/scripts/azure/create-users-and-assign-role.md @@ -112,7 +112,7 @@ flowchart TD %% ===== STYLES ===== classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF - classDef input fill:#F59E0B,stroke:#D97706,color:#000000 + 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 diff --git a/docs/scripts/azure/delete-deployment-credentials.md b/docs/scripts/azure/delete-deployment-credentials.md index cf3b6997..78f060f6 100644 --- a/docs/scripts/azure/delete-deployment-credentials.md +++ b/docs/scripts/azure/delete-deployment-credentials.md @@ -104,7 +104,7 @@ flowchart TD %% ===== STYLES ===== classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF - classDef input fill:#F59E0B,stroke:#D97706,color:#000000 + 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 diff --git a/docs/scripts/azure/delete-users-and-assigned-roles.md b/docs/scripts/azure/delete-users-and-assigned-roles.md index 905d360b..f6dd8e34 100644 --- a/docs/scripts/azure/delete-users-and-assigned-roles.md +++ b/docs/scripts/azure/delete-users-and-assigned-roles.md @@ -112,7 +112,7 @@ flowchart TD %% ===== STYLES ===== classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF - classDef input fill:#F59E0B,stroke:#D97706,color:#000000 + 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 diff --git a/docs/scripts/azure/generate-deployment-credentials.md b/docs/scripts/azure/generate-deployment-credentials.md index 2a9ebf00..01828621 100644 --- a/docs/scripts/azure/generate-deployment-credentials.md +++ b/docs/scripts/azure/generate-deployment-credentials.md @@ -112,7 +112,7 @@ flowchart TD %% ===== STYLES ===== classDef trigger fill:#818CF8,stroke:#4F46E5,color:#FFFFFF - classDef input fill:#F59E0B,stroke:#D97706,color:#000000 + 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 From d0750e5bf16ba20c62ef662bd329649e446c6c31 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 10:50:34 -0800 Subject: [PATCH 41/44] Fix link formatting in documentation by removing unnecessary characters from prerequisites and error handling sections across multiple Azure scripts. --- docs/scripts/azure/create-custom-role.md | 4 +-- .../azure/create-users-and-assign-role.md | 4 +-- .../azure/delete-deployment-credentials.md | 4 +-- .../azure/delete-users-and-assigned-roles.md | 4 +-- .../azure/generate-deployment-credentials.md | 6 ++-- docs/scripts/configuration/clean-up.md | 8 ++--- docs/scripts/configuration/winget-update.md | 6 ++-- .../create-github-secret-azure-credentials.md | 30 +++++++++---------- .../delete-github-secret-azure-credentials.md | 20 ++++++------- 9 files changed, 43 insertions(+), 43 deletions(-) diff --git a/docs/scripts/azure/create-custom-role.md b/docs/scripts/azure/create-custom-role.md index 984d6906..be9914e6 100644 --- a/docs/scripts/azure/create-custom-role.md +++ b/docs/scripts/azure/create-custom-role.md @@ -38,11 +38,11 @@ tags: - [๐ŸŽฏ Overview](#-overview) - [๐Ÿ“Š Flow Visualization](#-flow-visualization) - [๐Ÿ“ Parameters](#-parameters) -- [โš™๏ธ Prerequisites](#%EF%B8%8F-prerequisites) +- [โš™๏ธ Prerequisites](#-prerequisites) - [๐Ÿ“œ Role Definition](#-role-definition) - [๐Ÿ”ง Functions Reference](#-functions-reference) - [๐Ÿ“ Usage Examples](#-usage-examples) -- [โš ๏ธ Error Handling](#%EF%B8%8F-error-handling) +- [โš ๏ธ Error Handling](#-error-handling) - [๐Ÿ”ง Troubleshooting](#-troubleshooting) - [๐Ÿ” Security Considerations](#-security-considerations) - [๐Ÿ”— Related Scripts](#-related-scripts) diff --git a/docs/scripts/azure/create-users-and-assign-role.md b/docs/scripts/azure/create-users-and-assign-role.md index e4a62229..6bf68e8f 100644 --- a/docs/scripts/azure/create-users-and-assign-role.md +++ b/docs/scripts/azure/create-users-and-assign-role.md @@ -35,11 +35,11 @@ tags: - [๐ŸŽฏ Overview](#-overview) - [๐Ÿ“Š Flow Visualization](#-flow-visualization) - [๐Ÿ“ Parameters](#-parameters) -- [โš™๏ธ Prerequisites](#%EF%B8%8F-prerequisites) +- [โš™๏ธ Prerequisites](#-prerequisites) - [๐Ÿ”‘ Assigned Roles](#-assigned-roles) - [๐Ÿ”ง Functions Reference](#-functions-reference) - [๐Ÿ“ Usage Examples](#-usage-examples) -- [โš ๏ธ Error Handling](#%EF%B8%8F-error-handling) +- [โš ๏ธ Error Handling](#-error-handling) - [๐Ÿ”ง Troubleshooting](#-troubleshooting) - [๐Ÿ” Security Considerations](#-security-considerations) - [๐Ÿ”— Related Scripts](#-related-scripts) diff --git a/docs/scripts/azure/delete-deployment-credentials.md b/docs/scripts/azure/delete-deployment-credentials.md index 78f060f6..e67cec6f 100644 --- a/docs/scripts/azure/delete-deployment-credentials.md +++ b/docs/scripts/azure/delete-deployment-credentials.md @@ -38,10 +38,10 @@ tags: - [๐ŸŽฏ Overview](#-overview) - [๐Ÿ“Š Flow Visualization](#-flow-visualization) - [๐Ÿ“ Parameters](#-parameters) -- [โš™๏ธ Prerequisites](#%EF%B8%8F-prerequisites) +- [โš™๏ธ Prerequisites](#-prerequisites) - [๐Ÿ”ง Functions Reference](#-functions-reference) - [๐Ÿ“ Usage Examples](#-usage-examples) -- [โš ๏ธ Error Handling](#%EF%B8%8F-error-handling) +- [โš ๏ธ Error Handling](#-error-handling) - [๐Ÿ”ง Troubleshooting](#-troubleshooting) - [๐Ÿ” Security Considerations](#-security-considerations) - [๐Ÿ”— Related Scripts](#-related-scripts) diff --git a/docs/scripts/azure/delete-users-and-assigned-roles.md b/docs/scripts/azure/delete-users-and-assigned-roles.md index f6dd8e34..9dacfe56 100644 --- a/docs/scripts/azure/delete-users-and-assigned-roles.md +++ b/docs/scripts/azure/delete-users-and-assigned-roles.md @@ -35,11 +35,11 @@ tags: - [๐ŸŽฏ Overview](#-overview) - [๐Ÿ“Š Flow Visualization](#-flow-visualization) - [๐Ÿ“ Parameters](#-parameters) -- [โš™๏ธ Prerequisites](#%EF%B8%8F-prerequisites) +- [โš™๏ธ Prerequisites](#-prerequisites) - [๐Ÿ”‘ Removed Roles](#-removed-roles) - [๐Ÿ”ง Functions Reference](#-functions-reference) - [๐Ÿ“ Usage Examples](#-usage-examples) -- [โš ๏ธ Error Handling](#%EF%B8%8F-error-handling) +- [โš ๏ธ Error Handling](#-error-handling) - [๐Ÿ”ง Troubleshooting](#-troubleshooting) - [๐Ÿ” Security Considerations](#-security-considerations) - [๐Ÿ”— Related Scripts](#-related-scripts) diff --git a/docs/scripts/azure/generate-deployment-credentials.md b/docs/scripts/azure/generate-deployment-credentials.md index 01828621..9069a006 100644 --- a/docs/scripts/azure/generate-deployment-credentials.md +++ b/docs/scripts/azure/generate-deployment-credentials.md @@ -40,13 +40,13 @@ tags: - [๐Ÿ“Š Flow Visualization](#-flow-visualization) - [๐Ÿ”„ Service Principal Creation Flow](#-service-principal-creation-flow) - [๐Ÿ“ Parameters](#-parameters) -- [โš™๏ธ Prerequisites](#%EF%B8%8F-prerequisites) +- [โš™๏ธ Prerequisites](#-prerequisites) - [๐Ÿ‘ฅ Assigned Roles](#-assigned-roles) - [๐Ÿ”ง Functions Reference](#-functions-reference) - [๐Ÿ“ Usage Examples](#-usage-examples) -- [โš ๏ธ Error Handling](#%EF%B8%8F-error-handling) +- [โš ๏ธ Error Handling](#-error-handling) - [๐Ÿ”’ Security Considerations](#-security-considerations) -- [๐Ÿ› ๏ธ Troubleshooting](#%EF%B8%8F-troubleshooting) +- [๐Ÿ› ๏ธ Troubleshooting](#-troubleshooting) - [๐Ÿ”— Related Scripts](#-related-scripts) --- diff --git a/docs/scripts/configuration/clean-up.md b/docs/scripts/configuration/clean-up.md index 10c8e2d8..95dcd502 100644 --- a/docs/scripts/configuration/clean-up.md +++ b/docs/scripts/configuration/clean-up.md @@ -38,12 +38,12 @@ tags: - [๐ŸŽฏ Overview](#-overview) - [๐Ÿ“Š Flow Visualization](#-flow-visualization) - [๐Ÿ“ Parameters](#-parameters) -- [โš™๏ธ Prerequisites](#๏ธ-prerequisites) -- [๐Ÿ—‚๏ธ Resource Groups Deleted](#๏ธ-resource-groups-deleted) +- [โš™๏ธ Prerequisites](#-prerequisites) +- [๐Ÿ—‚๏ธ Resource Groups Deleted](#-resource-groups-deleted) - [๐Ÿ”ง Functions Reference](#-functions-reference) - [๐Ÿ“ Usage Examples](#-usage-examples) -- [โš ๏ธ Error Handling](#๏ธ-error-handling) -- [๐Ÿ› ๏ธ Troubleshooting](#๏ธ-troubleshooting) +- [โš ๏ธ Error Handling](#-error-handling) +- [๐Ÿ› ๏ธ Troubleshooting](#-troubleshooting) - [๐Ÿ”’ Security Considerations](#-security-considerations) - [๐Ÿ”— Related Scripts](#-related-scripts) diff --git a/docs/scripts/configuration/winget-update.md b/docs/scripts/configuration/winget-update.md index cf5a6c1b..4fe5d4a7 100644 --- a/docs/scripts/configuration/winget-update.md +++ b/docs/scripts/configuration/winget-update.md @@ -40,11 +40,11 @@ tags: - [๐Ÿ“Š Flow Visualization](#-flow-visualization) - [๐Ÿ”„ Update Process Flow](#-update-process-flow) - [๐Ÿ“ Parameters](#-parameters) -- [โš™๏ธ Prerequisites](#๏ธ-prerequisites) -- [๐Ÿ› ๏ธ Configuration](#๏ธ-configuration) +- [โš™๏ธ Prerequisites](#-prerequisites) +- [๐Ÿ› ๏ธ Configuration](#-configuration) - [๐Ÿ”ง Functions Reference](#-functions-reference) - [๐Ÿ“ Usage Examples](#-usage-examples) -- [โš ๏ธ Error Handling](#๏ธ-error-handling) +- [โš ๏ธ Error Handling](#-error-handling) - [๐Ÿ” Troubleshooting](#-troubleshooting) - [๐Ÿ”„ DSC Integration](#-dsc-integration) - [๐Ÿ”’ Security Considerations](#-security-considerations) diff --git a/docs/scripts/github/create-github-secret-azure-credentials.md b/docs/scripts/github/create-github-secret-azure-credentials.md index fa477637..ff5469ef 100644 --- a/docs/scripts/github/create-github-secret-azure-credentials.md +++ b/docs/scripts/github/create-github-secret-azure-credentials.md @@ -36,13 +36,13 @@ tags: - [๐ŸŽฏ Overview](#-overview) - [๐Ÿ“Š Flow Visualization](#-flow-visualization) - [๐Ÿ“ Parameters](#-parameters) -- [โš™๏ธ Prerequisites](#๏ธ-prerequisites) +- [โš™๏ธ 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) +- [โš™๏ธ 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) @@ -126,7 +126,7 @@ flowchart TD --- -[โฌ†๏ธ Back to Top](#-creategithubsecretazurecredentialsps1) +[โฌ†๏ธ Back to Top](#-table-of-contents) --- @@ -140,7 +140,7 @@ flowchart TD --- -[โฌ†๏ธ Back to Top](#-creategithubsecretazurecredentialsps1) +[โฌ†๏ธ Back to Top](#-table-of-contents) --- @@ -160,7 +160,7 @@ flowchart TD --- -[โฌ†๏ธ Back to Top](#-creategithubsecretazurecredentialsps1) +[โฌ†๏ธ Back to Top](#-table-of-contents) --- @@ -181,7 +181,7 @@ This format is output by `az ad sp create-for-rbac --json-auth`. --- -[โฌ†๏ธ Back to Top](#-creategithubsecretazurecredentialsps1) +[โฌ†๏ธ Back to Top](#-table-of-contents) --- @@ -220,7 +220,7 @@ This format is output by `az ad sp create-for-rbac --json-auth`. --- -[โฌ†๏ธ Back to Top](#-creategithubsecretazurecredentialsps1) +[โฌ†๏ธ Back to Top](#-table-of-contents) --- @@ -269,7 +269,7 @@ You can now use this secret in your GitHub Actions workflows. --- -[โฌ†๏ธ Back to Top](#-creategithubsecretazurecredentialsps1) +[โฌ†๏ธ Back to Top](#-table-of-contents) --- @@ -299,7 +299,7 @@ jobs: --- -[โฌ†๏ธ Back to Top](#-creategithubsecretazurecredentialsps1) +[โฌ†๏ธ Back to Top](#-table-of-contents) --- @@ -321,7 +321,7 @@ $WarningPreference = 'Stop' --- -[โฌ†๏ธ Back to Top](#-creategithubsecretazurecredentialsps1) +[โฌ†๏ธ Back to Top](#-table-of-contents) --- @@ -355,7 +355,7 @@ gh auth token --- -[โฌ†๏ธ Back to Top](#-creategithubsecretazurecredentialsps1) +[โฌ†๏ธ Back to Top](#-table-of-contents) --- @@ -382,7 +382,7 @@ When rotating credentials: --- -[โฌ†๏ธ Back to Top](#-creategithubsecretazurecredentialsps1) +[โฌ†๏ธ Back to Top](#-table-of-contents) --- @@ -398,7 +398,7 @@ When rotating credentials:
-[โ† winget-update.ps1](../configuration/winget-update.md) | [โฌ†๏ธ Back to Top](#-creategithubsecretazurecredentialsps1) | [deleteGitHubSecretAzureCredentials.ps1 โ†’](delete-github-secret-azure-credentials.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 index 074d2d16..b442f264 100644 --- a/docs/scripts/github/delete-github-secret-azure-credentials.md +++ b/docs/scripts/github/delete-github-secret-azure-credentials.md @@ -38,11 +38,11 @@ tags: - [๐ŸŽฏ Overview](#-overview) - [๐Ÿ“Š Flow Visualization](#-flow-visualization) - [๐Ÿ“ Parameters](#-parameters) -- [โš™๏ธ Prerequisites](#๏ธ-prerequisites) +- [โš™๏ธ Prerequisites](#-prerequisites) - [๐Ÿ”ง Functions Reference](#-functions-reference) - [๐Ÿ“ Usage Examples](#-usage-examples) -- [โš ๏ธ Error Handling](#๏ธ-error-handling) -- [๐Ÿ› ๏ธ Troubleshooting](#๏ธ-troubleshooting) +- [โš ๏ธ Error Handling](#-error-handling) +- [๐Ÿ› ๏ธ Troubleshooting](#-troubleshooting) - [๐Ÿ”’ Security Considerations](#-security-considerations) - [๐Ÿ”— Related Scripts](#-related-scripts) @@ -54,7 +54,7 @@ This script authenticates to GitHub using the GitHub CLI and removes a specified --- -[โฌ†๏ธ Back to Top](#๏ธ-deletegithubsecretazurecredentialsps1) +[โฌ†๏ธ Back to Top](#-table-of-contents) --- @@ -127,7 +127,7 @@ flowchart TD --- -[โฌ†๏ธ Back to Top](#๏ธ-deletegithubsecretazurecredentialsps1) +[โฌ†๏ธ Back to Top](#-table-of-contents) --- @@ -141,7 +141,7 @@ flowchart TD --- -[โฌ†๏ธ Back to Top](#๏ธ-deletegithubsecretazurecredentialsps1) +[โฌ†๏ธ Back to Top](#-table-of-contents) --- @@ -161,7 +161,7 @@ flowchart TD --- -[โฌ†๏ธ Back to Top](#๏ธ-deletegithubsecretazurecredentialsps1) +[โฌ†๏ธ Back to Top](#-table-of-contents) --- @@ -206,7 +206,7 @@ flowchart TD --- -[โฌ†๏ธ Back to Top](#๏ธ-deletegithubsecretazurecredentialsps1) +[โฌ†๏ธ Back to Top](#-table-of-contents) --- @@ -247,7 +247,7 @@ GitHub secret deletion completed. --- -[โฌ†๏ธ Back to Top](#๏ธ-deletegithubsecretazurecredentialsps1) +[โฌ†๏ธ Back to Top](#-table-of-contents) --- @@ -277,7 +277,7 @@ The script is **idempotent**: --- -[โฌ†๏ธ Back to Top](#๏ธ-deletegithubsecretazurecredentialsps1) +[โฌ†๏ธ Back to Top](#-table-of-contents) --- From 8d4dec8a2c46865dfd594f6e70214c1d9bba3861 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 10:52:05 -0800 Subject: [PATCH 42/44] Update navigation links in documentation for consistency and clarity across Azure and GitHub scripts. --- docs/scripts/azure/README.md | 2 +- docs/scripts/configuration/README.md | 194 ++++++++++++++++++ docs/scripts/github/README.md | 188 +++++++++++++++++ .../delete-github-secret-azure-credentials.md | 6 +- 4 files changed, 386 insertions(+), 4 deletions(-) create mode 100644 docs/scripts/configuration/README.md create mode 100644 docs/scripts/github/README.md diff --git a/docs/scripts/azure/README.md b/docs/scripts/azure/README.md index f63686eb..cb692636 100644 --- a/docs/scripts/azure/README.md +++ b/docs/scripts/azure/README.md @@ -25,7 +25,7 @@ tags: | Previous | Index | Next | |:---------|:-----:|-----:| -| [โ† Scripts Index](../README.md) | [Docs Index](../../README.md) | [GitHub Scripts โ†’](../github/README.md) | +| [โ† Scripts Index](../README.md) | [Scripts Index](../README.md) | [GitHub Scripts โ†’](../github/README.md) | 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/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/delete-github-secret-azure-credentials.md b/docs/scripts/github/delete-github-secret-azure-credentials.md index b442f264..28742a3f 100644 --- a/docs/scripts/github/delete-github-secret-azure-credentials.md +++ b/docs/scripts/github/delete-github-secret-azure-credentials.md @@ -308,7 +308,7 @@ gh secret list | findstr "AZURE_CREDENTIALS" --- -[โฌ†๏ธ Back to Top](#๏ธ-deletegithubsecretazurecredentialsps1) +[โฌ†๏ธ Back to Top](#-table-of-contents) --- @@ -333,7 +333,7 @@ gh secret list | findstr "AZURE_CREDENTIALS" --- -[โฌ†๏ธ Back to Top](#๏ธ-deletegithubsecretazurecredentialsps1) +[โฌ†๏ธ Back to Top](#-table-of-contents) --- @@ -349,7 +349,7 @@ gh secret list | findstr "AZURE_CREDENTIALS"
-[โ† createGitHubSecretAzureCredentials.ps1](create-github-secret-azure-credentials.md) | [โฌ†๏ธ Back to Top](#๏ธ-deletegithubsecretazurecredentialsps1) +[โ† createGitHubSecretAzureCredentials.ps1](create-github-secret-azure-credentials.md) | [โฌ†๏ธ Back to Top](#-table-of-contents) *DevExp-DevBox โ€ข deleteGitHubSecretAzureCredentials.ps1 Documentation* From 2b6ce3162027a5f3a266440a6ef6813550521d88 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 11:04:49 -0800 Subject: [PATCH 43/44] Refactor table of contents links in documentation for improved consistency and clarity across README, CI, deploy, and release files. --- docs/devops/README.md | 18 +++++++++--------- docs/devops/ci.md | 20 ++++++++++---------- docs/devops/deploy.md | 26 +++++++++++++------------- docs/devops/release.md | 25 +++++++++++++------------ 4 files changed, 45 insertions(+), 44 deletions(-) diff --git a/docs/devops/README.md b/docs/devops/README.md index f1f86930..3e91f667 100644 --- a/docs/devops/README.md +++ b/docs/devops/README.md @@ -32,14 +32,14 @@ tags: ## ๐Ÿ“‘ Table of Contents -- [๐ŸŽฏ Overview](#overview) -- [๐Ÿ—๏ธ Master Pipeline Architecture](#master-pipeline-architecture) -- [๐Ÿ“š Workflow Documentation](#workflow-documentation) -- [โšก Quick Reference](#quick-reference) -- [๐Ÿ”„ Reusable Components](#reusable-components) -- [๐Ÿท๏ธ Versioning Strategy](#versioning-strategy) -- [โœ… Best Practices](#best-practices) -- [๐Ÿ”— Related Documentation](#related-documentation) +- [๐ŸŽฏ 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) --- @@ -327,7 +327,7 @@ The project uses a **branch-based semantic versioning** strategy:
-[โฌ†๏ธ Back to Top](#-table-of-contents) | [CI Workflow โ†’](ci.md) +[โฌ†๏ธ 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 index 11bfe26e..6a61653b 100644 --- a/docs/devops/ci.md +++ b/docs/devops/ci.md @@ -30,15 +30,15 @@ tags: ## ๐Ÿ“‘ Table of Contents -- [๐ŸŽฏ Overview](#overview) -- [๐Ÿ“Š Pipeline Visualization](#pipeline-visualization) -- [๐ŸŽฏ Triggers](#triggers) -- [โš™๏ธ Jobs & Steps](#jobs--steps) -- [๐Ÿ” Prerequisites](#prerequisites) -- [๐Ÿท๏ธ Versioning Strategy](#versioning-strategy) -- [๐Ÿ“ฆ Artifacts](#artifacts) -- [๐Ÿ”ง Troubleshooting](#troubleshooting) -- [๐Ÿ”— Related Documentation](#related-documentation) +- [๐ŸŽฏ 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) --- @@ -277,7 +277,7 @@ The CI workflow implements a **branch-based versioning strategy**:
-[โ† DevOps Overview](README.md) | [โฌ†๏ธ Back to Top](#-table-of-contents) | [Deploy Workflow โ†’](deploy.md) +[โ† 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 index 5be2284d..6caaf258 100644 --- a/docs/devops/deploy.md +++ b/docs/devops/deploy.md @@ -31,18 +31,18 @@ tags: ## ๐Ÿ“‘ Table of Contents -- [๐ŸŽฏ Overview](#overview) -- [๐Ÿ“Š Pipeline Visualization](#pipeline-visualization) -- [๐ŸŽฏ Triggers](#triggers) -- [โš™๏ธ Jobs & Steps](#jobs--steps) -- [๐Ÿ” Prerequisites](#prerequisites) -- [๐ŸŒ Environment Variables](#environment-variables) -- [๐Ÿ”’ Concurrency Control](#concurrency-control) -- [๐Ÿ“ฆ Artifacts](#artifacts) -- [๐Ÿ“ Usage Examples](#usage-examples) -- [๐Ÿ”ง Troubleshooting](#troubleshooting) -- [๐Ÿ›ก๏ธ Security Considerations](#security-considerations) -- [๐Ÿ”— Related Documentation](#related-documentation) +- [๐ŸŽฏ 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) --- @@ -365,7 +365,7 @@ gh workflow run deploy.yml \
-[โ† CI Workflow](ci.md) | [โฌ†๏ธ Back to Top](#-table-of-contents) | [Release Workflow โ†’](release.md) +[โ† 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 index 5b069d6b..65533058 100644 --- a/docs/devops/release.md +++ b/docs/devops/release.md @@ -30,17 +30,18 @@ tags: ## ๐Ÿ“‘ Table of Contents -- [๐ŸŽฏ Overview](#overview) -- [๐Ÿ“Š Pipeline Visualization](#pipeline-visualization) -- [๐ŸŽฏ Triggers](#triggers) -- [โš™๏ธ Jobs & Steps](#jobs--steps) -- [๐Ÿ” Prerequisites](#prerequisites) -- [๐Ÿท๏ธ Versioning Strategy](#versioning-strategy) -- [๐Ÿ”’ Concurrency Control](#concurrency-control) -- [๐Ÿ“ฆ Artifacts](#artifacts) -- [๐Ÿ“ Usage Examples](#usage-examples) -- [๐Ÿ”ง Troubleshooting](#troubleshooting) -- [๐Ÿ”— Related Documentation](#related-documentation) +- [๐ŸŽฏ 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) --- @@ -486,7 +487,7 @@ gh workflow run release.yml -r feature/my-feature -f force_release=true
-[โ† Deploy Workflow](deploy.md) | [โฌ†๏ธ Back to Top](#-table-of-contents) +[โ† Deploy Workflow](deploy.md) | [โฌ†๏ธ Back to Top](#%EF%B8%8F-branch-based-release-strategy-workflow) *DevExp-DevBox โ€ข Release Workflow Documentation* From 693e635623d931613c7cf29ab7697e4f527c7694 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Evil=C3=A1zaro=20Alves?= Date: Fri, 23 Jan 2026 11:07:13 -0800 Subject: [PATCH 44/44] Enhance documentation across multiple files with tips, warnings, and important notes for improved clarity and user guidance in DevOps workflows. --- docs/devops/README.md | 6 +++++- docs/devops/ci.md | 6 ++++++ docs/devops/deploy.md | 15 ++++++++++++++- docs/devops/release.md | 12 ++++++++++++ 4 files changed, 37 insertions(+), 2 deletions(-) diff --git a/docs/devops/README.md b/docs/devops/README.md index 3e91f667..fd7e34bc 100644 --- a/docs/devops/README.md +++ b/docs/devops/README.md @@ -13,7 +13,8 @@ tags: # ๐Ÿ”„ DevOps Documentation -> ๐Ÿ“– Comprehensive documentation for GitHub Actions workflows in the Dev Box Accelerator project. +> [!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 @@ -299,6 +300,9 @@ The project uses a **branch-based semantic versioning** strategy: ### 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 diff --git a/docs/devops/ci.md b/docs/devops/ci.md index 6a61653b..4c8866c3 100644 --- a/docs/devops/ci.md +++ b/docs/devops/ci.md @@ -46,6 +46,9 @@ tags: 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) @@ -248,6 +251,9 @@ The CI workflow implements a **branch-based versioning strategy**: ## ๐Ÿ”ง Troubleshooting +> [!WARNING] +> Build failures can block PR merges. Review these common issues to quickly resolve problems. + ### Common Issues | Issue | Cause | Solution | diff --git a/docs/devops/deploy.md b/docs/devops/deploy.md index 6caaf258..db486158 100644 --- a/docs/devops/deploy.md +++ b/docs/devops/deploy.md @@ -50,6 +50,9 @@ tags: 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) @@ -210,6 +213,9 @@ These variables must be configured in the repository settings under **Settings > ### 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 @@ -220,7 +226,8 @@ This workflow uses **OpenID Connect (OIDC)** for secure, secretless authenticati - Entity type: `Environment` - Environment name: `{AZURE_ENV_NAME}` -> ๐Ÿ“– See [Azure OIDC Authentication Documentation](https://learn.microsoft.com/en-us/azure/developer/github/connect-from-azure) +> [!TIP] +> ๐Ÿ“– See [Azure OIDC Authentication Documentation](https://learn.microsoft.com/en-us/azure/developer/github/connect-from-azure) for detailed setup instructions. --- @@ -304,6 +311,9 @@ gh workflow run deploy.yml \ ## ๐Ÿ”ง 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 | @@ -344,6 +354,9 @@ gh workflow run deploy.yml \ ## ๐Ÿ›ก๏ธ 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 diff --git a/docs/devops/release.md b/docs/devops/release.md index 65533058..053e83f5 100644 --- a/docs/devops/release.md +++ b/docs/devops/release.md @@ -49,6 +49,9 @@ tags: 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) @@ -300,6 +303,9 @@ permissions: ## ๐Ÿท๏ธ 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 @@ -426,6 +432,9 @@ Each published release includes: ### 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** @@ -451,6 +460,9 @@ gh workflow run release.yml -r feature/my-feature -f force_release=true ## ๐Ÿ”ง 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 |